Refunds

Full and partial refunds — only when your provider supports them.

bash

curl https://api.onegate.am/v1/payments/pay_.../refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: refund-ORD-1001-1" \
  -d '{"amount": 2500, "reason": "customer request"}'

Idempotency-Key is required. Omit amount to refund the whole remaining balance.

Statuses

Status	Meaning
`created`	Reserved; being sent to the provider.
`pending`	The provider accepted it or has not confirmed the outcome yet. OneGate confirms it with the provider.
`completed`	The provider refunded the money.
`failed`	The provider rejected it, or it never reached the provider. The amount can be refunded again.
`cancelled`	Cancelled before completion.

Webhooks: refund.created, refund.completed, refund.failed, and payment.partially_refunded / payment.refunded on the payment.

Safety guarantees

Refunds can never exceed the payment amount, even under concurrent requests: the refundable amount is reserved atomically.
A timeout or unclear provider answer never counts as a failure. The amount stays reserved and OneGate confirms the outcome with the provider.
OneGate never re-sends a refund whose outcome is uncertain. If a provider cannot report refund status, the refund is flagged with requires_manual_action and failure_code refund_outcome_requires_review: confirm it in the provider's portal.

If a provider cannot refund through its API, OneGate returns refund_not_supported_by_provider: “Refund must be completed using the payment provider.” OneGate never pretends a refund succeeded.