Core concepts

Accounts, wallets & IDs

Every batch payment moves money from one of your company's wallets to the people and businesses you pay. A BatchTransfer request names your company and the wallet that funds the batch. Each item in it names a recipient, a send method and a destination, and carries your own ID so you can follow it. This page explains the objects behind those fields and lists the identifiers you work with: what each looks like, which call returns it and where you use it.

#The object model

Xtrm has two kinds of account, told apart by the prefix of the account number: company accounts start with SPN and personal accounts start with PAT. A batch payment involves three roles:

RoleAccountWhat it isField in a batchHow you get one
Your companySPNThe company account that owns your API credentials and the wallets you pay from.IssuerAccountNumberYou sign up for it. See Sandbox & environments.
Individual recipientPATA person you pay.RecipientIdCreateUser
Business recipientSPNA business you pay.RecipientIdCreateBeneficiary

We call anyone you pay a recipient. Older operation and field names in the API use other words: User means an individual recipient, and Beneficiary means a business recipient or, in some names, any recipient. So CreateUser creates an individual recipient, CreateBeneficiary creates a business recipient, and LinkBankBeneficiary links a bank account to either. Your company appears as Issuer or Remitter, as in IssuerAccountNumber and GetUserWalletTransactionsByRemitter.

Every account has Xtrm wallets, and each wallet holds one currency. Your company pays from its wallets, and each payment lands in a wallet of the recipient first. Xtrm is a payment platform, not a bank.

Individual and business recipients can also have linked bank accounts and cards. Each item in a batch delivers its payment to one of the recipient's wallets, bank accounts or cards, or as a digital gift card, a prepaid virtual debit card or a mailed check; the item's send method decides which. Recipients are Xtrm accounts in their own right: the tree shows what a batch refers to, not who owns what.

Object model
Your company (SPN…, sent as IssuerAccountNumber)
├── Wallets (WalletID; the one that funds a batch is its SourceWalletId)
└── Batch payments (CustomerBatchId)
    └── Items: one per payment (CustomerTransactionId)
        ├── RecipientId    the account you pay: PAT… or SPN…
        ├── SendMethodId   how the payment is delivered (XTR945xx)
        └── Destination    where it is delivered, depending on SendMethodId
            ├── WalletId            a wallet of the recipient
            ├── BeneficiaryBankID   a bank account linked to the recipient
            ├── CardToken           a card linked to the recipient
            ├── SKU and Email       a gift card or prepaid card product
            └── BeneficiaryCheck…   the recipient name and address for a mailed check

Recipient: individual (PAT…) or business (SPN…)
├── Wallets (WalletID; one per currency for PAT, more than one allowed for SPN)
├── Linked bank accounts (BeneficiaryId; up to 3 for PAT, more for SPN)
└── Linked cards (CardToken)

Batch payments are wallet-first: Xtrm credits each payment to a wallet of the recipient before it delivers the money on to an external destination such as a bank account or card. If the recipient has no wallet in the batch currency, Xtrm creates one named Wallet - <currency code>. While Xtrm delivers a bank, card, check, gift card or prepaid payment on from that wallet, the item shows RetainedInWallet, usually only briefly, and it moves on to Success once the delivery goes through. Don't act on that status while the batch is still Processing. An item that is still RetainedInWallet once the batch status is final didn't reach its destination, and the money stays in the recipient's Xtrm wallet. Treat it like a wallet payment. You can't retry it as a batch payment, and the fee isn't refunded. When a payment stays RetainedInWallet explains how the money moves on from there. See How batch payments work.

The prefix tells you the account type, not the role

Your company and the business recipients you pay both have SPN account numbers. The field tells you the role: IssuerAccountNumber is always your company (or, if you use pseudo credentials, the client company you call on behalf of), while RecipientId names the account an item in a batch pays. Other calls name the account they act on with fields such as UserID or BeneficiaryAccountNumber.

#Identifiers in a batch

These are the IDs a batch carries or returns, in the order you meet them.

