Comprar créditos (cartão salvo)

POST

/v1/billing/purchase

Compra créditos cobrando um cartão salvo sem o cliente presente (off-session). Informe quantity (entre 250 e 1.000.000) ou plan_id (uuid de um pacote de GET /v1/billing/plans). Se card_id for omitido, usa o cartão padrão. status=succeeded já credita o saldo; processing confirma de forma assíncrona.
Idempotência: cada chamada gera uma compra/cobrança nova. NÃO faça retry cego — em timeout, consulte GET /v1/billing/invoices antes de repetir, para não comprar em duplicidade. Endpoint com rate-limit estrito (429).

Requisição

Authorization

Bearer Token

Forneça seu token bearer no cabeçalho

Authorization

ao fazer requisições para recursos protegidos.

Exemplo:

Authorization: Bearer ********************

Parâmetros Bodyapplication/jsonObrigatório

Exemplo

{
    "quantity": 250,
    "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
    "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304",
    "coupon": "string"
}

Códigos de solicitação

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location '/v1/billing/purchase' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "quantity": 250,
    "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",
    "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304",
    "coupon": "string"
}'

Respostas

🟢200

application/json

Compra registrada

Bodyapplication/json

Exemplo

{
    "status": "succeeded",
    "invoiceUuid": "d7b1f0c6-56bf-43f4-8d08-5baf1e1acebc",
    "total": 500,
    "quantity": 5000,
    "paymentIntentId": "pi_3ABC..."
}

🟠400

🟠402

🔴503

🟠401Unauthorized

🟠422ValidationError

🟠429TooManyRequests

Modificado em 2026-07-01 17:10:11