Refunds

4 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.

Remaining refundable amount for a payment

GET/v1/payments/{id}/refundable

What can still be refunded on a succeeded payment: the captured amount minus succeeded, pending and unconfirmed refunds (pending and unknown refunds count as spent), with the amount in words. With amount, that amount is also returned in words for the confirmation step.

Authentication: API key (Bearer)
Permission: payment:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Query parameters

amountinteger
min 0

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/payments/cc33efd3-aae5-42f5-a0af-4878-6af/refundable" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Refund a payment (full or partial)

POST/v1/payments/{id}/refunds

Full or partial refund (integer minor units) through the processor that captured the payment. Checked under a row lock against what is still refundable; a retry with the same Idempotency-Key never refunds twice. The refund starts pending; its final status comes from the processor webhook or a status fetch. Audited.

Authentication: API key (Bearer)
Permission: refund:create
Idempotency-Key: Required
Success: 200

Path parameters

idstringrequired

Headers

Idempotency-Keystringrequired
Unique per logical operation: 8-255 characters of A-Z a-z 0-9 _ - : . Retrying with the same key returns the original result and never repeats the side effect; derive it from your own order/payment id.
min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

amountintegerrequired
greater than 0
reasonstring
max 500 chars

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

200 response fieldsRefund

idstring · uuidrequired
objectstringrequired
Alwaysrefund
paymentIdstring · uuidrequired
statusstringrequired
amountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
sourcestringrequired
createdAtstringrequired

Request · cURL

curl -X POST "$GIEP_API_URL/v1/payments/cc33efd3-aae5-42f5-a0af-4878-6af/refunds" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: refund-1042-1" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 4999
}'

{
  "id": "37386ae0-251d-4f38-a753-611e841d7",
  "object": "refund",
  "paymentId": "a7c488a4-4db8-4274-ad74-a9a8-710",
  "status": "succeeded",
  "amount": {
    "amount": 4999,
    "currency": "USD"
  },
  "source": "string",
  "createdAt": "2026-10-26T12:00:00.000Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Retrieve a refund

GET/v1/refunds/{id}

One refund: status (pending, succeeded, failed, unknown), amount, source and payment. unknown means the processor did not answer in time; it is reconciled and counts as spent meanwhile.

Authentication: API key (Bearer)
Permission: refund:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

200 response fieldsRefund

idstring · uuidrequired
objectstringrequired
Alwaysrefund
paymentIdstring · uuidrequired
statusstringrequired
amountobjectrequired
Amount in integer minor units of the currency.
Fields: 2 fields
- amountintegerrequired
- currencystringrequired
  3 chars
sourcestringrequired
createdAtstringrequired

Request · cURL

curl -X GET "$GIEP_API_URL/v1/refunds/cc33efd3-aae5-42f5-a0af-4878-6af" \
  -H "Authorization: Bearer $GIEP_API_KEY"

{
  "id": "37386ae0-251d-4f38-a753-611e841d7",
  "object": "refund",
  "paymentId": "a7c488a4-4db8-4274-ad74-a9a8-710",
  "status": "succeeded",
  "amount": {
    "amount": 4999,
    "currency": "USD"
  },
  "source": "string",
  "createdAt": "2026-10-26T12:00:00.000Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Refund several payments; per-item result

POST/v1/refunds/bulk

Up to 100 refunds, each with its own payment, amount and idempotency key. Items run in order, each through the single-refund checks; one failure never blocks or rolls back the others. The response lists a result per item.

Authentication: API key (Bearer)
Permission: refund:create
Idempotency-Key: Not used
Success: 200

Request body · application/jsonrequired

itemsarray<object>required
min 1 items · max 100 items
Each item has 3 fields
- paymentIdstring · uuidrequired
- amountintegerrequired
  greater than 0
- keystringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/refunds/bulk" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "paymentId": "a7c488a4-4db8-4274-ad74-a9a8-710",
      "amount": 4999,
      "key": "string"
    }
  ]
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}