IdentifierFormat and exampleWhich call returns itWhere you use it
Your company account numberStarts with SPN, e.g. SPN1111222None: it's your company's SPN, tied to the API credentials you get under Settings → Integrations → Get Credentials (see Sandbox & environments)IssuerAccountNumber in BatchTransfer, and on nearly every other request
Source wallet IDNumber, e.g. 122181GetCompanyWallets and CreateCompanyWallet (WalletID)SourceWalletId in BatchTransfer, as an integer (a numeric string such as "122181" works too). The wallet's currency is the batch currency.
Batch IDYour own string, e.g. BATCH-IDS-0001. Required: Xtrm never generates one.You set it in BatchTransfer. Xtrm echoes it in the 202 response (BatchTransferResponse.CustomerBatchId), in the status calls and in webhooks.CustomerBatchId in BatchTransfer, and in the path of both status calls
Item IDYour own string, e.g. TXN-IDS-0001. Required: Xtrm never generates one.You set it on each item in BatchTransfer. Xtrm echoes it in Accepted or Rejected in the 202 response, in each item of the status calls and in item webhooks.Items[].CustomerTransactionId in BatchTransfer, and in the path of the item status call
Recipient account numberPAT for an individual recipient (PAT9999888), SPN for a business recipient (SPN8888777)Individual recipients: CreateUser (UserID), CheckUserExist and GetPersonalBeneficiaries (AccountNo). Business recipients: CreateBeneficiary and GetBeneficiaries (BeneficiaryID), CheckBeneficiaryExist (AccountNumber)Items[].RecipientId
Send method IDXTR945xx, e.g. XTR94500GetPaymentMethods (PaymentMethodId)Items[].SendMethodId
Destination wallet IDNumber, e.g. 67812 (an individual recipient's wallet) or 122311 (a business recipient's)GetUserWallets (WalletID) for an individual recipient, GetBeneficiaryWallets (ID) for a business recipientDestination.WalletId on any item, as an integer (a numeric string such as "67812" works too). Optional: without it, Xtrm credits the recipient's oldest active Standard wallet in the batch currency, or creates one. See Recipient wallets.
Linked bank ID32-character hex string, e.g. 41953ec32f3e4765a35a902c82bdd995LinkBankBeneficiary and GetLinkedBankAccounts (BeneficiaryId)Destination.BeneficiaryBankID on bank transfer items (XTR94500). Required for an individual recipient. A business recipient sent with a WalletId can be paid to the bank linked to that wallet instead; see Linked bank accounts.
Card tokenA 15-character string of digits and capital letters A to F, e.g. EC1B22028C5B488, a transfer card in the GetLinkedCards example. Store it as a string, exactly as returned.LinkCard and GetLinkedCards (CardToken)Destination.CardToken on Rapid Transfer items (XTR94508). Required, and it must be a transfer card linked to the recipient.
Card product SKUString, e.g. U935268 (a digital gift card) or PREP9001 (a prepaid card)GetPrepaidCards and GetDigitalGiftCards (sku in items)Destination.SKU, together with Destination.Email, on prepaid virtual debit card (XTR94503) and digital gift card (XTR94505) items, which pay individual recipients only. Required.
Attempt numberInteger: 1 for the first submission, one higher for each accepted resubmissionBoth status calls with history=true, in each item's Attempts (AttemptNo)Your records. When you resubmit a failed item, its next attempt gets the next AttemptNo, and the earlier attempts are kept.

Copy field names exactly

The same kind of ID goes by different field names from call to call, sometimes differing only in case. A wallet ID is WalletID in GetCompanyWallets, ID in GetBeneficiaryWallets, and SourceWalletId or Destination.WalletId in a batch. Copy each field name from the endpoint's reference entry.

#A batch payment, field by field

