Batch payments

Payment methods & destinations

Each payment in a batch can go to a bank account by ACH, wire or RTP, to a card, as a mailed check or a gift card, or straight into the recipient's Xtrm wallet. SendMethodId picks the method for each item, and the Destination object carries the fields that method needs. Each item has its own method, so one batch can pay bank accounts, wallets, cards and checks together.

Payments and currency exchange are executed by regulated financial partners.

This page lists every payment method, the Destination fields it takes and where to get each value. For the batch itself, see How batch payments work, Create a batch payment and the BatchTransfer reference.

#Methods at a glance

SendMethodIdMethodDelivers toRequired Destination fields
XTR94500Bank transferThe recipient's linked bank account, by ACH, wire or RTPBeneficiaryBankID or WalletId; see Bank transfer
XTR94502Individual walletAn individual recipient's Xtrm walletNone
XTR94504Business walletA business recipient's Xtrm walletNone
XTR94508Push to card (Rapid Transfer in the API)A US card linked to the recipient as a transfer cardCardToken
XTR94503Prepaid virtual debit cardAn individual recipient, as a prepaid card whose credentials are sent by emailEmail, SKU
XTR94505Digital gift cardAn individual recipient, as a gift card whose credentials are sent by emailEmail, SKU
XTR94507Physical checkA check mailed to a US addressBeneficiaryCheckName, BeneficiaryCheckAddress1, BeneficiaryCheckCity, BeneficiaryCheckState, BeneficiaryCheckPostalCode, BeneficiaryCheckCountryCodeISO2, BeneficiaryCheckMemo, BeneficiaryCheckReference

Destination itself is required on every item, even when all of its fields are optional for the method. For example, send "Destination": {} for a wallet item without a WalletId.

Prepaid and gift cards (XTR94503, XTR94505) can pay individual recipients only: an item for a business recipient fails during processing with SENDMETHODID_NOT_FOUND. Bank, push-to-card and check items can pay both kinds of recipient.

Every payment lands in the recipient's wallet first (see wallet-first delivery). For a bank, card or check payment, Xtrm first credits the recipient's wallet, then debits it and delivers the payment, and the item becomes Success when the bank or provider accepts it. RetainedInWallet is a pass-through status for bank, card, check, gift card and prepaid payments: wait while the batch is Processing. If the 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: treat it like a wallet payment (details). For what each status means and what to do, see Batch and payment statuses.

Match on the ID, not the name

The same method goes by different names in different places. For example, GetPaymentMethods calls XTR94502 AnyPay Individual, XTR94504 AnyPay Company, XTR94500 Bank and XTR94507 Bank Check. Always match on the XTR945xx ID.

#Destination fields by method

Copy each field name exactly as shown here. Names match in any case, but Xtrm silently drops a field it doesn't recognize, so a misspelled name such as Wallet_Id is lost without an error. Xtrm also discards fields that don't belong to the item's method, except WalletId, which every method accepts.

#Bank transfer: XTR94500

Use XTR94500 to pay a recipient's linked bank account by ACH, wire or RTP.

