Every payment method uses the same pattern: buckaroo.method('<service code>').<action>({...}).request(). Which fields the request takes depends on the payment method.


How a payment works

Most online payment methods follow the same flow:

  1. Start the payment. Your server calls pay(). Buckaroo responds with a transaction key and, for most methods, a redirect URL.
  2. Redirect the customer to that URL to complete the payment.
  3. The customer comes back to your return URL. Use this to show a "thank you" or "payment failed" page.
  4. Buckaroo sends a push message to your push URL. Use the push message to update the order.

Do not treat the customer returning to your return URL as proof of payment. The customer can close the browser or lose connection before they return.

The push message is always sent. See Push messages.


Start a payment

const response = await buckaroo
    .method('ideal')
    .pay({
        invoice: 'INV-1001', // must be unique per payment
        amountDebit: 10.0,
        description: 'Order #1001',
        returnURL: 'https://example.com/buckaroo/return',
        pushURL: 'https://example.com/buckaroo/push',
    })
    .request();

// Store the transaction key with your order so you can match the push message later
// await saveTransactionKey('INV-1001', response.getTransactionKey());

if (response.hasRedirect()) {
    res.redirect(response.getRedirectUrl());
}

The action builds the request, and .request() sends it and returns a promise.

Swap ideal for another service code to use a different payment method. For card payments, the service code is the card brand:

const response = await buckaroo
    .method('visa') // or 'mastercard', 'amex', 'maestro', ...
    .pay({
        invoice: 'INV-1002',
        amountDebit: 10.0,
    })
    .request();

Shared fields

These fields are shared by all payment methods. Each method can add its own.

FieldRequiredDescription
amountDebitYesThe amount to charge
invoiceRecommendedYour unique invoice number. The SDK generates one if you leave it out
currencyNoISO currency code. Defaults to the configured currency
orderNoYour order number. The SDK generates one if you leave it out
descriptionNoShown to the customer and in Plaza
returnURLFor redirect methodsWhere the customer is sent after paying. Defaults to the configured URL
returnURLCancel, returnURLError, returnURLRejectNoAlternative return pages
pushURLNoWhere Buckaroo sends the push message. Defaults to the configured URL, then to the push settings in Plaza
clientIPDepends on the methodThe customer's IP address. Required by some methods, such as the buy now, pay later methods
cultureNoLanguage of the payment page, such as nl-NL
customParameters, additionalParametersNoYour own key and value data. It is returned in the push message

Always pass your own invoice. A generated invoice number cannot be matched to your order when the push message arrives.

Write field names in camelCase, as in the table (amountDebit, originalTransactionKey). The API reference uses PascalCase (AmountDebit) because it describes the raw JSON request, which the SDK builds for you. The SDK silently ignores names it does not recognise, and it does not check that an amount is present: a request with AmountDebit: 10.0 is sent without an amount.


Service codes and method fields

  • The example folder in the repository has an example for each payment method
  • Payment methods and the API reference describe the parameters each method accepts
  • In TypeScript, the service codes and the fields of each method are typed, so your editor completes them

Read the response

pay(), refund(), authorize() and most other actions return a TransactionResponse:

response.isSuccess();            // status 190
response.isWaitingOnUserInput(); // status 790
response.isPendingProcessing();  // status 791
response.isAwaitingConsumer();   // status 792
response.isPendingApproval();    // status 794
response.isFailed();             // status 490
response.isValidationFailure();  // status 491
response.isRejected();           // status 690
response.isCanceled();           // status 890 or 891

response.hasRedirect();          // does the customer need to be redirected?
response.getRedirectUrl();

response.getTransactionKey();    // store this: you need it for refunds and lookups
response.getStatusCode();
response.getErrorMessage();      // the status description
response.data;                   // the full response

See Status and Substatus for what each code means.


Handle errors

A declined payment and a failed request are handled differently:

  • Buckaroo declined the payment. The request completed and you get a normal response. Check it with isSuccess(), isFailed() and the other status methods.
  • The request did not complete. The SDK throws an error and you do not get a response.

Every error extends BuckarooError. Check for a subclass to handle a specific cause:

ErrorThrown when
ParameterValidationErrorThe input is invalid, for example an unknown service code. Nothing was sent
AuthenticationErrorThe keys are missing, or Buckaroo rejected them. Check the store key, the secret key and the mode
BuckarooApiErrorBuckaroo could not be reached, the request timed out, or Buckaroo returned an HTTP error. The HTTP status and body are in error.httpStatus and error.body
import {
    AuthenticationError,
    BuckarooApiError,
    ParameterValidationError,
} from '@buckaroo/buckaroo_sdk';

try {
    const response = await buckaroo
        .method('ideal')
        .pay({ invoice: 'INV-1001', amountDebit: 10.0 })
        .request();

    if (response.hasRedirect()) {
        // redirect the customer to response.getRedirectUrl()
    } else if (!response.isSuccess()) {
        // Buckaroo declined the payment
        console.warn('Payment failed:', response.getStatusCode(), response.getErrorMessage());
    }
} catch (error) {
    if (error instanceof ParameterValidationError) {
        console.error('Invalid input:', error.message);
    } else if (error instanceof AuthenticationError) {
        console.error('Check your Buckaroo keys and mode.');
    } else if (error instanceof BuckarooApiError) {
        console.error('Buckaroo could not be reached:', error.httpStatus);
    } else {
        throw error;
    }
}

After a BuckarooApiError caused by a timeout or lost connection, Buckaroo may still have processed the payment. Wait for the push message before you retry, so the customer is not charged twice.


Encrypted card data

Card and Bancontact payments can be sent with the card data encrypted in the browser, using the JS Client Side Encryption SDK. The card data then never reaches your server unencrypted.

const response = await buckaroo
    .method('visa')
    .payEncrypted({
        invoice: 'INV-1003',
        amountDebit: 10.0,
        encryptedCardData: 'ENCRYPTED_STRING', // produced by the JavaScript library
    })
    .request();


Did this page help you?