This batch pays four items from wallet 122181, each with a different send method, so it shows every kind of destination ID. The recipients already exist, and each destination belongs to its recipient; the table after the code says where each ID comes from. Looking up a recipient's bank and card IDs needs a connection to the recipient, which your company has with every recipient it creates. 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-IDS-0001",
  "Items": [
    {
      "CustomerTransactionId": "TXN-IDS-0001",
      "RecipientId": "SPN8888777",
      "Amount": 100,
      "SendMethodId": "XTR94500",
      "Destination": {
        "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
        "BeneficiaryBankPaymentMethod": "ACH"
      }
    },
    {
      "CustomerTransactionId": "TXN-IDS-0002",
      "RecipientId": "SPN8888776",
      "Amount": 50,
      "SendMethodId": "XTR94504",
      "Destination": {
        "WalletId": 122311
      }
    },
    {
      "CustomerTransactionId": "TXN-IDS-0003",
      "RecipientId": "PAT9999888",
      "Amount": 50,
      "SendMethodId": "XTR94503",
      "Destination": {
        "Email": "[email protected]",
        "SKU": "PREP9001"
      }
    },
    {
      "CustomerTransactionId": "TXN-IDS-0004",
      "RecipientId": "SPN9999888",
      "Amount": 50,
      "SendMethodId": "XTR94508",
      "Destination": {
        "CardToken": "EC1B22028C5B488"
      }
    }
  ]
}'
ItemRecipientIdSendMethodIdDestination IDWhere you get it
TXN-IDS-0001SPN8888777, a business recipientXTR94500, bank transferBeneficiaryBankIDBeneficiaryId from GetLinkedBankAccounts
TXN-IDS-0002SPN8888776, a business recipientXTR94504, company walletWalletIdID from GetBeneficiaryWallets
TXN-IDS-0003PAT9999888, an individual recipientXTR94503, prepaid virtual debit cardSKU, plus the Email that receives the cardsku from GetPrepaidCards
TXN-IDS-0004SPN9999888, a business recipientXTR94508, Rapid TransferCardToken of a transfer cardCardToken from GetLinkedCards

XTR94504 (AnyPay Company) pays a business recipient's wallet; to pay an individual recipient's wallet, use XTR94502 (AnyPay Individual). IssuerAccountNumber is your company and SourceWalletId is one of its wallets. For what every send method needs, see Payment methods & destinations.

Xtrm checks the fields of each item when you submit the batch and answers 202 Accepted when at least one item passes. The response echoes your CustomerBatchId and lists each accepted item by its CustomerTransactionId, with its recipient, send method, amount and currency, and each rejected item in Rejected, also by CustomerTransactionId. The amount comes back as a number with the decimals you sent, so 100 comes back as 100.0. Errors covers the rejections. This excerpt shows the first item accepted:

Response (excerpt)
{
  "BatchTransferResponse": {
    "CustomerBatchId": "BATCH-IDS-0001",
    "Status": "Accepted",
    "Accepted": [
      {
        "CustomerTransactionId": "TXN-IDS-0001",
        "Amount": 100.0,
        "Currency": "USD",
        "SendMethodId": "XTR94500",
        "RecipientId": "SPN8888777"
      }
    ],
    "Rejected": []
  }
}

202 Accepted doesn't mean the payments went through. Xtrm checks that each recipient, recipient wallet, bank account, card token and SKU exists, and that your balance covers the item, while it processes the item. Follow each item by its IDs with the status calls; see Batch and item IDs and How batch payments work.

#Your company and its wallets

Your company is the SPN account tied to the API credentials you get from Settings → Integrations → Get Credentials in the Xtrm dashboard. Nearly every request carries its account number as IssuerAccountNumber; in a batch, it is the account that owns the source funds. If you're a managing platform using a client company's pseudo credentials, which require manager services, IssuerAccountNumber is instead that client company's SPN, and "your company" on these pages means the client company. See How managing platforms work.

A few requests don't take IssuerAccountNumber, among them the token request, the lists that take an empty {} body and the two batch status calls; see Requests & responses. The status calls identify the batch by your IDs in the path, and your access token is scoped to your company account. You can look up only the batches that belong to a company your token can act for; any other batch returns 401.

#Choose the source wallet

A batch pays from one of your company's wallets. List them, with their IDs, currencies and balances, with GetCompanyWallets:

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
      }
    }
  }
}

