Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

The control surface credential. Send Authorization: Bearer <token>.

Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ or puk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.

Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.

Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.

Body

application/json

Validated operation fields; monetary amounts are server-quoted.

requestId
string
required
quoteId
string
required
returnQuoteId
string
returnQuantity
integer
Required range: 1 <= x <= 1000

Response

Authoritative durable projection.

id
string
required
requestId
string
required
status
enum<string>
required
Available options:
pending,
unknown,
confirmed,
failed
currency
string
required
updatedAt
string<date-time>
required
principalMicros
string
required

Integer micros. One settlement-currency unit equals 1,000,000 micros.

Pattern: ^(0|[1-9][0-9]{0,17})$
taxMicros
string
required

Integer micros. One settlement-currency unit equals 1,000,000 micros.

Pattern: ^(0|[1-9][0-9]{0,17})$
feeMicros
string
required

Integer micros. One settlement-currency unit equals 1,000,000 micros.

Pattern: ^(0|[1-9][0-9]{0,17})$
totalMicros
string
required

Integer micros. One settlement-currency unit equals 1,000,000 micros.

Pattern: ^(0|[1-9][0-9]{0,17})$
paymentUrl
string<uri>
closeReason
enum<string>

Only with status failed: the Checkout was closed unpaid, not declined. abandoned = the customer came back without paying; replaced = a newer top-up was started; expired = Checkout timed out with no payment attempt. No failure notice is sent for these.

Available options:
abandoned,
replaced,
expired
returnQuoteId
string
returnQuantity
integer
Required range: x >= 0
quoteId
string
termsVersion
string
start
object

Present when this top-up was opened by POST /v1/minute/starts: the phone selection it pays for and where it stands.

taxBehavior
enum<string>
Available options:
exclusive