Skip to main content
POST
Charge an invoice

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

invoiceID
string<uuid>
required

Invoice ID.

Body

application/json
method
enum<string>
required

Payment method for the charge.

Available options:
pix,
boleto,
card,
crypto

Response

Charge created.

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.