Send the WalletID of the wallet you pay from as SourceWalletId, as the same JSON number: 122181 in the batch above. It must be an active wallet of your company itself: a wallet that another company shares with you fails the whole request with 403. The wallet determines the currency of the batch: every item pays in that currency, and the status calls report it in Currency. A company can hold more than one wallet in the same currency, so pick the wallet by its WalletID. To add a wallet, see CreateCompanyWallet.

We recommend checking that WalletBalance covers the batch and its fees before you submit it. The balance is checked as each item is processed, for the item's Amount plus its fee, and an item the wallet can't cover fails with INSUFFICIENT_BALANCE.

In the sandbox, Xtrm credits test funds to your sandbox wallets after approving your IP addresses. See Test funds.

#Batch and item IDs

CustomerBatchId identifies a batch payment and CustomerTransactionId identifies one payment in it. They are your tracking IDs: you choose them, and you use them to look up status and to reconcile with your own records. Xtrm echoes both, as it stored them, in the submit responses, the status responses and the item webhook events (Batch.Item.…); the batch-level webhook events carry only CustomerBatchId.

Both are required, and Xtrm never generates either one. Each is a string of 1 to 128 letters, digits and . _ - : @. CustomerBatchId values are shared across all Xtrm accounts, so make yours unique, for example by including your account number or a UUID. A CustomerTransactionId only has to be unique within its batch. Retries & idempotency has every rule for these IDs, what Xtrm does when you send one again, and how to retry safely.

The batch payment endpoints return no transaction ID of Xtrm's own, so store both IDs with your payment records. Create them before the first send: if a response never reaches you, you can then resend the identical request. See A safe retry pattern.

#Look up a payment by its IDs

Pass your IDs in the path of the status calls. GET /Fund/BatchTransfer/{CustomerBatchId} returns the batch and a page of its items; GET /Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId} returns one item. Set history to true to include every attempt:

curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-IDS-0001/Items/TXN-IDS-0001?history=true" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"

The response identifies the item by its CustomerBatchId and CustomerTransactionId, repeats its RecipientId, SendMethodId, Amount and Currency, and lists each attempt in Attempts with its AttemptNo, Result and ErrorCode. Batch and payment statuses explains each status, the DeliveryType and the error codes on attempts. If you use webhooks, the events carry the same IDs; see Webhooks.

#Recipients

Each item's RecipientId is the account number of the person or business you pay: an individual recipient (PAT) or a business recipient (SPN). It must be an existing Xtrm account: a batch never creates an account or a connection. Xtrm checks the account while it processes the item, not when it accepts the batch, and a RecipientId that doesn't match an account in status active (A), email not verified (NC) or pending approval (EV) fails the item with RECIPIENT_NOT_FOUND.

Create recipients before the batch

Look up or create each recipient before you add it to a batch: create a person with CreateUser or a company with CreateBeneficiary, then send the account number it returns as RecipientId. You can pay the new account right away.

In the Xtrm web app, you can create a person's account as you pay them, which also connects it to your company, but a company needs more details, so you create it first.

Once Xtrm credits a payment to a recipient's wallet, the recipient appears in your recipient list, which GetPersonalBeneficiaries and GetBeneficiaries page through. The list also holds every recipient you create or connect to.

#Individual recipients

An individual recipient is a person's Xtrm account. Its account number starts with PAT, for example PAT9999888. The recipient can use the account to make and receive payments, and has Xtrm wallets, one per currency.

  • CheckUserExist looks up one person by Email and returns the account number as AccountNo. We recommend calling it before you create an account.
  • GetPersonalBeneficiaries pages through the individual recipients in your recipient list, each with its AccountNo.
  • CreateUser creates the account with a full profile and returns the account number as UserID. It also creates a wallet in the currency of the country in Address.CountryISO2.

Here is an example CreateUser response:

Response
{
  "CreateUserResponse": {
    "CreateUserResult": {
      "UserID": "PAT9999888",
      "AccountIdentityLevel": "Standard",
      "OperationStatus": {
        "Success": true,
        "Errors": null
      }
    }
  }
}

