Get started

Sandbox & environments

Build and test in the sandbox, then go live when you're ready.

The sandbox is kept separate from production, but it works the same way: the same batch payment code and the same API endpoints. That means you can build and test your whole integration with test funds before a single real payment goes out, and what works in the sandbox works in production.

What sets the sandbox apart is your data and your money, and How the sandbox behaves walks you through both. When you're ready to launch, Xtrm's ops team gets on a call with you to make sure everything is set for production.

#Environments at a glance

SandboxProduction
Use it forBuilding and testing your batch paymentsLive payments
Web apphttps://sandbox.xtrm.comhttps://www.xtrm.com
API base URLhttps://xapisandbox.xtrm.com/API/v4https://xapi.xtrm.com/API/v4
Batch payment URLhttps://xapisandbox.xtrm.com/API/v4/Fund/BatchTransferhttps://xapi.xtrm.com/API/v4/Fund/BatchTransfer
Token URLhttps://xapisandbox.xtrm.com/oAuth/tokenhttps://xapi.xtrm.com/oAuth/token
API credentialsSettings > Integrations > Get Credentials in your sandbox company accountSettings > Integrations > Get Credentials in your live company account
IP allowlistingRequested on the Get Credentials screen, approved by XtrmRequested on the Get Credentials screen in the live web app, approved by Xtrm
DataTest data only, completely separate from your production accountReal accounts. Individual and business recipients you create with CreateUser and CreateBeneficiary are approved straight away and reviewed for KYC compliance: identity checks that confirm each recipient is who they say they are.
MoneyNo actual money is sent or receivedBatch payments move real funds
Starting balanceTest funds that Xtrm credits to your sandbox wallets after approving your IP addresses.See Fund your wallet for the funding endpoints.
Batch payment processingThe same as production. Wallet payments reach Success when the wallet is credited; other payments when the provider accepts themWallet payments reach Success when the wallet is credited; other payments when the provider accepts them

#Hosts and URLs

#API base URL

Every endpoint except the token request lives under the API base URL, grouped by resource. The three batch payment endpoints are:

TEXT
POST https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer
GET  https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/{CustomerBatchId}
GET  https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}

The first creates a batch payment; the other two return the status of a batch and of a single payment. In production, the same paths sit under https://xapi.xtrm.com/API/v4.

#Token URL

The token endpoint is at the root of the host, outside /API/v4. In the sandbox it is https://xapisandbox.xtrm.com/oAuth/token, and in production it is https://xapi.xtrm.com/oAuth/token.

Keep environment settings out of your code

We recommend keeping everything that differs between environments in environment-specific configuration (for example, environment variables or a secrets manager): the API base URL, the token URL, your credentials, your company's account number, the source wallet IDs of your batch payments and, if you use them, your webhook signing secret. Moving from the sandbox to production is then a configuration change, not a code change.

#Get sandbox access

  1. Create your sandbox company account

    Sign up with the sandbox company signup form. This becomes your company account, the account that owns your sandbox API credentials and the wallets your test batches are paid from.

  2. Validate your email

    After you sign up, you receive a validation link by email. Click it to accept the terms and conditions and create your login password. The Xtrm team then approves your account and completes the setup for you.

  3. Get your credentials and request IP addresses

    Log in to the sandbox web app at https://sandbox.xtrm.com, go to Settings > Integrations and click Get Credentials. On this screen you get your API credentials (client_id and client_secret) and request the IP addresses you want allowlisted.

    Store the credentials as XTRM_CLIENT_ID and XTRM_CLIENT_SECRET, the environment variables this site's samples read.

  4. Wait for approval and test funds

    After approving your IP addresses, Xtrm credits test funds to your sandbox wallets, so you can start submitting test batch payments.

#IP allowlisting

You request the IP addresses to allowlist on the Get Credentials screen, and the Xtrm team approves them. Sandbox funding happens after approval.

The allowlist belongs to your company, so all of your company's credentials share it. A call to any endpoint from an address that isn't on the list gets 401 with invalid_authorization, the same response as an unknown token.

