PIX

Criar uma cobrança

curl -X POST https://api.tamino.com.br/v1/pix/charges \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 5000,
    "payerDocument": "12345678900",
    "externalId": "pedido-12345"
  }'

const charge = await gateway.pix.create({
  amountInCents: 5000,
  payerDocument: '12345678900',
  externalId: 'pedido-12345',
});

{
  "id": "51119cde-7a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "object": "pix_charge",
  "externalId": "pedido-12345",
  "status": "pending_payment",
  "method": "pix",
  "amountInCents": 5000,
  "currency": "BRL",
  "merchantId": "0d303c3b-cb6d-417e-8aa7-2a5cc8fde653",
  "customerId": null,
  "description": null,
  "metadata": { "pixTxid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" },
  "txid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "qrCode": "00020101021226850014br.gov.bcb.pix2563...6304ABCD",
  "copyPaste": "00020101021226850014br.gov.bcb.pix2563...6304ABCD",
  "expiration": "2026-10-27T16:28:40.000Z",
  "createdAt": "2026-10-27T15:28:40.000Z",
  "updatedAt": "2026-10-27T15:28:40.000Z"
}

copyPaste é o código "Pix Copia e Cola" — ofereça como texto copiável e use ele pra desenhar o QR Code (qualquer lib de QR do seu frontend). qrCode normalmente traz o mesmo texto, mas em algumas configurações vem como imagem (data:image/png;base64,...) — não dependa do formato dele. expiration é a data/hora (ISO 8601) em que a cobrança deixa de poder ser paga.

Seu id do pedido (externalId) e timeout

Mande em externalId o id do pedido no seu sistema (até 64 caracteres: letras, números, ., _, : e -). Ele volta em todas as respostas da cobrança (criação e consulta; null se não enviado) e em todos os webhooks dela, e é único por merchant: repetir o POST com o mesmo externalId devolve a cobrança que já existe — mesmo id, mesmo QR Code/copyPaste — sem criar outra. O mesmo externalId com outro valor ou outro método responde 409.

Exceção: se a tentativa anterior falhou no provider e nenhum QR Code chegou a ser emitido, reenviar com o mesmo externalId tenta de novo na mesma cobrança (mesmo id) e devolve o QR Code novo.

Se o pedido der timeout ou erro de rede, você não recebe o nosso id, mas não perde a cobrança:

• consulte pelo seu id: GET /v1/pix/charges/external/{externalId} (404 = a cobrança não foi criada);
• ou simplesmente reenvie o mesmo pedido com o mesmo externalId — nunca nasce uma segunda cobrança.

Com uma API key do tenant (não presa a um merchant), passe ?merchantId= na consulta quando o mesmo externalId existir em mais de um merchant (senão a resposta é 400).

curl https://api.tamino.com.br/v1/pix/charges/external/pedido-12345 \
  -H "Authorization: Bearer sk_test_..."

Consultar

GET /v1/pix/charges/:id sempre reconsulta o status ao vivo — qrCode/copyPaste voltam de novo na resposta (não são descartados depois da criação):

const charge = await gateway.pix.get('pay_123');

Depois do pagamento, a consulta traz os dados do Pix e de quem pagou em metadata:

{
  "id": "51119cde-7a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "object": "pix_charge",
  "externalId": "pedido-12345",
  "status": "paid",
  "method": "pix",
  "amountInCents": 5000,
  "currency": "BRL",
  "merchantId": "0d303c3b-cb6d-417e-8aa7-2a5cc8fde653",
  "customerId": null,
  "description": "Order #1234",
  "metadata": {
    "reference": "order-1234",
    "pixTxid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "pixEndToEndId": "E00360305202610271530abcdef123456",
    "pixPaidAt": "2026-10-27T15:30:12.000Z",
    "payerIspb": "00360305",
    "pixPayer": {
      "name": "MARIA DA SILVA",
      "document": "12345678909",
      "documentType": "cpf",
      "ispb": "00360305",
      "bankName": "Caixa Econômica Federal"
    }
  },
  "txid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "qrCode": "00020101021226850014br.gov.bcb.pix2563...6304ABCD",
  "copyPaste": "00020101021226850014br.gov.bcb.pix2563...6304ABCD",
  "expiration": "2026-10-27T16:28:40.000Z",
  "createdAt": "2026-10-27T15:28:40.000Z",
  "updatedAt": "2026-10-27T15:30:13.000Z"
}

Os campos que você mandou em metadata na criação (ex.: reference) voltam iguais, junto com esses. O provider que processou o Pix nunca aparece na resposta.

Status

Saber quando foi pago

Uma cobrança PIX é assíncrona por natureza — o jeito confiável de saber que foi paga é o webhook pix.paid (ou payment.paid), não polling. Ver Webhooks.

Quando o PIX é pago, pix.paid/payment.paid trazem o objeto payer com os dados de quem pagou (nome, CPF/CNPJ, ISPB, banco, agência, conta — o que o banco do pagador informar), e GET /v1/pix/charges/:id passa a devolver os mesmos dados em metadata.pixPayer. Ver Webhooks.

Estornar

curl -X POST https://api.tamino.com.br/v1/pix/charges/51119cde-.../refund \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: refund-order-1234"

await gateway.pix.refund('51119cde-...');

Só funciona numa cobrança paid; o estorno de PIX é sempre total — o valor volta pra conta de quem pagou e sai do seu saldo.

Depois do estorno, o status continua paid (é o status do pagamento em si). O estorno fica registrado na própria cobrança: metadata.refundedAt (quando) e metadata.refundedAmountInCents (quanto). Um segundo pedido de estorno da mesma cobrança é recusado com 400. O webhook payment.refunded é enviado tanto pro estorno pela API quanto pelo Backoffice.

Expiração

Toda cobrança expira (expiration, ISO 8601) — depois disso ela não pode mais ser paga. O prazo default é curto (pensado pra checkout); se seu caso de uso precisa de uma cobrança de longa duração (cobrança com vencimento), fale com quem administra sua instância.