API reference

Recipient transfers

A recipient transfer moves money out of a recipient's Xtrm wallet to a payment method such as a bank account, Rapid Transfer, a prepaid card or a digital gift card. Use UserWithdrawFund for individual recipients (PAT…) and BeneficiaryCompanyWithdrawFund for business recipients (SPN…).

Recipients transfer money out of their wallets themselves in the Xtrm web app, for example after a bank payment stays RetainedInWallet once its batch is final. These calls let your company request a transfer on a recipient's behalf. Your company must be connected to the recipient, and the recipient confirms each transfer with a six-digit one-time password (OTP). See Bank accounts & transfers.

Send transfer calls one at a time: wait for a successful response to the current call before you send the next one.

Your first request, without OTP, makes Xtrm send the OTP to the account holder: the individual recipient for UserWithdrawFund, the business recipient for BeneficiaryCompanyWithdrawFund. You then resubmit the request with the OTP to complete the transfer. Both responses are HTTP 200 with Success: true, so don't decide with Success alone: the transfer is made only when the response has PaymentStatus Completed and a PaymentTransactionId.

#Transfer from an individual recipient's wallet

POST/API/v4/Fund/UserWithdrawFund

Transfers money from an individual recipient's Xtrm wallet to one of their payment methods. Your company makes the call on the recipient's behalf: it must be connected to the recipient, or the call is refused with Not authorized to access this resource. Make One Time Password API Call to access this resource, and the recipient confirms each transfer with a six-digit one-time password (OTP). This call never debits your company's wallets. To pay an individual recipient from your company's wallet, use a batch payment.

A transfer takes two UserWithdrawFund requests, confirmed with a six-digit one-time password (OTP):

  1. Call UserWithdrawFund without OTP, or with OTP left blank. Xtrm generates a six-digit OTP and sends it to the account holder. The response is HTTP 200 with Success: true and the code-sent message in Errors, and PaymentTransactionId, PaymentDate, PaymentStatus and the amounts are null: no money moves.
  2. Retrieve the OTP from the account holder in your application.
  3. Resubmit UserWithdrawFund with OTP included to complete the transfer.

Don't decide with Success alone, because the first request also returns Success: true. The transfer is made only when the response has PaymentStatus Completed and a PaymentTransactionId. Keep that ID to reconcile. Read any other 200 response from Errors:

  • One Time Password sent to user. Please resubmit with One Time Password. (Success: true): no money moved. Get the code from the account holder and send the same request again with it in OTP.
  • Invalid one time password. A new one has been sent and the original has been expired. Please use the new one. (Success: false): the code was wrong or had expired. No money moved, the old code no longer works, and Xtrm has sent a new one. Send the request again with the new code.

An OTP that is blank, 000000 or not a number counts as a first request: Xtrm sends a new code, the previous code stops working, and you get the code-sent message. The code expires 10 minutes after Xtrm sends it and counts in whole minutes, so send it back within 9 minutes. Each code covers one attempt: once Xtrm accepts it, the code is used up, even if the transfer then fails, so start again with a first request.

Set PaymentMethodID to one of the four payment methods this call accepts, in capitals, exactly as shown:

  • XTR94500 (Bank): the request sends UserLinkedBankID, which you retrieve with GetLinkedBankAccounts. BankPaymentMethod comes from the PaymentMethods collection within the BankDetails object of the same response.
  • XTR94508 (Rapid Transfer, USD only): the request sends CardToken.
  • XTR94503 (Prepaid Virtual Debit Card): the request sends SKU and UserPrepaidVisaEmailID.
  • XTR94505 (Digital Gift Cards): the request sends SKU and UserGiftCardEmailID.

Any other value is refused with <id> - Invalid Payment Method Id. GetUserPaymentMethods also lists XTR94502, which you use to pay an individual recipient's Xtrm wallet in a batch payment, and XTR94506 (Reward Link), a reward card that recipients choose in the Xtrm web app. UserWithdrawFund accepts neither.

The call has no wallet field: it debits the recipient's wallet in Currency.

Get gift card SKUs from GetDigitalGiftCards or GetGiftCardDetails, and prepaid card SKUs from GetPrepaidCards or GetPrepaidCardDetails.

