General

The merchant starts by sending the request for a transfer to a BPE transaction gateway. The gateway processes the request and sends a response to the merchant. Additionally, a transaction push is sent to the merchant as well (Both contain the current status of the transaction). On gateways that have the customer visiting them, the transfer details are also shown to the customer. Optionally, the BPE can also send an email to the customer, containing the details for the money transfer. Once the customer transfers the money to the Buckaroo bank account, the Buckaroo Payment Engine detects this and updates the transactions status (or creates a new transaction in case the amount is incorrect). This new status is then pushed to the merchant website, together with the bank details from the customer, if they are available.

Servicecodes and actions

The Transfer service uses the servicecode: transfer

The Transfer service supports the following actions: Pay, Refund

Pay

The pay action is the default action for the Transfer service. The action is used to register a payment and it will result in a pending transaction and bank transfer details that are either shown to the customer or returned to merchant, so that the merchant can show them. Optionally, an email is sent to the customer with the same bank details. After the money arrives on the Buckaroo bank account, the transaction status is updated to success.

Please note – very important: If however the actually transferred amount does not match the original transaction, a new transfer transaction is created, which is a copy of the original, with only a different amount, and that one is set to success. This new transaction will send a push message (see the Gateway manual for information about push messages) with the same invoicenumber and a success status, with one of the parameters being the amount of this transaction. It is therefore very important you check the amount of the push message, so your system knows what amount has been paid and you do not automatically set an order to status “paid” in your system when the incorrect amount has been transferred by the customer.

View in playground

Request


JSON gateway request

CustomerGender

Gender of the customer, possible values: 1: Male, 2: Female, 0: Unknown, 9: Not applicable.

Customeremail
Required

The e-mail address of the customer.

Customerfirstname
Required

The first name of the customer.

Customerlastname
Required

The surname of the customer.

Sendmail

If true (default), the BPE will send an email with the payment details to the customer. (Boolean). If false, then it is the responsibility of the merchant to make the payment details (which are sent in the API response) available to the customer.

DateDue

The date by which the customer should pay. This is only for display purposes, to be able to use it in email templates.

CustomerCountry

The 2-letter iso-code specifying the country for which the bank details should be used. (This is usually the country the customer resides).

JSON