We recommend requesting every address you'll call the API from, such as developer machines and CI or staging servers, before you test from them. For help with IP approval or sandbox access, email [email protected].

#Test funds

After approving your IP addresses, Xtrm credits test funds to your sandbox wallets. These are test funds; no actual money moves. If you need more, ask [email protected].

These wallets are the source wallets of your test batches. The source wallet sets the currency of a batch, so if you plan to pay in your local currency, ask for local-currency test funds too.

You can try the funding calls in the sandbox too, but Xtrm credits a bank transfer or bank debit only once it approves the funding request, so in the sandbox those requests stay Pending until Xtrm approves them. Test your batches with the test funds Xtrm credits.

#Verify your sandbox setup

The Quickstart is the quickest check that everything works: its first calls get an access token with your sandbox credentials and list your company wallets, so you can see that your test funds have arrived. It then pays a test recipient end to end. To build a full batch, see Create a batch payment.

#How the sandbox behaves

The sandbox works the same as production. It supports the same API endpoints, including all three batch payment endpoints, and processes payments the same way. Bank, routing and IBAN numbers and SKUs work the same as in production, with no sandbox-only values. For cards, use the standard test card numbers (see No real money moves), and for bank accounts, see Test bank accounts. What differs is the data it holds and the money it moves.

#Test data only

The sandbox contains only test data and is completely separate from your production account. Create the test individual and business recipients your batches pay, and any email addresses you send cards to, here, not in production.

There are no test bank accounts. To link a bank to a test recipient, use a real bank's routing number or SWIFT-BIC with a made-up account number in the format the bank's country needs, never a real account number; see Test bank accounts.

#No real money moves

No actual money is sent or received in sandbox transactions, including batch payments. Never use real financial data in the sandbox, such as real bank account details or card numbers, whether you link them to a test recipient or use them to test card funding.

For cards, use the standard test numbers instead, with a future expiry date and a three-digit CVV:

CardTest number
Visa4111111111111111
Mastercard5555555555554444

#Test bank accounts

The sandbox has no test bank accounts. Link a bank account to a test recipient the same way as in production, with LinkBankBeneficiary, which needs the recipient to be connected to your company (a recipient you create is connected from the start). The routing number or SWIFT-BIC must belong to a real bank, which you can look up with SearchBankByNationalID or SearchBankByBIC. The account number must be in the format the bank's country needs; if it isn't, LinkBankBeneficiary tells you which field to fix. Use a made-up account number in that format, never a real one. Like every sandbox payment, a bank payment to it moves no real money.

#How payments finish in the sandbox

The sandbox processes batch payments the same way production does, so every payment is credited to the recipient's wallet first (wallet-first delivery):

  • Wallet payments (XTR94502, XTR94504) reach Success once the recipient's wallet is credited.
  • Bank transfer, Rapid Transfer, check, prepaid card and gift card payments (XTR94500, XTR94508, XTR94507, XTR94503, XTR94505) then go to the provider, and reach Success when the provider accepts the payment, as in production.

Success means the provider accepted the payment, not that the funds settled. On the way to Success, these payments pass through RetainedInWallet while Xtrm delivers them from the recipient's wallet, so wait while the batch is Processing. If a payment is still RetainedInWallet once the batch is final, the delivery didn't go through, the money stays in the recipient's Xtrm wallet, and the fee isn't refunded (details).

There are no special test values that force an outcome. To test failures, use inputs that make a payment fail, in the sandbox as in production:

  • A RecipientId that isn't an Xtrm account, such as PAT0000001, or whose account is closed or suspended (RECIPIENT_NOT_FOUND).
  • A BeneficiaryBankID that isn't linked to the recipient, such as 00000000000000000000000000000000, sent without a business recipient's WalletId (BANKID_INVALID). With a business recipient's WalletId, the wallet's linked bank can replace the ID you send.
  • An Amount that, with the fee, exceeds your source wallet's balance and is within your send limits (INSUFFICIENT_BALANCE). A payment over your send limits fails with SEND_LIMIT_EXCEEDED first.
  • A gift card SKU that doesn't exist, such as U000000 (SKU_NOT_FOUND).
  • A check to a country other than US (COUNTRY_UNSUPPORTED), or a check payment from a non-USD wallet, which is rejected when you submit it (CURRENCY_MISMATCH).