FieldRequiredIf you omit itWhere the value comes from
BeneficiaryBankIDIndividual recipient: yes. Business recipient: yes, unless you send WalletIdWith no WalletId either, the item is rejected with Beneficiary bank id or wallet id is required.. For an individual recipient, the item fails during processing with BENEFICIARY_BANKID_REQUIRED: Xtrm never falls back to a default bank. For a business recipient sent with WalletId, Xtrm uses the bank linked to that wallet (see below).The linked bank's 32-character BeneficiaryId, from GetLinkedBankAccounts or the LinkBankBeneficiary response
BeneficiaryBankPaymentMethodNoXtrm uses the bank account's primary rail.The rail: exactly ACH, WIRE or RTP, in any case. Xtrm rejects other names when you submit the batch.
WalletIdNoXtrm credits the recipient's oldest active Standard wallet in the batch currency, as for wallet items.For a business recipient, the wallet whose linked bank you want to pay; see the callout below
  • Link the recipient's bank account first with LinkBankBeneficiary. Linking needs the recipient to be connected to the company in IssuerAccountNumber; an account you create with CreateUser or CreateBeneficiary is connected from the start. The bank item itself needs no connection: Xtrm checks only that the bank is linked to the recipient. An individual recipient can have up to 3 linked banks and a business recipient up to 25; LinkBankBeneficiary refuses further links with You can link maximum N banks.
  • GetLinkedBankAccounts takes the recipient's account number in RecipientUserId. Each linked bank lists its rails in BankDetails.BeneficiaryBankInformation.PaymentMethods, for example ["ACH"]. Treat that list as a guide, not a promise: during processing, Xtrm checks the rail against the bank's own rail and Xtrm's RTP settings. A rail that doesn't fit them fails during processing with INVALID_PAYMENTMETHOD. Some rail problems show up only after the wallet credit, as Invalid payment method, and the payment stays RetainedInWallet once its batch is final.
  • During processing, before any money moves, the bank must be pending or approved and linked to the recipient's account (or to another profile of the same company). Otherwise the item fails with BANKID_INVALID, for example for a mistyped or deleted bank, or another account's bank. A bank that the bank provider doesn't recognize fails with BANK_NOT_FOUND.
  • Don't take bank IDs from GetACHDebitLinkedBankAccounts. That list holds the banks that fund company wallets by bank debit, not the banks you pay.

#Wallets: XTR94502 and XTR94504

Use XTR94502 to pay an individual recipient's Xtrm wallet and XTR94504 to pay a business recipient's wallet. The RecipientId must start with PAT for XTR94502 and with SPN for XTR94504; otherwise Xtrm rejects the item when you submit the batch. A wallet item is Success as soon as the recipient's wallet is credited.

Xtrm recommends paying into the Xtrm wallet: the recipient then decides how to transfer the money out of it.

FieldRequiredIf you omit itWhere the value comes from
WalletIdNoXtrm credits the recipient's oldest active Standard wallet in the batch currency, not the wallet marked as default. If the recipient has no active wallet in that currency, Xtrm creates one named Wallet - <currency code>, for example Wallet - EUR. If its only wallets in that currency are of another type, the item fails with WALLET_AUTO_CREATE_FAILED.The recipient's wallet ID: ID from GetBeneficiaryWallets (business and individual recipients), or WalletID from GetUserWallets (individual recipients)
  • The wallet lists return the ID as a number, for example 67812; send it in WalletId as a number too.
  • WalletId works on every payment method, not only on wallets: on a bank, card or check item it picks the recipient wallet that Xtrm credits before the delivery. It can't be your SourceWalletId; that rejects the item. During processing, it must be an active wallet of the recipient in the batch currency; otherwise the item fails with INVALID_BENEFICIARY_WALLET before any money moves.
  • An individual recipient has one wallet per currency. A business recipient can have more than one wallet in the same currency, so set WalletId when the money must land in a specific one.

#Push to card: XTR94508

Push to card pays a card linked to the recipient. The API calls this method Rapid Transfer. It works only in USD batches: from a source wallet in another currency, the item fails during processing with CURRENCY_MISMATCH.

FieldRequiredIf you omit itWhere the value comes from
CardTokenYesThe item is rejected.The card's CardToken from GetLinkedCards, or from the LinkCard response when you link the card. It's a 15-character string of digits and capital letters A to F, for example EC1B22028C5B488; store and send it as a string, exactly as returned.
  • Link the recipient's card with LinkCard, setting LinkCardType to transfer. Only US cards (CountryCode2 set to US) can be linked, and a transfer card must be enabled for push payments when you link it.
  • During processing, before any money moves, the token must be an active transfer card linked to the recipient's account. Otherwise the item fails with TOKEN_NOT_FOUND, for example for an identity card, a deleted card or another account's card. For a business recipient, the card must be linked to the company's own account.
  • GetLinkedCards takes the recipient's account number in lowercase userid and returns each card's CardToken and LinkCardType.

#Prepaid virtual debit card (XTR94503) and digital gift card (XTR94505)

