Public developer API
POST /v1/card-payments
Creates a development-mode mock payment record in pending status. It never contacts Visa, Mastercard, a payment provider, or a merchant wallet.
Access
A project-specific API key (Authorization: Bearer dapi_live_...) and its Business ID (X-Business-Id). Rate limited per business (120 calls a minute by default).
Requires an Idempotency-Key header.
AVAILABLE ON 25 DECEMBER 2026. Before that date, this endpoint runs only outside production when CARD_PAYMENTS_MODE=mock is enabled. Production requests return 503 card_payments_not_available.
This route is also mounted at POST /api/v1/card-payments for compatibility; the standard API reference uses the /v1 base path.
The response includes mode: mock, liveProcessing: false and a placeholder checkout URL. No card is charged and no card numbers, CVV, PINs or track data may be sent.
Send an Idempotency-Key header. Status changes in development require a signed mock webhook callback; test events are not evidence of a real card transaction.
Body
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | yes | Positive payment amount, up to two decimal places. |
currency | string | yes | Supported three-letter currency code: USD, EUR, GBP, CAD, AUD, XAF, NGN, GHS, KES or ZAR. |
merchantReference | string | yes | Unique business reference, 4–64 letters, digits, dot, underscore, colon or hyphen. |
customer.name | string | no | Customer name. Never include card credentials. |
customer.email | string | no | Customer email address. |
description | string | no | Optional description, up to 140 characters. |
returnUrl | string | no | HTTPS URL for the hosted-checkout return. |
webhookUrl | string | no | HTTPS URL metadata for payment event delivery. |
Example request
curl --request POST \
--url 'https://production.dutchapi.co/v1/card-payments' \
--header 'X-Business-Id: YOUR_BUSINESS_ID' \
--header 'Authorization: Bearer bsk_live_YOUR_BUSINESS_SECRET' \
--header 'Idempotency-Key: card-payments-0001' \
--header 'Content-Type: application/json' \
--data '{"amount":25.5,"currency":"USD","merchantReference":"order-1042","customer":{"name":"Ada Example","email":"ada@example.com"},"description":"Order 1042","returnUrl":"https://merchant.example/return","webhookUrl":"https://merchant.example/webhooks/card-payments"}'Response 201
{
"id": "cp_mock_4c8f70a64b22458c8de92f3a",
"object": "card_payment",
"merchantReference": "order-1042",
"amount": 25.5,
"currency": "USD",
"status": "pending",
"checkoutUrl": "https://checkout.dutchapi.co/mock/cp_mock_4c8f70a64b22458c8de92f3a",
"createdAt": "2026-10-28T12:00:00.000Z",
"mode": "mock",
"liveProcessing": false
}Errors
| Status | error | Meaning |
|---|---|---|
| 400 | idempotency_key_required | Send an Idempotency-Key header. |
| 400 | valid_amount_required | amount must be positive and no greater than the documented limit. |
| 400 | unsupported_currency | currency is not on the supported mock currency list. |
| 400 | merchant_reference_required | merchantReference must be 4–64 valid characters. |
| 400 | card_data_prohibited | Card numbers, CVV, PIN and track data must never be sent. |
| 409 | duplicate_merchant_reference | This business already used merchantReference. |
| 503 | card_payments_not_available | Live card processing is not connected. |