A successful response returns the payment status and the transfer's Amount, Fee and TotalAmount. For a bank transfer or Rapid Transfer, the fee comes out of the Amount you send: the response's Amount is what the bank account or card receives, and TotalAmount is the Amount you sent. Gift card and prepaid card transfers carry no fee for the recipient: the card is worth the full Amount. Gift card and prepaid card transfers also return RedemptionDetails with the credentials and redemption instructions. The Rapid Transfer example returns PayDirectTransactionDetails.

Note

Pass SendTransferCodeToEmail and SendTransferCodeToMobile as strings, not JSON booleans, and only to choose where the code goes: on this call any value that isn't empty, "false" included, turns that channel on. Leave both out to send the code by email and, when the profile has a mobile number, by text message.

Note

For a bank transfer (XTR94500), Xtrm pays exactly the bank in UserLinkedBankID. It must be one of the recipient's own banks with BankBeneficiaryStatus Approved: a request without it is refused with <UserID> - User BankID is mandatory, another account's bank with <UserLinkedBankID> - Invalid User Linked Bank ID, and a bank that's still pending with <UserLinkedBankID> - User Linked Bank ID is in pending status.

Body parameters

  • UserWithdrawFundobjectRequired

    Wrapper object for the operation.

    Child parameters1
    • requestobjectRequired

      The transfer request.

      Child parameters15
      • IssuerAccountNumberstringRequired

        Your company account's Xtrm account identifier, starting with SPN, for the credentials you use for the call. With pseudo credentials, use the SPN of the company on whose behalf you make the call.

      • UserIDstringRequired

        Xtrm account identifier of the individual recipient making the transfer, starting with PAT. The recipient must be connected to your company.

      • AmountstringRequired

        Amount to transfer, as a decimal string, for example "50.00".

      • CurrencystringRequired

        Three-letter ISO 4217 currency code for the transfer, for example USD or EUR. Xtrm debits the recipient's wallet in this currency.

      • PaymentMethodIDstringRequired

        The payment method to transfer to: XTR94500 (bank account), XTR94503 (prepaid card), XTR94505 (digital gift card) or XTR94508 (Rapid Transfer, USD only). Send it in capitals, exactly as shown.

        Allowed values: XTR94500, XTR94503, XTR94505, XTR94508.

      • OTPstringRequired

        Six-digit one-time password, as a string. Omit it or leave it blank on the first request to generate and send an OTP. Include it on the second request to complete the transfer. The OTP expires 10 minutes after Xtrm sends it. 000000 or a value that isn't a number counts as a first request and sends a new code. A value longer than 6 characters returns 400 with One Time Password must be an integer with a maximum length of 6, and no code is sent.

      • BankPaymentMethodstringOptional

        Bank transfer method, for example ACH. Retrieve it from the PaymentMethods collection within the BankDetails object of the GetLinkedBankAccounts response.

      • CardTokenstringOptional

        The CardToken of one of the recipient's linked cards, for Rapid Transfer (XTR94508): a 15-character string of digits and capital letters A to F, as GetLinkedCards returns it.

      • EmailNotificationbooleanOptional

        Whether the recipient receives a standard email notification about this transfer (true / false).

        Default: false.

      • SKUstringOptional

        Item identifier or purchase code, for example for gift card transfers. GetDigitalGiftCards, GetGiftCardDetails, GetPrepaidCards and GetPrepaidCardDetails return SKUs.

      • SendTransferCodeToEmailstringOptional

        Send "true", a string rather than a JSON boolean, to send the transfer code to the account holder's registered email address. With neither this field nor SendTransferCodeToMobile, Xtrm sends the code by email and, when the profile has a mobile number, by text message. On this call any value that isn't empty turns this on, "false" included, so leave the field out instead of sending "false".

      • SendTransferCodeToMobilestringOptional

        Send "true", a string rather than a JSON boolean, to send the transfer code to the account holder's registered mobile number. On this call any value that isn't empty turns this on, "false" included, so leave the field out instead of sending "false". If the profile has no mobile number, the call returns 400 with Mobile # is not available in the user profile.

      • UserGiftCardEmailIDstringOptional

        The email address the gift card details are sent to. Required when PaymentMethodID is XTR94505: without it, the transfer is refused with <UserID> Gift Card EmailID is mandatory.

      • UserLinkedBankIDstringOptional

        The BeneficiaryId of the recipient's linked bank account, from GetLinkedBankAccounts. Required when PaymentMethodID is XTR94500. The bank must be one of the recipient's own banks and approved; Xtrm pays exactly this bank.

      • UserPrepaidVisaEmailIDstringOptional

        The email address the prepaid card details are sent to. Required when PaymentMethodID is XTR94503: without it, the transfer is refused with <UserID> Prepaid Visa EmailID is mandatory.

