General
With the Marketplaces service, Buckaroo merchants can perform split payment transactions. These transactions can be performed with iDEAL, Bancontact or SEPA Direct Debit. Once the split payment transaction is successful, Buckaroo can split the transaction into smaller amounts and allocate them to other parties, making it a suitable payment solution for online marketplaces. Since mixed basket purchases are a key feature of marketplace platforms, split payment transactions are the perfect way to get the funds directly to the involved sellers.
- In order to use the Marketplaces service and perform split payment transactions, both the marketplace and its affiliated sellers need to have a Buckaroo account.
- The marketplace will need 2 accounts; a marketplace account to perform the Marketplaces API communication and a funds account to receive its share of the split payment funds (it will also be used by Buckaroo to pay out the funds to the marketplace).
- The account ID's of the sellers will be provided to the marketplace by Buckaroo's back office. They are necessary when specifying the sellers in the API calls with Buckaroo.
Servicename: Marketplaces
Available actions:
- Split (supplementary action for transaction request)
- Transfer (data request)
- Refund (supplementary action for transaction request)
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 seller accounts. The following transaction types are currently supported:
- iDEAL: action Pay
- Bancontact: action Pay, PayEncrypted, PayOnceClick
- SEPA Direct Debit: action Pay, PayWithEmandate
Important notes:
- 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
- It is required to provide at least 1 split for a target account. Definition of a split consists of: specified Amount, Description and AccountId (in case of a seller)
- If a marketplace or seller 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 seller must have a unique group ID
Request
JSON gateway request
|
DaysUntilTransfer
string
|
Amount of days the funds are kept in the marketplace 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 marketplace account until they are transferred through separate Transfer requests (see action "Transfer") |
|
Amount
decimal
|
GroupType: Marketplace. Amount reserved for the marketplace. |
|
Description
string
|
GroupType: Marketplace. Description of the reserved amount for the marketplace. We advise to always start with the invoice number of the order, followed by the description of the split. Example: "INV001 Commission Marketplace". |
|
AccountId
string
|
GroupType: Seller. Buckaroo merchant ID of the seller account. |
|
Amount
decimal
|
GroupType: Seller. Amount reserved for the seller account. |
|
Description
string
|
GroupType: Seller. Description of the reserved amount for the seller 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 seller. Example: "INV001 Payout Beauty Products BV". |
JSON
{
"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 Marketplace"
},
{
"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"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
The standard PAY response of the specified payment method service will be returned.
JSON
{
"Key": "4E8BD922192746C3918BF4077CXXXXXX",
"Status": {
"Code": {
"Code": 791,
"Description": "Pending processing"
},
"SubCode": {
"Code": "S002",
"Description": "An additional action is required: RedirectToIdeal"
},
"DateTime": "2017-03-28T11:23:42"
},
"RequiredAction": {
"RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=904A643",
"RequestedInformation": null,
"PayRemainderDetails": null,
"Name": "Redirect",
"TypeDeprecated": 0
},
"Services": [
{
"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.0,
"TransactionType": "C021",
"MutationType": 1,
"RelatedTransactions": null,
"ConsumerMessage": null,
"Order": null,
"IssuingCountry": null,
"StartRecurrent": false,
"Recurring": false,
"CustomerName": null,
"PayerHash": null,
"PaymentKey": "644545E2409D4223AC09E880ADXXXXXX"
}Push
Gateway push response
The standard push response of the specified payment method service will be returned.
JSON
{
"Transaction": {
"Key": "4E8BD922192746C3918BF4077CXXXXXX",
"Invoice": "testinvoice 123",
"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": 10.0,
"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
}
],
"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.
Request
JSON gateway request
If funds are to be transferred according to the full original split specification, then only the original transaction key is required in the request.
|
OriginalTransactionKey
string
|
Required
Transaction key of a split payment transaction. Please note that this is a basic parameter, not a service specific parameter. |
JSON
{
"OriginalTransactionKey": "D3732474ED0",
"Services": {
"ServiceList": [
{
"Name": "Marketplaces",
"Action": "Transfer"
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
JSON
{
"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
}Push
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 count down, 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 a marketplace or seller 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 seller has to have a unique group ID
Request
JSON gateway request
|
OriginalTransactionKey
string
|
Required
Transaction key of a split payment transaction. Please note that this is a basic parameter, not a service specific parameter. |
|
Amount
decimal
|
GroupType: Marketplace. Amount reserved for the marketplace. |
|
Description
string
|
GroupType: Marketplace. Description of the reserved amount for the marketplace. We advise to always start with the invoice number of the order, followed by the description of the split. Example: "INV001 Commission Marketplace". |
|
AccountId
string
|
GroupType: Seller. Buckaroo merchant ID of the seller account. |
|
Amount
string
|
GroupType: Seller. Amount reserved for the seller account. |
|
Description
string
|
GroupType: Seller. Description of the reserved amount for the seller 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 seller. Example: "INV001 Payout Beauty Products BV". |
JSON
{
"OriginalTransactionKey": "D3732474ED0",
"Services": {
"ServiceList": [
{
"Name": "Marketplaces",
"Action": "Transfer",
"Parameters": [
{
"Name": "Amount",
"GroupType": "Marketplace",
"Value": "10.00"
},
{
"Name": "Description",
"GroupType": "Marketplace",
"Value": "INV0001 Commission Marketplace"
},
{
"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"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
JSON
{
"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
}Push
RefundSupplementary (I)
The RefundSupplementary action should be used as a supplementary action in a (refund) transaction request to return funds from the funds or seller accounts back to the marketplace 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 marketplace account. This is performed via the primary refund action of the chosen payment method. Secondly, the same amount has to be returned to the Marketplace account from one or more target accounts. This is done via the RefundSupplementary action.
Request
JSON gateway request
If all of the performed Transfers of a split payment transaction need to be reverted (meaning: returning every transferred split back to the marketplace account), then it is sufficient to only provide the transaction key of the split payment transaction.
|
OriginalTransactionKey
string
|
Required
Transaction key of a split payment transaction. Please note that this is a basic parameter, not a service parameter. |
JSON
{
"OriginalTransactionKey": "D3737EDA42474ED0",
"Currency": "EUR",
"AmountCredit": 50.00,
"Invoice": "INV0001",
"Services": {
"ServiceList": [
{
"Name": "ideal",
"Action": "Refund"
},
{
"Name": "Marketplaces",
"Action": "RefundSupplementary"
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
The standard gateway response of the specified payment method service will be returned.
JSON
{
"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"
}Push
JSON push response
The standard push response of the specified payment method service will be returned.
JSON
{
"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)
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 a specifying a split). This also means that the marketplace has the flexibility to retrieve a different amount from a target account than what was originally transferred to it.
- For a Seller account, you cannot retrieve more than what was originally transferred to it. For example, if 2 splits of 20 Euro were transferred to a seller, the marketplace can specify a 'split' of 30 Euro to be retrieved from that seller to the marketplace account. But it cannot be 50 Euro (because that exceeds the total transferred amount of 40 Euro to that seller).
- 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 seller, 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.
Request
JSON gateway request
This request illustrates a refund of 30 Euro to the consumer and the retrieval of 30 euro back from a seller account to the marketplace account.
|
OriginalTransactionKey
string
|
Required
Transaction key of a split payment transaction. Please note that this is a basic parameter, not a service parameter. |
|
Amount
decimal
|
Grouptype: Marketplace. Amount to be retrieved back from the funds account to the marketplace account. |
|
Description
string
|
Grouptype: Marketplace. Description of the amount to be retrieved back from the funds account to the marketplace account. We advise to always start with the invoice number of the original order, followed by the description of the split. Example: "INV001 Refund Marketplace". |
|
AccountId
string
|
GroupType: Seller. Buckaroo merchant ID of the seller account. |
|
Amount
decimal
|
GroupType: Seller. Amount to be retrieved back from the seller account to the marketplace account. |
|
Description
string
|
GroupType: Seller. Description of the amount to be retrieved back from the seller account to the marketplace 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 seller. Example: "INV001 Refund Beauty Products BV". |
JSON
{
"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"
}
]
}
]
}
}Response 200 Status: Ok 400 Status: Access denied 500 Status: Bad request
JSON gateway response
The standard gateway response of the specified payment method service will be returned.
JSON
{
"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"
}Push
JSON push response
The standard push response of the specified payment method service will be returned.
JSON
{
"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"
}
}