---
title: "Reference: POST /v1/charges"
url: "https://devcenter.stone.com.br/reference-charges-create"
image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_~UmVmZXJlbmNlOiBQT1NUIC92MS9jaGFyZ2Vz,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii9yZWZlcmVuY2UtY2hhcmdlcy1jcmVhdGUi,s_2upTswcOcIcbN5PH.png"
---

## **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](#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](#resposta)

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

## [Erros comuns](#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

```bash
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

```javascript
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

```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`](#response-201-created)

```json
{
  "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..."
}
```

Siga a Stone nas redes sociais

[](https://www.facebook.com/stonepagamentos/)[](https://x.com/sejastone/)[](https://www.instagram.com/stone/)[](https://br.linkedin.com/company/stone-co)[](https://www.youtube.com/channel/UCk4L4JykgoDkN8YeuxkNqIQ)

© Stone Instituição de Pagamento S.A. CNPJ 16.501.555/0001-57

Av. Rebouças, 2880, 4º andar, Pinheiros, CEP 05.402-500 – São Paulo/SP

Instituição de pagamento autorizada pelo Banco Central do Brasil, nas modalidades de credenciadora e emissora de moeda eletrônica.