The Buckaroo Python SDK is a library for integrating the Buckaroo payment gateway into your Python applications. It supports 40+ payment methods through a fluent builder API with built-in HMAC authentication, retry logic, and full type hints.

Features

40+ payment methods (iDEAL, Credit Card, PayPal, Klarna, Apple Pay, and more)
Fluent builder pattern for clean, readable payment creation
Automatic HMAC SHA-256 request signing
Test and live environment support
Full type hint coverage for IDE autocompletion
Configurable retry logic and timeouts

Requirements

Python 3.8 or newer
requests >= 2.20 (optional but recommended)
typing_extensions >= 4.5.0 (required on Python < 3.11)

Download

Installation & Configuration

Installation

Install the SDK via pip:

pip install buckaroo-sdk

Or from source:

git clone https://github.com/buckaroo-it/BuckarooSDK_Python.git cd BuckarooSDK_Python pip install -r requirements.txt

API credentials

You need a Buckaroo store key and secret key. Find them in the Buckaroo Plaza under Settings → API Keys.

Store them as environment variables, never hard-code credentials in source files:

export BUCKAROO_STORE_KEY="your_store_key"
export BUCKAROO_SECRET_KEY="your_secret_key"

Contribute

We appreciate it when developers contribute to improving the Buckaroo plugins. If you want to contribute as well, then please follow our Contribution Guidelines.

Quick Start

This page gets you from zero to a working payment in under five minutes.

1. Initialize the client

import os
from buckaroo.app import Buckaroo

app = Buckaroo.quick_setup(
    store_key=os.environ["BUCKAROO_STORE_KEY"],
    secret_key=os.environ["BUCKAROO_SECRET_KEY"],
    mode="test",   # use "live" in production
)

quick_setup is the fastest way to get started. For advanced configuration (timeouts, retries, logging) see Configuration.

2. Create a payment

response = (
    app.payments.create_payment("ideal")
    .currency("EUR")
    .amount(25.50)
    .description("Order #1042")
    .invoice("INV-1042")
    .return_url("https://yourshop.com/return")
    .return_url_cancel("https://yourshop.com/cancel")
    .return_url_error("https://yourshop.com/error")
    .return_url_reject("https://yourshop.com/reject")
    .add_parameter("issuer", "INGBNL2A")   # pre-select bank; omit for bank picker
    .pay()
)

3. Handle the response

Most payment methods require a redirect to the bank or payment provider. Check requires_action() first:

if response.requires_action():
    redirect_url = response.get_redirect_url()
    # redirect the customer — store transaction_key in your database
    transaction_key = response.transaction_key

elif response.is_successful():
    print("Payment completed immediately")

elif response.is_pending():
    print("Awaiting customer action")

else:
    print(f"Payment failed: {response.status.code.description}")

4. Receive the result via push notification

Buckaroo posts the final payment status to your push_url. Parse the incoming payload with PushHandler:

5. Issue a refund

from buckaroo.models import TransactionContext

ctx = TransactionContext(original_transaction_key=transaction_key)

refund_response = (
    app.payments.create_payment("ideal")
    .currency("EUR")
    .amount(25.50)
    .description("Refund for Order #1042")
    .invoice("INV-1042")
    .return_url("https://yourshop.com/return")
    .return_url_cancel("https://yourshop.com/cancel")
    .return_url_error("https://yourshop.com/error")
    .return_url_reject("https://yourshop.com/reject")
    .refund(ctx)
)

Versioning

MAJOR: Breaking changes that require additional testing/caution.
MINOR: Changes that should not have a big impact.
PATCHES: Bug and hotfixes only.