Get started

Quickstart

Your first batch payment is a handful of calls away.

You'll get an access token, find the wallet your payments come from, create an individual recipient and pay her USD 50.00 straight into her Xtrm wallet. Then you'll check that the money arrived.

A wallet payment needs nothing but the recipient's account number, so it's the quickest way to see the whole flow work. Submit the batch and Xtrm answers right away, then pays each recipient in the background. When you're ready for bank accounts, cards, mixed payment methods and retries, carry on with Create a batch payment.

If you're a managing platform

Run this quickstart with a client company's pseudo credentials and its SPN, once the company is approved. Pseudo credentials require manager services, which Xtrm turns on for your company. See Onboard a client company.

#What you'll do

StepCallWhat you get back
Get an access tokenPOST /oAuth/tokenaccess_token for every other call
Find your source walletPOST /Wallet/GetCompanyWalletsThe WalletID you pay from
Create a recipientPOST /Register/CreateUserThe recipient's account number, UserID
Submit the batch paymentPOST /Fund/BatchTransfer202 Accepted, with the payments accepted and rejected
Check the batch statusGET /Fund/BatchTransfer/{CustomerBatchId}The status of the batch and of each payment

Prefer Postman?

Import the whole API into Postman: choose Import, then paste https://www.xtrm.com/developers/xtrm-api-v4.postman_collection.json. Set the collection variables client_id and client_secret, then send Get or renew an access token. The token is saved and used by every other request.

#Before you begin

You need:

  • A sandbox company account with API credentials (a client ID and a client secret). The first step summarizes how to get them.
  • Your company's Xtrm account number. Company account numbers start with SPN. Contact [email protected] if you don't know yours.
  • cURL, or one of: Node.js 18+, Python 3 with requests, .NET 8, Java 17+, PHP 8 with the curl extension. The cURL samples use bash syntax.

The samples use these example values. Replace them with your own:

ValueExample
Your company's account numberSPN1111222
Your source wallet122181, a USD wallet
Your recipientJane Doe, [email protected], who gets the account number PAT9999888