Error codes on attempts explains each code.

Tip

Don't assume every external payment reaches Success: a payment can also end Failed, or stay RetainedInWallet when its delivery doesn't go through. We recommend giving your status polling a time limit, in the sandbox as in production.

#Follow your test batches

You follow a test batch the same ways as a live one:

  • Poll the status endpoints: the batch by its CustomerBatchId, or a single payment by its CustomerBatchId and CustomerTransactionId. Set history to true to see every attempt.
  • Receive webhooks. Webhooks work in the sandbox the same way as in production, with one endpoint per company account in each environment. See Webhooks for how to set one up.
  • Contact Xtrm support about a specific batch. Your CustomerBatchId isn't shown in the Xtrm web app, but Xtrm staff can look a batch up by it, so include it when you need help with a batch.

#Move to production

Test your application in the sandbox first. Your live company account is separate from your sandbox account, and onboarding it isn't API-only. Your company signs up for it in the Xtrm web app at https://www.xtrm.com and completes its Identity profile there, including its documents: a government-issued photo ID for its administrator and, for a private company, a company tax document such as a W-9 for a US company, uploaded under Identity > Identity Documents. No API call uploads documents. Then it submits its advanced profile (the identity checks for the company and its owners). Once Xtrm approves it, your company is fully onboarded and can fund its wallets. See Complete the advanced profile.

Once your sandbox testing is complete, Xtrm's ops team holds a call with you to verify that you're ready for production. Production then works like the sandbox, in your live company account.

Before your first live batch payment, we recommend that you:

  1. Contact Xtrm for the readiness call at [email protected] once your batch payment flows work end to end in the sandbox.
  2. Finish onboarding your live company account in the web app. Complete its Identity profile there, including its documents, since no API call uploads them, and get its advanced profile approved. If you're a managing platform, each client company needs the same, with its documents uploaded by your platform as a manager service or by the company itself. See Onboard a client company.
  3. Get your production credentials under Settings > Integrations > Get Credentials in your live company account, request your production IP addresses there, and switch your token URL to https://xapi.xtrm.com/oAuth/token. Production has its own allowlist; see IP allowlisting.
  4. Switch your API base URL to https://xapi.xtrm.com/API/v4. Batch payments are then at https://xapi.xtrm.com/API/v4/Fund/BatchTransfer.
  5. Load your account number and source wallet IDs from configuration, including your IssuerAccountNumber (SPN) and the SourceWalletId of your batches, and check them against your production account, for example with GetCompanyWallets. Sandbox values don't carry over: the sandbox is completely separate from your production account.
  6. Create your production recipients before you pay them. Recipients you created in the sandbox don't exist in production, and a batch pays existing account numbers only. Create each person with CreateUser and each business with CreateBeneficiary in production before the batch that pays them, and use their production PAT and SPN numbers as RecipientId.
  7. Remove test data from every flow that creates individual or business recipients.
  8. Fund your production source wallet. Sandbox test funds aren't real money. See Fund your wallet.
  9. Plan for your batch limits. Xtrm sets the maximum number of payments per batch for each account, and a maximum request size applies to every account. Keep your batches well under them; see Limits.
  10. Give every batch and payment your own unique IDs, and store them with your payment records. CustomerBatchId values are shared across all Xtrm accounts, so make yours unique, for example by including your account number or a UUID. See Retries & idempotency for the ID rules and a safe way to resend after a timeout.
  11. Have Xtrm support set up your production webhook endpoint if you use webhooks. Xtrm support sets up the endpoint and its signing secret with you, and your production endpoint has its own secret; keep it in your production configuration. See Webhooks.

#Next steps