copy
{
   "Currency": "EUR",
   "AmountDebit": 10,
   "Invoice": "testinvoice 123",
   "Services": {
      "ServiceList": [
         {
            "Name": "transfer",
            "Action": "Pay",
            "Parameters": [
               {
                  "Name": "CustomerFirstName",
                  "Value": "John"
               },
               {
                  "Name": "CustomerLastName",
                  "Value": "Smith"
               },
               {
                  "Name": "CustomerGender",
                  "Value": "0"
               },
               {
                  "Name": "CustomerCountry",
                  "Value": "NL"
               },
               {
                  "Name": "SendMail",
                  "Value": "true"
               },
               {
                  "Name": "CustomerEmail",
                  "Value": "your@email.com"
               },
               {
                  "Name": "DateDue",
                  "Value": "2019-01-01"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

PaymentReference

This is the payment reference (or description), which the customer needs to give to the transfer when making the payment.

BankAccount

The localized bank account number.

BIC

The BIC code identifying the bank to which the payment must be made.

IBAN

The IBAN code identifying the bank account to which the payment must be made.

AccountHolderName

The name of the account holder of the account to which the payment must be made.

AccountHolderCity

The city of the account holder.

AccountHolderCountry

The country of the account holder.

JSON

copy
{
   "Key": "DFA1E22BC3FD4E3CBA0D0D60E0BDXXXX",
   "Status": {
      "Code": {
         "Code": 792,
         "Description": "Waiting for consumer"
      },
      "SubCode": {
         "Code": "C300",
         "Description": "The payment for this transfer is still being expected."
      },
      "DateTime": "2018-01-08T10:29:21"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "transfer",
         "Action": null,
         "Parameters": [
            {
               "Name": "BIC",
               "Value": "RABONL2U"
            },
            {
               "Name": "IBAN",
               "Value": "NL05RABO0121503038"
            },
            {
               "Name": "AccountHolderName",
               "Value": "Buckaroo Stichting Derdengelden"
            },
            {
               "Name": "BankAccount",
               "Value": "1215.03.038"
            },
            {
               "Name": "AccountHolderCity",
               "Value": "Utrecht"
            },
            {
               "Name": "AccountHolderCountry",
               "Value": "The Netherlands"
            },
            {
               "Name": "PaymentReference",
               "Value": "5112XXXX"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice 123",
   "ServiceCode": "transfer",
   "IsTest": false,
   "Currency": "EUR",
   "AmountDebit": 10,
   "TransactionType": "C001",
   "MutationType": 1,
   "RelatedTransactions": null,
   "ConsumerMessage": {
      "MustRead": true,
      "CultureName": "en-US",
      "Title": "Transfer to bank account",
      "PlainText": "Please transfer the specified amount (10.00 EUR) stating the payment reference 5112XXXX, using the bank details below:\r\n\r\nPayment reference: 5112XXXX\r\nAccountholder: Buckaroo Stichting Derdengelden\r\nIBAN: NL05RABO0121503038\r\nBIC: RABONL2U",
      "HtmlText": "Please transfer the specified amount (EUR 10.00) stating the payment reference 51122469, using the bank details below:\r\n<br/>\r\n<table class=\"bankdetails\">\r\n\t<tr>\r\n\t\t<td class=\"label\" id=\"amountlabel\">Amount:<\/td>\r\n\t\t<td class=\"labelvalue\" id=\"amount\">EUR 10.00<\/td>\r\n\t<\/tr>\r\n\t<tr>\r\n\t\t<td class=\"label\" id=\"referencelabel\">Payment reference:<\/td>\r\n\t\t<td class=\"labelvalue\" id=\"reference\">5112XXXX<\/td>\r\n\t<\/tr>\r\n  <tr>\r\n\t\t<td class=\"label\" id=\"accountholdernamelabel\">Accountholder:<\/td>\r\n\t\t<td class=\"labelvalue\" id=\"accountholdername\">Buckaroo Stichting Derdengelden<\/td>\r\n\t<\/tr>\r\n\t<tr>\r\n\t\t<td class=\"label\" id=\"ibanlabel\">IBAN-code:<\/td>\r\n\t\t<td class=\"labelvalue\" id=\"ibancode\">NL05RABO0121503038<\/td>\r\n\t<\/tr>\r\n\t<tr>\r\n\t\t<td class=\"label\" id=\"biclabel\">BIC-code:<\/td>\r\n\t\t<td class=\"labelvalue\" id=\"biccode\">RABONL2U<\/td>\r\n\t<\/tr>\r\n<\/table>"
   },
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": "John Smith",
   "PayerHash": null,
   "PaymentKey": "45ED99DBDAB34FBD98A16B8D0430XXXX"
}

Push


JSON push response

JSON

copy
{
   "Transaction": {
      "Key": "DFA1E22BC3FD4E3CBA0D0D60E0BXXXXX",
      "Invoice": "testinvoice 123",
      "ServiceCode": "transfer",
      "Status": {
         "Code": {
            "Code": 792,
            "Description": "Wacht op consument"
         },
         "SubCode": {
            "Code": "C300",
            "Description": "Betaling voor deze overschrijving wordt nog verwacht."
         },
         "DateTime": "2018-01-08T10:29:21"
      },
      "IsTest": false,
      "Order": null,
      "Currency": "EUR",
      "AmountDebit": 10,
      "TransactionType": "C001",
      "Services": [
         {
            "Name": "transfer",
            "Action": null,
            "Parameters": [
               {
                  "Name": "CustomerIban",
                  "Value": "NL06ABNAXXXXXXXXXX"
               },
               {
                  "Name": "CustomerBic",
                  "Value": "ABNANL2A"
               },
               {
                  "Name": "CustomerAccountName",
                  "Value": "John Smith"
               },
                  "Name": "BIC",
                  "Value": "RABONL2U"
               },
               {
                  "Name": "IBAN",
                  "Value": "NL05RABO0121503038"
               },
               {
                  "Name": "AccountHolderName",
                  "Value": "Buckaroo Stichting Derdengelden"
               },
               {
                  "Name": "BankAccount",
                  "Value": "1215.03.038"
               },
               {
                  "Name": "AccountHolderCity",
                  "Value": "Utrecht"
               },
               {
                  "Name": "AccountHolderCountry",
                  "Value": "The Netherlands"
               },
               {
                  "Name": "PaymentReference",
                  "Value": "5112XXXX"
               }
            ],
            "VersionAsProperty": 1
         }
      ],
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 1,
      "RelatedTransactions": null,
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": "John Smith",
      "PayerHash": null,
      "PaymentKey": "45ED99DBDAB34FBD98A16B8D0430XXXX"
   }
}

Refund

To refund a successful transfer transaction, use the action Refund.  A bank transfer is then initiated which transfers (some of) the amount of the original transaction to the consumer.

View in playground

Request


JSON gateway request

originaltransaction
Required

Transaction key of the original transaction that needs to be refunded. Please note: This is a basic request variable, not a service specific variable.

customeraccountname

The account holder beneficiary name.

customeraccountnumber

The account number.

customeriban

The IBAN code for the customer account.

customerbic

The BIC code identifying the customer bank.

JSON

copy
{
   "Currency": "EUR",
   "AmountCredit": 1.00,
   "Invoice": "B000000143",
   "OriginalTransactionKey": "XXXXXXXXXXXXXXXXXXXXXXX",
   "Services": {
      "ServiceList": [
         {
            "Name": "transfer",
            "Action": "Refund"
         }
      ]
   }
}

Response


JSON gateway response

JSON

copy
{
   "Key": "XXXXXXXXXXXXXXXXXXXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2017-03-31T09:03:45"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "transfer",
         "Action": null,
         "Parameters": [
            {
               "Name": "customeraccountname",
               "Value": "John Smith"
            },
            {
               "Name": "CustomerIBAN",
               "Value": "NL03INGBXXXXXXXXX"
            },
            {
               "Name": "CustomerBIC",
               "Value": "INGBNL2A"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testinvoice 123",
   "ServiceCode": "transfer",
   "IsTest": true,
   "Currency": "EUR",
   "AmountCredit": 1,
   "TransactionType": "C101",
   "MutationType": 1,
   "RelatedTransactions": [
      {
         "RelationType": "refund",
         "RelatedTransactionKey": "XXXXXXXXXXXXXXXXXXXX"
      }
   ],
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": "John Smith",
   "PayerHash": null,
   "PaymentKey": "XXXXXXXXXXXXXXXXXXXX"
}

Push


JSON push response

JSON

copy
{
   "Transaction": {
      "Key": "XXXXXXXXXXXXXXXXXXXX",
      "Invoice": "testinvoice 123",
      "ServiceCode": "transfer",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Succes"
         },
         "SubCode": {
            "Code": "S001",
            "Description": "Transaction successfully processed"
         },
         "DateTime": "2015-08-25T14:52:52"
      },
      "IsTest": false,
      "Order": null,
      "Currency": "EUR",
      "AmountCredit": 1.00,
      "TransactionType": "C101",
      "Services": [
         {
            "Name": "transfer",
            "Action": null,
            "Parameters": [
               {
                  "Name": "customeraccountname",
                  "Value": "John Smith"
               },
               {
                  "Name": "CustomerIBAN",
                  "Value": "NL03INGBXXXXXXXXX"
               },
               {
                  "Name": "CustomerBIC",
                  "Value": "INGBNL2A"
               }
            ],
            "VersionAsProperty": 1
         }
      ],
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 1,
      "RelatedTransactions": [
         {
            "RelationType": "refund",
            "RelatedTransactionKey": "XXXXXXXXXXXXXXXXXXXX"
         }
      ],
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": "John Smith",
      "PayerHash": null,
      "PaymentKey": "XXXXXXXXXXXXXXXXXXXX"
   }
}