Response fields

  • UserWithdrawFundResponseobject

    Response wrapper.

    Child parameters1
    • UserWithdrawFundResultobject

      Result of the transfer.

      Child parameters10
      • PaymentTransactionIdstring

        Identifier of the transfer, returned as a string, for example "397781". null until the transfer is made: the code-sent and invalid-code responses don't carry one.

      • PaymentDatestring

        Recorded timestamp or payment date of the transaction, for example 2026-06-05T15:40:41.8090592Z.

      • PaymentStatusstring

        Completed once the transfer is made. null on a response that only sends a code. Decide with this field and PaymentTransactionId, not with Success alone.

      • Amountstring

        Amount paid to the payment method, in the transfer currency, as a string. For a bank transfer or Rapid Transfer, it's the Amount you sent minus Fee. Bank, Rapid Transfer and prepaid card transfers return it with two decimals and, from 1,000, a thousands separator, for example "1,000.00", so strip separators before you parse the amounts. null on a response that only sends a code.

      • Feestring

        Fee for the transfer, in the transfer currency, as a string. Gift card and prepaid card transfers carry no fee for the recipient.

      • TotalAmountstring

        Total debited from the recipient's wallet (Amount plus Fee), in the transfer currency, as a string. For a bank transfer or Rapid Transfer, it equals the Amount you sent.

      • Currencystring

        Three-letter ISO 4217 currency code used for the transfer.

      • PayDirectTransactionDetailsarray

        Additional transfer details, as an array of arrays of Name / Value objects (for example Transfer Type, Transaction Status and Order Number). Populated in the Rapid Transfer example and null in the others.

      • RedemptionDetailsobject

        Redemption details for gift card and prepaid card transfers. null in the bank and Rapid Transfer examples.

        Child parameters11
        • Methodstring

          Redemption method, for example Digital Gift Card or Prepaid Virtual Visa or Mastercard.

        • TransactionStatusstring

          Status of the redemption transaction, for example Success.

        • TransactionNumberstring

          Redemption transaction number, for example RA260605-146803-04.

        • Giftcardstring

          Name of the card, for example Visa® Prepaid Card USD.

        • GiftcardImageUrlstring

          URL of the card image.

        • RecipientEmailstring

          Recipient's email address.

        • RecipientNamestring

          Recipient's name.

        • RecipientMobilePhoneNumberstring

          Recipient's mobile phone number, for example +14085551234.

        • Amountstring

          Redeemed amount followed by the currency code, for example 50.00 USD.

        • TimeProcessedstring

          When the redemption was processed, for example Jun 05, 2026 11:40:41 AM.

        • Rewardobject

          Reward credentials and redemption instructions.

          Child parameters3
          • Credentialsobject

            Credentials object.

            Child parameters1
            • ClaimCodestring

              Claim code. null in the examples.

          • CredentialListobject[]

            Credentials for the reward, such as a redemption link, digital token, PIN or serial number.

            Child parameters4
            • Labelstring

              Categorical name or term for the returned detail, for example Redemption Link or PIN.

            • Valuestring

              Data value corresponding to Label.

            • Typestring

              Value type, for example url or text.

            • CredentialTypestring

              Credential type, for example redemptionUrl, cardNumber or pin.

          • RedemptionInstructionsstring

            Redemption instructions, as an HTML string.

      • OperationStatusobject

        Outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the call ran without errors (true / false). It's also true on the first request, which only sends a code, so don't decide with Success alone: check PaymentStatus and PaymentTransactionId.

        • Errorsstring[]

          Messages about the call, as an array of strings. A completed transfer returns an empty array []. A 200 response can still carry a message here: the code-sent message on the first request, or the invalid-code message when the code was wrong or had expired.

#Errors

MessageMeaning
400 · Not authorized to access this resource. Make One Time Password API Call to access this resourceYour company isn't connected to the recipient. No code is sent. Connect the account first; see Connect existing accounts.
400 · Your previous transfer is in progress. Please wait or try later.An earlier transfer from the recipient's wallet hasn't finished. Xtrm checks this before it sends a code and again after it accepts one, when the code is already used up. Wait, then start again with a first request.
400 · One Time Password must be an integer with a maximum length of 6OTP is longer than 6 characters. No code is sent.
400 · Mobile # is not available in the user profileYou asked for the code by text message, and the account holder's profile has no mobile number. No code is sent. Leave out SendTransferCodeToMobile.

