Refund a terminal payment
Initiate a refund for a completed terminal payment. The refund is sent to the same terminal that processed the original sale. `amount_minor` is optional — omit for a full refund. For partial refunds, specify the amount in minor units. The refund command is dispatched asynchronously. Subscribe to `billing.terminal_refund.succeeded` webhooks for the outcome. --- **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments` — List terminal payments - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `422 unprocessable_entity` — business-rule failure (for example, refunding more than the original charge). **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency).
Initiate a refund for a completed terminal payment. The refund is sent to the same terminal that processed the original sale.
amount_minor is optional — omit for a full refund. For partial refunds, specify the amount in minor units.
The refund command is dispatched asynchronously. Subscribe to billing.terminal_refund.succeeded webhooks for the outcome.
Related endpoints
POST /terminal-payments— Initiate a terminal paymentGET /terminal-payments— List terminal paymentsGET /terminal-payments/{id}— Retrieve a terminal paymentPOST /terminal-payments/{id}/cancel— Cancel a terminal paymentPOST /terminal-payments/{id}/void— Void a terminal payment
Common errors
404 resource_missing— the referenced resource does not exist or is not visible to your key.422 unprocessable_entity— business-rule failure (for example, refunding more than the original charge).
Idempotency
Pass an Idempotency-Key header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see the idempotency guide.
Your RevKeen merchant API key. Create and manage keys in Dashboard → Settings → Developer. Use rk_sandbox_* for staging/test and rk_live_* for production. The same key may be sent as Authorization: Bearer <key> if that suits your HTTP client better. A missing, invalid, expired, or revoked key returns 401 with a WWW-Authenticate: Bearer challenge; a valid key without the required scope returns 403.
In: header
Path Parameters
Terminal payment attempt ID of the original sale
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Parameters for refunding a completed terminal payment, optionally specifying a partial amount.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.revkeen.com/v2/terminal-payments/00000000-0000-0000-0000-000000000000/refund" \
-H "x-api-key: $REVKEEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_minor": 2500,
"reason": "Customer return"
}'{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32", "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940", "type": "sale", "status": "requested", "amount_minor": 0, "currency": "string", "reference": "string", "terminal_serial": "string", "uti": "string", "auth_code": "string", "response_code": "string", "rrn": "string", "card_scheme": "string", "masked_pan": "string", "entry_mode": "string", "error_message": "string", "created_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z" }}List terminal payments GET
List terminal payment attempts for the authenticated merchant. Supports filtering by invoice, status, type, and device. Uses cursor-based pagination. --- **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `401 authentication_error` — missing, invalid, expired, or revoked credential. Codes: `authentication_failed`, `invalid_api_key`, `expired_api_key`, `api_key_revoked`, `session_invalid`, `merchant_required`. Carries a `WWW-Authenticate: Bearer` challenge. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers.
Void a terminal payment POST
Void a completed terminal payment. Voids are always for the full amount — partial voids are not supported. The void is sent to the same terminal that processed the original sale. Voids are only possible for unsettled transactions. If the transaction has already settled, use a refund instead. The void command is dispatched asynchronously. Subscribe to `billing.terminal_void.succeeded` webhooks for the outcome. --- **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments` — List terminal payments - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `422 unprocessable_entity` — business-rule failure (for example, refunding more than the original charge). **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency).