Payments
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:
- Start the payment. Your server calls
pay(). Buckaroo responds with a transaction key and, for most methods, a redirect URL. - Redirect the customer to that URL to complete the payment.
- The customer comes back to one of your return URLs. Use this to show a "thank you" or "payment failed" page.
- 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_urlSwap 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.
| Field | Required | Description |
|---|---|---|
currency | Yes | ISO currency code, such as EUR |
amount | Yes | The amount to charge |
invoice | Yes | Your unique invoice number |
description | Yes | Shown to the customer and in Plaza |
return_url | Yes | Where the customer is sent after paying |
return_url_cancel, return_url_error, return_url_reject | Yes | Where the customer is sent after cancelling, an error or a rejection. They can all point to the same page |
push_url | No | Where Buckaroo sends the push message. Falls back to the push settings in Plaza |
push_url_failure | No | A separate push URL for failed payments |
client_ip | Depends on the method | The customer's IP address. Required by some methods, such as the buy now, pay later methods |
culture | No | Language of the payment page, such as nl-NL |
service_parameters | Depends on the method | Fields 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.
| Exception | Raised when |
|---|---|
ParameterValidationError | A required field or service parameter is missing. Nothing was sent |
ValueError | Several required fields are missing, the mode is invalid, or a refund has no transaction key. Nothing was sent |
AuthenticationError | The keys are missing, or Buckaroo rejected them. Check the store key, the secret key and the mode |
BuckarooApiError | Buckaroo 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
BuckarooApiErrorcaused 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()Updated about 2 hours ago