Balance Transfers
- Onboarding
- United States
- Legacy
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.
When Card chargebacks or Direct Debit Returns get posted for a Split Payout transaction, the merchant or platform initiating the transaction needs to transfer the corresponding balances between linked accounts to offset, if required, any portions originally transferred between them through Split Payouts.
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
curl -X POST https://api.test.paysafe.com/accountmanagement/v1/accounts/1001384520/debits \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
-d ' {
"amount": 100,
"merchantRefNum": "merchantRefNum8",
"detail": "Refund",
"linkedAccount": "100222222"
}'
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. This account must already be linked to the merchant account. | 100222222 |
| merchantRefNum | string | Yes | The merchant's unique identifier for this request. | merchantRefNum8 |
{
"id": "82e0094d-1083-4c17-a6bc-d1c1fed1bdc6",
"amount": 100,
"detail": "Refund",
"linkedAccount": "100222222",
"merchantRefNum": "merchantRefNum8",
"status": "COMPLETED",
"links": [{
"rel": "self",
"href": "http://api.test.paysafe.com/accountmanagement/v1/accounts/1001384520/debits/82e0094d-1083-4c17-a6bc-d1c1fed1bdc6"
}]
}
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.
curl -X POST https://api.test.paysafe.com/accountmanagement/v1/accounts/1001384520/credits \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
-d ' {
"amount": 500,
"merchantRefNum": "ORDER_ID:1231",
"detail":"Charging 1004509410 a fee",
"linkedAccount":"1004509410"
}'
{
"id": "82e0094d-1083-4c17-a6bc-d1c1fed1bdc7",
"amount": 500,
"detail": "Charging 1004509410 a fee",
"linkedAccount": "1004509410",
"merchantRefNum": "ORDER_ID:1231",
"status": "COMPLETED",
"links": [{
"rel": "self",
"href": "http://localhost:7001/accountmanagement/v1/accounts/1001384520/credits/82e0094d-1083-4c17-a6bc-d1c1fed1bdc7"
}]
}
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:
|