API reference

Refunds

Refund a settled payment.

POST `/refunds`

Create a refund

Refund all or part of a settled payment. Omit amount for a full refund.

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	string (uuid)	Optional client-supplied UUID. The gateway caches the response for this key for the process lifetime; replays return the cached response.

Request body application/json required

Field	Type	Description
`amount`	object
`amount.amount` required	string	Decimal string in major units (e.g. "19.99", not 1999). Up to 4 decimal places.
`amount.currency` required	string	ISO-4217 alpha-3 currency code.
`provider_payment_id` required	string
`reason`	string	One of: `duplicate`, `fraudulent`, `requested_by_customer`, `expired_uncaptured`, `other`
`refund_id` required	string	Caller-assigned identifier; replays return the original response.

Responses

200 Refund result.
400 The request body or query failed validation. The response body lists each field-level issue. invalid_request
404 The named resource was not found. not_found
409 The resource is not in a state that allows this operation (e.g. capturing an already-voided charge). invalid_state

Request

curl -X POST "$KULPAY_URL/refunds" \
  -H "Authorization: Bearer $KULPAY_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "provider_payment_id": "pay_01J9X8K2Y3M4N5P6Q7R8S9T0V1",
  "reason": "requested_by_customer",
  "refund_id": "01J9X8K2Y3M4N5P6Q7R8S9T0V4"
}'

200 Response application/json

{
  "money": {
    "amount": "2.00",
    "currency": "MZN"
  },
  "processed_at": "2026-10-10T22:15:51Z",
  "provider_refund_id": "3KWPrnqkKWDuWJClOCrLq4csLVz",
  "refund_id": "rf-trace-1",
  "status": "succeeded"
}

400 Error · invalid_request application/problem+json

{
  "code": "invalid_request",
  "detail": "The request body failed validation.",
  "error": {
    "code": "invalid_request",
    "errors": [
      {
        "field": "money.amount",
        "message": "must be a positive decimal with at most 2 places"
      }
    ],
    "message": "The request body failed validation."
  },
  "errors": [
    {
      "field": "money.amount",
      "message": "must be a positive decimal with at most 2 places"
    }
  ],
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

404 Error · not_found application/problem+json

{
  "code": "not_found",
  "detail": "No payment with this id.",
  "error": {
    "code": "not_found",
    "message": "No payment with this id."
  },
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

409 Error · invalid_state application/problem+json

{
  "code": "invalid_state",
  "detail": "The payment is already captured.",
  "error": {
    "code": "invalid_state",
    "message": "The payment is already captured."
  },
  "status": 409,
  "title": "Conflict",
  "type": "about:blank"
}

Refunds

POST /refunds

Parameters

Request body application/json required

Responses

POST `/refunds`