Skip to main content
POST
Refund a payment

Authorizations

Authorization
string
header
required

Your account's secret key: Authorization: Bearer sk_test_… or sk_live_…. Server-side only.

Headers

Idempotency-Key
string

A unique key per operation (a UUID works). Retrying with the same key returns the original response.

Path Parameters

paymentID
string
required
Pattern: ^pay_[0-9A-Za-z]{22}$
Example:

"pay_585vbbvnwDyuyeA3MTOitd"

Body

application/json
amount
string

Amount to refund, as a decimal string. Empty or omitted refunds the full amount.

reasonCode
enum<string>
Available options:
requested_by_customer,
duplicate,
fraudulent,
product_issue,
other
reason
string

Reason for the refund, for your records.

Maximum string length: 1000
revokeAccess
boolean

Whether the buyer's digital-product download stops working. Omit it for the default, which fits almost every case: a full refund cuts access, a partial one keeps it. Send false to refund in full and let the buyer keep the file; send true to cut access on a partial refund. Once access is cut, the download link answers 410.

Response

The payment after the refund.

One charge attempt against an invoice. An invoice can have several payments.

id
string
required
Pattern: ^pay_[0-9A-Za-z]{22}$
Example:

"pay_585vbbvnwDyuyeA3MTOitd"

invoiceId
string
required
Pattern: ^inv_[0-9A-Za-z]{22}$
Example:

"inv_6yi30EKotIwGHZdePSdsFc"

provider
string
required

The processor the charge ran through. In sandbox, sandbox.

method
enum<string>
required
Available options:
pix,
card
amount
string
required

Amount charged, as a decimal string.

currency
string
required
status
enum<string>
required

pending awaits payment; confirmed was paid; failed was not paid (see failureCode); refunded was fully refunded; charged_back was disputed by the buyer with their bank.

Available options:
pending,
confirmed,
failed,
refunded,
charged_back
createdAt
string<date-time>
required
switchable
boolean
required

Whether this charge can still be dropped so the same invoice is paid another way: true while pending, false once paid or failed. Present only on the charge-creation response; treat a missing value as false.

providerId
string | null

The charge's reference at the processor, useful for support.

refundedAmount
string

Total refunded so far, as a decimal string. Absent when nothing was refunded. A partial refund keeps status at confirmed; only refunding the full amount sets refunded. Use this field, not status, to know how much went back.

failureCode
enum<string> | null

Why the charge failed. superseded is not a decline: the buyer switched payment method to pay the same invoice. Null when the payment did not fail or when no reason was recorded. New codes may appear; treat an unknown value as a generic failure.

Available options:
insufficient_funds,
do_not_honor,
card_declined,
authentication_required,
card_expired,
card_stolen,
card_invalid,
mandate_revoked,
mandate_refused,
brand_changed,
provider_error,
provider_timeout,
superseded,
null
failedAt
string<date-time> | null

When the charge moved to failed.

payer
object | null

Who paid. On a one-off invoice, id is the customer ID; on a subscription invoice, it is the ID of the customer's enrollment in the product. Present only on GET /billing/payments and GET /billing/payments/{paymentID}, and null when the invoice does not identify the customer.

invoiceUrl
string

Hosted payment page. Present only on the charge-creation response.

pixPayload
string

Pix copy-and-paste code. Render the QR from it. Still available on later reads of the payment.

pixQrImage
string

The Pix QR as a base64 PNG (no data: prefix), if you would rather not render it yourself.

pixExpiresAt
string<date-time> | null

When the Pix code expires (Pix charges only).

checkoutAction
object

What is needed to mount a card payment on an international sale through BEINFI LTD. Coming soon.