Public developer API
POST /v1/card-payments/:id/refund
Marks an eligible succeeded mock payment refunded. This does not initiate a network refund or move money.
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. Refund requests operate only on mock records in non-production mode; no real card transaction can be refunded by this foundation.
The /api/v1/card-payments/:id/refund compatibility prefix is also available.
Example request
curl --request POST \
--url 'https://production.dutchapi.co/v1/card-payments/ID/refund' \
--header 'X-Business-Id: YOUR_BUSINESS_ID' \
--header 'Authorization: Bearer bsk_live_YOUR_BUSINESS_SECRET' \
--header 'Idempotency-Key: card-payments-0001'Response 201
{
"id": "cp_mock_4c8f70a64b22458c8de92f3a",
"status": "refunded",
"refundReference": "rf_mock_a813dfc7",
"refundedAt": "2026-10-28T12:30:00.000Z",
"mode": "mock",
"liveProcessing": false
}Errors
| Status | error | Meaning |
|---|---|---|
| 400 | idempotency_key_required | Send an Idempotency-Key header. |
| 403 | insufficient_scope | This project key is not allowed to do that. |
| 404 | card_payment_not_found | No payment with that id belongs to this business. |
| 409 | payment_not_refundable | Only a succeeded mock payment can be marked refunded. |
| 503 | card_payments_not_available | Mock refunds are disabled. |