Refunds

Refund a charge to return funds to the customer's card. You can refund the full amount or issue a partial refund, except for Tap to Pay, which supports full refunds only. 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. Partial refunds are not supported for Tap to Pay.

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"
}

Tap to Pay refunds

For Tap to Pay, Synapto asks Softpay, the payment provider, to cancel the completed purchase. Softpay decides whether cancellation is permitted. This does not stop a payment that is still in progress.

Use the same CreateRefund endpoint from your server with payments.write access. Omit amount, set it to 0, or supply the full original purchase amount. The entire amount must remain refundable; a partial amount is rejected, never increased to a full refund.

Store the returned Refund name and track its state through GetRefund or refund.updated events:

• PENDING: the outcome is not yet known. Only SUCCEEDED confirms the refund. A destination_details.card.type of REVERSAL identifies a cancellation, not its success.
• FAILED: the provider rejected cancellation. Read payment_error. Synapto does not fall back to a separate credit refund.
• REQUIRES_ACTION with an unknown outcome: contact Synapto support with the Refund name. The amount remains reserved. Do not initiate another return of money.

Repeated full-refund requests return the existing pending, support-required, or successful reversal rather than start another cancellation.

Retrieving a refund

API reference

Use GetRefund for the current state. Retrying a creation request with the same idempotency key can return the original response, even if the state has since changed.

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

Key fields

Refund states

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.

A successful Tap to Pay cancellation leaves the Charge and Payment Intent in SUCCEEDED. Use the Refund and the charge's refunded amount to track the money returned, not a CANCELED payment state.

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.