Refunds

Refund a charge to return funds to the customer's card. You can refund the full amount or issue a partial refund. Refunds are processed back to the original payment method.

Creating a refund

API reference

To refund a charge, pass the charge resource name. The Idempotency-Key header lets you safely retry the request if it fails — see Idempotency.

Full refund

Omit the amount field (or set it to 0) to refund the full remaining amount:

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/refunds \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "charge": "accounts/acct_YOUR_ACCOUNT/charges/ch_CHARGE_ID",
    "reason": "CUSTOMER_REQUEST"
  }'

Partial refund

Set amount to refund a specific amount (in the smallest currency unit). You can issue multiple partial refunds against the same charge until the full amount has been refunded.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/refunds \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "charge": "accounts/acct_YOUR_ACCOUNT/charges/ch_CHARGE_ID",
    "amount": "5000",
    "reason": "CUSTOMER_REQUEST"
  }'

Response

{
  "name": "accounts/acct_YOUR_ACCOUNT/refunds/re_REFUND_ID",
  "state": "SUCCEEDED",
  "charge": "accounts/acct_YOUR_ACCOUNT/charges/ch_CHARGE_ID",
  "amount": "5000",
  "currency": "GBP",
  "reason": "CUSTOMER_REQUEST",
  "destination_details": {
    "card": {
      "type": "REFUND"
    }
  },
  "create_time": "2025-11-17T16:49:42Z",
  "update_time": "2025-11-17T16:49:45Z"
}

Retrieving a refund

API reference

curl https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/refunds/re_REFUND_ID \
  -H "Authorization: Api-Key $API_KEY"

Key fields

Field	Description
`charge`	Resource name of the charge being refunded (required)
`amount`	Amount to refund in smallest currency unit. Omit or set to `0` to refund the full remaining amount
`currency`	Three-letter ISO currency code (always matches the charge)
`reason`	Why the refund was issued: `CUSTOMER_REQUEST` or `FRAUD`
`metadata`	Key-value pairs for your own use (max 50 keys, key max 40 chars, value max 500 chars)

Refund states

State	Description
`PENDING`	Refund is being processed
`REQUIRES_ACTION`	An action must be performed to process the refund
`SUCCEEDED`	Funds have been returned to the customer
`FAILED`	Refund failed — see `payment_error` for details
`CANCELED`	Refund was canceled

In rare cases, a refund can transition from SUCCEEDED to FAILED if an error occurs during clearing (e.g. the cardholder closed their account). When this happens, the amount is returned to the merchant and the payment_error field is populated with details.

Charges after refund

When a charge is partially or fully refunded, its amount_refunded field reflects the total refunded amount, and refunded is set to true once the full amount has been refunded.

Webhooks

When a refund's state changes, a refund.updated event is sent to your webhook endpoints. This event fires on any state transition, not only on success. See Webhooks for setup instructions.