APIs

Buckaroo offers a JSON-based gateway for establishing an API connection with the Buckaroo Payment Engine. By sending API requests to specific Buckaroo endpoints, you can perform various operations like initiating transactions or retrieving information. Most requests require specifying an 'action'. For example, most payment methods require the 'Pay' action to initiate a payment, while the ‘Refund’ action initiates a refund of an existing payment. Other payment methods, such as credit cards, support actions like 'Authorize' (to reserve an amount) and 'Capture' (to charge the credit card with the authorized amount). Please refer to the payment method sections for all available actions and parameters.

Basic Request Variables

Below is a list of basic variables that can be used to provide information in a request:

Website Key

This key can be found in the Buckaroo payment plaza at Buckaroo Plaza. Click on your merchant name in the menu on the left side of the screen -> websites -> {yourwebsite}. Here you can find the website key in the table in the first row.

Currency

This denotes the currency in which the transaction is done. Possible values are EUR, USD, GBP, and others.

AmountDebit

The debit amount for the request. This is in decimal format, with a point as the decimal separator. For example, if the currency is specified as EUR, sending “1” will mean that 1 euro will be paid. “1.00” is also 1 euro. “0.01” means 1 cent. A transaction must have either a debit amount or a credit amount, and it cannot have both.

AmountCredit

The credit amount for the request. This is in decimal format, with a point as the decimal separator. For example, if the currency is specified as EUR, sending “1” will mean that 1 euro will be paid. “1.00” is also 1 euro. “0.01” means 1 cent. A transaction must have either a debit amount or a credit amount, and it cannot have both.

Invoice

The invoice number used for the request. This can be a combination of numbers and letters. Note that the invoice will be trimmed on our side, so white spaces at the beginning and end will be removed.

Order

The order number for which the request is done. This can be a combination of numbers and letters. Note that this field is not yet supported, and anything sent in with this field is currently ignored.

Description

The description of the transaction.

ClientIP

In this field, the IP address of the customer (or employee) for which the action is being performed can be passed. If this field is not sent to our gateway, your server IP address will be used as the client IP. This may result in unwanted behaviour for anti-fraud checks. Certain payment methods perform checks on the IP address, and if an IP address is overused, the request could be blocked. This field is sent in the following format, where type 0 = IPv4 and type 1 = IPv6: "ClientIP": { "Type": 0, "Address": "0.0.0.0" }

There are two situations where we will automatically update your server address to the client's address:

1. The client lands on our hosted payment page.
2. The client returns from an external (payment) environment.

ReturnURL

This is the URL to which a customer is redirected after completing a payment. For some payments, the customer needs to be sent to a webpage to complete the payment. After completing the process on this page, the customer is then redirected back to the page specified in this field. If this field is omitted, the URL configured in the Payment Plaza is used.

ReturnURLCancel

Specifies an alternative return URL for transactions cancelled by the customer.

ReturnURLError

Specifies an alternative return URL for transactions that generate an error during processing.

ReturnURLReject

Specifies an alternative return URL for transactions that have been rejected.

OriginalTransactionKey

Some requests need to refer to a previously created transaction, as they perform an additional action upon them. In this field, the transaction key identifying the transaction can be specified.

StartRecurrent

Some services support recurring payments (identified by the action PayRecurrent). Before being able to do a recurrent payment, a normal payment needs to be made with this field set to true (the default value for this field is false).

ContinueOnIncomplete

Specifies if a redirect URL to a payment form will be returned to which a customer should be sent if no payment method is selected or if any required parameter that the customer may provide is missing or incorrect.
Possible values:

• No: The default. The request will fail if not all needed information is provided.
• RedirectToHTML: A redirect to the HTML gateway is provided if recoverable problems are detected in the request. The customer can then provide the needed information there.

Services

Specifies which service (can be a payment method and/or additional service) is being called upon in the request.

ServicesSelectableByClient

If no primary service is provided and ContinueOnIncomplete is set, this list of comma-separated service codes can be used to limit the number of services from which the customer may choose once they are redirected to the payment form. Only services entered in this field are selectable. This field is optional, and when empty or missing, the customer may choose any of the available services. The order in which the payment methods are listed also determines the order in which they are displayed to the customer on the Buckaroo checkout page.

ServicesExcludedForClient

If no primary service is provided and ContinueOnIncomplete is set, this list of comma-separated service codes can be used to limit the number of services from which the customer may choose once they are redirected to the payment form. Services entered in this field are not selectable. This field is optional.

PushURL

When provided, this push URL overrides all the push URLs configured in the payment plaza under websites for the associated website key.

PushURLFailure

When provided, this push URL overrides the push URL for failed transactions as configured in the payment plaza under websites for the associated website key.

ClientUserAgent

This tag can be used to tell the Payment Engine what the user agent of the client’s web browser is. This can be used for statistical purposes but also to perform anti-fraud checks on transactions.

OriginalTransactionReference

Some requests need to refer to a previously created transaction, as they perform an additional action upon them. In this field, an alternative reference to the original transaction can be provided.

CustomParameters

Custom variables. These are to be created manually first in the Buckaroo Payment Plaza.

AdditionalParameters

Additional parameters.

For a full overview of all available API calls and basic parameters, click here.

In addition to the basic variables, each service (like a payment method) can have additional service-specific variables that may be required in the request. These are explained in each of the payment methods and additional services sections.