Reference: POST /v1/charges

Cria uma cobrança. Cartão, Pix, boleto e wallets.

POST /v1/charges

Cria uma cobrança. É o endpoint mais usado da API Stone — cobre cartão, Pix, boleto e wallet.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`amount`	integer	sim	Valor em centavos. Ex: `1990` = R$ 19,90
`currency`	string	sim	ISO-4217. Atualmente apenas `BRL`
`payment_method`	string	sim	`credit_card` · `debit_card` · `pix` · `boleto`
`customer`	object	sim	Dados do pagador (nome, CPF/CNPJ, email)
`card`	object	condicional	Token ou dados do cartão
`installments`	integer	não	1–18. Default 1
`capture`	boolean	não	`true` (one-step) ou `false` (auth-only)
`split`	array	não	Até 15 recebedores
`reference_id`	string	não	Seu identificador (idempotente para conciliação)
`metadata`	object	não	Até 20 pares chave/valor

Resposta

Retorna um objeto Charge com status em: pending · authorized · paid · failed · refunded.

Erros comuns

402 card_declined — emissor recusou (veja detail para o motivo)
422 invalid_tax_id — CPF/CNPJ inválido
409 idempotency_key_reused — chave reusada com corpo diferente

cURL

curl -X POST https://api.stone.com.br/v1/charges \\
  -H "Authorization: Bearer $TOKEN" \\
  -H "Idempotency-Key: $(uuidgen)" \\
  -H "Content-Type: application/json" \\
  -d '{
    "amount": 1990,
    "currency": "BRL",
    "payment_method": "pix",
    "customer": {
      "name": "Maria da Silva",
      "tax_id": "11144477735",
      "email": "maria@example.com"
    },
    "reference_id": "pedido-1042"
  }'

Node.js

import Stone from '@stone/node';

const client = new Stone({
  clientId: process.env.STONE_CLIENT_ID,
  clientSecret: process.env.STONE_CLIENT_SECRET
});

const charge = await client.charges.create({
  amount: 1990,
  currency: 'BRL',
  payment_method: 'pix',
  customer: {
    name: 'Maria da Silva',
    tax_id: '11144477735',
    email: 'maria@example.com'
  },
  reference_id: 'pedido-1042'
}, { idempotencyKey: crypto.randomUUID() });

console.log(charge.pix.qr_code);

Python

from stone import Stone
import os, uuid

client = Stone(
    client_id=os.environ["STONE_CLIENT_ID"],
    client_secret=os.environ["STONE_CLIENT_SECRET"],
)

charge = client.charges.create(
    amount=1990,
    currency="BRL",
    payment_method="pix",
    customer={"name": "Maria da Silva", "tax_id": "11144477735"},
    reference_id="pedido-1042",
    idempotency_key=str(uuid.uuid4()),
)

print(charge.pix.qr_code)

Response `201 Created`

{
  "id": "ch_3M2k7eLwx9aB1cD2",
  "object": "charge",
  "status": "pending",
  "amount": 1990,
  "currency": "BRL",
  "payment_method": "pix",
  "customer": {
    "name": "Maria da Silva",
    "tax_id": "11144477735"
  },
  "pix": {
    "qr_code": "00020126360014BR.GOV.BCB.PIX0114+5511...6304ABCD",
    "qr_code_image": "data:image/png;base64,iVBORw0KGgo...",
    "expires_at": "2026-04-28T15:32:11Z"
  },
  "reference_id": "pedido-1042",
  "created_at": "2026-04-28T14:32:11Z",
  "request_id": "req_8K2x9Lp..."
}