Both methods deliver a card by email, to individual recipients only. They take the same fields; the SKU comes from a different catalog for each.

FieldRequiredIf you omit itWhere the value comes from
EmailYesThe item is rejected.The email address that receives the card's digital credentials, for example the recipient's own address. It must be a valid address.
SKUYesThe item is rejected.A product sku, at most 20 characters, from GetPrepaidCards for XTR94503, or from GetDigitalGiftCards for XTR94505
  • Both catalogs take a Currency and vary by currency. Request them in the batch currency, which is the currency of your source wallet.
  • Each product has a valueType: FIXED_VALUE or VARIABLE_VALUE. A FIXED_VALUE product is a set denomination: its price is in faceValue, and minValue and maxValue are 0. A VARIABLE_VALUE product takes any amount from minValue to maxValue, and its faceValue is 0. For example, prepaid card PREP9001 is VARIABLE_VALUE from USD 5.00 to USD 1,000.00, and gift card U935268 is FIXED_VALUE at USD 25.00.
  • During processing, before any money moves, a fixed-value card needs an Amount equal to its face value, and a variable-value card an Amount between its minimum and maximum. Otherwise the item fails with INVALID_CARD_AMOUNT.
  • In both catalogs, each product also lists countries, the two-letter codes of the countries that use the card's currency, and a status such as Active.
  • To check one SKU before you submit it, call GetPrepaidCardDetails or GetGiftCardDetails with it. These details calls don't return countries.
  • A prepaid card is the prepaid card for the batch currency. SKU is still required, and Xtrm checks it and the amount against the prepaid cards for that currency, but the current release orders the first prepaid card for the batch currency, at Amount.
  • The card provider always emails the credentials to Email, and no API returns or resends them, so check the address before you submit. The batch-level EmailNotification field doesn't control this. It's a boolean: true sends each recipient a separate payment-received email at their own address when their wallet is credited, for every payment method.

#Physical check: XTR94507

Xtrm mails the check to the address you give. Checks go to US addresses only, and only from a USD source wallet: from a wallet in another currency, Xtrm rejects the item when you submit the batch, with CURRENCY_MISMATCH and the message Bank check allows only USD wallet. Take the name and mailing address from your own records.

FieldRequiredDescription
BeneficiaryCheckNameYesThe recipient's full name to print on the check. Xtrm doesn't compare it with the name on the recipient's account.
BeneficiaryCheckAddress1YesThe primary street address
BeneficiaryCheckAddress2NoThe secondary address line, such as a suite or apartment
BeneficiaryCheckCityYesThe city
BeneficiaryCheckStateYesThe US state the check is mailed to, for example CA, up to 50 characters (the error message for a longer value says 30)
BeneficiaryCheckPostalCodeYesThe ZIP code, up to 30 characters
BeneficiaryCheckCountryCodeISO2YesThe two-letter country code of the mailing address, at most 2 characters: US. A longer value, such as USA, is rejected when you submit the batch. Any other code of up to 2 characters passes submission but fails during processing with COUNTRY_UNSUPPORTED, before any money moves.
BeneficiaryCheckMemoYesThe check memo, up to 150 characters
BeneficiaryCheckReferenceYesYour reference for the check, such as an invoice number, up to 75 characters

Xtrm HTML-encodes these values before it checks their length, so an & counts as 5 characters.

#Example: a wallet, a bank and a card in one batch

This batch pays from source wallet 122181 (USD) to three recipients, one per method family:

  • TXN-METHODS-0001 pays business recipient SPN8888776 into its wallet 122311 (XTR94504).
  • TXN-METHODS-0002 pays business recipient SPN8888777 to a linked bank account by ACH (XTR94500). It sends BeneficiaryBankID without WalletId, so Xtrm pays that bank.
  • TXN-METHODS-0003 pays individual recipient PAT9999888 with a USD prepaid virtual debit card by email (XTR94503), naming the SKU PREP9001.

The batch sets EmailNotification to true, so Xtrm also emails each recipient a payment-received message when their wallet is credited. The prepaid card's credentials go to Destination.Email either way.

