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<uuid>
required

Body

application/json
amount
string

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

reason
string

Reason for the refund, for your records.

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<uuid>
invoiceId
string<uuid>
provider
string

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

providerId
string | null

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

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

Amount charged, as a decimal string.

currency
string
status
enum<string>

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
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.

createdAt
string<date-time>
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.

chargeToken
string

Single-use token for the crypto payment widget. Present only on a crypto charge response.

network
enum<string>

Crypto widget environment for this charge: main (real) or test.

Available options:
main,
test
settlementAsset
enum<string>

Asset the crypto charge settles in.

Available options:
USDC
settlementNetwork
enum<string>

Network the crypto charge settles on.

Available options:
base,
solana
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.

providerPixPayload
string

Sandbox only: the Pix code the test processor generated, for inspection. Not payable. In sandbox, pixPayload carries the test confirmation link.

sandboxConfirmUrl
string

Sandbox only: a page that marks this charge as paid without real money. Branch on whether this field is present, not on the shape of pixPayload. You do not need it to render: pixPayload is a QR in both environments.

pixExpiresAt
string<date-time> | null

When the Pix code expires (Pix charges only).

clientSecret
string

Temporary secret to confirm a card charge in the browser. Present only on the charge-creation response.

publishableKey
string

Public key paired with clientSecret. Present only on the charge-creation response.

nextAction
object

Data to complete a card charge in the browser. Present only on the charge-creation response.

switchable
boolean

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.