Store the UserID. It is the value you send as RecipientId in a batch item, and as UserID in the personal wallet calls such as GetUserWallets. For the full request, see Pay individual recipients.

AccountIdentityLevel is the compliance verification level of the account's identity, on one scale for people and companies. It rises as the profile is completed:

LevelWhat the profile holds
DraftThe lowest level: the account exists with only the bare minimum of details.
BasicFirst and last name and email address, plus the company name for a company.
StandardEverything in Basic plus the full address: street, city, state, country and postal code. A person's profile also needs a tax ID and date of birth.
AdvancedA complete profile: everything in Standard, the tax ID for a company, and the identity documents uploaded in the Xtrm web app. For a company, that's a government-issued photo ID of its administrator and, for a private company, a company tax document that shows its tax ID (a W-9 for a US company); a public company needs only the photo ID. No API call uploads documents.

Xtrm approves accounts you create through the API straight away, at whatever level their profile has reached. You can read any account's level, connected or not, with CheckUserExist or CheckBeneficiaryExist. A company needs a 100% complete profile, which the API reports as Advanced, and an approved advanced profile before Xtrm unlocks funding for its account; see Complete the advanced profile. Getting a company there isn't API-only, because no API call uploads documents. The company uploads its documents in the Xtrm web app, under Identity > Identity Documents. For a client company, your platform can upload them for it instead, as a manager service: choose Identity Documents in the company's Connected Manager Services menu. Then the company, or your platform for it, submits the advanced profile (the Advanced Services application), in the web app or with CompanyAdvancedProfile.

#Business recipients

A business recipient is the Xtrm account of a business you pay. Like your company, its account number starts with SPN, for example SPN9999888.

  • CheckBeneficiaryExist searches every company account on Xtrm and returns each match's account number as AccountNumber. When you know the company's email domain, search with CompanyEmailDomain on its own: send the domain (acmecorp.com) or any address at it ([email protected]). A company's own domain usually returns just that company, and a shared domain can return several. A CompanyName search returns every company whose name contains the text, and if you send both, you get the companies that match either one. Check Email and Name before you use an AccountNumber. Companies often already have an Xtrm account, so search before you create one.
  • GetBeneficiaries pages through the business recipients in your recipient list, each with its BeneficiaryID.
  • CreateBeneficiary creates the company and its master administrator, and returns the account number as BeneficiaryID.

Here is an example CreateBeneficiary response, with placeholder values for the credentials:

Response
{
  "CreateBeneficiaryResponse": {
    "CreateBeneficiaryResult": {
      "BeneficiaryID": "SPN9999888",
      "AccountIdentityLevel": "Basic",
      "ClientID": "YOUR_CLIENT_ID",
      "SecretKey": "YOUR_CLIENT_SECRET",
      "OperationStatus": {
        "Success": true,
        "Errors": []
      }
    }
  }
}

BeneficiaryID is the account number you send as RecipientId in a batch item, and as BeneficiaryAccountNumber in calls such as GetBeneficiaryWallets. ClientID and SecretKey are your pseudo credentials for the new company, not the company's own credentials: with them, your company requests an access token that acts as the new company, with its SPN as IssuerAccountNumber. If you call CreateBeneficiary with a client company's pseudo credentials, the pair is issued to that client company. Pseudo credentials require manager services, which Xtrm turns on for your company. Keep them on your server, as you keep your own, and out of logs. See Pseudo credentials. For the full request, see Pay business recipients.

#Connections

You don't need a connection to pay an account in a batch, and paying it doesn't connect it. A connection is what lets your company manage more about a recipient: for example, link a bank account with LinkBankBeneficiary, see an individual recipient's balance with GetUserWalletBalance or update a profile with UpdateUser.

Your company is connected to every recipient it creates with CreateUser or CreateBeneficiary. In the API, you connect an account that already exists with a one-time password: its holder gives you the code that GetOTPAuthorizedVendor sends them, and you confirm it with ValidateOTPAuthorizeVendor. See Connect existing accounts. Connections and manager services lists what your company can do with and without a connection.

