Quick start

This guide helps you create your first Sale at Buckaroo.

1. Choose an authentication method

You can authenticate with either:

• OAuth 2.0 access tokens (see Client Credentials)
• An API key in the Buck-Api-Key header

For ease of use we'll continue with API key authentication.

2. Use an API key

If you use API key authentication, include this header:

Buck-Api-Key: <your-api-key>

3. Make your first request

A simple starting point is retrieving your merchant account details:

GET /v1/merchant

Example request

curl -X GET "https://api.buckaroo.io/v1/merchant" \
  -H "Buck-Api-Key: <your-api-key>"

4. Creating your first Sale

Collecting payments can be done by creating Sales. You create one with:POST /v1/sales

Required fields

At minimum, a sale request includes:

• reference
• currency
• totalAmount
• sequenceType
• intentType

Example request

Example request with cURL:

curl -X POST "https://api.buckaroo.io/v1/sales" \
  -H "Buck-Api-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-10001",
    "currency": "EUR",
    "totalAmount": "49.95",
    "sequenceType": "OneOff",
    "intentType": "Pay",
    "description": "Order 10001",
    "paymentMethods": ["Pos"],
    "paymentMethodOptions": {
		  "pos": {
	      "terminalId": "t_abcd1234efgh5678"
	    }
	  }
  }'

5. Handle errors

Always check for problem responses such as:

• 400 when the request is invalid
• 401 when authentication is missing or invalid
• 404 when the resource does not exist

Example error:

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or invalid API key.",
  "errorCode": ""
}