Skip to main content
POST
Pay invoice

Authorizations

Authorization
string
header
required

Biscuit-based bearer token. Obtain tokens from the Adaptyv Portal or via the /tokens endpoint. Tokens encode organization membership and role-based capabilities; the API verifies the token's cryptographic signature and authorization claims before processing requests. Use /tokens/attenuate to create restricted tokens for delegation.

Headers

X-Adaptyv-Payment-Method
string | null

Settlement method: mpp-spt or x402-exact. Omit to read the current invoice state and pay via the hosted URL instead. The methods an environment accepts are listed in payment.methods on the confirm response.

Path Parameters

invoice_id
string
required

Foundry invoice UUID or Stripe invoice ID (in_xxx)

Response

Invoice paid (or already paid)

Response returned by POST /invoices/{invoice_id}/pay.

Reports the invoice after the call, so no follow-up GET is needed. It is returned for three outcomes, which status and already_paid tell apart: a settlement this request performed, an invoice that was already paid, and — when no payment-method header was sent — the current state of an invoice that is still unpaid and that this call settled nothing on.

A 200 therefore does not by itself mean the invoice is paid. Read status. The 402 challenge is not this body.

already_paid
boolean
required

true when the call was a no-op because the invoice was already paid before this request.

false otherwise — which covers two different outcomes: this request settled the invoice, or no payment method was selected and the body reports the invoice's current state without settling. Read status to tell those apart; false alone does not mean the invoice is paid.

id
string
required

Stripe invoice ID (in_xxx) that was paid.

Example:

"in_1OqLk2LkdIwHu7ix6OboRpXl"

status
enum<string>
required

Current invoice status after the call. paid on success.

Available options:
draft,
open,
paid,
void,
uncollectible
hosted_invoice_url
string | null

Stripe-hosted invoice URL, when known.

Example:

"https://invoice.stripe.com/i/acct_1234/test_5678"

settlement_reference
object

Names what settled this invoice — the on-chain transaction for x402-exact, or the Stripe PaymentIntent for mpp-spt.

Only a response that performed the settlement can carry it, so it is absent when already_paid is true and absent from the state read of an unpaid invoice. Treat it as optional even on a settling response: when the rail reports nothing this API can name honestly, the field is omitted rather than guessed at.

Record it when you receive it. Repeating the call afterwards answers already_paid without the reference, and it is not available from any other endpoint.