#Destinations

An item's SendMethodId picks how the payment is delivered, and its Destination object says where. Wallet, bank and card IDs refer to the item's recipient, so look them up with the same account number you send as RecipientId.

Looking up or linking a recipient's bank accounts and cards needs a connection to the recipient, which you have with every recipient you create. Listing an individual recipient's wallets with GetUserWallets doesn't, and neither does a wallet item that leaves Destination empty.

Send methodSendMethodIdDestination IDWhere you get it
Bank transferXTR94500BeneficiaryBankID (required for an individual recipient; see Linked bank accounts)BeneficiaryId from GetLinkedBankAccounts
Wallet of an individual recipientXTR94502WalletId (optional)WalletID from GetUserWallets
Wallet of a business recipientXTR94504WalletId (optional)ID from GetBeneficiaryWallets
Prepaid virtual debit card (individual recipients only)XTR94503SKU, with Email (both required)sku from GetPrepaidCards
Digital gift card (individual recipients only)XTR94505SKU, with Email (both required)sku from GetDigitalGiftCards
Rapid Transfer (push to card)XTR94508CardToken of a transfer card (required)CardToken from GetLinkedCards
Check (US only)XTR94507None: the recipient's name and mailing address go in the BeneficiaryCheck… fieldsNot needed

Every send method also accepts Destination.WalletId, which picks the recipient's wallet that Xtrm credits first; see Recipient wallets. GetPaymentMethods lists the send method IDs with their names, for example XTR94500 (Bank). Payment methods & destinations has every field each method takes and the checks Xtrm runs on it.

#Recipient wallets

On any item, Destination.WalletId picks the recipient's wallet that Xtrm credits. Send the ID as a JSON number: WalletID from GetUserWallets for an individual recipient, or ID from GetBeneficiaryWallets for a business recipient. Leave it out and Xtrm credits the recipient's wallet in the batch currency, creating one if the recipient doesn't have one. Wallets: XTR94502 and XTR94504 says which wallet Xtrm picks and when a wallet ID fails the item.

#Linked bank accounts

LinkBankBeneficiary links a bank account that receives payments to a recipient's account (UserID, SPN or PAT), and GetLinkedBankAccounts lists a recipient's linked bank accounts (RecipientUserId). To link a bank for a recipient, the recipient must be connected to your company; see Connections. Both calls identify each linked bank profile with a BeneficiaryId, such as 907599f594b044d08cf81a2afb0a7967. A personal account can have up to 3 linked banks, and a company account more, up to a limit Xtrm sets. A link over the limit fails with 400 and the message You can link maximum N banks.

To pay a linked bank account, send its BeneficiaryId as Destination.BeneficiaryBankID on a bank transfer (XTR94500) item. The bank must be linked to the recipient you pay. A business recipient's wallet can also have a bank of its own, which a bank transfer item that names that wallet in WalletId may pay instead: Bank transfer: XTR94500 explains which bank Xtrm pays and when you can leave BeneficiaryBankID out.

To delete a linked bank account, send its BeneficiaryId as BeneficiaryBankID in DeleteBankBeneficiary. Banks linked for bank debit with LinkACHDebitBankBeneficiary are for funding your company wallets; see Fund your wallet.

BeneficiaryId is not an account number

In the bank calls, BeneficiaryId identifies a linked bank profile, such as 907599f594b044d08cf81a2afb0a7967. Don't confuse it with BeneficiaryID in CreateBeneficiary, GetBeneficiaries and UpdateBeneficiary, which is a business recipient's SPN account number.

#Linked cards

LinkCard links a card to a recipient's account (UserID) and returns a CardToken; GetLinkedCards lists a recipient's cards with their tokens (userid). Both need a connection to the recipient. To pay a linked card, send its token as Destination.CardToken on a Rapid Transfer (XTR94508) item, the push-to-card method; Push to card: XTR94508 lists what the item needs. DeleteCard and UserWithdrawFund take the token as CardToken too.

