Process Card Purchase Split Payouts
POST /cardpayments/v1/accounts/account_id/auths
Processing a Split Payouts purchase is a variant of processing a standard card purchase, where a share of the total transaction amount is transferred to one or more linked accounts.
To process a purchase, you must initiate a POST request to the auths endpoint, and the request must contain a settleWithAuth flag set to true, so that the card processing system charges the card as part of the same request.
Split Payouts cannot be used in Authorizations that have settleWithAuth = false, where the intention is to settle the purchase later. In those situations, Split Payouts must be used in the settlement request.
curl -X POST https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/auths \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum" : "demo-1",
"amount" : 10098,
"settleWithAuth":true,
"card" : {
"cardNum" : "4111111111111111",
"cardExpiry":{
"month":2,
"year":2027
},
"cvv":123
},
"billingDetails":{
"street":"100 Queen Street West",
"city":"Toronto",
"state":"ON",
"country":"CA",
"zip":"M5H 2N2"
}
"splitpay": [
{
"linkedAccount": "123124124",
"percent": 5
},
{
"linkedAccount": "767862873",
"amount": 500
}
]
} '
The splitpay object is an array of linked accounts, each of which has the following attributes
| 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 |
| percent | number | Either percent or amount is required, but not both. | The percentage of the total transaction amount to transfer to the linked account, to up to two decimal places. The total percentage to all linked accounts cannot exceed 100%. | 5.31 |
| amount | integer | The amount to transfer to the linked account in minor currency units. The total amount to all linked accounts cannot exceed the transaction total. | 500 |
The amount is specified 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.
By default the card processing system checks for duplicate transactions.
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.
Before trying the example above, you should:
- Provide a unique merchant reference number for each transaction.
- 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 have received.
- Replace any linked account numbers and percent and amount values with test values.
{
"links":[
{
"rel":"self",
"href":"https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/auths/ebf6ae3d-88e1-40da-9b98-81044467345b"
},
{
"rel":"settlement",
"href":"https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/settlements/ebf6ae3d-88e1-40da-9b98-81044467345b"
},
],
"id":"ebf6ae3d-88e1-40da-9b98-81044467345b",
"merchantRefNum":"demo-1",
"txnTime":"2017-05-01T14:52:35Z",
"status":"COMPLETED",
"amount":10098,
"settleWithAuth":true,
"availableToSettle":0,
"card":{
"type":"VI",
"lastDigits":"1111",
"cardExpiry":{
"month":2,
"year":2027
}
},
"authCode":"114974",
"billingDetails":{
"street":"100 Queen Street West",
"city":"Toronto",
"state":"ON",
"country":"CA",
"zip":"M5H2N2"
},
"merchantDescriptor":{
"dynamicDescriptor":"Test",
"phone":"123-1234123"
},
"currencyCode":"CAD",
"avsResponse":"MATCH",
"splitpay": [
{
"linkedAccount": "123124124",
"percent": 5
},
{
"linkedAccount": "767862873",
"amount": 500
}
],
"settlement" : {
"links": [
{
"rel": "self",
"href": "https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/settlements/ebf6ae3d-88e1-40da-9b98-81044467345b"
}
],
"id": "ebf6ae3d-88e1-40da-9b98-81044467345b",
"merchantRefNum": "demo-1",
"txnTime": "2014-05-01T14:52:35Z",
"status": "PENDING",
"amount": 10098,
"availableToRefund": 0,
"splitpay": [
{
"linkedAccount": "123124124",
"percent": 5,
"amount": 505
},
{
"linkedAccount": "767862873",
"amount": 500
}
]
}
}
The status is set to COMPLETED and the value for availableToSettle is 0 because the card was automatically charged as part of the request, since the settleWithAuth flag was set to true. You can look up the transaction at any future time using either the merchantRefNum (demo-1) or the id returned in the response (in this case - ebf6ae3d-88e1-40da-9b98-81044467345b).
The obligatory response parameters that differ from those of the standard purchase request are described below:
| Value | Type | Description |
|---|---|---|
| splitpay | array of splitpay objects | The Split Payouts information from the request. |
| settlements | array of settlement objects | Contains a single settlement object, which contains a splitpay object. |
The splitpay object in the settlement object is an array containing one or more linked account objects:
| Value | Type | Required? | Description | Example |
|---|---|---|---|---|
| amount | integer | Yes | The amount to transfer to 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 |
| linkedAccount | string | Yes | The ID of the linked account. This account must already be linked to the merchant account. | 123124124 |
| 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 to 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 Authorization endpoint.