Balance Transfers

Platforms can transfer balances between their linked merchants and their own account using the Transfer capability. For example, the platform may want to issue a merchant with credit as a part of a promotion. To be able to perform transfers, Paysafe Technical Support configures the platform account with the capability, which enables it to Transfer Balances with all its linked merchants. To be able to Transfer Balances, the platform must first be linked to the other accounts during onboarding, and only accounts settling in the same currency can be linked. Balances can be transferred from only one account to another at a time, and the transfer amount cannot exceed the positive balance of the source account.

Endpoints

Balance transfers uses the Account Management API; and the endpoint (URI or URL) must point to either the Test or the Production (live) environment.

  • Test API endpoint: https://api.test.paysafe.com/
    For example: https://api.test.paysafe.com/accountmanagement/v1/accounts
  • Production API endpoint: https://api.paysafe.com/
    For example: https://api.paysafe.com/accountmanagement/v1/accounts

Full details of each API request is given in the Account Management API Reference.

Create a Debit Transfer

Use a debit transfer to transfer a balance from the account identified in the API endpoint URI to the linked account in the body of the request.

POST /accountmanagement/v1/accounts/account_id/debits

Request Example

The request object contains the following attributes:

Value Type Required? Description Example
amount integer Yes The amount to transfer to the linked account in minor currency units. 100
detail string No A description of the transaction, added by the merchant. Maximum length 4000 characters. Refund
dupCheck boolean No Set to "false" to override the default duplicate transaction check. false
linkedAccount string Yes The ID of the linked account to receive the debited amount. 100222222
merchantRefNum string Yes

The merchant's unique identifier for this request.

merchantRefNum8
status string Yes The status of the transaction. COMPLETED
Response Example

The response contains the same fields as the request, plus the transaction id, the transaction status (for example: COMPLETED), and a links object, which contains the transaction URI. To look-up a transaction use either the transaction ID, or the merchantRefNum supplied with the original debits request.

Create a Credit Transfer

Use a credit transfer to transfer balances from the linked account in the body of the request to the account identified in the API endpoint URI.

POST /accountmanagement/v1/accounts/account_id/credits

The structures of the credit transfer request and response are identical to those from the debit transfer.

Request Example
Response Example

Look-up a Debit Transfer

You can look up a debit transfer by providing your account number and the transaction ID (returned in the debit response) in the URL as follows:

GET /accountmanagement/v1/accounts/account_id/debits/transaction_id

If you do not have a transaction ID, you can look up a transaction based on the merchantRefNum you supplied with the original debit request:

GET /accountmanagement/v1/accounts/account_id/debits?merchantRefNum=merchantRefNum

The response to each of these requests is an array of transfers, with only one item in the array when dupCheck is true.

Look-up a Credit Transfer

You can look up a credit transfer by providing your account number and the transaction ID (returned in the credit response) in the URL as follows:

GET /accountmanagement/v1/accounts/account_id/credits/transaction_id

If you do not have a transaction ID, you can look up a transaction based on the merchantRefNum you supplied with the original credit request:

GET /accountmanagement/v1/accounts/account_id/credits?merchantRefNum=merchantRefNum

The response to each of these requests is an array of transfers, with only one item in the array when dupCheck is true.

Errors

The following errors may be returned.

HTTP Error Code Error Code Error Message Description
409 5031 The transaction you have submitted has already been processed. This is a duplicate transaction.
402 5021 Your transaction request has been declined. Attempting to transfer an amount larger than the account balance.
401 5040

Your merchant account is not configured for the transaction you attempted.

Account:

  • Not enabled for balance transfers
  • Not linked to the specified account
  • Payment status is on hold
  • Suspended but attempting a debit
Did you find this page useful?