Process Card Refund Split Payouts
POST /cardpayments/v1/accounts/account_id/settlements/id/refunds
During a Split Payouts settlement refund, a portion of the refunded amount can be retrieved from one or more linked accounts, irrespective of whether the original settlement was split.
To process a refund, you must make a POST request to the refunds endpoint, replacing account_id with your unique merchant account number and id with the unique ID returned in the response to the original settlement.
curl -X POST https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/settlements/280e3b80-1beb-424a-9cb3-5ef7444112f9/refunds \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum" : "merchantRef_003",
"amount": 10098,
"splitpay": [
{
"linkedAccount": "1001391850",
"percent": 5.75
},
{
"linkedAccount": "1001391860",
"amount": 500
}
]
} '
The following request attributes are required:
| Value | Type | Description |
|---|---|---|
| amount | number | The amount of the request, in minor units of the currency of the merchant account specified using the account_id URL parameter. For example, to process US $10.99, this value should be 1099; to process 1000 Japanese yen, this value should be 1000; to process 10.139 Tunisian dinar, this value should be 10139. This attribute is optional; if a value is not provided, the remaining amount on the settlement will be refunded. |
| merchantRefNum | string | The merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request. |
| splitpay | array | Required for a Split Payout refund. Details of the linked accounts contributing to the refund. |
Before trying the example above, you should:
- Provide a unique merchant reference number for each transaction (if this value is not unique, and the number has been used in the past 90 days, the request will be flagged as a duplicate).
- Replace the account number (89987201) in the URL with the test account number you received.
- Replace the API key (after the -u) with the API key you received.
- Replace any linked account numbers and percent and amount values with test values.
By default the card processing system will check for duplicate transactions. You can override this behavior by setting the dupCheck parameter to false, like this: "dupCheck": "false",
With Split Payouts, the following are also checked:
- A percent or an amount – but not both – is specified for each linked account.
- Split Payouts are enabled for the Partner or Merchant account identified in the API POST or GET request.
- The linked accounts are linked to the Partner or Merchant account.
- The Partner/Merchant account is not one of the linked accounts.
- The sum of the amount allocated to all linked accounts does not exceed the transaction total.
{
"links":[
{
"rel":"self",
"href":"https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/refunds/ebf6ae3d-88e1-40da-9b98-81044467345b"
}
],
"id":"ebf6ae3d-88e1-40da-9b98-81044467345b",
"merchantRefNum":"merchantRef_003",
"txnTime":"2017-05-01T14:52:35Z",
"status": "PENDING",
"acquirerResponse": {
"code": "DJN",
"terminalId": "12345678",
"batchNumber": "001",
"seqNumber": "151",
"effectiveDate": "170728"
},
"amount": 10098,
"splitpay": [
{
"linkedAccount": "1001391850",
"percent": 5.75,
"amount": 581
},
{
"linkedAccount": "1001391860",
"amount": 500
}
]
}
In addition to the attributes in the request, the response may also contain the attributes described below.
| Value | Type | Description |
|---|---|---|
| acquirerResponse | array | The response from the acquirer. |
| id | string | The response ID, which can be used to retrieve the response in the future. |
| links | array | The endpoints to be targeted depending on the end state of the transaction. |
| splitpay | array | The linked accounts and the amounts refunded. |
| status | enum | The status of the transaction request. |
| txnTime | string | The date and time the transaction was processed. |
The splitpay array contains one or more linked account objects:
| Value | Type | Required? | Description | Example |
|---|---|---|---|---|
| linkedAccount | string | Yes | The ID of the linked account. This account must already be linked to the merchant account. | 123124124 |
| amount | integer | Yes | The amount to transfer from the linked account in minor currency units. This is either the "amount" (if specified) in the request or - if "percent" was specified - the result of the percentage calculation. | 505 |
| percent | number | No | The "percent" (if specified) in the request for the linked account, which is the percentage of the total transaction amount to transfer from that account. This is not returned if an "amount" was specified in the request. | 5.25 |
See our API Reference section for a list of all the JSON attributes and types available for the refunds endpoint.