Requests
Split
The Split action can be used as a supplementary action in a transaction request to provide split information. This is called the split payment transaction. Based on the split information, Buckaroo can transfer funds to target accounts; these can consist of one funds account and/or one or multiple third party accounts. The following transaction types are currently supported:
- iDEAL: action Pay
- Bancontact: actions Pay, PayEncrypted, PayOnceClick
- SEPA Direct Debit: actions Pay, PayWithEmandate
- Transfer: action Pay
- Simple SEPA Direct Debit
- Sofort: action Pay
- Giropay: action Pay
- EPS: action Pay
- KBC: action Pay
- Przelewy24: action Pay
- Trustly: action Pay
- WeChatPay: action Pay
- AliPay: action Pay
- Afterpay: action Pay
- PayPerEmail: action PaymentInvitation. Be sure to only allow the previously mentioned payment methods for the PayPerEmail.
Key Points:
- Split information will only be accepted and processed if the split payment transaction is successful.
- The sum of all specified split amounts cannot exceed the split payment transaction amount.
- At least one split for a target account is required. Definition of a split consists of specified Amount, Description, and AccountId (in case of a third party).
- Multiple splits for the same target account can be specified.
- Each split for a third party must have a unique group ID.
Split Request
Parameters
| Parameter | Type | Required | Recommended | Description |
|---|---|---|---|---|
| issuerID | string | yes | BIC code of the issuing bank of the consumer. The bank must support iDIN | |
| DaysUntilTransfer | string | Amount of days the funds are kept in the Split Payments account before being transferred to the specified target account(s). Possible values: 0 to 93. If 0 is provided, the funds are transferred immediately after the split payment transaction is successful. If not provided, the funds will be kept in the Split Payments account until they are transferred through separate Transfer requests (see action "Transfer") | ||
| Amount | decimal | GroupType: Marketplace. Amount reserved for the Split Payments merchant. | ||
| Description | string | GroupType: Marketplace. Description of the reserved amount for the Split Payments Funds account. We advise to always start with the invoice number of the order, followed by the description of the split. Example: "INV001 Commission Platform". | ||
| AccountId | string | GroupType: Seller. Buckaroo merchant ID of the third party account. | ||
| Amount | decimal | GroupType: Seller. Amount reserved for the third party account. | ||
| Description | string | GroupType: Seller. Description of the reserved amount for the third party account. We advise to always start with the invoice number of the order, followed by the description of the split, ending with the name of the third party. Example: "INV001 Payout Beauty Products BV". |
Example Request
{
"Currency": "EUR",
"AmountDebit": 95.00,
"Invoice": "INV0001",
"Services": {
"ServiceList": [
{
"Name": "ideal",
"Action": "Pay",
"Parameters": [
{
"Name": "issuer",
"Value": "ABNANL2A"
}
]
},
{
"Name": "Marketplaces",
"Action": "Split",
"Parameters": [
{
"Name": "DaysUntilTransfer",
"Value": "2"
},
{
"Name": "Amount",
"GroupType": "Marketplace",
"Value": "10.00"
},
{
"Name": "Description",
"GroupType": "Marketplace",
"Value": "INV0001 Commission Platform"
},
{
"Name": "AccountId",
"GroupType": "Seller",
"GroupID": "1",
"Value": "789C60F316D24B088ACD471"
},
{
"Name": "Amount",
"GroupType": "Seller",
"GroupID": "1",
"Value": "50.00"
},
{
"Name": "Description",
"GroupType": "Seller",
"GroupID": "1",
"Value": "INV001 Payout Make-Up Products BV"
},
{
"Name": "AccountId",
"GroupType": "Seller",
"GroupID": "2",
"Value": "369C60F316D24B088ACD238"
},
{
"Name": "Amount",
"GroupType": "Seller",
"GroupID": "2",
"Value": "35.00"
},
{
"Name": "Description",
"GroupType": "Seller",
"GroupID": "2",
"Value": "INV0001 Payout Beauty Products BV"
}
]
}
]
}
}
Split Response
Parameters
| Parameter | Type | Required | Recommended | Description |
|---|---|---|---|---|
| SplitGuid_Marketplace | string | Unique identifier for the split that is specified for the Split Payments Funds account. Will also be provided in the push response of the related Internal Transfer transaction. | ||
| SplitGuid_Seller_X | string | Unique identifier for the split that is specified for a third party (X is the specified GroupID). The SplitGuid will also be provided in the push response of the relating Internal Transfer transaction. |
Example Response
{
"Key": "021641D88B3C41EAB37FE77xxxxxxx",
"Status": {
"Code": {
"Code": 791,
"Description": "Pending processing"
},
"SubCode": {
"Code": "S002",
"Description": "An additional action is required: RedirectToIdeal"
},
"DateTime": "2021-08-23T16:41:06"
},
"RequiredAction": {
"RedirectURL": "http://testcheckout.local/html/redirect.ashx?r=29B3B3DDxxxxx",
"RequestedInformation": null,
"PayRemainderDetails": null,
"Name": "Redirect",
"TypeDeprecated": 0
},
"Services": [
{
"Name": "Marketplaces",
"Action": null,
"Parameters": [
{
"Name": "SplitGuid_Marketplace",
"Value": "E0B520E8C8EE48AEA50CFCB3B5xxxxx"
},
{
"Name": "SplitGuid_Seller_1",
"Value": "1F77D27D5A484748A15C9F821xxxxxx"
},
{
"Name": "SplitGuid_Seller_2",
"Value": "76BF6D2FDE8D4E68BADDAA001xxxxxx"
}
]
},
{
"Name": "ideal",
"Action": null,
"Parameters": [
{
"Name": "consumerIssuer",
"Value": "ABN AMRO"
},
{
"Name": "transactionId",
"Value": "0000000000000001"
}
]
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"Invoice": "INV0001",
"ServiceCode": "ideal",
"IsTest": true,
"Currency": "EUR",
"AmountDebit": 95.00,
"TransactionType": "C021",
"MutationType": 1,
"RelatedTransactions": null,
"ConsumerMessage": null,
"Order": null,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": null,
"PayerHash": null,
"PaymentKey": "9898D1B8003E4C968Axxxxxx"
}
Split Push
The standard push response of the specified payment method service will be returned.
Parameters
| Parameter | Type | Required | Recommended | Description |
|---|---|---|---|---|
| SplitGuid_Marketplace | string | Unique identifier for the split that is specified for the Split Payments Funds account. Will also be provided in the push response of the related Internal Transfer transaction. | ||
| SplitGuid_Seller_X | string | Unique identifier for the split that is specified for a third party (X is the specified GroupID). The SplitGuid will also be provided in the push response of the relating Internal Transfer transaction. |
Example Push
{
"Transaction": {
"Key": "021641D88B3C41EAB37FE77xxxxxxx",
"Invoice": "INV0001",
"ServiceCode": "ideal",
"Status": {
"Code": {
"Code": 190,
"Description": "Success"
},
"SubCode": {
"Code": "S001",
"Description": "Transaction successfully processed"
},
"DateTime": "2017-03-28T11:24:14"
},
"IsTest": true,
"Order": null,
"Currency": "EUR",
"AmountDebit": 95,
"TransactionType": "C021",
"Services": [
{
"Name": "ideal",
"Action": null,
"Parameters": [
{
"Name": "consumerIssuer",
"Value": "ABN AMRO"
},
{
"Name": "transactionId",
"Value": "0000000000000001"
},
{
"Name": "consumerName",
"Value": "J. de Tèster"
},
{
"Name": "consumerIBAN",
"Value": "NL44RABO0123456789"
},
{
"Name": "consumerBIC",
"Value": "RABONL2U"
}
],
"VersionAsProperty": 2
},
{
"Name": "Marketplaces",
"Action": null,
"Parameters": [
{
"Name": "SplitGuid_Marketplace",
"Value": "E0B520E8C8EE48AEA50CFCB3B5xxxxx"
},
{
"Name": "SplitGuid_Seller_1",
"Value": "1F77D27D5A484748A15C9F821xxxxxx"
},
{
"Name": "SplitGuid_Seller_2",
"Value": "76BF6D2FDE8D4E68BADDAA001xxxxxx"
}
],
"VersionAsProperty": 2
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"MutationType": 1,
"RelatedTransactions": null,
"IsCancelable": false,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": "J. de Tèster",
"PayerHash": "d2e447e9bd91d63",
"PaymentKey": "644545E2409D4223AC09E880ADXXXXXX"
}
}
Transfer (I)
The Transfer action can be used to immediately transfer (part of) the funds of an existing split payment transaction to the target account(s). This could be necessary when, for example:
- Funds of a split payment transaction are pending for transfer (DaysUntilTransfer count down) but need to be transferred earlier
- The DaysUntilTransfer parameter was not provided for the split payment transaction and therefore can only be transferred with a separate Transfer request.
Transfer Request
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| OriginalTransactionKey | string | Yes | Transaction key of a split payment transaction. Please note that this is a basic parameter, not a service-specific parameter. In case of a PayPerEmail, make sure to use the transaction key of the actual payment transaction (e.g. iDEAL) instead of the PayPerEmail transaction. |
Example Request
{
"OriginalTransactionKey": "D3732474ED0",
"Services": {
"ServiceList": [
{
"Name": "Marketplaces",
"Action": "Transfer"
}
]
}
}
Transfer Response
Example Response
{
"Key": "6FAA272A23934EC6ABAAC47BC0C8FF36",
"Status": {
"Code": {
"Code": 190,
"Description": "Success"
},
"SubCode": {
"Code": "S990",
"Description": "The request was successful."
},
"DateTime": "2020-10-21T14:52:52"
},
"RequiredAction": null,
"Services": null,
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"ServiceCode": "Marketplaces",
"IsTest": true,
"ConsumerMessage": null
}
Transfer (II)
The Transfer request can also be used to perform a Transfer with different split information than originally provided in the split payment transaction. This could be necessary when, for example:
- The original split specification contains incorrect or outdated split information.
- Only a part of the funds are to be transferred (at that particular moment).
Like with the Split action, (new) split data can be provided with the Transfer request. By doing this, the original split specification that was provided with the split payment transaction will be canceled entirely.
Important Notes
- It is possible to perform a Transfer request for only a part of the split payment transaction amount, making it possible to perform multiple (partial) Transfers for 1 split payment transaction until the full transaction amount has been transferred.
- A partial Transfer request will remove a split payment transaction (with DaysUntilTransfer) out of a transfer countdown, since the original split specification is canceled entirely. If this is the case, the remaining funds can only be transferred with separate Transfer requests.
- Since the Transfer action is a request for an immediate transfer, the DaysUntilTransfer parameter is not available for this action.
Like the Split action, the following applies as well:
- The sum of all specified split amounts cannot exceed the split payment transaction amount.
- If the Split Payment Funds account or third party account is specified, all parameters in that group are required.
- It is possible to specify multiple splits for the same target account.
- Each split for a third party has to have a unique group ID.
Transfer (II) Request
Parameters
| Parameter | Type | Required | Recommended | Description |
|---|---|---|---|---|
| OriginalTransactionKey | string | Yes | Transaction key of a split payment transaction. Please note that this is a basic parameter, not a service-specific parameter. In case of a PayPerEmail, make sure to use the transaction key of the actual payment transaction (e.g. iDEAL) instead of the PayPerEmail transaction. | |
| Amount | decimal | GroupType: Marketplace | Amount reserved for the Split Payments merchant. | |
| Description | string | GroupType: Marketplace | Description of the reserved amount for the Split Payments merchant. We advise to always start with the invoice number of the order, followed by the description of the split. Example: "INV001 Commission Platform". | |
| AccountId | string | GroupType: Seller | Buckaroo merchant ID of the third party account. | |
| Amount | string | GroupType: Seller | Amount reserved for the third party account. | |
| Description | string | GroupType: Seller | Description of the reserved amount for the third party account. We advise to always start with the invoice number of the order, followed by the description of the split, ending with the name of the third party. Example: "INV001 Payout Beauty Products BV". |
Example Request
{
"OriginalTransactionKey": "D3732474ED0",
"Services": {
"ServiceList": [
{
"Name": "Marketplaces",
"Action": "Transfer",
"Parameters": [
{
"Name": "Amount",
"GroupType": "Marketplace",
"Value": "10.00"
},
{
"Name": "Description",
"GroupType": "Marketplace",
"Value": "INV0001 Commission Platform"
},
{
"Name": "AccountId",
"GroupType": "Seller",
"GroupID": "1",
"Value": "789C60F316D24B088ACD471"
},
{
"Name": "Amount",
"GroupType": "Seller",
"GroupID": "1",
"Value": "50.00"
},
{
"Name": "Description",
"GroupType": "Seller",
"GroupID": "1",
"Value": "INV0001 Payout Beauty Products BV"
}
]
}
]
}
}
Transfer (II) Response
Example Response
{
"Key": "6FAA272A23934EC6ABAAC47BC0C8FF36",
"Status": {
"Code": {
"Code": 190,
"Description": "Success"
},
"SubCode": {
"Code": "S990",
"Description": "The request was successful."
},
"DateTime": "2020-10-21T14:52:52"
},
"RequiredAction": null,
"Services": null,
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"ServiceCode": "Marketplaces",
"IsTest": true,
"ConsumerMessage": null
}
RefundSupplementary (I)
RefundSupplementary Action
The RefundSupplementary action should be used as a supplementary action in a (refund) transaction request to return funds from the funds or third party accounts back to the Split Payments account. The following transaction types are currently supported:
- iDEAL: action Refund
- Bancontact: action Refund
- SEPA Direct Debit: action Refund
A refund to a consumer is always initially funded through the funds of the Split Payments account. This is performed via the primary refund action of the chosen payment method. Secondly, the same amount has to be returned to the Split Payments account from one or more target accounts. This is done via the RefundSupplementary action.
RefundSupplementary (I) Request
Parameters
| Parameter | Type | Required | Recommended | Description |
|---|---|---|---|---|
| OriginalTransactionKey | string | Yes | Transaction key of a split payment transaction. Please note that this is a basic parameter, not a service-specific parameter. In case of a PayPerEmail, make sure to use the transaction key of the actual payment transaction (e.g. iDEAL) instead of the PayPerEmail transaction. |
Example Request
{
"OriginalTransactionKey": "D3737EDA42474ED0",
"Currency": "EUR",
"AmountCredit": 50.00,
"Invoice": "INV0001",
"Services": {
"ServiceList": [
{
"Name": "ideal",
"Action": "Refund"
},
{
"Name": "Marketplaces",
"Action": "RefundSupplementary"
}
]
}
}
RefundSupplementary (I) response
Example Response
{
"Key": "F996EE747ECD43CDA8851C5F83XXXXXX",
"Status": {
"Code": {
"Code": 190,
"Description": "Success"
},
"SubCode": {
"Code": "S001",
"Description": "Transaction successfully processed"
},
"DateTime": "2017-03-31T09:03:45"
},
"RequiredAction": null,
"Services": [
{
"Name": "ideal",
"Action": null,
"Parameters": [
{
"Name": "customeraccountname",
"Value": "J. de Tèster"
},
{
"Name": "CustomerIBAN",
"Value": "NL44RABO0123456789"
},
{
"Name": "CustomerBIC",
"Value": "RABONL2U"
}
]
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"Invoice": "INV0001",
"ServiceCode": "ideal",
"IsTest": true,
"Currency": "EUR",
"AmountCredit": 50.0,
"TransactionType": "C121",
"MutationType": 1,
"RelatedTransactions": [
{
"RelationType": "refund",
"RelatedTransactionKey": "4E8BD922192746C"
}
],
"ConsumerMessage": null,
"Order": null,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": "J. de Tèster",
"PayerHash": null,
"PaymentKey": "AE8B6E18A2684846AAAF06A63FXXXXXX"
}
RefundSupplementary (I) Push
Example Push
{
"Transaction": {
"Key": "F996EE747ECD43CDA8851C5F83XXXXXX",
"Invoice": "INV0001",
"ServiceCode": "ideal",
"Status": {
"Code": {
"Code": 190,
"Description": "Success"
},
"SubCode": {
"Code": "S001",
"Description": "Transaction successfully processed"
},
"DateTime": "2017-03-31T09:03:45"
},
"IsTest": true,
"Order": null,
"Currency": "EUR",
"AmountCredit": 50.0,
"TransactionType": "C121",
"Services": [
{
"Name": "ideal",
"Action": null,
"Parameters": [
{
"Name": "customeraccountname",
"Value": "J. de Tèster"
},
{
"Name": "CustomerIBAN",
"Value": "NL44RABO0123456789"
},
{
"Name": "CustomerBIC",
"Value": "RABONL2U"
}
],
"VersionAsProperty": 2
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"MutationType": 1,
"RelatedTransactions": [
{
"RelationType": "refund",
"RelatedTransactionKey": "4E8BD922192746C391"
}
],
"IsCancelable": false,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": "J. de Tèster",
"PayerHash": null,
"PaymentKey": "AE8B6E18A2684846AAAF06A63FXXXXXX"
}
}
RefundSupplementary (II)
Certainly! Here is the provided text converted into Markdown format:
RefundSupplementary (II) Request
Besides reverting all of the performed Transfers of a split payment transaction by performing a RefundSupplementary action as illustrated in the previous example, it is also possible to specify the funds that are to be retrieved from one or more target accounts (similar to specifying a split). This also means that the Split Payments account has the flexibility to retrieve a different amount from a target account than what was originally transferred to it.
- For a third party account, you cannot retrieve more than what was originally transferred to it. For example, if 2 splits of 20 Euro were transferred to a third party, the Split Payments account can specify a 'split' of 30 Euro to be retrieved from that third party to the Split Payments account. But it cannot be 50 Euro (because that exceeds the total transferred amount of 40 Euro to that third party).
- For the Funds account, any amount can be retrieved. Per RefundSupplementary action, the total amount to be retrieved from target accounts should always be equal to the amount that is refunded to the consumer. For example, if 40 Euro is refunded to the consumer and only 30 Euro is retrieved from a third party, then the other 10 Euro should be retrieved from one or more other target accounts.
- It is possible to perform multiple (partial) refunds (with RefundSupplementary action) on 1 split payment transaction until the full amount is refunded to the consumer.
Parameters
| Parameter | Type | Required | Recommended | Description |
|---|---|---|---|---|
| OriginalTransactionKey | string | Yes | Transaction key of a split payment transaction. Please note that this is a basic parameter, not a service-specific parameter. In case of a PayPerEmail, make sure to use the transaction key of the actual payment transaction (e.g. iDEAL) instead of the PayPerEmail transaction. | |
| Amount | decimal | GroupType: Marketplace | Amount to be retrieved back from the funds account to the Split Payments account. | |
| Description | string | GroupType: Marketplace | Description of the amount to be retrieved back from the funds account to the Split Payments account. We advise to always start with the invoice number of the original order, followed by the description of the split. Example: "INV001 Refund Platform". | |
| AccountId | string | GroupType: Seller | Buckaroo merchant ID of the third party account. | |
| Amount | decimal | GroupType: Seller | Amount to be retrieved back from the third party account to the Split Payments account. | |
| Description | string | GroupType: Seller | Description of the amount to be retrieved back from the third party account to the Split Payments account. We advise to always start with the invoice number of the original order, followed by the description of the split, ending with the name of the third party. Example: "INV001 Refund Beauty Products BV". |
Example Request
{
"OriginalTransactionKey": "D3737EDA42474ED0",
"Currency": "EUR",
"AmountCredit": 30.00,
"Invoice": "INV0001",
"Services": {
"ServiceList": [
{
"Name": "ideal",
"Action": "Refund"
},
{
"Name": "Marketplaces",
"Action": "RefundSupplementary",
"Parameters": [
{
"Name": "AccountId",
"GroupType": "Seller",
"GroupID": "1",
"Value": "789C60F316D24B088ACD471"
},
{
"Name": "Amount",
"GroupType": "Seller",
"GroupID": "1",
"Value": "30.00"
},
{
"Name": "Description",
"GroupType": "Seller",
"GroupID": "1",
"Value": "INV0001 Refund Beauty Products BV"
}
]
}
]
}
}
RefundSupplementary (II) Response
Example Response
{
"Key": "F996EE747ECD43CDA8851C5F83XXXXXX",
"Status": {
"Code": {
"Code": 190,
"Description": "Success"
},
"SubCode": {
"Code": "S001",
"Description": "Transaction successfully processed"
},
"DateTime": "2017-03-31T09:03:45"
},
"RequiredAction": null,
"Services": [
{
"Name": "ideal",
"Action": null,
"Parameters": [
{
"Name": "customeraccountname",
"Value": "J. de Tèster"
},
{
"Name": "CustomerIBAN",
"Value": "NL44RABO0123456789"
},
{
"Name": "CustomerBIC",
"Value": "RABONL2U"
}
]
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"RequestErrors": null,
"Invoice": "INV0001",
"ServiceCode": "ideal",
"IsTest": true,
"Currency": "EUR",
"AmountCredit": 30.0,
"TransactionType": "C121",
"MutationType": 1,
"RelatedTransactions": [
{
"RelationType": "refund",
"RelatedTransactionKey": "4E8BD922192746C39"
}
],
"ConsumerMessage": null,
"Order": null,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": "J. de Tèster",
"PayerHash": null,
"PaymentKey": "AE8B6E18A2684846AAAF06A63FXXXXXX"
}
RefundSupplementary (II) Push
Example Push
{
"Transaction": {
"Key": "F996EE747ECD43CDA8851C5F83XXXXXX",
"Invoice": "INV0001",
"ServiceCode": "ideal",
"Status": {
"Code": {
"Code": 190,
"Description": "Success"
},
"SubCode": {
"Code": "S001",
"Description": "Transaction successfully processed"
},
"DateTime": "2017-03-31T09:03:45"
},
"IsTest": true,
"Order": null,
"Currency": "EUR",
"AmountCredit": 30.0,
"TransactionType": "C121",
"Services": [
{
"Name": "ideal",
"Action": null,
"Parameters": [
{
"Name": "customeraccountname",
"Value": "J. de Tèster"
},
{
"Name": "CustomerIBAN",
"Value": "NL44RABO0123456789"
},
{
"Name": "CustomerBIC",
"Value": "RABONL2U"
}
],
"VersionAsProperty": 2
}
],
"CustomParameters": null,
"AdditionalParameters": null,
"MutationType": 1,
"RelatedTransactions": [
{
"RelationType": "refund",
"RelatedTransactionKey": "4E8BD922192746C391"
}
],
"IsCancelable": false,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": "J. de Tèster",
"PayerHash": null,
"PaymentKey": "AE8B6E18A2684846AAAF06A63FXXXXXX"
}
}
Updated about 2 months ago