Every payment method uses the same pattern: payments.create_payment("<service code>", {...}) returns a builder, and an action such as .pay() sends the 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 one of your return URLs. 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

response = payments.create_payment(
    "ideal",
    {
        "currency": "EUR",
        "amount": 10.00,
        "invoice": "INV-1001",  # must be unique per payment
        "description": "Order #1001",
        "return_url": "https://example.com/buckaroo/return",
        "return_url_cancel": "https://example.com/buckaroo/cancel",
        "return_url_error": "https://example.com/buckaroo/error",
        "return_url_reject": "https://example.com/buckaroo/reject",
        "push_url": "https://example.com/buckaroo/push",
    },
).pay()

# Store the transaction key with your order so you can match the push message later
# save_transaction_key("INV-1001", response.key)

if response.requires_action():
    redirect_url = response.get_redirect_url()
    # redirect the customer to redirect_url

Swap ideal for another service code to use a different payment method. The same request can be built with chained methods:

response = (
    payments.create_payment("ideal")
    .currency("EUR")
    .amount(10.00)
    .invoice("INV-1001")
    .description("Order #1001")
    .return_url("https://example.com/buckaroo/return")
    .return_url_cancel("https://example.com/buckaroo/cancel")
    .return_url_error("https://example.com/buckaroo/error")
    .return_url_reject("https://example.com/buckaroo/reject")
    .push_url("https://example.com/buckaroo/push")
    .pay()
)

Shared fields

These fields are shared by all payment methods.

FieldRequiredDescription
currencyYesISO currency code, such as EUR
amountYesThe amount to charge
invoiceYesYour unique invoice number
descriptionYesShown to the customer and in Plaza
return_urlYesWhere the customer is sent after paying
return_url_cancel, return_url_error, return_url_rejectYesWhere the customer is sent after cancelling, an error or a rejection. They can all point to the same page
push_urlNoWhere Buckaroo sends the push message. Falls back to the push settings in Plaza
push_url_failureNoA separate push URL for failed payments
client_ipDepends 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
service_parametersDepends on the methodFields that belong to the payment method

The SDK checks the required fields before it sends anything, and raises an error when one is missing. It silently ignores top-level fields and service parameters it does not recognise, so check the spelling when a value does not reach Buckaroo.


Method fields

Fields that belong to one payment method go in service_parameters. The exception is the card brand, which is a top-level brand field:

response = payments.create_payment(
    "creditcard",
    {
        "brand": "visa",  # card brand: visa, mastercard, amex, maestro, ...
        "currency": "EUR",
        "amount": 10.00,
        "invoice": "INV-1002",
        "description": "Order #1002",
        "return_url": "https://example.com/buckaroo/return",
        "return_url_cancel": "https://example.com/buckaroo/cancel",
        "return_url_error": "https://example.com/buckaroo/error",
        "return_url_reject": "https://example.com/buckaroo/reject",
    },
).pay()
  • Payment methods and the API reference describe the parameters each method accepts
  • payments.get_available_methods() returns the service codes the SDK knows
  • The examples folder in the repository has runnable scripts

Read the response

Every action returns a PaymentResponse:

from buckaroo.models.payment_response import BuckarooStatusCode

response.key                      # the transaction key: store this
response.status.code.code         # the Buckaroo status code, such as 190
response.status.code.description

response.is_pending()             # status 790, 791, 792 or 793
response.is_failed()              # status 490, 491, 492 or 690
response.is_cancelled()           # status 890 or 891

response.requires_action()        # does the customer need to be redirected?
response.get_redirect_url()

response.get_some_error()         # readable error message, if any
response.to_dict()                # the full raw response

paid = (
    response.status is not None
    and response.status.code.code == BuckarooStatusCode.SUCCESS  # 190
)

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 the status code and get_some_error().
  • The request did not complete. The SDK raises an exception and you do not get a response.
ExceptionRaised when
ParameterValidationErrorA required field or service parameter is missing. Nothing was sent
ValueErrorSeveral required fields are missing, the mode is invalid, or a refund has no transaction key. 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 error response

ParameterValidationError, AuthenticationError and BuckarooApiError all extend BuckarooError.

from buckaroo import (
    AuthenticationError,
    BuckarooApiError,
    BuckarooError,
    ParameterValidationError,
)

try:
    response = payments.create_payment("ideal", order_fields).pay()
except (ParameterValidationError, ValueError) as e:
    raise SystemExit(f"Invalid input: {e}")
except AuthenticationError:
    raise SystemExit("Check your Buckaroo keys and mode.")
except BuckarooApiError:
    raise SystemExit("Buckaroo could not be reached. Please try again later.")
except BuckarooError as e:
    raise SystemExit(f"Payment could not be started: {e}")

if response.is_failed() or response.is_cancelled():
    # Buckaroo declined the payment
    raise SystemExit(f"Payment failed: {response.get_some_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

A card payment 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.

response = payments.create_payment(
    "creditcard",
    {
        "brand": "visa",
        "currency": "EUR",
        "amount": 10.00,
        "invoice": "INV-1003",
        "description": "Order #1003",
        "return_url": "https://example.com/buckaroo/return",
        "return_url_cancel": "https://example.com/buckaroo/cancel",
        "return_url_error": "https://example.com/buckaroo/error",
        "return_url_reject": "https://example.com/buckaroo/reject",
        "service_parameters": {
            "encryptedCardData": "ENCRYPTED_STRING",  # produced by the JavaScript library
        },
    },
).payEncrypted()


Did this page help you?