LinkCard takes a LinkCardType: identity or transfer. transfer cards are prepaid debit cards that receive funds, and only they can receive a Rapid Transfer item. Only US cards can be linked, and a transfer card must be able to receive push payments. In the GetLinkedCards example, EC1B22028C5B488 is a transfer card and A3F9C27E1B8D054 is an identity card.

#Gift card and prepaid card SKUs

Prepaid virtual debit card (XTR94503) and digital gift card (XTR94505) items name a product by its SKU and send the card's digital credentials to the address in Email. GetPrepaidCards and GetDigitalGiftCards take a Currency and list the products, each with its sku; the catalogs vary by currency, so pick the SKU from the catalog for your batch currency. In the examples on these pages, U935268 is a digital gift card and PREP9001 is a prepaid card. Payment methods & destinations lists what each card item needs, and Rewards with gift & prepaid cards walks through paying with them.

#Wallets

A wallet is one account's balance in one currency. Xtrm generates its WalletID. After you create a wallet you can change only its name: the WalletID and currency are fixed.

AccountWallets per currencyCreateListRename
Your companyMore than one allowedCreateCompanyWalletGetCompanyWalletsUpdateCompanyWallet
Business recipientMore than one allowedCreateBeneficiaryCompanyWalletGetBeneficiaryWalletsUpdateBeneficiaryCompanyWallet
Individual recipientOneCreateUserWallet (CreateUser also creates one with the account)GetUserWallets; GetUserWalletBalance for a balanceUpdateUserWallet
  • Batch payments create wallets. If a recipient has no wallet in the batch currency, Xtrm creates one, so you don't have to create recipient wallets before you pay.
  • Personal wallets are one per currency, so some calls identify a personal wallet by account and currency instead of WalletID: GetUserWalletBalance (UserId and Currency), GetUserWalletTransactions (UserID and WalletCurrency) and UserWithdrawFund (UserID and Currency).
  • Create Standard wallets. When you create a wallet for your company or a business recipient, set WalletType to Standard. The field is required, and Standard is the only type to use when you create a wallet through the API.
  • Some calls need a connection. Creating a recipient's wallets, renaming an individual recipient's wallet and reading its balance work only for a recipient connected to your company. Listing an individual recipient's wallets with GetUserWallets doesn't need a connection, and you can rename a business recipient's wallet once the business is in your recipient list. Connections and manager services lists every call.
  • Send the ID, not the name. Where a funding, exchange or recipient transfer request names a wallet, send its numeric WalletID, for example "122181". A funding or recipient transfer request with a wallet name in place of the ID is rejected, and no money moves.

#Three wallet lists, three shapes

The three list calls describe the same things with different field names:

GetCompanyWalletsGetBeneficiaryWalletsGetUserWallets
Whose walletsYour company (IssuerAccountNumber)A recipient (BeneficiaryAccountNumber)An individual recipient (UserID)
Wallet IDWalletIDIDWalletID
NameWalletNameNameWalletName
CurrencyWalletCurrencyCurrencyWalletCurrency
BalanceWalletBalanceBalanceNot returned; use GetUserWalletBalance
TypeWalletTypeTypeNot returned
Bank link flagsIsBankLinked, AllowWalletLinkedBankOverrideIsBankLinked, AllowWalletLinkedBankOverrideNot returned
Entity IDEntityIDEntityIDNot returned

#Other identifiers

IdentifierFormat and exampleWhich call returns itWhere you use it
Wallet transaction IDNumber in lists (888601), string in requests ("888601")GetCompanyWalletTransactions and GetUserWalletTransactions (TransactionID)TransactionID in GetCompanyWalletTransactionDetails and GetUserWalletTransactionDetails
Program IDString from CreateProgram ("1026"), number from GetPrograms (1026)CreateProgram (ProgramID), GetPrograms (ProgramId)ProgramID in FundWalletUsingBankTransfer and UpdateProgram
Program category and type IDsNumbers in responses (2, 4), strings in requests ("2")ProgramCategory (CategoryID), ProgramType (SubCategoryID)CategoryID in ProgramType; TransactionCategoryID and TransactionSubCategoryID in CreateProgram and UpdateProgram
Entity IDNumber, e.g. 27044GetEntities (EntityId)EntityID in wallet creation (CreateCompanyWallet, CreateBeneficiaryCompanyWallet) and in bank and card linking; see Entity IDs