Related: List payment methods for individual recipients · List a recipient's linked bank accounts · List a recipient's linked cards · List digital gift cards · Get gift card details · List prepaid cards · Get prepaid card details · Get an individual recipient's wallet balance · Transfer from a business recipient's wallet

#Transfer from a business recipient's wallet

POST/API/v4/Fund/BeneficiaryCompanyWithdrawFund

Transfers money out of a business recipient's own Xtrm wallet to the recipient's own linked bank or card. Your company makes the call on the recipient's behalf: it must be connected to the recipient, and the recipient confirms each transfer with a six-digit one-time password (OTP). This call never debits your company's wallets. To pay a business recipient from your company's wallet, use a batch payment.

Identify the business recipient with BeneficiaryAccountNumber (starting with SPN) and the wallet to debit with BeneficiaryWalletID, which must be one of the recipient's wallets in Currency. Xtrm doesn't create a wallet for this call. Set the payment method with PaymentMethodID.

A transfer takes two requests:

  1. Call BeneficiaryCompanyWithdrawFund without OTP. Xtrm sends a six-digit OTP to the business recipient. The response is HTTP 200 with Success: true and the code-sent message in Errors, and PaymentTransactionId, PaymentDate and PaymentStatus are null: no money moves.
  2. Get the OTP from the recipient.
  3. Resubmit the request with OTP included to complete the transfer.

Don't decide with Success alone, because the first request also returns Success: true. The transfer is made only when the response has PaymentStatus Completed and a PaymentTransactionId. Keep that ID to reconcile. Read any other 200 response from Errors:

  • One Time Password sent to user. Please resubmit with One Time Password. (Success: true): no money moved. Get the code from the recipient and send the same request again with it in OTP.
  • Invalid one time password. A new one has been sent and the original has been expired. Please use the new one. (Success: false): the code was wrong or had expired. No money moved, the old code no longer works, and Xtrm has sent a new one. Send the request again with the new code.

An OTP that is blank, 000000 or not a number counts as a first request: Xtrm sends a new code, the previous code stops working, and you get the code-sent message. The code expires 10 minutes after Xtrm sends it and counts in whole minutes, so send it back within 9 minutes. Each code covers one attempt: once Xtrm accepts it, the code is used up, even if the transfer then fails, so start again with a first request.

The call accepts two of the payment method IDs that GetBeneficiaryCompanyPaymentMethods lists:

  • XTR94500 (Bank): the request sends BeneficiaryLinkedBankID and BankPaymentMethod. BankPaymentMethod comes from the PaymentMethods collection within the BankDetails object of the GetLinkedBankAccounts response.
  • XTR94508 (Rapid Transfer, USD only): the request sends BeneficiaryCardToken.

Xtrm applies the recipient's own fee schedule and takes the fee out of Amount. A successful response returns the PaymentTransactionId, PaymentDate and PaymentStatus of the payment.

Note

Pass SendTransferCodeToEmail and SendTransferCodeToMobile as strings ("true" / "false"), but EmailNotification as a JSON boolean (true / false).

Note

For a bank transfer (XTR94500), Xtrm pays exactly the bank in BeneficiaryLinkedBankID, whatever bank is linked to the wallet. It must be one of the recipient's own banks with BankBeneficiaryStatus Approved: a request without it is refused with <BeneficiaryAccountNumber> Beneficiary Linked BankID is mandatory, another account's bank with <BeneficiaryLinkedBankID> - Invalid Beneficiary Linked BankID, and a bank that's still pending with <BeneficiaryLinkedBankID> - Beneficiary Linked BankID is in pending status.

