Welcome 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.
\nAll API requests should be made to:
\nhttps://b2b.getorbital.io\n\nThe Orbital API uses a two-factor authentication approach combining an API key and request signature for maximum security.
\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.
Every 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.
Signature Generation in this collection:
\nWe have made a script available in this collection that reads your private key as an environment variable privateKey and will attempt to use it to sign your requests so signatures don't need to be generated before every request.
Signature Generation method:
\nConstruct the signing string by concatenating: HTTP_METHOD + PATH + BODY (+ ?QUERY_STRING for requests with query parameters)
Sign the resulting string using RSA-SHA256 with your private key
\nBase64-encode the signature
\nsigningString = METHOD + PATH + BODY\nsignature = Base64(RSA-SHA256(privateKey, signingString))\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.
x-api-key: your-api-key-here\nx-signature: base64-encoded-rsa-signature\nContent-Type: application/json\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.
Endpoints that return lists of resources support pagination through the following query parameters:
\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.
This API follows semantic versioning. Breaking changes will be communicated in advance and may require migration to a new API version.
\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.).
\nEach account has a unique identifier and contains balance information, account identification details (such as IBAN, account number, or wallet address), and status information.
\nNote: Account attributes vary depending on whether the account is fiat or crypto-based.
\nRetrieve transactions processed within the Orbital Global Payments platform. Transactions include:
\nPayments: Outbound fiat or crypto payments to beneficiaries
\nCurrency Conversions: Exchange between different currencies
\nInternal Transfers: Movements between your own accounts
\nInbound Receipts: Funds received from external sources
\nTransaction attributes vary depending on the transaction type and whether it involves fiat or cryptocurrency.
\nCreate and manage payments using the Orbital Global Payments platform. This allows you to initiate payments to beneficiaries from your accounts.
\nPayments support both fiat and cryptocurrency transfers, with automatic routing to the appropriate payment rail.
\nKey Features:
\nIdempotent payment creation using externalId
Support for same-currency payments
\nReal-time payment status tracking via webhooks
\nManage beneficiaries (payment recipients) within the Orbital Global Payments platform. Beneficiaries can receive both fiat and cryptocurrency payments.
\nBeneficiary Types:
\nIndividual: Personal accounts for individuals
\nBusiness: Corporate or business accounts
\nBeneficiary Status:
\nnew: Beneficiary created, pending compliance screening
approved: Beneficiary passed compliance screening and can receive payments
rejected: Beneficiary failed compliance screening
All new beneficiaries undergo automatic compliance screening before being approved for payments.
\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.
\nConversion Flow:
\nGet Quote: Request a conversion quote via POST /conversions/quotes
Execute Conversion: Use the quoteId to execute the conversion, or provide account details directly
Quotes are valid for a limited time (indicated in the response) and lock in the exchange rate.
\nInstruction Type:
Both quote and conversion endpoints accept an optional instructionType parameter:
sell (default): The amount represents how much of the source currency you want to sell
buy: The amount represents how much of the destination currency you want to buy
Manage payers (originators) for Travel Rule compliance when receiving cryptocurrency payments. Payers represent the source of funds for inbound crypto transactions.
\nThis feature enables compliance with global Travel Rule regulations by capturing and storing originator information for cryptocurrency transactions.
\nUse Cases:
\nRegister external crypto wallet owners
\nLink payer information to incoming transactions
\nMaintain Travel Rule compliance records
\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.
\nAll webhook requests include an X-Orbital-Signature header. Verify this signature to ensure the webhook originated from Orbital:
const crypto = require('crypto');\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\nFailed webhook deliveries are automatically retried up to 4 times with exponential backoff.
\nContact Support:
Name: Orbital Support
Email: support@getorbital.io
Retrieve detailed information about a specific transaction using its unique transaction ID.
\n","urlObject":{"path":["transactions",":id"],"host":["https://b2b.getorbital.io"],"query":[],"variable":[{"id":"ef1b2282-d311-47ef-9b68-a54394bfb646","description":{"content":"The unique transaction identifier
\n","type":"text/plain"},"type":"any","value":"tx_abc123def456","key":"id"}]}},"response":[{"id":"cdd8c002-3907-4600-970f-a50e8fcc016d","name":"Successfully retrieved the transaction","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: apikey","key":"x-api-key","value":"Retrieve detailed information about a specific transaction using its transaction reference.
\nThe transaction reference is a human-readable identifier in the format PAY{timestamp}{random}PAYM that can be used when communicating with Orbital support.
The transaction reference (e.g., PAY202401151234567890PAYM)
Retrieve a paginated list of transactions for your account. You can filter transactions by date range and status.
\nTransactions are returned in descending order by creation date (most recent first).
\n","urlObject":{"path":["transactions"],"host":["https://b2b.getorbital.io"],"query":[{"description":{"content":"Filter transactions created on or after this date (ISO 8601 format)
\n","type":"text/plain"},"key":"fromDate","value":"2024-01-01T00:00:00Z"},{"description":{"content":"Filter transactions created on or before this date (ISO 8601 format)
\n","type":"text/plain"},"key":"toDate","value":"2024-12-31T23:59:59Z"},{"description":{"content":"Filter by transaction status
\n","type":"text/plain"},"key":"status","value":"completed"},{"description":{"content":"Filter by account ID
\n","type":"text/plain"},"key":"accountId","value":"0cb55a48-c7cb-40ab-9192-dd66c1a5eeae"},{"description":{"content":"Page number for pagination (1-indexed)
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Number of items per page (maximum 100)
\n","type":"text/plain"},"key":"pageSize","value":"10"}],"variable":[]}},"response":[{"id":"b21f125d-73d4-4747-855a-d6182e9fd468","name":"Successfully retrieved transactions","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: apikey","key":"x-api-key","value":"Create a new payment from one of your accounts to a beneficiary.
\nPayment Options:\nYou must specify the payment recipient using one of these options:
\nbeneficiaryId: ID of an existing approved beneficiarycreditorAccountId: ID of another account you own (for internal transfers)beneficiary: Full beneficiary details for a one-time payment (beneficiary will be created automatically)Idempotency:\nUse the externalId field to ensure idempotency. If you submit the same externalId twice, the second request will return the original payment details rather than creating a duplicate.
Currency Matching:\nThe payment currency must match both the source account currency and the beneficiary account currency. For cross-currency payments, use the Currency Conversions API.
\n","urlObject":{"path":["payments"],"host":["https://b2b.getorbital.io"],"query":[],"variable":[]}},"response":[{"id":"a5ddc723-e595-447b-8265-016013cda912","name":"Payment to existing beneficiary","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: apikey","key":"x-api-key","value":"Credit funds to a sandbox account for testing purposes. This endpoint is only available in the sandbox environment.
\nUse this to simulate incoming deposits so you can test payment flows without waiting for real funds.
\n","urlObject":{"path":["accounts",":id","topup"],"host":["https://b2b.getorbital.io"],"query":[],"variable":[{"id":"0df12ff6-7673-4c60-a31f-b69c2fca5612","description":{"content":"The unique account identifier to credit
\n","type":"text/plain"},"type":"any","value":"0cb55a48-c7cb-40ab-9192-dd66c1a5eeae","key":"id"}]}},"response":[{"id":"efba5c46-c4fc-4d48-912f-1da1933daba8","name":"Account topped up successfully","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: apikey","key":"x-api-key","value":"Retrieve detailed information about a specific account using its unique account ID.
\n","urlObject":{"path":["accounts",":id"],"host":["https://b2b.getorbital.io"],"query":[],"variable":[{"id":"e5947a5b-f49f-4a5c-a4d4-1c6d8ce2b9e7","description":{"content":"The unique account identifier (UUID format)
\n","type":"text/plain"},"type":"any","value":"0cb55a48-c7cb-40ab-9192-dd66c1a5eeae","key":"id"}]}},"response":[{"id":"27219615-d2b8-42a4-b29b-1bfe229a1362","name":"Successfully retrieved the account","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: apikey","key":"x-api-key","value":"Retrieve a paginated list of all accounts associated with your organization.
\nFilter accounts by status or currency to find specific accounts.
\n","urlObject":{"path":["accounts"],"host":["https://b2b.getorbital.io"],"query":[{"description":{"content":"Filter by account status
\n","type":"text/plain"},"key":"status","value":"inactive"},{"description":{"content":"Filter by currency code (e.g., USD, EUR, BTC, USDT)
\n","type":"text/plain"},"key":"currency","value":"USD"},{"description":{"content":"Page number for pagination (1-indexed)
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Number of items per page (maximum 100)
\n","type":"text/plain"},"key":"pageSize","value":"10"}],"variable":[]}},"response":[{"id":"bdccbf0c-20c5-4a01-ba30-66eccbda8f79","name":"Successfully retrieved accounts","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: apikey","key":"x-api-key","value":"Retrieve detailed information about a specific beneficiary using their unique ID.
\n","urlObject":{"path":["beneficiaries",":id"],"host":["https://b2b.getorbital.io"],"query":[],"variable":[{"id":"5d60ceec-e7ac-4df3-965e-5c70375286d5","description":{"content":"The unique beneficiary identifier (UUID format)
\n","type":"text/plain"},"type":"any","value":"e78733bd-0a45-4777-9715-b32221e58f7b","key":"id"}]}},"response":[{"id":"bab3dbf5-b81d-480e-9f03-bda078769e07","name":"Successfully retrieved the beneficiary","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: apikey","key":"x-api-key","value":"Delete a beneficiary by their unique ID.
\nWarning: This action cannot be undone. You will need to recreate the beneficiary if you want to send payments to them again.
\n","urlObject":{"path":["beneficiaries",":id"],"host":["https://b2b.getorbital.io"],"query":[],"variable":[{"id":"8063b946-0e38-411e-921b-31d1383f9ce5","description":{"content":"The unique beneficiary identifier (UUID format)
\n","type":"text/plain"},"type":"any","value":"e78733bd-0a45-4777-9715-b32221e58f7b","key":"id"}]}},"response":[{"id":"7bc71654-5933-4f5d-9ad5-1761c52b4208","name":"Beneficiary successfully deleted","originalRequest":{"method":"DELETE","header":[{"description":"Added as a part of security scheme: apikey","key":"x-api-key","value":"Retrieve a paginated list of all beneficiaries associated with your organization.
\nFilter beneficiaries by status or currency to find specific recipients.
\n","urlObject":{"path":["beneficiaries"],"host":["https://b2b.getorbital.io"],"query":[{"description":{"content":"Filter by beneficiary status
\n","type":"text/plain"},"key":"status","value":"approved"},{"description":{"content":"Filter by currency code (e.g., USD, EUR, USDT)
\n","type":"text/plain"},"key":"currency","value":"GBP"},{"description":{"content":"Page number for pagination (1-indexed)
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Number of items per page (maximum 100)
\n","type":"text/plain"},"key":"pageSize","value":"10"}],"variable":[]}},"response":[{"id":"5278ecd9-f4da-407a-83ba-217af49ac380","name":"Successfully retrieved beneficiaries","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: apikey","key":"x-api-key","value":"Create a new beneficiary for receiving payments.
\nBeneficiary Types:
\nCompliance Screening:\nAll new beneficiaries undergo automatic compliance screening. The beneficiary will be created with status new and will transition to approved or rejected after screening completes.
You will receive a BeneficiaryScreened webhook event when screening is complete. Alternatively, poll GET /beneficiaries/{id} until the status changes from new.
Request a quote for converting currency between two of your accounts.
\nThe quote includes:
\nQuote Expiration:\nQuotes are valid for a limited time (typically 30 seconds). Use the quote before expiration to lock in the rate.
\nInstruction Type:\nUse instructionType to control whether the amount represents the source or destination side:
sell (default): The amount is the source amount you are sellingbuy: The amount is the destination amount you want to buyRequirements:
\nExecute a currency conversion between two of your accounts.
\nTwo execution modes:
\nWith Quote ID (recommended):
\nPOST /conversions/quotesquoteId to lock in the quoted rateWithout Quote ID:
\nfromAccount, toAccount, and amount directlyQuote-based execution is recommended for predictable rates, especially for large amounts.
\nInstruction Type:\nUse instructionType to control whether the amount represents the source or destination side:
sell (default): The amount is the source amount you are sellingbuy: The amount is the destination amount you want to buy