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. |
|
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. |
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": "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": "Payment ORD0001"
},
{
"Name": "AccountId",
"GroupType": "Seller",
"GroupID": "2",
"Value": "369C60F316D24B088ACD238"
},
{
"Name": "Amount",
"GroupType": "Seller",
"GroupID": "2",
"Value": "35.00"
},
{
"Name": "Description",
"GroupType": "Seller",
"GroupID": "2",
"Value": "Payment ORD0001"
}
]
}
]
}
}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. |
|
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. |
JSON
{
"OriginalTransactionKey": "D3732474ED0",
"Services": {
"ServiceList": [
{
"Name": "Marketplaces",
"Action": "Transfer",
"Parameters": [
{
"Name": "Amount",
"GroupType": "Marketplace",
"Value": "10.00"
},
{
"Name": "Description",
"GroupType": "Marketplace",
"Value": "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": "Payment ORD0001"
}
]
}
]
}
}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 can 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. Thus, it is possible to refund split payment transactions without retrieving money back from sellers (in that case a regular refund request would suffice). Most likely, there will be a reason for having a seller to pay back funds that have been transferred to them. Product returns being a good case example. To do this, the refund request can be supplemented with the Marketplaces 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. It is required that it has funds already transferred to a target account, since the RefundSupplementary action is used to returning these funds back to the marketplace account. 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 a target account (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 (but it cannot be more than what was originally transferred). 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). This way it is possible to perform multiple RefundSupplementary actions on 1 split payment transaction until all of the transferred funds are returned to the marketplace account, but always taking into account that you cannot retrieve more from a target account than what was transferred to it.
Request
JSON gateway request
This request illustrates a refund of 40 Euro to the consumer and the retrieval of 20 euro back from a seller account to the marketplace account.
|
OriginalTransactionKey
string
|
Required
Transaction key of a split payment transaction. It is required that it has funds already transferred to a target account, since the RefundSupplementary action is used to returning these funds back to the marketplace account. 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. |
|
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. |
JSON
{
"OriginalTransactionKey": "D3737EDA42474ED0",
"Currency": "EUR",
"AmountCredit": 40.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": "Refund articles ABC and XYZ"
}
]
}
]
}
}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": 40.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": 40.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"
}
}