Body parameters

  • BeneficiaryCompanyWithdrawFundobjectRequired

    Wrapper object for the operation.

    Child parameters1
    • requestobjectRequired

      The transfer request.

      Child parameters13
      • IssuerAccountNumberstringRequired

        Your company account's Xtrm account identifier, starting with SPN, for the credentials you use for the call. With pseudo credentials, use the SPN of the company on whose behalf you make the call.

      • CurrencystringRequired

        Three-letter ISO 4217 currency code for the transfer, for example USD or EUR.

      • AmountstringRequired

        Amount to transfer, as a decimal string, for example "50.00".

      • PaymentMethodIDstringRequired

        Unique internal identifier of the payment method to transfer to, for example XTR94500.

      • BeneficiaryAccountNumberstringRequired

        Xtrm account identifier of the business recipient, starting with SPN for company accounts.

      • BeneficiaryWalletIDstringRequired

        The ID of the business recipient's wallet to debit, a whole number from GetBeneficiaryWallets. It must be one of the recipient's wallets in Currency. Wallet names aren't accepted: a request with a name is rejected with HTTP 400 and BeneficiaryWalletID is Mandatory and must be an integer, and no money moves.

      • OTPstringRequired

        Six-digit one-time password, as a string. Leave it out on the first request: Xtrm then sends an OTP to the business recipient. Include it when you resubmit the request to complete the transfer. The OTP expires 10 minutes after Xtrm sends it. A blank value, 000000 or a value that isn't a number counts as a first request and sends a new code. A value longer than 6 characters returns 400 with One Time Password must be an integer with a maximum length of 6, and no code is sent.

      • BankPaymentMethodstringOptional

        Bank transfer method, for example ACH. Retrieve it from the PaymentMethods collection within the BankDetails object of the GetLinkedBankAccounts response.

      • BeneficiaryCardTokenstringOptional

        The CardToken of a card linked to the business recipient, for Rapid Transfer (USD only): a 15-character string of digits and capital letters A to F.

      • BeneficiaryLinkedBankIDstringOptional

        The BeneficiaryId of a bank linked to the business recipient, from GetLinkedBankAccounts. Required when PaymentMethodID is XTR94500. The bank must be one of the recipient's own banks and approved; Xtrm pays exactly this bank.

      • EmailNotificationbooleanOptional

        Whether the recipient receives a standard email notification about this transfer. Unlike the transfer code flags, pass a JSON boolean (true / false).

        Default: false.

      • SendTransferCodeToEmailstringOptional

        Whether to send the transfer code to the registered email address. Pass a string ("true" / "false"), not a JSON boolean. When this field and SendTransferCodeToMobile are both "false" or left out, Xtrm sends the code by email and, when the recipient's profile has a mobile number, by text message.

      • SendTransferCodeToMobilestringOptional

        Whether to send the transfer code to the registered mobile number. Pass a string ("true" / "false"), not a JSON boolean. With "true" and no mobile number on the recipient's profile, the call returns 400 with Mobile # is not available in the user profile.

Response fields

  • BeneficiaryCompanyWithdrawFundResponseobject

    Response wrapper.

    Child parameters1
    • BeneficiaryCompanyWithdrawFundResultobject

      Result of the transfer.

      Child parameters5
      • PaymentTransactionIdstring

        Identifier of the transfer, returned as a string, for example "879538". null until the transfer is made: the code-sent and invalid-code responses don't carry one.

      • PaymentDatestring

        Recorded timestamp or payment date of the transaction, for example 2026-06-08T16:21:43.4155509Z.

      • PaymentStatusstring

        Completed once the transfer is made. null on a response that only sends a code. Decide with this field and PaymentTransactionId, not with Success alone.

      • OperationStatusobject

        Outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the call ran without errors (true / false). It's also true on the first request, which only sends a code, so don't decide with Success alone: check PaymentStatus and PaymentTransactionId.

        • Errorsstring[]

          Messages about the call, as an array of strings. A completed transfer returns an empty array []. A 200 response can still carry a message here: the code-sent message on the first request, or the invalid-code message when the code was wrong or had expired.

      • PayDirectTransactionDetailsarray

        Additional transfer details. null in the example.

#Errors

MessageMeaning
400 · Not authorized to access this resource. Make One Time Password API Call to access this resourceYour company isn't connected to the business recipient. No code is sent. Connect the account first; see Connect existing accounts.
400 · Your previous transfer is in progress. Please wait or try later.An earlier transfer from the recipient's wallet hasn't finished. Xtrm checks this before it sends a code and again after it accepts one, when the code is already used up. Wait, then start again with a first request.
400 · One Time Password must be an integer with a maximum length of 6OTP is longer than 6 characters. No code is sent.
400 · Mobile # is not available in the user profileSendTransferCodeToMobile is "true", and the recipient's profile has no mobile number. No code is sent.

Related: List payment methods for business recipients · List a recipient's linked bank accounts · List a recipient's linked cards · List a recipient's wallets · List company wallets · Get a company's wallet fees · Transfer from an individual recipient's wallet · Create a batch payment