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
/API/v4/Fund/UserWithdrawFundTransfers 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):
- Call
UserWithdrawFundwithoutOTP, or withOTPleft blank. Xtrm generates a six-digit OTP and sends it to the account holder. The response is HTTP200withSuccess: trueand the code-sent message inErrors, andPaymentTransactionId,PaymentDate,PaymentStatusand the amounts arenull: no money moves. - Retrieve the OTP from the account holder in your application.
- Resubmit
UserWithdrawFundwithOTPincluded 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 inOTP.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 sendsUserLinkedBankID, which you retrieve withGetLinkedBankAccounts.BankPaymentMethodcomes from thePaymentMethodscollection within theBankDetailsobject of the same response.XTR94508(Rapid Transfer,USDonly): the request sendsCardToken.XTR94503(Prepaid Virtual Debit Card): the request sendsSKUandUserPrepaidVisaEmailID.XTR94505(Digital Gift Cards): the request sendsSKUandUserGiftCardEmailID.
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.
Important
Send transfer calls one at a time. Wait for a successful response to the current call before you send the next one.
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
UserWithdrawFundobjectRequiredWrapper object for the operation.
Child parameters1
requestobjectRequiredThe transfer request.
Child parameters15
IssuerAccountNumberstringRequiredYour company account's Xtrm account identifier, starting with
SPN, for the credentials you use for the call. With pseudo credentials, use theSPNof the company on whose behalf you make the call.UserIDstringRequiredXtrm account identifier of the individual recipient making the transfer, starting with
PAT. The recipient must be connected to your company.AmountstringRequiredAmount to transfer, as a decimal string, for example
"50.00".CurrencystringRequiredThree-letter ISO 4217 currency code for the transfer, for example
USDorEUR. Xtrm debits the recipient's wallet in this currency.PaymentMethodIDstringRequiredThe payment method to transfer to:
XTR94500(bank account),XTR94503(prepaid card),XTR94505(digital gift card) orXTR94508(Rapid Transfer,USDonly). Send it in capitals, exactly as shown.Allowed values:
XTR94500,XTR94503,XTR94505,XTR94508.OTPstringRequiredSix-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.
000000or a value that isn't a number counts as a first request and sends a new code. A value longer than 6 characters returns400withOne Time Password must be an integer with a maximum length of 6, and no code is sent.BankPaymentMethodstringOptionalBank transfer method, for example
ACH. Retrieve it from thePaymentMethodscollection within theBankDetailsobject of theGetLinkedBankAccountsresponse.CardTokenstringOptionalThe
CardTokenof one of the recipient's linked cards, for Rapid Transfer (XTR94508): a 15-character string of digits and capital letters A to F, asGetLinkedCardsreturns it.EmailNotificationbooleanOptionalWhether the recipient receives a standard email notification about this transfer (
true/false).Default:
false.SKUstringOptionalItem identifier or purchase code, for example for gift card transfers.
GetDigitalGiftCards,GetGiftCardDetails,GetPrepaidCardsandGetPrepaidCardDetailsreturn SKUs.SendTransferCodeToEmailstringOptionalSend
"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 norSendTransferCodeToMobile, 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".SendTransferCodeToMobilestringOptionalSend
"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 returns400withMobile # is not available in the user profile.UserGiftCardEmailIDstringOptionalThe email address the gift card details are sent to. Required when
PaymentMethodIDisXTR94505: without it, the transfer is refused with<UserID> Gift Card EmailID is mandatory.UserLinkedBankIDstringOptionalThe
BeneficiaryIdof the recipient's linked bank account, fromGetLinkedBankAccounts. Required whenPaymentMethodIDisXTR94500. The bank must be one of the recipient's own banks and approved; Xtrm pays exactly this bank.UserPrepaidVisaEmailIDstringOptionalThe email address the prepaid card details are sent to. Required when
PaymentMethodIDisXTR94503: without it, the transfer is refused with<UserID> Prepaid Visa EmailID is mandatory.
Response fields
UserWithdrawFundResponseobjectResponse wrapper.
Child parameters1
UserWithdrawFundResultobjectResult of the transfer.
Child parameters10
PaymentTransactionIdstringIdentifier of the transfer, returned as a string, for example
"397781".nulluntil the transfer is made: the code-sent and invalid-code responses don't carry one.PaymentDatestringRecorded timestamp or payment date of the transaction, for example
2026-06-05T15:40:41.8090592Z.PaymentStatusstringCompletedonce the transfer is made.nullon a response that only sends a code. Decide with this field andPaymentTransactionId, not withSuccessalone.AmountstringAmount paid to the payment method, in the transfer currency, as a string. For a bank transfer or Rapid Transfer, it's the
Amountyou sent minusFee. 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.nullon a response that only sends a code.FeestringFee for the transfer, in the transfer currency, as a string. Gift card and prepaid card transfers carry no fee for the recipient.
TotalAmountstringTotal debited from the recipient's wallet (
AmountplusFee), in the transfer currency, as a string. For a bank transfer or Rapid Transfer, it equals theAmountyou sent.CurrencystringThree-letter ISO 4217 currency code used for the transfer.
PayDirectTransactionDetailsarrayAdditional transfer details, as an array of arrays of
Name/Valueobjects (for exampleTransfer Type,Transaction StatusandOrder Number). Populated in the Rapid Transfer example andnullin the others.RedemptionDetailsobjectRedemption details for gift card and prepaid card transfers.
nullin the bank and Rapid Transfer examples.Child parameters11
MethodstringRedemption method, for example
Digital Gift CardorPrepaid Virtual Visa or Mastercard.TransactionStatusstringStatus of the redemption transaction, for example
Success.TransactionNumberstringRedemption transaction number, for example
RA260605-146803-04.GiftcardstringName of the card, for example
Visa® Prepaid Card USD.GiftcardImageUrlstringURL of the card image.
RecipientEmailstringRecipient's email address.
RecipientNamestringRecipient's name.
RecipientMobilePhoneNumberstringRecipient's mobile phone number, for example
+14085551234.AmountstringRedeemed amount followed by the currency code, for example
50.00 USD.TimeProcessedstringWhen the redemption was processed, for example
Jun 05, 2026 11:40:41 AM.RewardobjectReward credentials and redemption instructions.
Child parameters3
CredentialsobjectCredentials object.
Child parameters1
ClaimCodestringClaim code.
nullin the examples.
CredentialListobject[]Credentials for the reward, such as a redemption link, digital token, PIN or serial number.
Child parameters4
LabelstringCategorical name or term for the returned detail, for example
Redemption LinkorPIN.ValuestringData value corresponding to
Label.TypestringValue type, for example
urlortext.CredentialTypestringCredential type, for example
redemptionUrl,cardNumberorpin.
RedemptionInstructionsstringRedemption instructions, as an HTML string.
OperationStatusobjectOutcome of the operation.
Child parameters2
SuccessbooleanWhether the call ran without errors (
true/false). It's alsotrueon the first request, which only sends a code, so don't decide withSuccessalone: checkPaymentStatusandPaymentTransactionId.Errorsstring[]Messages about the call, as an array of strings. A completed transfer returns an empty array
[]. A200response 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
| Message | Meaning |
|---|---|
400 · Not authorized to access this resource. Make One Time Password API Call to access this resource | Your 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 6 | OTP is longer than 6 characters. No code is sent. |
400 · Mobile # is not available in the user profile | You 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
/API/v4/Fund/BeneficiaryCompanyWithdrawFundTransfers 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:
- Call
BeneficiaryCompanyWithdrawFundwithoutOTP. Xtrm sends a six-digit OTP to the business recipient. The response is HTTP200withSuccess: trueand the code-sent message inErrors, andPaymentTransactionId,PaymentDateandPaymentStatusarenull: no money moves. - Get the OTP from the recipient.
- Resubmit the request with
OTPincluded 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 inOTP.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 sendsBeneficiaryLinkedBankIDandBankPaymentMethod.BankPaymentMethodcomes from thePaymentMethodscollection within theBankDetailsobject of theGetLinkedBankAccountsresponse.XTR94508(Rapid Transfer,USDonly): the request sendsBeneficiaryCardToken.
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.
Important
Send transfer calls one at a time. Wait for a successful response to the current call before you send the next one.
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
BeneficiaryCompanyWithdrawFundobjectRequiredWrapper object for the operation.
Child parameters1
requestobjectRequiredThe transfer request.
Child parameters13
IssuerAccountNumberstringRequiredYour company account's Xtrm account identifier, starting with
SPN, for the credentials you use for the call. With pseudo credentials, use theSPNof the company on whose behalf you make the call.CurrencystringRequiredThree-letter ISO 4217 currency code for the transfer, for example
USDorEUR.AmountstringRequiredAmount to transfer, as a decimal string, for example
"50.00".PaymentMethodIDstringRequiredUnique internal identifier of the payment method to transfer to, for example
XTR94500.BeneficiaryAccountNumberstringRequiredXtrm account identifier of the business recipient, starting with
SPNfor company accounts.BeneficiaryWalletIDstringRequiredThe
IDof the business recipient's wallet to debit, a whole number fromGetBeneficiaryWallets. It must be one of the recipient's wallets inCurrency. Wallet names aren't accepted: a request with a name is rejected with HTTP400andBeneficiaryWalletID is Mandatory and must be an integer, and no money moves.OTPstringRequiredSix-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,
000000or a value that isn't a number counts as a first request and sends a new code. A value longer than 6 characters returns400withOne Time Password must be an integer with a maximum length of 6, and no code is sent.BankPaymentMethodstringOptionalBank transfer method, for example
ACH. Retrieve it from thePaymentMethodscollection within theBankDetailsobject of theGetLinkedBankAccountsresponse.BeneficiaryCardTokenstringOptionalThe
CardTokenof a card linked to the business recipient, for Rapid Transfer (USDonly): a 15-character string of digits and capital letters A to F.BeneficiaryLinkedBankIDstringOptionalThe
BeneficiaryIdof a bank linked to the business recipient, fromGetLinkedBankAccounts. Required whenPaymentMethodIDisXTR94500. The bank must be one of the recipient's own banks and approved; Xtrm pays exactly this bank.EmailNotificationbooleanOptionalWhether the recipient receives a standard email notification about this transfer. Unlike the transfer code flags, pass a JSON boolean (
true/false).Default:
false.SendTransferCodeToEmailstringOptionalWhether to send the transfer code to the registered email address. Pass a string (
"true"/"false"), not a JSON boolean. When this field andSendTransferCodeToMobileare both"false"or left out, Xtrm sends the code by email and, when the recipient's profile has a mobile number, by text message.SendTransferCodeToMobilestringOptionalWhether 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 returns400withMobile # is not available in the user profile.
Response fields
BeneficiaryCompanyWithdrawFundResponseobjectResponse wrapper.
Child parameters1
BeneficiaryCompanyWithdrawFundResultobjectResult of the transfer.
Child parameters5
PaymentTransactionIdstringIdentifier of the transfer, returned as a string, for example
"879538".nulluntil the transfer is made: the code-sent and invalid-code responses don't carry one.PaymentDatestringRecorded timestamp or payment date of the transaction, for example
2026-06-08T16:21:43.4155509Z.PaymentStatusstringCompletedonce the transfer is made.nullon a response that only sends a code. Decide with this field andPaymentTransactionId, not withSuccessalone.OperationStatusobjectOutcome of the operation.
Child parameters2
SuccessbooleanWhether the call ran without errors (
true/false). It's alsotrueon the first request, which only sends a code, so don't decide withSuccessalone: checkPaymentStatusandPaymentTransactionId.Errorsstring[]Messages about the call, as an array of strings. A completed transfer returns an empty array
[]. A200response 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.
PayDirectTransactionDetailsarrayAdditional transfer details.
nullin the example.
#Errors
| Message | Meaning |
|---|---|
400 · Not authorized to access this resource. Make One Time Password API Call to access this resource | Your 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 6 | OTP is longer than 6 characters. No code is sent. |
400 · Mobile # is not available in the user profile | SendTransferCodeToMobile 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