--- updatedAt: 2026-03-31T10:41:44.000Z agentTools: projectIndex: https://docs.getorbital.com/llms.txt --- # Add account to payer Add a new wallet account to an existing payer (originator). This allows associating multiple cryptocurrency wallet addresses with a single payer for Travel Rule compliance across different blockchains or currencies. # OpenAPI definition ````json { "openapi": "3.0.3", "info": { "title": "B2B Global Payments API", "version": "1.0.0", "description": "# Introduction\n\nWelcome to the B2B Global Payments API. This API enables you to programmatically access the Orbital platform to manage accounts, execute payments, handle currency conversions, and manage beneficiaries across both fiat and cryptocurrency rails.\n\n## Base URL\n\nAll API requests should be made to:\n```\nhttps://b2b.getorbital.io\n```\n\n## Authentication\n\nThe Orbital API uses a two-factor authentication approach combining an API key and request signature for maximum security.\n\n### API Key\nEvery request must include an `x-api-key` header containing your unique API key. You can obtain an API key from the Orbital Application page on Client Portal.\n\n### Request Signature\nEvery request must also include an `x-signature` header containing an RSA-SHA256 signature, signed with your private key. The corresponding public key is registered with Orbital during Orbital Application setup.\n\n**Signature Generation:**\n\n1. Construct the signing string by concatenating: `HTTP_METHOD` + `PATH` + `BODY` (+ `?QUERY_STRING` for requests with query parameters)\n2. Sign the resulting string using RSA-SHA256 with your private key\n3. Base64-encode the signature\n\n```\nsigningString = METHOD + PATH + BODY\nsignature = Base64(RSA-SHA256(privateKey, signingString))\n```\n\nFor GET requests without a body, omit the body portion (i.e. `METHOD + PATH`). When query string parameters are present, append them as `?key=value&key=value`.\n\n### Example Headers\n```http\nx-api-key: your-api-key-here\nx-signature: base64-encoded-rsa-signature\nContent-Type: application/json\n```\n\n## Rate Limiting\n\nAPI requests are rate-limited to ensure fair usage across all clients. If you exceed the rate limit, you will receive a `429 Too Many Requests` response. Please implement exponential backoff in your retry logic.\n\n## Pagination\n\nEndpoints that return lists of resources support pagination through the following query parameters:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `page` | integer | Page number (1-indexed). Defaults to 1. |\n| `pageSize` | integer | Number of items per page. Defaults to 10, maximum 100. |\n\n## Idempotency\n\nFor payment operations, include an `externalId` in your request to ensure idempotency. If you retry a request with the same `externalId`, you will receive the original response rather than creating a duplicate payment.\n\n## Versioning\n\nThis API follows semantic versioning. Breaking changes will be communicated in advance and may require migration to a new API version.\n\n---\n\n## Accounts\n\nManage your accounts within the Orbital Global Payments platform. Accounts can hold both fiat currencies (USD, EUR, GBP, etc.) and cryptocurrencies (BTC, ETH, USDT, etc.).\n\nEach account has a unique identifier and contains balance information, account identification details (such as IBAN, account number, or wallet address), and status information.\n\n**Note:** Account attributes vary depending on whether the account is fiat or crypto-based.\n\n## Transactions\n\nRetrieve transactions processed within the Orbital Global Payments platform. Transactions include:\n\n- **Payments**: Outbound fiat or crypto payments to beneficiaries\n- **Currency Conversions**: Exchange between different currencies\n- **Internal Transfers**: Movements between your own accounts\n- **Inbound Receipts**: Funds received from external sources\n\nTransaction attributes vary depending on the transaction type and whether it involves fiat or cryptocurrency.\n\n## Payments\n\nCreate and manage payments using the Orbital Global Payments platform. This allows you to initiate payments to beneficiaries from your accounts.\n\nPayments support both fiat and cryptocurrency transfers, with automatic routing to the appropriate payment rail.\n\n**Key Features:**\n- Idempotent payment creation using `externalId`\n- Support for same-currency payments\n- Real-time payment status tracking via webhooks\n\n## Beneficiaries\n\nManage beneficiaries (payment recipients) within the Orbital Global Payments platform. Beneficiaries can receive both fiat and cryptocurrency payments.\n\n**Beneficiary Types:**\n- **Individual**: Personal accounts for individuals\n- **Business**: Corporate or business accounts\n\n**Beneficiary Status:**\n- `new`: Beneficiary created, pending compliance screening\n- `approved`: Beneficiary passed compliance screening and can receive payments\n- `rejected`: Beneficiary failed compliance screening\n\nAll new beneficiaries undergo automatic compliance screening before being approved for payments.\n\n## Currency Conversions\n\nExecute currency conversions between your accounts holding different currencies. The conversion API supports fiat-to-fiat, fiat-to-crypto, crypto-to-fiat, and crypto-to-crypto conversions.\n\n**Conversion Flow:**\n1. **Get Quote**: Request a conversion quote via `POST /conversions/quotes`\n2. **Execute Conversion**: Use the `quoteId` to execute the conversion, or provide account details directly\n\nQuotes are valid for a limited time (indicated in the response) and lock in the exchange rate.\n\n**Instruction Type:**\nBoth quote and conversion endpoints accept an optional `instructionType` parameter:\n- `sell` (default): The `amount` represents how much of the source currency you want to sell\n- `buy`: The `amount` represents how much of the destination currency you want to buy\n\n## Payers\n\nManage payers (originators) for Travel Rule compliance when receiving cryptocurrency payments. Payers represent the source of funds for inbound crypto transactions.\n\nThis feature enables compliance with global Travel Rule regulations by capturing and storing originator information for cryptocurrency transactions.\n\n**Use Cases:**\n- Register external crypto wallet owners\n- Link payer information to incoming transactions\n- Maintain Travel Rule compliance records\n\n## Webhooks\n\nOrbital delivers webhooks to the notification URL you configure for your application (for example in the Client Portal). Events are sent as HTTP POST requests to that URL so your integration can react in near real time.\n\n### Webhook Events\n\n| Event | Description |\n|-------|-------------|\n| `BeneficiaryCreated` | A new beneficiary has been created |\n| `BeneficiaryRemoved` | A beneficiary has been deleted |\n| `PaymentCreated` | A new payment has been initiated |\n| `PaymentCompleted` | A payment has been successfully settled |\n| `PaymentRejected` | A payment has been rejected or failed |\n| `PaymentInformationRequired` | A payment requires additional information (e.g. payer details for Travel Rule) |\n\n### Webhook Signature Verification\n\nAll webhook requests include an `X-Orbital-Signature` header. Verify this signature to ensure the webhook originated from Orbital:\n\n```javascript\nconst crypto = require('crypto');\n\nfunction verifyWebhookSignature(webhookSecret, webhookUrl, body, signature) {\n const data = webhookSecret + webhookUrl + body;\n const expectedSignature = crypto\n .createHash('sha256')\n .update(data)\n .digest('base64');\n return crypto.timingSafeEqual(\n Buffer.from(signature),\n Buffer.from(expectedSignature)\n );\n}\n```\n\n### Retry Policy\n\nFailed webhook deliveries are automatically retried up to 4 times with exponential backoff.\n", "contact": { "name": "Orbital Support", "email": "support@getorbital.io", "url": "https://getorbital.io/support" }, "license": { "name": "Proprietary", "url": "https://getorbital.io/terms" } }, "servers": [ { "url": "https://b2b.getorbital.io", "description": "Production API" }, { "url": "https://sbx.b2b.getorbital.io", "description": "Sandbox API" } ], "tags": [ { "name": "Payers", "description": "Manage payer (originator) records for Travel Rule compliance." } ], "paths": { "/payers/{id}/accounts": { "post": { "tags": [ "Payers" ], "summary": "Add account to payer", "description": "Add a new wallet account to an existing payer (originator).\n\nThis allows associating multiple cryptocurrency wallet addresses with a single payer for Travel Rule compliance across different blockchains or currencies.\n", "operationId": "addPayerAccount", "security": [ { "ApiKeyAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique payer identifier", "schema": { "type": "string" }, "example": "payer_abc123def456" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletAddress", "currency", "blockchain" ], "properties": { "walletAddress": { "type": "string", "description": "Cryptocurrency wallet address", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bE85" }, "currency": { "type": "string", "enum": [ "BCH", "BTC", "ETH", "LTC", "SOL", "TRX", "USDC", "USDT", "BUSD" ], "description": "Cryptocurrency", "example": "USDC" }, "blockchain": { "type": "string", "enum": [ "BCH", "BTC", "ETH", "LTC", "SOL", "TRX" ], "description": "Blockchain network", "example": "ETH" } } } } } }, "responses": { "201": { "description": "Successfully added account to payer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerAccount" }, "example": { "id": "acct_xyz789", "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bE85", "currency": "USDC", "blockchain": "ETH", "createdAt": "2024-01-15T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "description": "Payer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Payer not found", "code": "PAYER_NOT_FOUND" } } } }, "500": { "$ref": "#/components/responses/Error500" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your unique API key obtained from the Orbital dashboard" }, "SignatureAuth": { "type": "apiKey", "in": "header", "name": "x-signature", "description": "Base64-encoded RSA-SHA256 signature of the request (method + path + body + query string), signed with your private key" } }, "schemas": { "PayerAccount": { "type": "object", "description": "A wallet account associated with a payer", "properties": { "id": { "type": "string", "description": "Unique account identifier" }, "walletAddress": { "type": "string", "description": "Cryptocurrency wallet address" }, "currency": { "type": "string", "description": "Cryptocurrency code" }, "blockchain": { "type": "string", "description": "Blockchain network" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code for programmatic handling", "enum": [ "MISSING_API_KEY", "DISABLED_API_KEY", "INVALID_API_KEY", "MISSING_SIGNATURE", "INVALID_SIGNATURE", "INSUFFICIENT_PERMISSIONS", "FORBIDDEN", "INVALID_REQUEST_PAYLOAD", "MISSING_REQUEST_BODY", "INVALID_REQUEST", "ACCOUNT_NOT_FOUND", "BENEFICIARY_NOT_FOUND", "TRANSACTION_NOT_FOUND", "PAYER_NOT_FOUND", "CURRENCY_MISMATCH", "INVALID_BALANCE_FORMAT", "INSUFFICIENT_FUNDS", "ACCOUNT_INACTIVE", "AMOUNT_BELOW_MINIMUM", "DUPLICATE_PAYMENT", "BENEFICIARY_ALREADY_EXISTS", "INVALID_IBAN", "INVALID_BIC", "BANK_NOT_FOUND", "EXTERNAL_SERVICE_ERROR", "INTERNAL_SERVER_ERROR" ] }, "details": { "type": "object", "nullable": true, "description": "Additional context about the error (structure varies by error code)" } } } }, "responses": { "Error400": { "description": "Bad Request - The request was malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "currencyMismatch": { "summary": "Currency mismatch", "value": { "error": "Currency mismatch: this endpoint only supports payments between accounts with the same currency", "code": "CURRENCY_MISMATCH", "details": { "accountCurrency": "USD", "beneficiaryCurrency": "EUR" } } }, "insufficientFunds": { "summary": "Insufficient funds", "value": { "error": "Insufficient funds: the payment amount exceeds the available balance", "code": "INSUFFICIENT_FUNDS", "details": { "requestedAmount": 1000, "availableBalance": 500, "currency": "USD" } } }, "accountInactive": { "summary": "Account inactive", "value": { "error": "Account is not active", "code": "ACCOUNT_INACTIVE", "details": { "accountStatus": "suspended" } } }, "invalidRequestPayload": { "summary": "Invalid request payload", "value": { "error": "Invalid request payload", "code": "INVALID_REQUEST_PAYLOAD", "details": { "validationErrors": [ { "path": [ "amount" ], "message": "Amount must be a valid positive number" } ] } } }, "missingRequestBody": { "summary": "Missing request body", "value": { "error": "Request body is missing", "code": "MISSING_REQUEST_BODY" } }, "beneficiaryExists": { "summary": "Beneficiary already exists", "value": { "error": "Beneficiary with these details already exists", "code": "BENEFICIARY_ALREADY_EXISTS" } }, "invalidIban": { "summary": "Invalid IBAN", "value": { "error": "Invalid IBAN format", "code": "INVALID_IBAN" } }, "amountBelowMinimum": { "summary": "Amount below minimum", "value": { "error": "Transaction amount is below the minimum threshold", "code": "AMOUNT_BELOW_MINIMUM", "details": { "minimumAmount": 1, "providedAmount": 0.5, "currency": "USD" } } }, "duplicatePayment": { "summary": "Duplicate payment", "value": { "error": "A payment with this external ID already exists", "code": "DUPLICATE_PAYMENT", "details": { "transactionReference": "PAY202503201254556468PAYM" } } } } } } }, "Error401": { "description": "Authentication Error - Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingApiKey": { "summary": "Missing API key", "value": { "error": "Missing x-api-key header", "code": "MISSING_API_KEY" } }, "disabledApiKey": { "summary": "Disabled API key", "value": { "error": "API Key has been disabled", "code": "DISABLED_API_KEY" } }, "invalidApiKey": { "summary": "Invalid API key", "value": { "error": "Invalid API Key", "code": "INVALID_API_KEY" } }, "missingSignature": { "summary": "Missing signature", "value": { "error": "Missing x-signature header", "code": "MISSING_SIGNATURE" } }, "invalidSignature": { "summary": "Invalid signature", "value": { "error": "Invalid signature", "code": "INVALID_SIGNATURE" } } } } } }, "Error403": { "description": "Forbidden - Valid credentials but insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficientPermissions": { "summary": "Insufficient permissions", "value": { "error": "API Key does not have required permissions", "code": "INSUFFICIENT_PERMISSIONS" } }, "forbidden": { "summary": "Forbidden resource", "value": { "error": "Access to this resource is forbidden", "code": "FORBIDDEN" } } } } } }, "Error500": { "description": "Internal Server Error - An unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internalServerError": { "summary": "Internal server error", "value": { "error": "Could not process request, please reach out to customer support", "code": "INTERNAL_SERVER_ERROR", "details": { "requestId": "123e4567-e89b-12d3-a456-426614174000" } } } } } } } } } } ````