CustomerBatchId values are shared across all Xtrm accounts. Replace the sample IDs with your own unique values, for example ones that include your account number or a UUID, before you run this in the sandbox.

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-METHODS-0001",
  "EmailNotification": true,
  "Items": [
    {
      "CustomerTransactionId": "TXN-METHODS-0001",
      "RecipientId": "SPN8888776",
      "Amount": 50,
      "SendMethodId": "XTR94504",
      "Destination": {
        "WalletId": 122311
      },
      "Description": "TXN-METHODS-0001 Q3 Channel Partner Marketing Bonus"
    },
    {
      "CustomerTransactionId": "TXN-METHODS-0002",
      "RecipientId": "SPN8888777",
      "Amount": 100,
      "SendMethodId": "XTR94500",
      "Destination": {
        "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
        "BeneficiaryBankPaymentMethod": "ACH"
      },
      "Description": "TXN-METHODS-0002 Q3 Executive Sales Performance Incentive"
    },
    {
      "CustomerTransactionId": "TXN-METHODS-0003",
      "RecipientId": "PAT9999888",
      "Amount": 50,
      "SendMethodId": "XTR94503",
      "Destination": {
        "Email": "[email protected]",
        "SKU": "PREP9001"
      },
      "Description": "TXN-METHODS-0003 Q3 Top Performer Contractor Reward"
    }
  ]
}'

Xtrm accepts the batch with 202 and pays each item in the background. For the response, how to follow each payment to its final status and how to retry a failed one, see Create a batch payment.

Payments in the sandbox

The sandbox works the same as production. For cards, use the standard test numbers: Visa 4111111111111111 or Mastercard 5555555555554444, with a future expiry date and a three-digit CVV. The sandbox has no test bank accounts: link a real bank's routing number or SWIFT-BIC with a made-up account number in the right format, never a real one; see Test bank accounts. There are no sandbox-only SKUs either: use the SKUs the catalog calls return. See How payments finish in the sandbox for the failures you can trigger on purpose.

#Currency and country rules

  • One currency per batch. The source wallet (SourceWalletId) sets the currency of the whole batch, and every accepted item is credited to the recipient's wallet in it. To pay in another currency, submit a separate batch from a wallet in that currency.
  • Banks. A linked bank account can be in a different currency from the batch. When it is, the amount is converted when it's transferred to the bank.
  • Wallets. Without WalletId, Xtrm credits the recipient's oldest active Standard wallet in the batch currency, and creates one only if the recipient has no active wallet in that currency (see Wallets).
  • Push to card. USD batches only. In another currency, the item fails during processing with CURRENCY_MISMATCH.
  • Prepaid and gift cards. Xtrm checks the card against the batch currency while it processes the item, not when you submit the batch. A gift card (XTR94505) in another currency fails with CURRENCY_MISMATCH. A prepaid card (XTR94503) fails with CURRENCY_INVALID when Xtrm offers no prepaid card in the batch currency, or with SKU_NOT_FOUND when the SKU isn't one of them. In the catalogs, each product's countries lists the countries that use its currency.
  • Checks. Xtrm mails checks to US addresses only, from USD source wallets only.

#When Xtrm checks a destination

Xtrm checks a destination in two stages:

  1. When you submit the batch, Xtrm runs a lightweight check of each item's fields and formats. An item that is missing a required Destination field is rejected, and its entry in Rejected names the field, for example Items[0].Destination.SKU. Items that pass are still accepted. See Errors when you submit a batch payment.
  2. While it processes the item, Xtrm first checks the recipient, the wallet, the destination and the method, before any money moves; a problem ends the item Failed. Xtrm then debits your source wallet and credits the recipient's wallet, which can also end the item Failed, for example with INSUFFICIENT_BALANCE. For a bank, card or check item, Xtrm then delivers the payment, and the item shows RetainedInWallet while it does; if the delivery fails, the item is still RetainedInWallet when the batch status becomes final. Each outcome that a stage records is an attempt with an ErrorCode, which you see in the item's Attempts when you request it with history=true.