#Pay your first batch payment

  1. Get sandbox credentials
    1. Create a sandbox company account with the signup link in Get sandbox access, and open the validation link Xtrm emails you. The Xtrm team then approves your account.
    2. Log in to the sandbox web app at https://sandbox.xtrm.com, go to Settings > Integrations and click Get Credentials. Copy your client ID and client secret, and request the IP addresses you'll call the API from.

    Once Xtrm approves your IP addresses, it credits test funds to your sandbox wallets. That's the money your first batch payment pays. No real money moves in the sandbox; see Sandbox & environments.

  2. Set your environment variables

    Every sample on this site reads your credentials from environment variables, so no secret ends up in your code. Set them in the terminal you'll run the samples from:

    export XTRM_CLIENT_ID="YOUR_CLIENT_ID"
    export XTRM_CLIENT_SECRET="YOUR_CLIENT_SECRET"

    We recommend storing the client secret in your secret manager or deployment environment, never in code or in a committed .env file.

  3. Get an access token

    Exchange your client ID and secret for an access token. The token endpoint sits at the host root, outside /API/v4, and takes form-encoded fields with grant_type=password.

    curl -X POST "https://xapisandbox.xtrm.com/oAuth/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -H "Accept: application/json" \
      --data-urlencode "grant_type=password" \
      --data-urlencode "client_id=$XTRM_CLIENT_ID" \
      --data-urlencode "client_secret=$XTRM_CLIENT_SECRET"
    Response
    {
      "access_token": "YOUR_ACCESS_TOKEN",
      "token_type": "bearer",
      "expires_in": 86399,
      "refresh_token": "YOUR_REFRESH_TOKEN",
      ".issued": "Tue, 27 Oct 2026 14:58:21 GMT",
      ".expires": "Wed, 28 Oct 2026 14:58:21 GMT",
      "client_id": "YOUR_CLIENT_ID"
    }

    Save the access_token for the next steps. Every other call sends it in the Authorization: Bearer <access_token> header. It lasts 24 hours; Authentication covers renewing it.

    export XTRM_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
  4. Find your source wallet

    Every payment in a batch comes out of one of your company wallets, the source wallet, and its currency is the currency of the whole batch. List your wallets with GetCompanyWallets, passing your company's account number as IssuerAccountNumber:

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetCompanyWallets": {
        "request": {
          "IssuerAccountNumber": "SPN1111222"
        }
      }
    }'
    Response
    {
      "GetCompanyWalletResponse": {
        "CompanyWalletResult": {
          "CompanyWallets": {
            "CompanyWalletDetails": [
              {
                "WalletID": 122181,
                "WalletName": "USD Wallet for Main Company",
                "WalletCurrency": "USD",
                "WalletBalance": 57715.15,
                "WalletType": "Standard",
                "IsBankLinked": false,
                "AllowWalletLinkedBankOverride": false,
                "EntityID": 12345
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Pick a USD wallet whose WalletBalance covers the payment, USD 50.00 here, plus its fee: Xtrm charges each payment's fee to the source wallet on top of its Amount. Note its WalletID, 122181 in the example. You send it as SourceWalletId, a JSON number.

  5. Create a recipient

    A batch pays existing Xtrm accounts only, by their account numbers, so create the recipient before you pay her. Create Jane's personal Xtrm account with CreateUser. The required fields are IssuerAccountNumber, EmailAddress, EmailNotification, LegalFirstName, LegalLastName and the country in Address.CountryISO2; the sample also sends a street address and a date of birth. Xtrm creates a wallet for her in the currency of her country, USD here.

    Each email address can belong to only one personal account, and the sandbox is shared, so use an address of your own that has no Xtrm account yet. If the address already has one, CreateUser answers 400 with Email Already Exists; to find and pay an existing account instead, see Pay individual recipients.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Register/CreateUser" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "CreateUser": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "EmailAddress": "[email protected]",
          "EmailNotification": "true",
          "LegalFirstName": "Jane",
          "LegalLastName": "Doe",
          "Address": {
            "AddressLine1": "123 Main Street",
            "City": "Los Angeles",
            "Region": "CA",
            "PostalCode": "90001",
            "CountryISO2": "US"
          },
          "DateOfBirth": {
            "Day": "15",
            "Month": "08",
            "Year": "1990"
          }
        }
      }
    }'
    Response
    {
      "CreateUserResponse": {
        "CreateUserResult": {
          "UserID": "PAT9999888",
          "AccountIdentityLevel": "Basic",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    UserID is Jane's account number, PAT9999888. Personal account numbers start with PAT. It's the RecipientId you pay in the next step. Xtrm approves an account you create through the API straight away, so you can pay Jane now, without waiting for the KYC review.

  6. Submit the batch payment

    Pay Jane USD 50.00 into her Xtrm wallet with POST /Fund/BatchTransfer. This batch, BATCH-QS-0001, has one payment, TXN-QS-0001. Unlike most Xtrm API calls, the fields sit at the root of the body, with no wrapper object.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "IssuerAccountNumber": "SPN1111222",
      "SourceWalletId": 122181,
      "CustomerBatchId": "BATCH-QS-0001",
      "Items": [
        {
          "CustomerTransactionId": "TXN-QS-0001",
          "RecipientId": "PAT9999888",
          "Amount": 50,
          "SendMethodId": "XTR94502",
          "Destination": {},
          "Description": "TXN-QS-0001 Q3 Top Performer Contractor Reward"
        }
      ]
    }'

    What each field does:

    • IssuerAccountNumber is your company's account number, and SourceWalletId is the wallet from step 4. The wallet must belong to your company, and its currency is the batch currency.
    • CustomerBatchId and CustomerTransactionId are your own IDs for the batch and for each payment. Both are required, and Xtrm never generates them. You use them to check, reconcile and retry your payments.
    • RecipientId is Jane's account number from step 5, and Amount is a JSON number in the batch currency, with at most 2 decimal places.
    • SendMethodId XTR94502 pays into an individual recipient's Xtrm wallet. It's one of the seven send methods that GetPaymentMethods lists. Send Destination on every item: {} lets Xtrm credit Jane's wallet in the batch currency, creating one if she has none.
    • Description is an optional note for the payment. Xtrm copies it to the wallet transactions the payment creates, in your wallet and in Jane's, where she sees it. The sample starts it with the CustomerTransactionId, which we recommend: that's how you find those transactions later. See Track & reconcile payments.

    CustomerBatchId values are shared across all Xtrm accounts, so replace the sample IDs with your own unique values before you run this, for example ones that include your account number or a UUID. Give every new batch a new CustomerBatchId and every new payment a new CustomerTransactionId: Xtrm uses them to tell a new payment from a resubmitted one, so you never pay anyone twice. See Retries & idempotency.

    Xtrm checks the request and each payment's fields, and answers 202 Accepted right away:

    Response
    {
      "BatchTransferResponse": {
        "CustomerBatchId": "BATCH-QS-0001",
        "Status": "Accepted",
        "ItemsCount": {
          "Total": 1,
          "Accepted": 1,
          "Rejected": 0
        },
        "Accepted": [
          {
            "CustomerTransactionId": "TXN-QS-0001",
            "Amount": 50.0,
            "Currency": "USD",
            "SendMethodId": "XTR94502",
            "RecipientId": "PAT9999888"
          }
        ],
        "Rejected": []
      }
    }

    Status Accepted means your payment passed the checks and is queued. Jane hasn't been paid yet: Xtrm checks your balance and moves the money when it processes the payment, a moment later. A payment that fails the checks comes back in Rejected, with the Field and Message that explain why; see Errors.

  7. Check the batch status

    Get the status of the batch and its payments with GET /Fund/BatchTransfer/{CustomerBatchId}. recordsToSkip and recordsToTake page through the payments, and history=true adds each payment's attempts.

    curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-QS-0001?recordsToSkip=0&recordsToTake=50&history=true" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"
    Response
    {
      "CustomerBatchId": "BATCH-QS-0001",
      "Status": "Completed",
      "Currency": "USD",
      "ItemsCount": 1,
      "Items": [
        {
          "CustomerTransactionId": "TXN-QS-0001",
          "Status": "Success",
          "RecipientId": "PAT9999888",
          "SendMethodId": "XTR94502",
          "Amount": "50.00",
          "LastUpdatedAt": "2026-10-27T15:04:12.4410000Z",
          "Attempts": [
            {
              "AttemptNo": 1,
              "Result": "Success",
              "ErrorCode": "SUCCESS",
              "CreatedAt": "2026-10-27T15:04:11.9820000Z",
              "CompletedAt": "2026-10-27T15:04:12.4410000Z"
            }
          ]
        }
      ],
      "Pagination": {
        "HasMore": false,
        "NextRecordsToSkip": 0
      }
    }

    TXN-QS-0001 reads Success: Xtrm credited Jane's wallet with USD 50.00. The batch reads Completed because every payment in it succeeded. If the payment still reads Accepted, Processing or Verified, Xtrm hasn't finished with it yet: wait a few seconds and check again. A payment to a bank account or a card, or by check or gift card, also passes through RetainedInWallet on its way to Success, so for those, wait until the batch no longer reads Processing before you act on the payment. For what every status means, and what to do when a payment fails, see Batch and payment statuses.

    Instead of checking, you can have Xtrm notify your server when a payment completes. See Webhooks.

#Full example

This program puts steps 3, 6 and 7 together. It gets an access token, pays Jane USD 50.00 from your source wallet, then checks the status every 3 seconds, up to 10 times, until the payment is no longer in progress. Those timings are our choice for a demo, not API limits.

It reads XTRM_CLIENT_ID and XTRM_CLIENT_SECRET from the environment. Replace SPN1111222, 122181 and PAT9999888 with your own values, and the batch and payment IDs with your own unique ones. The program uses its own IDs, BATCH-QS-0002 and TXN-QS-0002, so it doesn't resend the batch from step 6; to run it again, change both.

#!/usr/bin/env bash
# Save as quickstart.sh and run: bash quickstart.sh
set -euo pipefail

# 1. Get an access token.
TOKEN_RESPONSE=$(curl -sS -X POST "https://xapisandbox.xtrm.com/oAuth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "client_id=$XTRM_CLIENT_ID" \
  --data-urlencode "client_secret=$XTRM_CLIENT_SECRET")
ACCESS_TOKEN=$(printf '%s' "$TOKEN_RESPONSE" | sed -n 's/.*"access_token" *: *"\([^"]*\)".*/\1/p')
if [ -z "$ACCESS_TOKEN" ]; then
  echo "Token request failed: $TOKEN_RESPONSE" >&2
  exit 1
fi

# 2. Pay 50.00 USD into the recipient's wallet.
RESPONSE=$(curl -sS -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -w '\n%{http_code}' \
  -d '{
  "IssuerAccountNumber": "SPN1111222",
  "SourceWalletId": 122181,
  "CustomerBatchId": "BATCH-QS-0002",
  "Items": [
    {
      "CustomerTransactionId": "TXN-QS-0002",
      "RecipientId": "PAT9999888",
      "Amount": 50,
      "SendMethodId": "XTR94502",
      "Destination": {},
      "Description": "TXN-QS-0002 Q3 Top Performer Contractor Reward"
    }
  ]
}')
HTTP_CODE=${RESPONSE##*$'\n'}
echo "${RESPONSE%$'\n'*}"
if [ "${HTTP_CODE:0:1}" != "2" ]; then
  echo "Batch not accepted (HTTP $HTTP_CODE)" >&2
  exit 1
fi

# 3. Check the status until no payment is still in progress.
for CHECK in 1 2 3 4 5 6 7 8 9 10; do
  STATUS=$(curl -sS -f "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-QS-0002?recordsToSkip=0&recordsToTake=50&history=true" \
    -H "Authorization: Bearer $ACCESS_TOKEN")
  if ! printf '%s' "$STATUS" | grep -Eq '"Status" *: *"(Accepted|Processing|Verified)"'; then
    break
  fi
  sleep 3
done
echo "$STATUS"

If a payment is still in progress after the last check, check the batch again later. A payment that ends Failed carries an ErrorCode on its latest attempt. Error codes on attempts says what each code means and what to do, and Create a batch payment shows a worked retry.

#Next steps

When you're ready to go live, see Move to production.