Refunds

Refund a payment

Refunds all or part of a paid payment.

POST/v1/payments/{payment_id}/refunds

Requires the refunds:write scope.

Without amount, everything still refundable is refunded; a payment can be refunded several times, never beyond what was paid. The refund is performed with the payment gateway before the answer is returned: succeeded (201), or pending (202) if the gateway's answer was lost, in which case the amount stays reserved and you must look at the refund (GET /refunds/{id}) before trying again. A refusal by the bank answers 402 refund_declined. A key can only refund payments of its own store and environment. Send an Idempotency-Key so that retrying can never refund twice.

curl https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/refunds \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b7e1c1c6-6f0a-4d2f-9d8b-3a5c2f1e7a90" \
  -d '{
  "amount": 150000,
  "reason": "Customer returned one item"
}'

Response201

{
  "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
  "object": "refund",
  "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "amount": 150000,
  "currency": "DZD",
  "status": "succeeded",
  "reason": "Customer returned one item",
  "failure": null,
  "fees": {
    "satim": 800,
    "rais": 200,
    "total": 1000
  },
  "livemode": false,
  "created": 1793000900
}

Request

Headers

Idempotency-Keystring

A unique value (at most 255 characters, a UUID is ideal) that makes the request safe to repeat: the same key with the same request returns the original answer without creating anything twice.

Path parameters

payment_idstringrequired

The id of the payment.

Body

Optional, JSON.

amountinteger

How much to refund, as an INTEGER in centimes (at least 100 = 1 DA). Defaults to everything still refundable.

reasonstring

Why you are refunding. For your records.

At most 255 characters.

Response

201The refund succeeded.

Returns the Refund object.

202The refund was sent but the gateway's answer was lost: status is pending and the amount is reserved.

Errors

Status	Code	Example message
400	`invalid_json`	The request body is not valid JSON.
400	`invalid_amount`	amount must be an integer number of centimes (500000 is 5,000.00 DA).
400	`amount_too_small`	The minimum amount is 50.00 DA (5000 centimes).
400	`refund_exceeds_balance`	The refund (500000 centimes) exceeds what can still be refunded (200000 centimes).
400	`insufficient_balance`	The store's balance is not sufficient to cover this refund and its fee.
400	`invalid_idempotency_key`	The Idempotency-Key header must be 1 to 255 printable ASCII characters.
401	`invalid_api_key`	Invalid API key provided.
402	`refund_declined`	The bank refused the refund.
403	`insufficient_scope`	This API key does not have the 'payments:write' permission.
403	`account_disabled`	This store is suspended or disabled.
403	`live_mode_not_enabled`	Complete business verification to take live payments.
404	`payment_not_found`	No such payment.
409	`payment_not_refundable`	Cannot refund a payment with status 'pending'.
409	`idempotency_in_progress`	A request with this Idempotency-Key is still being processed. Retry in a moment.
422	`idempotency_key_reused`	This Idempotency-Key was already used with different request parameters.
429	`rate_limit_exceeded`	Too many requests. Slow down and retry after the delay in the Retry-After header.
500	`internal_error`	Something went wrong on our side. Quote the request id to support.
503	`gateway_unavailable`	The payment gateway is temporarily unavailable. Please try again later.