canonical: https://jentic.com/apis/buckaroo.nl/buckaroo-nl

# Buckaroo Nl Buckaroo Checkout JSON Gateway API

Buckaroo's Checkout JSON Gateway is the European payment gateway API used by Dutch and EU merchants to create transactions across iDEAL, credit cards, SEPA Direct Debit, Bancontact, Klarna, and Apple Pay. The spec covers transaction creation, single and multi-key status polling, cancellation, refund and invoice lookup, KYC and verification data requests, and IBAN validation. This buckaroo.nl import describes the same gateway base URL exposed at checkout.buckaroo.nl and is the integration surface for online checkouts that need to settle in EUR through Buckaroo.

## For AI agents

Create and track payment transactions, run KYC data requests, and validate IBANs across European payment methods on the Buckaroo gateway.

## Scope

Does not handle merchant onboarding, payout reporting, or accounting reconciliation files - use for transaction creation, status, refunds, and IBAN validation only.

## Capabilities

- Create a payment transaction with iDEAL, card, SEPA Direct Debit, Klarna, or other Buckaroo-supported services
- Poll transaction status by key or fetch statuses for multiple transaction keys in one request
- Cancel a single transaction or batch-cancel multiple transactions in one call
- Fetch refund eligibility and pre-filled refund info for a transaction key before issuing the refund
- Retrieve credit invoice details by invoice key for finance reconciliation
- Run a Buckaroo data request for KYC, age verification, or address verification before payment
- Validate IBAN strings or convert Dutch BBAN to IBAN via the gateway tools endpoints

## Use cases

### Dutch and EU Online Checkout

Accept payments in EUR for Dutch and broader EU consumers by creating a transaction on `/json/Transaction` with the chosen Service such as ideal, paybycard, or sepadirectdebit. Buckaroo returns either a final status or a redirect URL the consumer follows to authorise the payment, after which the merchant polls `/json/Transaction/Status/{transactionKey}` until the transaction settles. End-to-end integration takes a few days when the merchant already has a Buckaroo contract.

Example prompt: POST to `/json/Transaction` with Services.ServiceList containing ideal, AmountDebit 49.99, Currency EUR, and the order Invoice number, then return the redirect URL

### Batched Status Reconciliation

Reconcile end-of-day transaction state by sending a list of transaction keys to `/json/Transaction/Statuses` to retrieve the current status for each in a single request. This is faster than polling each key individually, especially for merchants processing thousands of daily transactions, and feeds nightly batch jobs that update an internal ledger.

Example prompt: POST a list of transaction keys from the day's orders to `/json/Transaction/Statuses` and update the internal ledger with each returned status

### Pre-Payment KYC and IBAN Validation

Reduce failed direct debits and chargebacks by running a Buckaroo data request via postDataRequest for KYC, age, or address checks, and validating the consumer's IBAN with `/json/Tools/IbanConverter/{iban}` before submitting the payment. For Dutch BBAN inputs, `/json/Tools/BbanToIbanConverter/{bban}` converts to the full IBAN format required by SEPA. Validation happens in a single round trip.

Example prompt: GET `/json/Tools/IbanConverter/{iban}` with the customer-supplied IBAN and reject the checkout if the response indicates the IBAN is invalid

### AI Agent Payment Initiation Through Jentic

Allow an AI agent to initiate a Buckaroo payment on a user's behalf without holding the merchant's website key or secret key. Through Jentic, the agent searches for transaction creation, loads the postTransaction schema, and executes against `/json/Transaction` with the order details. The Buckaroo HMAC Authorization header is computed by Jentic from the secret stored in the vault so the credentials never enter the agent's context.

Example prompt: Use Jentic to search 'create a Buckaroo iDEAL payment', load the postTransaction schema, and execute with the order amount and Service ideal

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/json/Transaction` | Create a new payment transaction with a chosen service |
| GET | `/json/Transaction/Status/{transactionKey}` | Get the status of a single transaction |
| POST | `/json/Transaction/Statuses` | Get statuses for multiple transaction keys |
| GET | `/json/Transaction/Cancel/{transactionKey}` | Cancel a pending transaction |
| GET | `/json/Transaction/RefundInfo/{transactionKey}` | Retrieve refund eligibility and amount for a transaction |
| POST | `/json/DataRequest` | Run a KYC or verification data request |
| GET | `/json/Tools/IbanConverter/{iban}` | Validate an IBAN string |
| GET | `/json/Transaction/InvoiceInfo/{invoiceKey}` | Retrieve credit invoice details by invoice key |

## Key resources

- **Transactions** — Create, cancel, and inspect status of payment transactions across European payment methods
- **Data Requests** — Run KYC, age, and address verification data requests and fetch their service specifications
- **Refunds and Invoices** — Look up refundable amounts and credit invoice details for completed transactions
- **Tools** — Validate IBANs and convert Dutch BBANs to IBAN format

## Why Jentic

- **Setup:** Wiring the Buckaroo JSON Gateway by hand means computing the per-request HMAC-SHA256 Authorization header from your website key and secret and coordinating transaction, status, and refund endpoints yourself. Through Jentic you install once, import the Buckaroo Checkout JSON Gateway API from the API Directory, store the website key and secret once, and your agent calls it.
- **Permission scoping:** Buckaroo puts the transaction key in the URL path (`/json/Transaction/Status/{transactionKey}`, `/json/Transaction/Cancel/{transactionKey}`), so a rule can pin your agent to one transaction: it can read that transaction's status and refund info and nothing else. You choose the operations it may call, so creating a transaction is not included unless you add it.
- **Credential handling:** Your Buckaroo website key and secret are stored once, encrypted, by your own Jentic One instance, which computes the HMAC-SHA256 Authorization header at execution time. The secret never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an iDEAL payment', and Jentic returns the matching postTransaction operation with its Services schema so the agent calls `/json/Transaction` without browsing the reference docs.

## Related APIs

- **Buckaroo Checkout JSON Gateway API** — Same Buckaroo Checkout JSON Gateway sourced from the buckaroo.io vendor docs
- **Bud Financial API** — Open Banking aggregation that can verify account ownership before a SEPA Direct Debit
- **Buddy PT API** — Alternative payments-adjacent integration for a different European market

## FAQ

### What authentication does the Buckaroo Checkout JSON Gateway API use?

Buckaroo uses an apiKey-style Authorization header that contains an HMAC-SHA256 signature computed from the website key, secret key, request method, URL, timestamp, nonce, and request body hash. Through Jentic the website key and secret key are stored encrypted in the vault and the signature is computed at execution time so the secret key never enters the agent's context.

### Can I create an iDEAL payment with the Buckaroo API?

Yes. POST to `/json/Transaction` with Services.ServiceList containing ServiceName 'ideal', the AmountDebit, Currency 'EUR', Invoice number, and ClientIP. Buckaroo returns a RequiredAction with a RedirectURL for the consumer's bank, plus a transaction key you can poll on `/json/Transaction/Status/{transactionKey}` to confirm settlement.

### What are the rate limits for the Buckaroo API?

Buckaroo does not publish a global per-second rate limit in the spec. Production traffic is shaped by the merchant agreement and abuse-protection limits applied to the gateway. If a request is throttled the API returns an error response and clients should back off before retrying.

### How do I check a Buckaroo transaction status through Jentic?

Install the SDK with pip install jentic, search for 'check Buckaroo transaction status', load the getTransactionStatus schema, and execute it against `/json/Transaction/Status/{transactionKey}` with the transaction key. Jentic computes the HMAC Authorization header from the vault and returns the parsed status response.

### Can I refund a transaction with this API?

Yes. First call getTransactionRefundInfo on `/json/Transaction/RefundInfo/{transactionKey}` to confirm the refundable amount and pre-filled fields, then create a new refund transaction via `/json/Transaction` with the appropriate refund Service and the original transaction key in OriginalTransactionKey.

### Can I validate an IBAN before charging?

Yes. GET `/json/Tools/IbanConverter/{iban}` returns whether the IBAN is structurally valid and, where supported, the bank name. For Dutch BBAN inputs, `/json/Tools/BbanToIbanConverter/{bban}` converts to full IBAN. Use this before initiating SEPA Direct Debit to avoid downstream chargebacks for invalid account numbers.

### Can I limit what my agent is allowed to do with the Buckaroo Checkout JSON Gateway API?

Yes. Because you run Jentic One yourself, your own rules decide which Buckaroo operations and credentials the agent may use. Since Buckaroo puts the transaction key in the URL path, such as `/json/Transaction/Status/{transactionKey}` and `/json/Transaction/Cancel/{transactionKey}`, you can pin an agent to a single transaction so it only reads that transaction's status and refund info and nothing else. You choose the exact operations it may call, so creating a payment on `/json/Transaction` is excluded unless you explicitly allow it.