Process Direct Debit Purchase Split Payouts
POST /directdebit/v1/accounts/account_id/purchases
Processing a Split Payouts purchase is a variant of processing a standard direct debit purchase, where a share of the total transaction amount is transferred to one or more linked accounts.
A purchase request allows you to transfer money from a customer's bank account to your merchant account. To process a purchase, you must make a POST request to the purchases endpoint for the relevant bank account type. In the example below this is an ACH account. The transaction is completed in real time, though the banking network typically takes 3–5 days to transfer the funds. The request also contains a profile and billing address information. You can make a request without a profile, billing address, or bank account if you use a payment token from the Paysafe Customer Vault API. See our API Reference section for details.
curl -X POST https://api.test.paysafe.com/directdebit/v1/accounts/89987201/purchases \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum": "ORDER_ID:1231",
"amount": 10098,
"ach": {
"accountHolderName": "XYZ Company",
"accountType": "CHECKING",
"accountNumber": "988772192",
"routingNumber": "211589828",
"payMethod": "WEB"
},
"customerIp": "192.0.126.111",
"profile": {
"firstName": "Joe",
"lastName": "Smith",
"email": "Joe.Smith@hotmail.com"
},
"billingDetails": {
"street": "100 Queen Street West",
"city": "Los Angeles",
"state": "CA",
"country": "US",
"zip": "90210",
"phone": "3102649010"
},
"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 |
By default the Direct Debit processing system checks for duplicate transactions. You can override the duplicate check by setting the dupCheckparameter to false, as in the following example: "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.
Before trying the example, 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 example above) in the URL with the test account number you received.
- Replace the API key (after the -u) with the API key you have received.
{
"links": [
{
"rel": "self",
"href": "https://api.test.paysafe.com/directdebit/v1/accounts/89987201/purchases/a02e52c7-c991-4418-966a-b62989cb0eae"
}
],
"id": "a02e52c7-c991-4418-966a-b62989cb0eae",
"merchantRefNum": "ORDER_ID:1231",
"amount": 10098,
"ach": {
"accountHolderName": "XYZ Company",
"accountType": "CHECKING",
"lastDigits": "92",
"routingNumber": "211589828",
"payMethod": "WEB"
},
"customerIp": "192.0.126.111",
"profile": {
"firstName": "Joe",
"lastName": "Smith",
"email": "Joe.Smith@hotmail.com"
},
"billingDetails": {
"street": "100 Queen Street West",
"city": "Los Angeles",
"state": "CA",
"country": "US",
"zip": "90210",
"phone": "3102649010"
},
"txnTime": "2017-12-14T15:12:18Z",
"currencyCode": "USD",
"status": "PENDING",
"splitpay": [
{
"linkedAccount": "123124124",
"percent": 5,
"amount": 505
},
{
"linkedAccount": "767862873",
"amount": 500
}
]
}
The response returns an id value and a status that indicates whether the purchase is complete, pending, or failed. The purchase ID can be used to look up or cancel the purchase.
The splitpay object in the response 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 |