These are the processing error codes for each method:

MethodItem ends FailedItem stays RetainedInWallet
AnyRECIPIENT_NOT_FOUND, SENDMETHODID_NOT_FOUND, INVALID_BENEFICIARY_WALLET, INTERNAL_SERVICE_ERROR, SEND_LIMIT_EXCEEDED, INSUFFICIENT_BALANCE, WALLET_AUTO_CREATE_FAILED, SEND_FAILED, TEMPORARY_ERRORINSUFFICIENT_FUNDS_RUNTIME, PREVIOUS_TRANSFER_IN_PROGRESS (every method except wallets)
Bank transfer (XTR94500)BENEFICIARY_BANKID_REQUIRED, DEFAULT_BANK_NOT_FOUND, BANKID_INVALID, BANK_NOT_FOUND, INVALID_PAYMENTMETHODRETAINED_IN_WALLET, TEMPORARY_ERROR, Invalid payment method
Wallets (XTR94502, XTR94504)No other codesNone: a wallet item is Success once the wallet is credited
Push to card (XTR94508)CURRENCY_MISMATCH, TOKEN_NOT_FOUNDTEMPORARY_ERROR
Digital gift card (XTR94505)SKU_NOT_FOUND, CURRENCY_MISMATCH, INVALID_CARD_AMOUNTSKU_NOT_FOUND, INVALID_CARD_AMOUNT, TEMPORARY_ERROR
Prepaid virtual debit card (XTR94503)CURRENCY_INVALID, SKU_NOT_FOUND, INVALID_CARD_AMOUNTSKU_NOT_FOUND, TEMPORARY_ERROR
Physical check (XTR94507)COUNTRY_UNSUPPORTEDTEMPORARY_ERROR

For what each code means and what to do, see Error codes on attempts. To fix a Failed item, for example with a corrected BeneficiaryBankID, CardToken or SKU, see Resubmit failed payments. An item that stays RetainedInWallet once its batch is final can't be retried; for how the money then reaches the recipient's bank or card, see When a payment stays RetainedInWallet.

#Choose a payment method list

Three endpoints list payment methods. Take each batch item's SendMethodId from GetPaymentMethods: a batch accepts exactly its seven IDs, in capitals, and rejects any other value when you submit it. The other two aren't batch send methods: they list the ways an individual recipient or a business recipient can move its own money out of its Xtrm wallet.

EndpointReturnsID and name fieldsUse it to
GetPaymentMethodsAll seven payment methods on this pagePaymentMethodId, PaymentMethodNameChoose the SendMethodId for each item. It is the only list with XTR94504 (AnyPay Company) and XTR94507 (Bank Check).
GetUserPaymentMethodsThe ways an individual recipient can move their own money: XTR94500, XTR94502, XTR94503, XTR94505 and XTR94508, plus XTR94506 (Reward Link), which a batch rejects. It leaves out XTR94504 and XTR94507.UserPaymentMethodId, UserPaymentMethodNameSee the ways an individual recipient can move their own money. Don't build a batch method picker from it. UserWithdrawFund accepts four of them in PaymentMethodID, sent in capitals: XTR94500, XTR94503, XTR94505 and XTR94508. XTR94502 is only for paying the recipient's Xtrm wallet in a batch. XTR94506 is a reward card that recipients choose in the Xtrm web app. Neither UserWithdrawFund nor BatchTransfer accepts it: a batch item with it is rejected with INVALID_FIELD when you submit the batch.
GetBeneficiaryCompanyPaymentMethodsXTR94500 (Bank) and XTR94508 (Rapid Transfer)BeneficiaryCompanyPaymentMethodId, BeneficiaryCompanyPaymentMethodNameSee how a business recipient can transfer money out of its wallet, with BeneficiaryCompanyWithdrawFund.

All three take an empty JSON object {} as the body, with no account identifier, and return the same list for every account. Send them as POST requests: a GET returns HTTP 404. Each response nests its list under its own wrapper names, so read the path from that endpoint's example.

#Next steps