#Wallet transaction IDs

Your batch payments are tracked by your own CustomerBatchId and CustomerTransactionId. Wallet history uses IDs that Xtrm generates: GetCompanyWalletTransactions, GetUserWalletTransactions and GetUserWalletTransactionsByRemitter return a TransactionID (a number) for each credit and debit in a wallet. To see the full breakdown of a wallet transaction, pass its TransactionID as a string to GetCompanyWalletTransactionDetails or GetUserWalletTransactionDetails; GetUserWalletTransactionDetails also needs the UserID.

Each item in a batch is debited from your source wallet on its own, for its Amount plus its fee, when Xtrm processes it. Wallet transactions carry Xtrm's IDs rather than yours: no wallet call returns or searches your CustomerBatchId or CustomerTransactionId, so keep both of your IDs with every payment record.

What a wallet transaction does carry is the item's Description. Xtrm copies it to the debit in your source wallet and to the credit in the recipient's wallet, so it's the key that ties a payment to its money. We recommend starting every item's Description with its CustomerTransactionId, for example "TXN-2026-9912A Q3 Contractor Bonus". You can then find the payment's debit with GetCompanyWalletTransactions: send Filters with the ID in SearchParam, "TransactionType": "Sent" and a DateRange from the day before the payment was processed to the day after. The debit's TransactionID opens its details. The recipient sees the Description too, so use text you're happy to share. Track & reconcile payments shows how to match wallet transactions to your payments.

#Programs

Programs are your company's payment programs or projects, such as remittance, payment or budget programs. CreateProgram returns the new program's ID as a string in ProgramID ("1026"), and GetPrograms lists programs with the ID as a number in ProgramId (1026). To associate a funding transaction with a program, send the ID as ProgramID in FundWalletUsingBankTransfer. UpdateProgram requires ProgramID to identify the program you update. A batch payment request has no program field.

CreateProgram and UpdateProgram also take a category and a type. ProgramCategory lists the categories, each with a CategoryID, and ProgramType lists the types (subcategories) in a category, each with a SubCategoryID. Send them as TransactionCategoryID and TransactionSubCategoryID.

#Entity IDs

A company account can be divided into entities, for example a headquarters, a subsidiary and a regional branch. One of them is the company's prime entity, its default. GetEntities lists the active entities of the account in UserID, prime entity first, each with its EntityId and an IsPrimeEntity flag. It works for your own company and for a company connected to yours.

EntityID is always one of these Xtrm entity IDs, never a value from your own systems, and it's optional in every request that takes it:

  • Wallet creation. CreateCompanyWallet creates the wallet in that entity of your company, and CreateBeneficiaryCompanyWallet in that entity of the business recipient. Leave EntityID out, or send 0, and the wallet goes into the company's prime entity. An ID that isn't one of that company's active entities fails with 400 and <id> - Invalid Entity ID. CreateUserWallet takes no EntityID.
  • Bank and card linking. In LinkBankBeneficiary, LinkACHDebitBankBeneficiary and LinkCard, EntityID maps the bank or card profile to one of the entities of the company in UserID. LinkBankBeneficiary and LinkCard ignore it for a personal account. The LinkCard example links a card for SPN9999888 with EntityID 27044, that company's prime entity in the GetEntities example.

Send a whole number, or leave the field out. An empty string (""), a negative number or any other value that isn't a whole number fails with 400 and EntityID must be an integer.

The wallet lists return the entity each wallet belongs to as EntityID: GetCompanyWallets for your company's wallets and GetBeneficiaryWallets for a recipient's, where 0 means the wallet has no entity.

#Next steps