API v1
Em breve · Cobranças

Criar cobrança no cartão

POST/v1/card-chargescharges:writeEM BREVE

Ainda não disponível: hoje toda chamada responde 403 card_unavailable e nada é criado; use Pix. Quando for liberado, cria um checkout de cartão de crédito hospedado. Envie ao pagador o card.checkout_url, que expira em 30 minutos. A confirmação chega pelo evento charge.paid, nunca pelo redirecionamento. O valor pago fica a liberar até a liberação da venda no cartão.

Este recurso ainda não está disponível. O contrato abaixo mostra como ele vai funcionar, para você planejar a integração. Hoje a chamada é recusada e nada é criado; os campos podem mudar até a liberação, que sai no changelog.

Cabeçalhos

Authorizationstringobrigatório

Bearer seguido da sua chave: gw_test_ em teste, gw_live_ em produção.

Idempotency-Keystring · 8–128obrigatório

Identificador único da tentativa, entre 8 e 128 caracteres ASCII visíveis.

Corpo da requisição

external_idstring · 1–128obrigatório
amount_centsinteger · mín. 1obrigatório

Valor inteiro positivo em centavos.

exemplo 4990 = R$ 49,90
descriptionstring · 1–200obrigatório

Aparece no checkout do cartão.

metadataobject · até 20 chavesopcional

Pares chave-valor seus, até 20 chaves e 2 KB. Gravados uma vez na criação e devolvidos em toda consulta e webhook. Não guarde dados pessoais aqui.

Resposta 201

Cobrança no cartão criada.

iduuid
external_idstring
method

PIX ou CARD (checkout no cartão).

PIXCARD
statusstring
CREATINGPENDINGPAIDFAILEDCANCELEDEXPIREDUNDER_REVIEWREVERSED
amount_centsinteger

Valor inteiro em centavos.

exemplo 4990 = R$ 49,90
fee_centsinteger

Valor inteiro em centavos.

exemplo 149 = R$ 1,49
net_amount_centsinteger

Valor inteiro em centavos.

exemplo 4841 = R$ 48,41
pixPixArtifact | null
3 campos
copy_pastestring
qr_code_urlurl | null
qr_code_base64string | null
cardobject | nullNOVO

Só em cobranças CARD. O link do checkout aparece enquanto a cobrança está PENDING. O valor pago fica a liberar até a liberação da venda no cartão.

2 campos
checkout_urlurl | null
checkout_expires_atdatetime | null
expires_atdatetime | null
paid_atdatetime | null
created_atdatetime
updated_atdatetime
settlementobject
3 campos
modestring | null
D0D1
sourcestring | null
GLOBALMERCHANTLEGACY
withdrawable_atdatetime | null
descriptionstring | nullNOVO
metadataobject · até 20 chavesNOVO

Pares chave-valor seus, até 20 chaves e 2 KB. Gravados uma vez na criação e devolvidos em toda consulta e webhook. Não guarde dados pessoais aqui.

product_iduuid | nullNOVO

Produto do catálogo que esta cobrança vendeu, quando criada a partir de um.

payerobject | nullNOVO

Quem você informou que pagaria, com o documento mascarado.

2 campos
namestring | null
document_maskedstring | null

Ex.: ***.456.789-**

paid_byobject | nullNOVO

Quem pagou, segundo o banco. Pode ser diferente de payer. null até o pagamento.

3 campos
namestring | null
document_maskedstring | null

Ex.: ***.456.789-**

bankstring | null
end_to_end_idstring | nullNOVO

ID fim a fim do Pix no Banco Central. null até o pagamento.

reversed_atdatetime | nullNOVO

Códigos de resposta

HTTPQuando acontece
201Cobrança no cartão criada.
202Resultado da criação incerto; revisão manual, nunca um segundo checkout.
400Requisição ou cursor inválido
401Chave ausente, inválida ou sem o escopo exigido
403Criação de cobrança desabilitada pela política efetiva de verificação da conta ou por um bloqueio operacional explícito. O campo error é merchant_not_operational.
409Conflito de identificador externo, idempotência ou operação em andamento
422Regra financeira impediu a operação
429Limite de requisições ou limite operacional da conta excedido. Para error operation_limit_exceeded, reasons identifica os limites efetivos atingidos; Retry-After só é garantido para rate_limit_exceeded.
503Serviço temporariamente indisponível