Criar cobrança

curl -X POST 'https://api.gates2b.com/charge' \  -H 'Content-Type: application/json' \  -d '{  "grossAmount": "49.90",  "currency": "BRL",  "paymentMethod": "PIX",  "externalReference": "pedido-0001",  "description": "Assinatura mensal",  "expiresAt": "2026-11-30T23:59:59Z"}'

{  "id": "0192f4c6-7d1e-7a3b-9c2d-4e5f6a7b8c9d",  "chargeId": "01JC8Z3R5W7Y9A1C3E5G7J9K2M",  "status": "PROCESSING",  "paymentMethod": "PIX",  "checkoutMeta": {    "url": "https://pay.gates2b.com/01JC8Z3R5W7Y9A1C3E5G7J9K2M",    "paymentMethod": "PIX",    "emv": "00020101021226810014br.gov.bcb.pix2559qr.example.com/v2/cobv/9d36b84f...6304A1B2",    "qr_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."  },  "checkoutUrl": "https://pay.gates2b.com/01JC8Z3R5W7Y9A1C3E5G7J9K2M",  "createdAt": "2026-10-22T14:00:00.000Z",  "updatedAt": "2026-10-22T14:00:00.000Z"}

Como funcionaCopiar link da seção

Uma cobrança guarda o que você vende: valor, moeda, externalReference, prazo e status. O pagamento em si acontece numa tentativa de pagamento, ligada à cobrança. Uma cobrança pode ter várias tentativas (um PIX que venceu, depois um cartão no checkout), mas só é paga uma vez.

Por isso o formato da resposta muda. Com PIX ou BANK_SLIP, a API cria a cobrança e a tentativa na mesma chamada e devolve a tentativa, que é onde estão o QR Code e o boleto. Sem paymentMethod, ou com CREDIT_CARD, nenhuma tentativa é criada agora: a resposta é a cobrança, e a tentativa nasce quando o pagador escolhe o meio e paga em checkoutUrl. Dados de cartão nunca passam por esta API.

Status da cobrançaCopiar link da seção

• Libere o pedido em PAID. Esse é o único status de cobrança paga.
• Cada reembolso, parcial ou total, dispara charge.refunded. O parcial mantém a cobrança em PAID e aumenta refundedAmount; ela só vai a REFUNDED quando o total reembolsado chega a grossAmount.
• Uma tentativa recusada (cartão negado, por exemplo) não muda a cobrança: ela continua PENDING e aceita nova tentativa até o prazo.
• Nas consultas, uma cobrança PENDING com expiresAt vencido já aparece como EXPIRED.
• CANCELED e FAILED também existem. Trate os dois como cobrança encerrada sem pagamento.

Em cripto há mais um status, PARTIAL: o pagador transferiu menos que o cotado. A cobrança continua aberta e vira PAID quando o restante chega. Detalhes em Cripto na cobrança.

RegrasCopiar link da seção

• A conta precisa ter a verificação cadastral concluída. Antes disso, a criação responde 403 com code KYC_PENDING.
• grossAmount é string com ponto e duas casas decimais: "49.90". Não envie vírgula nem notação científica.
• O pagamento é confirmado pelo evento charge.paid, entregue às suas inscrições de webhook. O campo webhookUrl é gravado na cobrança, mas hoje não recebe notificação. Veja Webhooks.
• Use externalReference para ligar a cobrança ao pedido no seu sistema. Ela volta no charge.paid.
• attemptIdempotencyKey impede tentativa duplicada: a mesma chave usada de novo na conta, em até 30 dias, responde 409 e nada novo é criado. Depois de um timeout, busque a cobrança pelo externalReference antes de criar outra com chave nova.

BoletoCopiar link da seção

• customerMeta.name, customerMeta.document e o customerMeta.address completo (zipcode, street, number, neighborhood, city, state) são obrigatórios. Faltando algum, a resposta é 400 com todos os campos ausentes na mensagem, e a cobrança não é criada.
• O boleto é emitido na hora. A resposta traz o boleto em checkoutMeta.bankSlip e um QR Code PIX que paga o mesmo valor em checkoutMeta.pix.
• bankSlip.value e bankSlip.fee são inteiros em centavos de real (15000 = R$ 150,00), enquanto grossAmount é string em unidades da moeda. Em cobrança USD ou EUR, o boleto cobra o valor convertido em reais.
• A API não devolve imagem do boleto. Gere o código de barras a partir de barcode (padrão Interleaved 2 of 5) e mostre digitableLine para copiar.
• Se o boleto não estiver habilitado na conta, a resposta é 400 com BANK_SLIP is not enabled for this account.

Repasse de tarifasCopiar link da seção

Com passthroughFees: true, grossAmount é o valor que você quer receber; o pagador paga esse valor mais as tarifas. A opção exige paymentMethod definido e não vale para CRYPTO. Sem ela, o pagador paga grossAmount e as tarifas saem do seu valor (netAmount).

SplitCopiar link da seção

• O split divide o netAmount, não o grossAmount. PERCENT é um percentual dele; FIXED, um valor fixo em string com duas casas.
• Cada parte vai para a conta dona do email. Se não houver conta com esse e-mail, a parte fica com você.
• splitSettlement mostra a divisão efetiva, em centavos, depois que a cobrança é paga.

CriptoCopiar link da seção

Com paymentMethod: "CRYPTO", a quantidade de itens em gatewayOptions.cryptoTickers muda o comportamento:

• Um ticker trava a moeda. A resposta já traz endereço, valor e QR Code em checkoutMeta.crypto, e a reserva de 20 minutos começa a contar na criação.
• Dois ou mais tickers, ou o campo omitido, deixam a escolha para o pagador no checkout. A resposta vem sem checkoutMeta.crypto e sem qr_image.

Em CRYPTO, checkoutMeta.redirectUrl é uma página de pagamento alternativa para a tentativa, não a URL de retorno que você enviou em gatewayOptions.redirectUrl. Mande o pagador para checkoutUrl.

Tickers aceitos, reserva, status e exibição do valor: Cripto na cobrança.