API do hub de pagamentos
Endereços: https://api-payments.abeesys.com, https://api-payments.dev.abeesys.com. Nos exemplos, $HUB_URL é o endereço do seu ambiente.
Contrato 0.14.0 · OpenAPI 3.1.0 · baixar o openapi.yaml
Visão geral do contrato
Hub de pagamentos da plataforma Abeesys. Cada sistema cliente (tenant) se autentica com a própria API key e só enxerga o que é seu.
Autenticação. Toda rota de negócio exige a API key (Authorization: Bearer <key>). As exceções são as de saúde, os avisos de gateway (webhooks, autenticados pela assinatura), o retorno da autorização do recebedor e as quatro rotas de documentação (/openapi.yaml, /openapi.json, /llms.txt, /llms-full.txt), que não levam dado de sistema nenhum e só respondem pela rede privada e pelo endereço local — pedidas por um endereço público, são 404 (desde a 0.13.0; quem as publica é o portal de documentação).
Valores sempre em unidade mínima da moeda (centavos para BRL), inteiros, com a moeda ISO 4217 ao lado. Nunca decimal.
Erros seguem a RFC 9457 (application/problem+json), com type em https://abeesys.com/errors/<slug>.
O sistema pede o quê; o hub decide como. O sistema informa valor, meio, pagador e referência — nunca o gateway. O hub escolhe o gateway pela política de roteamento do sistema (ordem de preferência por meio, configurada por quem opera a plataforma), entre as contas que o próprio sistema conectou. O gateway que atendeu aparece na resposta, como informação para suporte e conciliação.
Avisos. A cada mudança de cobrança o hub envia um aviso assinado ao endereço que o sistema cadastrou com quem opera a plataforma — ver webhooks.chargeUpdated.
Estornos. O sistema pede o estorno de uma cobrança capturada, inteiro ou em partes (POST /api/v1/charges/{id}/refunds). O estorno é feito no mesmo gateway e na mesma conta em que a cobrança foi criada. Estornos feitos no painel do gateway também aparecem, com origin provider_dashboard.
Taxas do gateway. O gateway informa a taxa de cada cobrança — da captura e, quando cobra, de cada estorno — e o hub a lança no ledger (provider_fee; a correção que o gateway fizer depois entra como provider_fee_adjustment, para mais ou para menos). O saldo da carteira passa a ser o líquido: bruto menos as taxas lançadas. Enquanto o gateway não informa a taxa da captura, a cobrança mostra a taxa como pending, nunca como zero. A taxa não gera aviso: consulte a cobrança ou a carteira.
Conta da plataforma e subconta virtual (desde a 0.8.0, ADR 0007). Para cada gateway que a política tenta, a cobrança vai na conta do próprio sistema, se ele tem credencial naquele gateway; se não tem, e o sistema é da Lopes Tech (mesmo CNPJ) e foi liberado por quem opera, vai na conta da plataforma daquele gateway, e o valor capturado fica na subconta virtual do sistema. settles_in diz qual dos dois, como informação. O fallback é sempre entre gateways, nunca entre contas do mesmo gateway. O saldo e o extrato da subconta saem em GET /api/v1/subaccounts e GET /api/v1/subaccounts/entries, separados das carteiras; os lançamentos do modo plataforma não aparecem em GET /api/v1/ledger/entries, que é a listagem das carteiras espelho. O repasse do saldo da subconta é feito por quem opera, fora do hub, e registrado nele: aparece no extrato e no aviso subaccount.payout.
Endereço de volta do cartão (desde a 0.9.0). Há gateway que, quando o emissor pede uma autenticação extra (3-D Secure), devolve a ação ao pagador só se souber para onde ele volta depois. O formulário de cartão declara isso em return_url_required; quando true, a cobrança de cartão daquele formulário exige card.return_url (422 nomeando o campo, sem chamar o gateway). Para os outros gateways o campo é aceito e ignorado.
Split — venda dividida com um recebedor (desde a 0.10.0, spec 0017). O sistema cadastra o recebedor (POST /api/v1/recipients) e pede a autorização da conta dele no gateway (POST /api/v1/recipients/{id}/links): o recebedor autoriza a conta dele numa página do gateway e volta ao endereço que o sistema informou, com status=linked ou status=failed. Na cobrança, split diz a parte do recebedor, em valor ou em pontos-base; o resto é a comissão do sistema. A cobrança nasce na conta do recebedor no gateway (settles_in recipient_account) e a comissão vai como taxa de marketplace para a conta da plataforma, alocada na subconta virtual do sistema. A parte do recebedor nunca passa pela conta da plataforma. Por enquanto: um recebedor por cobrança e a taxa do gateway na conta do recebedor.
Estorno e disputa de cobrança dividida (desde a 0.11.0, spec 0061). O estorno, inteiro ou parcial, é proporcional à divisão: devolve a parte do recebedor e a comissão na proporção da cobrança. O centavo do arredondamento fica com a comissão até o fim (a comissão devolve o piso da proporção acumulada), e quando tudo foi devolvido cada parte voltou inteira. O estorno confirmado traz as duas partes em split, e a cobrança, o total devolvido de cada uma (split.refunded_recipient_amount, split.refunded_commission). A disputa perdida também é proporcional quando o gateway devolve a comissão; quando ele a mantém na conta da plataforma, a disputa fica em análise de quem opera, e a cobrança continua disputed. Sistema declarado marketplace por quem opera só cobra pela conta da plataforma com divisão: sem split, 422 no campo split.
Listas abertas. Os campos de saída documentados como lista aberta podem trazer valores novos sem aviso prévio: o sistema trata o valor desconhecido como genérico, sem recusar a resposta. São eles: o tipo do aviso, failure_reason da cobrança, kind do lançamento, status, origin, reason e failure_reason do estorno, fee.status e fee.origins[].origin da cobrança, settles_in da cobrança, e kind, counterparty.type e payout.status do extrato da subconta, e status e deactivation_reason do vínculo de recebedor. O status da cobrança é conjunto fechado.
Correlação (desde a 0.12.0). Toda resposta traz X-Request-Id: 32 caracteres hexadecimais minúsculos, gerados pelo hub a cada requisição. É a referência do detail de um 500 e o que quem opera procura no log; informe-a ao suporte. O X-Request-Id que o sistema enviar não é devolvido nem substitui o do hub: fica registrado à parte, só para casar com o log do sistema (antes da 0.12.0, o hub ecoava o valor recebido).
Cabeçalhos de segurança (desde a 0.12.0). Toda resposta traz também Strict-Transport-Security, X-Content-Type-Options: nosniff e Referrer-Policy: no-referrer.
Corpo acima do limite (desde a 0.12.0). Nas rotas de aviso de gateway, corpo acima de 1 MiB é 413 payload-too-large.
Limite de taxa (desde a 0.14.0). Acima do limite, a resposta é 429 rate-limited, com Retry-After em segundos inteiros e o mesmo número no detail. Nas rotas com API key, nada é gravado, nenhum gateway é chamado e a Idempotency-Key não é consumida: repetir depois tem o efeito de sempre. Nos avisos de gateway, nada é gravado; o 429 por origem e o de assinatura inválida saem antes de a assinatura ser conferida, e o gateway reenvia. Os limites valem por sistema (API key) e por endereço de origem — em toda rota, menos as de saúde, inclusive rota inexistente. Tentativas repetidas de key inválida, ou de assinatura inválida num mesmo endereço de aviso, bloqueiam a origem por um tempo: a origem bloqueada recebe 429 sem a key (ou a assinatura) ser conferida, e o 429 não revela se a key existe. Os números são configuração da plataforma e não fazem parte do contrato.
Autenticação
As rotas da API levam a API key do tenant no cabeçalho Authorization: Bearer <key>. Sem chave, ou com chave inválida: 401. A chave é entregue uma vez, a quem opera o sistema; nenhuma página deste site pede ou mostra chave.
apiKey: http bearer — API key do tenant (abs_live_...), gerada pelo CLItenant create.
Sem API key: GET /api/v1/health, GET /api/v1/health/ready, GET /api/v1/recipient-links/callback, POST /api/v1/webhooks/{provider}/{tenantID}, POST /api/v1/marketplace-webhooks/{accountID}, POST /api/v1/platform-webhooks/{accountID}.
curl "$HUB_URL/api/v1/charges/<id>" \
-H "Authorization: Bearer $HUB_KEY"Erros
Todo erro sai como application/problem+json (RFC 9457), com type, title, status e detail; no 422, também errors[]. Id de outro tenant responde 404, igual a um id que não existe.
- 429 RateLimited — acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
https://abeesys.com/errors/rate-limited - Health — estado do serviço
- 404 NotFound — recurso inexistente — ou de outro sistema, ou rota de documentação pedida por endereço público
https://abeesys.com/errors/not-found - 413 PayloadTooLarge — corpo acima de 1 MiB (1048576 bytes)
https://abeesys.com/errors/payload-too-large - 422 Problem — erro (RFC 9457)
https://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable
Outras
GET /api/v1/health
Liveness — não toca no banco
Sem API key.
Respostas
- 200 estado do serviço
application/jsonobjeto
GET /api/v1/health/ready
Readiness — confere o banco
Sem API key.
Respostas
- 200 estado do serviço
application/jsonobjeto - 503 estado do serviço
application/jsonobjeto
GET /api/v1/charges
Lista as cobranças do tenant, da mais recente à mais antiga
Exige a API key do tenant.
Só as cobranças do sistema autenticado, com qualquer filtro: a referência de um pedido de outro sistema devolve lista vazia, não erro.
Os filtros são opcionais e se combinam com E. Ordem total: created_at decrescente e, no empate, id decrescente — uma cobrança nunca aparece em duas páginas nem falta entre elas enquanto o conjunto não muda. Página além do fim devolve items vazio, com o total.
Percorrer sem deslocamento. Uma cobrança criada durante a leitura entra no topo e desloca as páginas seguintes. Para percorrer um conjunto fixo, guarde o instante da primeira consulta e mande-o em created_to em todas as páginas: o que nasce depois fica fora da janela.
Parâmetro que não está aqui, parâmetro repetido, ou valor fora do que o parâmetro aceita (status inexistente, gateway que o hub não conhece, data inválida, created_from igual ou depois de created_to, página fora da faixa, texto fora de UTF-8): 422, com o parâmetro em errors[].field — escapado como na URL (%FF) quando o próprio nome não é UTF-8. Query string malformada: 400.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
status | query | ChargeStatus pending authorized captured refunded failed canceled disputed | não | |
provider | query | string de 1 a 40 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$ | não | O gateway que atende a cobrança. Gateway que o hub não conhece é 422. |
reference | query | string de 1 a 255 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$ | não | A referência do pedido, por igualdade exata. Devolve todas as tentativas. |
created_from | query | string formato date-time | não | Criadas a partir deste instante, inclusive. |
created_to | query | string formato date-time | não | Criadas antes deste instante (exclusivo). |
page | query | integer de 1 a 10000 · padrão 1 | não | |
page_size | query | integer de 1 a 100 · padrão 20 | não |
Respostas
- 200 página de cobranças
application/jsonobjeto - 400 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 422 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
POST /api/v1/charges
Cria uma cobrança — o hub escolhe o gateway
Exige a API key do tenant.
Idempotente pela Idempotency-Key, única por tenant. Mesma chave e mesmo corpo devolvem a cobrança original com 200, sem chamar gateway nenhum — qualquer que tenha sido o gateway que a atendeu, e mesmo que a política tenha mudado depois. Mesma chave com outro corpo é 409.
Roteamento. O hub tenta o primeiro gateway da política daquele meio que aceita o valor e as condições (parcelas, validade do pix, vencimento do boleto). Se ele recusar antes de criar a cobrança (fora do ar, com certeza de que nada foi criado), o hub tenta o próximo. Nunca depois de um timeout: aí a cobrança fica pending naquele gateway. Se nenhum gateway da política atende o meio, o valor e as condições — inclusive política vazia —, 422 no-route, sem nome de gateway.
A cobrança nasce pending; a mudança de status chega pelo webhook do gateway. Se o gateway não responder (502), a cobrança fica pending — timeout não prova recusa — e é resolvida pelo webhook ou pela conciliação.
Pagador. Cada gateway exige um subconjunto diferente do pagador para cada meio (por exemplo: pix pede nome, e-mail e documento; boleto pede também o endereço). O hub confere contra o gateway escolhido antes de chamá-lo e responde 422 nomeando o campo que falta (errors[].field, como payer.email) — sem procurar outro gateway que exija menos. Texto vazio equivale a ausente.
Cartão. O hub nunca recebe número, validade nem código do cartão: só o token gerado pelo formulário do gateway no navegador do pagador. Antes, o sistema pede ao hub o formulário (POST /api/v1/card-forms) e manda de volta card.form_id: a cobrança vai ao gateway daquele formulário — sem fallback, porque o token não serve em outro —, mesmo que ele tenha saído da política depois, desde que a conta continue conectada; senão, 422 em card.form_id. O token é de uso único e não é guardado; a repetição com a mesma Idempotency-Key devolve a cobrança sem reenviá-lo. Parcelas acima do que o gateway aceita, ou em gateway que não parcela, são 422. Quando o gateway exige uma ação do pagador (3-D Secure), a cobrança fica pending e a resposta traz card.action_url.
Gateway indisponível. 502 em dois casos, com detail diferente: (1) o gateway não respondeu — a cobrança fica pending, e pode ter sido criada lá; consulte-a antes de tentar de novo; (2) todos os gateways possíveis recusaram antes de criar — a cobrança fica failed com failure_reason provider_unavailable, e nada foi cobrado.
Recusa do gateway (cartão negado, token gasto ou expirado) não é erro HTTP: a cobrança volta com status failed e failure_reason.
card, pix e boleto só valem para o method de mesmo nome; enviados com outro meio, 422.
Referência e metadados. reference é o pedido no sistema (não é única: um pedido pode ter várias tentativas) e metadata é um conjunto pequeno de pares chave-valor. O hub não interpreta nenhum dos dois, devolve-os em toda leitura e em todo aviso da cobrança, e não os muda depois da criação. Eles fazem parte do corpo para a idempotência: mesma chave com outra referência ou outros metadados é 409 (a ordem das chaves de metadata não importa).
Divisão (desde a 0.10.0). Com split, a cobrança vai ao primeiro gateway da política com split nativo em que o recebedor tem vínculo ativo, e nasce na conta dele. Nenhum gateway da política com split nativo: 422 capability-not-supported; o recebedor sem vínculo em nenhum deles: 422 no-route. Recebedor que não existe ou é de outro sistema: 422 em split.recipients[0].recipient_id. A divisão faz parte do corpo para a idempotência.
Nenhum campo aceita null: para não informar, omita o campo. null em qualquer nível é 422 nomeando o campo.
O corpo precisa ser UTF-8 válido (RFC 8259); fora disso, 400 — o hub não troca bytes em silêncio. Idempotency-Key fora de UTF-8 ou com caractere de controle é 422.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
Idempotency-Key | header | string de 1 a 255 caracteres | sim |
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | integer formato int64 · mínimo 1 | sim | Unidade mínima da moeda. Em cartão parcelado é o total — o hub não calcula juros de parcelamento. |
currency | string padrão ^[A-Z]{3}$ | sim | |
method | string card pix boleto | sim | |
description | string máximo 500 caracteres · padrão ^[^\x00]*$ | não | Quebra de linha vale; o caractere NUL (\\u0000) é 422. |
payer | Payer | não | |
card | CardInput | não | |
pix | PixInput | não | |
boleto | BoletoInput | não | |
reference | Reference | não | |
metadata | Metadata | não | |
device_id | string máximo 255 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$ | não | Identificador antifraude do dispositivo do pagador, quando o gateway usa um. O hub o repassa sem interpretar e não o guarda. |
split | SplitInput | não |
Respostas
- 200 repetição da mesma Idempotency-Key — a cobrança original
application/jsonCharge - 201 criada
application/jsonCharge - 400 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 409 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 422 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited - 502 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable
POST /api/v1/recipients
Cadastra um recebedor do sistema
Exige a API key do tenant.
Desde a 0.10.0 (spec 0017). O recebedor é quem fica com a parte de uma venda dividida — a loja parceira, o prestador —, numa conta em nome próprio no gateway. É do sistema que o cadastrou: o de outro sistema é 404.
Idempotente pela reference (o id do recebedor no seu sistema), única por sistema: a mesma referência com o mesmo nome devolve o recebedor já cadastrado com 200; com outro nome, 409. O recebedor nasce sem vínculo: a conta dele no gateway entra pela autorização (POST /api/v1/recipients/{id}/links).
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string de 1 a 100 caracteres | sim | |
reference | string de 1 a 255 caracteres | sim | o id do recebedor no seu sistema — única por sistema |
Respostas
- 200 a mesma referência — o recebedor já cadastrado
application/jsonRecipient - 201 cadastrado
application/jsonRecipient - 400 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 409 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 422 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /api/v1/recipients/{id}
Consulta um recebedor do sistema, com os vínculos
Exige a API key do tenant.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim |
Respostas
- 200 o recebedor
application/jsonRecipient - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 404 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
POST /api/v1/recipients/{id}/links
Abre a autorização da conta do recebedor num gateway
Exige a API key do tenant.
Devolve a página do gateway onde o recebedor autoriza a conta dele para o marketplace da plataforma. O sistema leva o recebedor até ela; o recebedor autoriza lá e volta a return_url, com status=linked (vínculo gravado) ou status=failed (negado, código recusado, ou a conta já vinculada a outro recebedor). O link vale até expires_at e serve uma vez.
O vínculo gravado gera o aviso recipient.link_updated. Um vínculo ativo por recebedor em cada gateway; a mesma conta autorizada de novo é o mesmo vínculo. A mesma conta do gateway não se vincula a dois recebedores — nem de sistemas diferentes.
Só para sistema que pode usar a conta da plataforma (o marketplace é dela). Gateway sem split nativo: 422 capability-not-supported. Sem o marketplace neste ambiente, ou sistema que não pode usar a conta da plataforma: 422 no campo provider.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim |
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
provider | string | sim | |
return_url | string máximo 2048 caracteres · padrão ^https://[^/\s][^\s]*$ | sim | para onde o recebedor volta, com status=linked ou status=failed |
Respostas
- 201 a página de autorização
application/jsonRecipientLinkAuthorization - 400 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 404 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 422 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /api/v1/recipient-links/callback
Volta da autorização do recebedor — quem chama é o navegador dele
Sem API key.
Rota pública: o gateway manda o navegador do recebedor de volta para cá. Sem API key — o state, de uso único e vida curta, é o que identifica o sistema e o recebedor; nada mais da query decide de quem é o vínculo. state inválido, vencido ou já usado: 400, e nada é gravado. Válido: 302 para o return_url informado na abertura, com status=linked ou status=failed.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
state | query | string máximo 128 caracteres | sim | |
code | query | string | não |
Respostas
- 302 de volta ao sistema, com
status - 400 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
POST /api/v1/card-forms
Qual formulário de cartão usar para esta cobrança
Exige a API key do tenant.
O sistema pergunta "vou cobrar cartão de R$ X" e o hub responde com o gateway, a chave pública do formulário dele e o que ele exige — o máximo de parcelas e os campos do pagador. O sistema monta o formulário do gateway no navegador do pagador com a public_key, recebe o token e cria a cobrança com card.form_id = id.
O gateway é o primeiro da política de cartão do sistema que aceita o valor e as parcelas e tem conta conectada. Nenhum: 422 no-route, sem nome de gateway. O formulário não cobra nada e não expira no hub — o token é que expira, no gateway.
Cobrança dividida (desde a 0.10.0): informe recipient_id, e o formulário é o da conta do recebedor — a cobrança de cartão com split exige este formulário, do mesmo recebedor (422 em card.form_id se não for).
O corpo precisa ser UTF-8 válido (RFC 8259); fora disso, 400.
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | integer formato int64 · mínimo 1 | sim | unidade mínima da moeda |
currency | string padrão ^[A-Z]{3}$ | sim | |
installments | integer de 1 a 24 · padrão 1 | não | |
recipient_id | string formato uuid | não | desde a 0.10.0 — o recebedor da cobrança dividida; o formulário é o da conta dele |
Respostas
- 201 o formulário a usar
application/jsonCardForm - 400 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 422 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /api/v1/charges/{id}
Consulta uma cobrança do tenant
Exige a API key do tenant.
Cobrança de outro tenant responde 404, igual a uma que não existe.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim |
Respostas
- 200 a cobrança
application/jsonCharge - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 404 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /api/v1/charges/{id}/refunds
Lista os estornos de uma cobrança, do mais antigo ao mais novo
Exige a API key do tenant.
Todos os estornos da cobrança — pedidos pela API e feitos no painel do gateway —, em qualquer estado, na ordem total created_at crescente e, no empate, id crescente. Cobrança de outro tenant responde 404, igual a uma que não existe. Parâmetro de consulta desconhecido é 422.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
page | query | integer de 1 a 10000 · padrão 1 | não | |
page_size | query | integer de 1 a 100 · padrão 20 | não |
Respostas
- 200 página de estornos
application/jsonobjeto - 400 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 404 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 422 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
POST /api/v1/charges/{id}/refunds
Pede o estorno de uma cobrança capturada, inteiro ou em parte
Exige a API key do tenant.
Idempotente pela Idempotency-Key, única por tenant entre os pedidos de estorno (o espaço de chaves é separado do da criação de cobrança). Mesma chave e mesmo corpo devolvem o mesmo estorno com 200, no estado em que ele está; mesma chave com outro corpo, ou para outra cobrança, é 409.
Estornável. Cabe pedir enquanto amount ≤ capturado − estornos confirmados − estornos pendentes − disputa perdida. O estorno pendente reserva o valor: outro pedido não pode usá-lo até ele se resolver; o que falha libera a reserva. Acima do estornável é 409, sem chamar o gateway. Vários parciais valem, enquanto couberem.
Quando a cobrança muda. Ela passa a refunded quando a soma dos estornos confirmados chega ao capturado — antes disso continua captured, com refunded_amount e pending_refund_amount dizendo quanto. A mudança de status sai num aviso charge.updated, como hoje.
Resultado. 201 com o estorno em um destes estados:
- succeeded — confirmado pelo gateway; lançado no ledger. - pending — o gateway aceitou e confirma depois; o valor fica reservado, e a confirmação chega pelo aviso refund.updated. - failed — recusa de negócio do gateway (prazo vencido, saldo insuficiente na conta, estorno não permitido), com failure_reason. Não é erro HTTP: a requisição deu certo, o estorno não. A reserva é liberada.
Gateway sem resposta. 502, e o estorno fica pending com o valor reservado: timeout não prova recusa — o gateway pode ter estornado, e o aviso de confirmação que chegar depois é aplicado normalmente. Repita o pedido com a mesma Idempotency-Key: o hub refaz a chamada com o mesmo id de estorno (o gateway não estorna duas vezes) e devolve o estado atual.
409 quando a cobrança não está captured (pendente, autorizada, falha, cancelada, estornada — inclusive depois de uma disputa perdida, que sempre a leva a refunded), quando está em disputa (disputed), ou quando o valor passa do estornável. 422 quando o gateway da cobrança não faz estorno parcial e amount é diferente do valor da cobrança, ou quando o gateway não estorna pela API o meio da cobrança (o boleto, em alguns gateways) — capability-not-supported, sem gravar estorno e sem chamar o gateway.
Cobrança dividida (desde a 0.11.0; antes, o parcial era 422). O estorno parcial é aceito como o de qualquer cobrança e é proporcional à divisão: numa cobrança de 10000 com comissão 2000, estornar 5000 devolve 4000 da parte do recebedor e 1000 da comissão. A divisão é feita sobre o valor lançado do estorno, quando o gateway o confirma, e aparece em split no estorno succeeded.
Descrição. description é do sistema: fica no hub, volta na consulta e nunca é enviada ao gateway. Ao gateway vai só reason.
Nenhum campo aceita null; o corpo precisa ser UTF-8 válido (fora disso, 400).
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim | |
Idempotency-Key | header | string de 1 a 255 caracteres | sim |
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | integer formato int64 · mínimo 1 | sim | Unidade mínima da moeda da cobrança. Igual ao valor da cobrança é estorno total; menor, parcial. |
reason | string requested_by_customer duplicate fraudulent other | sim | Lista fechada na entrada: fora dela, 422. Pedido do pagador, cobrança duplicada, suspeita de fraude, outro. |
description | string máximo 255 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$ | não | Do sistema: fica no hub e volta na consulta. Nunca é enviada ao gateway — não ponha dado do pagador aqui. |
Respostas
- 200 repetição da mesma Idempotency-Key — o estorno, no estado atual
application/jsonRefund - 201 estorno registrado —
succeeded,pendingoufailedapplication/jsonRefund - 400 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 404 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 409 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 422 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited - 502 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable
GET /api/v1/refunds/{id}
Consulta um estorno do tenant
Exige a API key do tenant.
Estorno de outro tenant responde 404, igual a um que não existe.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | string formato uuid | sim |
Respostas
- 200 o estorno
application/jsonRefund - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 404 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /api/v1/wallets
Saldo de cada carteira do tenant, por gateway e moeda
Exige a API key do tenant.
Derivado do ledger — soma das partidas, nunca um campo guardado. balance é o líquido (gross − fees, no centavo); gross e fees o decompõem, e pending_fee_charges/pending_fee_gross contam as cobranças cuja taxa ainda não foi informada pelo gateway.
Respostas
- 200 carteiras
application/jsonobjeto - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /api/v1/ledger/entries
Lançamentos do tenant, do mais recente ao mais antigo
Exige a API key do tenant.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
page | query | integer mínimo 1 · padrão 1 | não | |
page_size | query | integer de 1 a 100 · padrão 20 | não |
Respostas
- 200 página de lançamentos
application/jsonobjeto - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /api/v1/subaccounts
Saldo de cada subconta virtual do tenant, por gateway e moeda
Exige a API key do tenant.
A subconta virtual registra quanto do dinheiro da conta da plataforma num gateway foi gerado por este sistema e ainda não foi repassado a ele (ADR 0007). Derivado do ledger — soma dos lançamentos, nunca um campo guardado. Um sistema que só cobra com credencial própria não tem subconta (lista vazia): o dinheiro dele vai direto para a conta dele, e o saldo está em GET /api/v1/wallets.
O saldo é um número só (balance), e pode ficar negativo — um estorno ou uma disputa perdida depois do repasse. As disputas abertas e as taxas ainda não informadas aparecem só como informação, sem lançamento: não estão no saldo.
Respostas
- 200 subcontas
application/jsonobjeto - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
GET /api/v1/subaccounts/entries
Extrato de uma subconta, do lançamento mais recente ao mais antigo
Exige a API key do tenant.
Cada lançamento que mexeu na subconta, com a cobrança, o estorno ou o repasse que o causou. Ordem total: created_at decrescente, id decrescente — nenhum lançamento se repete nem some entre páginas. Parâmetro desconhecido é 422. Subconta que não existe devolve a página vazia.
A contrapartida de cada lançamento é a conta da plataforma no gateway, mostrada só como counterparty {type: platform_account, provider} — sem saldo, sem identificador e sem nada de outro sistema.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
provider | query | string de 1 a 64 caracteres | sim | |
currency | query | string padrão ^[A-Z]{3}$ | sim | |
page | query | integer de 1 a 100000 · padrão 1 | não | |
page_size | query | integer de 1 a 100 · padrão 20 | não |
Respostas
- 200 página do extrato
application/jsonobjeto - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 422 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
POST /api/v1/webhooks/{provider}/{tenantID}
Recebe o webhook de um gateway
Sem API key.
Sem API key: quem chama é o gateway. A autenticação é a assinatura, verificada com o segredo de webhook daquele tenant naquele gateway. Evento repetido, fora de ordem ou de cobrança desconhecida responde 200 — devolver erro faria o gateway reenviar para sempre — e fica registrado com o desfecho.
Estornos. O evento de estorno se casa com o estorno pelo id que o gateway deu a ele: resposta do pedido, webhook e consulta, em qualquer ordem, lançam uma vez só. Estorno feito no painel do gateway vira estorno novo da cobrança, lançado pelo valor informado; sem valor, fica registrado sem efeito para investigação (under_review) — nunca pelo total.
Taxas. O evento pode trazer a taxa do gateway, da captura ou de um estorno. O hub lança a diferença entre o total informado e o que já lançou para aquela origem: a mesma taxa repetida não lança nada; a corrigida lança o ajuste. Informação mais antiga que a última aplicada, ou da mesma hora com outro total, fica registrada sem efeito. Taxa que chega antes da captura (ou do estorno) espera e é lançada junto com ela. Taxa de cobrança falha, cancelada, em outra moeda, ou de estorno que falhou fica registrada como divergência, sem lançamento — assim como a taxa malformada (total negativo, moeda fora do formato); taxa de cobrança desconhecida, sem efeito. O desfecho é o do status; um evento sem efeito no status vira applied só quando a taxa foi lançada.
Antes da assinatura, uma resposta só (desde a 0.11.1). Identificador do caminho mal formado, sistema ou conta que não existe, sistema sem conta naquele gateway, gateway desconhecido e assinatura inválida ou ausente respondem o mesmo 401 invalid-signature, sem dizer o motivo: quem não assina não descobre o que existe.
Limite de taxa (desde a 0.14.0). O 429 por origem e o de assinatura inválida (por origem e caminho) saem antes de a assinatura ser conferida; o gateway reenvia depois. Nada é gravado.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
provider | path | string | sim | |
tenantID | path | string formato uuid | sim |
Corpo application/json
object
Respostas
- 200 evento processado
application/jsonobjeto - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 413 corpo acima de 1 MiB (1048576 bytes)
application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
POST /api/v1/marketplace-webhooks/{accountID}
Recebe o aviso do gateway ao marketplace de uma conta da plataforma
Sem API key.
Desde a 0.10.0 (spec 0017). O aviso de uma cobrança criada pelo marketplace da conta da plataforma na conta de um recebedor. O caminho identifica a conta da plataforma, nunca um sistema; a autenticação é a assinatura com o segredo do marketplace dela. A cobrança é achada pelo id do gateway, só entre as criadas por este marketplace na conta daquele recebedor; o sistema sai dela. Aviso desta rota nunca mexe em cobrança da conta de um sistema nem da conta da plataforma, e vice-versa.
Como nas outras rotas: repetido, fora de ordem ou sem cobrança deste marketplace responde 200 e fica registrado com o desfecho.
Antes da assinatura, uma resposta só (desde a 0.11.1). Identificador do caminho mal formado, conta que não existe, conta sem marketplace neste gateway e assinatura inválida ou ausente respondem o mesmo 401 invalid-signature, sem dizer o motivo: quem não assina não descobre o que existe.
Limite de taxa (desde a 0.14.0). O 429 por origem e o de assinatura inválida (por origem e caminho) saem antes de a assinatura ser conferida; o gateway reenvia depois. Nada é gravado.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
accountID | path | string formato uuid | sim |
Corpo application/json
object
Respostas
- 200 aviso processado
application/jsonobjeto - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 413 corpo acima de 1 MiB (1048576 bytes)
application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
POST /api/v1/platform-webhooks/{accountID}
Recebe o webhook de uma conta da plataforma num gateway
Sem API key.
A conta da plataforma (da Lopes Tech) atende vários sistemas: por isso o caminho identifica a conta, nunca um tenant. Sem API key: quem chama é o gateway. A autenticação é a assinatura, verificada com o segredo daquela conta, antes de qualquer leitura do corpo.
A cobrança é achada pelo identificador que o gateway deu na criação, buscado só entre as cobranças criadas nesta conta — nunca por referência ou metadado do corpo. O sistema dono da cobrança sai dela. Evento desta conta nunca mexe em cobrança criada na conta própria de um sistema, e vice-versa. Nos gateways que não assinam o webhook, o evento só move dinheiro depois de confirmado por consulta com a credencial da conta; divergência entre evento e consulta fica registrada sem efeito (under_review).
Como na rota do tenant: evento repetido, fora de ordem ou sem cobrança desta conta responde 200 e fica registrado com o desfecho; o repetido não produz efeito.
Antes da assinatura, uma resposta só (desde a 0.11.1). Identificador do caminho mal formado, conta que não existe e assinatura inválida ou ausente respondem o mesmo 401 invalid-signature, sem dizer o motivo: quem não assina não descobre o que existe.
Limite de taxa (desde a 0.14.0). O 429 por origem e o de assinatura inválida (por origem e caminho) saem antes de a assinatura ser conferida; o gateway reenvia depois. Nada é gravado.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
accountID | path | string formato uuid | sim |
Corpo application/json
object
Respostas
- 200 evento processado
application/jsonobjeto - 401 erro (RFC 9457)
application/problem+jsonProblemhttps://abeesys.com/errors/no-routehttps://abeesys.com/errors/conflicthttps://abeesys.com/errors/provider-unavailable - 413 corpo acima de 1 MiB (1048576 bytes)
application/problem+jsonProblemhttps://abeesys.com/errors/payload-too-large - 429 acima do limite de taxa — nada foi gravado e nenhum gateway foi chamado
application/problem+jsonProblemhttps://abeesys.com/errors/rate-limited
Avisos
POST aviso chargeUpdated
O aviso de mudança de cobrança — quem implementa é o sistema cliente
Enviado pelo hub ao endereço do sistema.
A cada mudança de cobrança, o hub envia um POST ao endereço que o sistema cadastrou com quem opera a plataforma (tenant notify --slug <sistema> --url https://…). O cadastro devolve o segredo de assinatura do sistema uma vez (whsec_…); guarde-o como credencial. Cada sistema recebe só avisos das próprias cobranças, assinados com o próprio segredo.
O que o aviso leva: o id do aviso, o tipo, o instante da mudança, o status anterior e a cobrança no mesmo formato de GET /api/v1/charges/{id} — sem payer. Quem precisar do pagador consulta a cobrança. O aviso nunca leva credencial, dado de cartão nem resposta do gateway.
Tipos (lista aberta — ignore com 2xx o que não conhece):
- charge.updated — a cobrança mudou de status. - refund.updated — um estorno chegou a succeeded ou failed. Leva também refund, o estorno no formato de GET /api/v1/refunds/{id}. Um estorno que leva a cobrança a refunded produz os dois avisos, nesta ordem: refund.updated e charge.updated. - subaccount.payout — quem opera registrou um repasse do saldo de uma subconta virtual do sistema (feito fora do hub, pela conta da plataforma no gateway), ou o reverso de um. Leva payout e não leva charge nem previous_status. - recipient.link_updated — desde a 0.10.0: o vínculo de um recebedor foi gravado, ou ficou inativo (a autorização foi desfeita, ou o gateway recusou a renovação). Leva recipient_id e recipient_link; não leva charge.
Assinatura — padrão [Standard Webhooks](https://www.standardwebhooks.com/), que tem biblioteca pronta em várias linguagens:
- tire o prefixo
whsec_do segredo e decodifique o resto em base64: são os 32 bytes da chave; - monte o conteúdo assinado:
<webhook-id>.<webhook-timestamp>.<corpo>— o corpo cru, byte a byte como chegou, antes de qualquer parse; - calcule
HMAC-SHA256(chave, conteúdo)e codifique em base64 (padrão, com=); webhook-signaturetraz uma ou mais assinaturas separadas por espaço, cada uma no formatov1,<base64>; aceite o aviso se alguma for igual à sua, comparando em tempo constante.
Anti-replay: recuse o aviso se webhook-timestamp estiver a mais de 5 minutos do seu relógio, para trás ou para a frente — um aviso capturado não pode ser reapresentado depois. Cada tentativa é assinada de novo com o instante do envio, então uma repetição legítima nunca chega com instante velho.
Exemplo que bate (corpo curto, para caber):
`` segredo whsec_AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyA= webhook-id 5f0c1a52-8f5e-4d7a-9a3e-2b1c4d6e8f90 webhook-timestamp 1791115200 corpo {"id":"5f0c1a52-8f5e-4d7a-9a3e-2b1c4d6e8f90","type":"charge.updated"} webhook-signature v1,StqoxgeT0W+w6bY3yMQDrlug4zz1qK/xxAbJGZMPfeA= ``
Repetição e ordem. O mesmo aviso pode chegar mais de uma vez (o hub reinicia, a sua resposta se perde): o id — igual ao cabeçalho webhook-id — não muda entre tentativas; guarde-o e ignore o repetido. Os avisos de uma mesma cobrança chegam na ordem em que aconteceram: o seguinte só sai depois de o anterior ser entregue. Avisos de cobranças diferentes não têm ordem entre si.
Resposta. Qualquer 2xx, com qualquer corpo, é entregue. Qualquer outra coisa é falha: outro status (inclusive 3xx — redirecionamento não é seguido), mais de 10 segundos sem resposta, conexão recusada, TLS inválido. Responda rápido e processe depois.
Tentativas. Depois de uma falha, o hub espera 10 s e tenta de novo, dobrando a espera a cada falha até 1 hora entre tentativas, por até 24 horas contadas da primeira tentativa. Esgotado o prazo, o aviso fica como não entregue, visível a quem opera, que pode pedir o reenvio; os avisos seguintes da mesma cobrança esperam o reenvio, para não chegarem fora de ordem. Avisos de outras cobranças seguem normalmente.
Endereço. Só https. Endereço de rede interna (localhost, IP privado ou link-local, *.railway.internal, nome sem domínio) é recusado no cadastro e na hora de conectar, pelo IP resolvido.
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
webhook-id | header | string formato uuid | sim | o id do aviso — igual a id no corpo; estável entre tentativas |
webhook-timestamp | header | string padrão ^[0-9]+$ | sim | o instante do envio, em segundos desde 1970-01-01T00:00:00Z |
webhook-signature | header | string | sim | v1,<base64 do HMAC-SHA256> — uma ou mais, separadas por espaço |
Corpo application/json
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | o id do aviso — estável entre tentativas; o sistema deduplica por ele |
type | string | sim | O tipo do aviso: charge.updated, refund.updated, subaccount.payout ou
recipient.link_updated. Lista aberta: ignore (com 2xx) o tipo que não
conhece. charge e previous_status estão em todo charge.updated e
refund.updated; payout, só em subaccount.payout; recipient_id e
recipient_link, só em recipient.link_updated.
|
created_at | string formato date-time | sim | o instante da mudança — não o do envio, que vai em webhook-timestamp |
previous_status | qualquer valor | não | O status da cobrança antes do fato. Em refund.updated, é igual ao status de
charge quando o estorno não mudou a cobrança.
|
charge | qualquer valor | não | A cobrança como ficou depois desta mudança, no formato da consulta, sem payer e
sem fee — a taxa não gera aviso, e o retrato não a acompanha.
É o retrato daquele momento: dois avisos da mesma cobrança contam a história, não
repetem o estado atual.
|
refund | qualquer valor | não | Só em refund.updated — o estorno como ficou. |
payout | qualquer valor | não | Só em subaccount.payout — o repasse como ficou. |
recipient_id | string formato uuid | não | Só em recipient.link_updated — o recebedor do vínculo. |
recipient_link | qualquer valor | não | Só em recipient.link_updated — o vínculo como ficou. |
Respostas
- 2XX entregue; o corpo da resposta é ignorado
- default falha; o hub tenta de novo com espera crescente
Tipos
CreateCharge
objeto
Não há campo de gateway: quem escolhe é o hub. provider enviado é 422 (campo desconhecido).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | integer formato int64 · mínimo 1 | sim | Unidade mínima da moeda. Em cartão parcelado é o total — o hub não calcula juros de parcelamento. |
currency | string padrão ^[A-Z]{3}$ | sim | |
method | string card pix boleto | sim | |
description | string máximo 500 caracteres · padrão ^[^\x00]*$ | não | Quebra de linha vale; o caractere NUL (\\u0000) é 422. |
payer | Payer | não | |
card | CardInput | não | |
pix | PixInput | não | |
boleto | BoletoInput | não | |
reference | Reference | não | |
metadata | Metadata | não | |
device_id | string máximo 255 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$ | não | Identificador antifraude do dispositivo do pagador, quando o gateway usa um. O hub o repassa sem interpretar e não o guarda. |
split | SplitInput | não |
SplitInput
objeto
Desde a 0.10.0. A parte do recebedor; o resto do valor é a comissão do sistema. No percentual, a parte é o piso de amount × percentage_bps / 10000 e o resto do arredondamento fica na comissão — parte + comissão = valor, sempre.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
recipients | lista de objeto de 1 a 1 itens | sim | |
recipients[].recipient_id | string formato uuid | sim | |
recipients[].amount | integer formato int64 · mínimo 1 | não | a parte do recebedor, em unidade mínima, até o valor da cobrança |
recipients[].percentage_bps | integer de 1 a 10000 | não | a parte do recebedor em pontos-base (10000 = 100%) |
fee_payer | string recipient padrão "recipient" | não | Quem arca com a taxa do gateway. Hoje só recipient: a taxa é debitada na conta
do recebedor, onde a cobrança nasce.
|
SplitDetails
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
recipients | lista de objeto | sim | |
recipients[].recipient_id | string formato uuid | sim | |
recipients[].amount | integer formato int64 | sim | a parte pedida do recebedor |
commission | integer formato int64 | sim | a comissão pedida |
applied_commission | integer formato int64 | não | A comissão que o gateway diz ter aplicado, quando informa. Diferente da pedida, é ela que o ledger lança — a diferença fica visível aqui. |
fee_payer | string recipient | sim | |
refunded_recipient_amount | integer formato int64 | não | Desde a 0.11.0. O total já devolvido da parte do recebedor pelos estornos
confirmados. Com refunded_commission, soma o refunded_amount da cobrança.
|
refunded_commission | integer formato int64 | não | Desde a 0.11.0. O total já devolvido da comissão pelos estornos confirmados. |
CreateRecipient
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string de 1 a 100 caracteres | sim | |
reference | string de 1 a 255 caracteres | sim | o id do recebedor no seu sistema — única por sistema |
Recipient
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
name | string | sim | |
reference | string | sim | |
links | lista de RecipientLink | sim | |
created_at | string formato date-time | sim |
RecipientLink
objeto
O vínculo, sem a conta do recebedor no gateway e sem credencial.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
provider | string | sim | |
status | string | sim | Lista aberta. active: o gateway entra na escolha das vendas deste recebedor. |
linked_at | string formato date-time | sim | |
deactivated_at | string formato date-time | não | |
deactivation_reason | string | não | Lista aberta. revoked: o recebedor desfez a autorização no gateway.
renewal_lost (desde a 0.10.1): a autorização venceu porque a renovação do
acesso se perdeu do lado do hub, sem o recebedor ter desfeito nada — ele precisa
autorizar de novo.
|
CreateRecipientLink
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
provider | string | sim | |
return_url | string máximo 2048 caracteres · padrão ^https://[^/\s][^\s]*$ | sim | para onde o recebedor volta, com status=linked ou status=failed |
RecipientLinkAuthorization
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
authorization_url | string formato uri | sim | |
expires_at | string formato date-time | sim |
Payer
objeto
Quem paga. O que é obrigatório depende do gateway e do meio. Dado pessoal: só o tenant dono da cobrança o vê, e o hub não o escreve em log.
Document
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string cpf cnpj | sim | |
number | string padrão ^[0-9A-Z]{11,14}$ | sim | Sem pontuação. CPF com 11 dígitos; CNPJ com 14 posições, inclusive no formato alfanumérico da Receita. O dígito verificador é conferido: inválido é 422. Os exemplos são números fictícios de teste, de ninguém. |
Address
objeto
Para country = BR, state é a UF (duas letras) e postal_code o CEP com 8 dígitos, sem hífen.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
street | string máximo 200 caracteres · padrão ^[^\x00-\x1F\x7F]*$ | sim | |
number | string máximo 20 caracteres · padrão ^[^\x00-\x1F\x7F]*$ | sim | |
complement | string máximo 100 caracteres · padrão ^[^\x00-\x1F\x7F]*$ | não | |
district | string máximo 100 caracteres · padrão ^[^\x00-\x1F\x7F]*$ | sim | |
city | string máximo 100 caracteres · padrão ^[^\x00-\x1F\x7F]*$ | sim | |
state | string máximo 64 caracteres · padrão ^[^\x00-\x1F\x7F]*$ | sim | |
postal_code | string máximo 16 caracteres · padrão ^[0-9A-Za-z -]*$ | sim | |
country | string padrão ^[A-Z]{2}$ | sim | ISO 3166-1 alfa-2 |
CardInput
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
form_id | string formato uuid | sim | O id devolvido por POST /api/v1/card-forms. Diz ao hub de qual gateway é o
token. Formulário inexistente, de outro sistema, ou de um gateway cuja conta foi
desconectada: 422 neste campo.
|
token | string máximo 255 caracteres · padrão ^[^\x00-\x1F\x7F]*$ | sim | Gerado pelo formulário do gateway no navegador do pagador. Uso único. |
installments | integer de 1 a 24 · padrão 1 | não | Cada gateway aceita até um número próprio; acima dele, 422. |
return_url | string formato uri · máximo 2048 caracteres · padrão ^https://[^/\x00-\x20\x7F-\x9F][^\x00-\x20\x7F-\x9F]*$ | não | Desde a 0.9.0. Para onde o pagador volta depois de uma autenticação extra do
emissor (3-D Secure): uma página do sistema, em https, com host, sem espaço nem
caractere de controle. Obrigatório quando o
formulário declarou return_url_required (422 neste campo se faltar); para os
outros gateways, aceito e ignorado. O gateway pode acrescentar parâmetros dele ao
endereço na volta; o resultado da cobrança chega pelo aviso, não pela volta.
|
PixInput
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
expires_in | integer de 1 a 2592000 | não | Validade do código, em segundos. Ausente: o padrão do gateway. Fora da faixa que o gateway aceita, 422. |
BoletoInput
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
due_date | string formato date | não | Vencimento. Ausente: o padrão do gateway. Fora da faixa que o gateway aceita (contada em dias a partir de hoje, em UTC), 422. |
Reference
string máximo 255 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$
A referência do pedido no sistema cliente (o ingresso reservado, a mensalidade). O hub não a interpreta e ela não é única: várias cobranças do mesmo pedido — uma que falhou, outra que passou — têm a mesma referência, e a listagem por referência devolve todas. Texto vazio equivale a ausente. Na resposta e no aviso está sempre presente: texto vazio quando a cobrança não tem referência.
Metadata
object
Pares chave-valor que o sistema quer ver de volta em toda leitura e em todo aviso da cobrança. Até 20 chaves; chave com 1 a 40 caracteres, valor com até 500, ambos texto sem caractere de controle. Acima disso, 422 nomeando o campo (metadata ou metadata.<chave>).
Não é lugar para dado de cartão nem dado pessoal do pagador (documento, e-mail, telefone, nome): o pagador tem campo próprio, com o tratamento que dado pessoal exige. Metadados são guardados e repetidos nos avisos como vieram.
Objeto vazio equivale a ausente. Na resposta e no aviso está sempre presente: objeto vazio quando a cobrança não tem metadados.
PageMeta
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
total | integer mínimo 0 | sim | quantas cobranças atendem aos filtros |
page | integer mínimo 1 | sim | |
page_size | integer de 1 a 100 | sim |
ChargeStatus
string pending authorized captured refunded failed canceled disputed
Charge
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
settles_in | string | sim | Onde a cobrança liquida — informação, desde a 0.8.0. Lista aberta.
tenant_account: na conta do próprio sistema no gateway (o saldo aparece em
GET /api/v1/wallets). virtual_subaccount: na conta da plataforma naquele
gateway, alocado na subconta virtual do sistema (GET /api/v1/subaccounts).
recipient_account (desde a 0.10.0): na conta do recebedor da divisão; só a
comissão vai à subconta virtual. Não muda depois de a cobrança chegar ao gateway.
|
provider | string | sim | O gateway que atende a cobrança — informação para suporte e conciliação, não para
o sistema decidir nada. Enquanto pending depois de um 502, é o gateway que não
respondeu. Em failed com failure_reason provider_unavailable, é o último
gateway que recusou — nenhum deles criou a cobrança.
|
external_id | string | não | id no gateway |
amount | integer formato int64 | sim | |
currency | string | sim | |
method | string card pix boleto | sim | |
status | ChargeStatus pending authorized captured refunded failed canceled disputed | sim | |
description | string | sim | |
reference | Reference | sim | |
metadata | Metadata | sim | |
payer | qualquer valor | não | Só na consulta, na listagem e na resposta da criação — nunca no aviso: o dado pessoal do pagador não sai do hub por um canal que repete a mensagem por até 24 h. |
card | CardDetails | não | |
pix | PixInstructions | não | |
boleto | BoletoInstructions | não | |
split | qualquer valor | não | Só na cobrança dividida (desde a 0.10.0). |
failure_reason | string | não | Só em failed. Vocabulário do hub, igual em todo gateway, e lista aberta —
trate valor desconhecido como recusa genérica. Hoje: card_declined,
insufficient_funds, card_token_invalid (token expirado, já usado ou
desconhecido), payer_action_failed (3-D Secure não concluído),
provider_rejected (recusa sem motivo mais específico), provider_unavailable
(todos os gateways possíveis recusaram antes de criar; nada foi cobrado).
|
pix_copy_paste | string | não | só em cobrança pix. Use pix.copy_paste. |
refunded_amount | integer formato int64 · mínimo 0 | não | Quanto já foi estornado e lançado no ledger: a soma dos estornos succeeded. Não
inclui disputa perdida. Na resposta está sempre presente (0 sem estorno).
|
pending_refund_amount | integer formato int64 · mínimo 0 | não | Quanto está reservado por estornos pending: não pode ser pedido de novo até
eles se resolverem. Na resposta está sempre presente (0 sem estorno pendente).
|
fee | qualquer valor | não | A taxa do gateway (spec 0008). Só em cobrança que chegou a ser capturada
(captured, disputed, refunded) — antes disso não há taxa a esperar. Não
vem no aviso: consulte a cobrança.
|
created_at | string formato date-time | sim | |
updated_at | string formato date-time | sim |
ChargeFee
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
status | string | sim | Lista aberta. pending: o gateway ainda não informou a taxa da captura —
ela não é zero, é desconhecida. posted: informou, e o total está lançado
(pode ser 0, se o gateway não cobrou).
|
amount | integer formato int64 | sim | O lançado de taxa da cobrança, todas as origens somadas (captura e estornos), na moeda da cobrança. 0 enquanto nada foi lançado. |
currency | string | sim | |
origins | lista de objeto | sim | O lançado por origem, para as origens com taxa lançada. A soma é amount. A taxa
de um estorno não volta quando o estorno acontece: ela é dele, separada da taxa
da captura.
|
origins[].origin | string | sim | Lista aberta. capture (a captura), refund (um estorno) ou, desde a
0.9.0, dispute (a tarifa que o gateway cobra pela contestação da cobrança,
quando cobra; uma origem por cobrança, sem refund_id).
|
origins[].refund_id | string formato uuid | não | só em refund — o estorno que é a origem da taxa |
origins[].amount | integer formato int64 | sim |
CardFormRequest
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | integer formato int64 · mínimo 1 | sim | unidade mínima da moeda |
currency | string padrão ^[A-Z]{3}$ | sim | |
installments | integer de 1 a 24 · padrão 1 | não | |
recipient_id | string formato uuid | não | desde a 0.10.0 — o recebedor da cobrança dividida; o formulário é o da conta dele |
CardForm
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | vai de volta em card.form_id |
provider | string | sim | O gateway do formulário — informação; o sistema não decide nada com ela. |
public_key | string | sim | Chave pública (publicável) do formulário do gateway. Não é segredo. |
max_installments | integer de 1 a 24 | sim | |
payer_fields | lista de string payer.name payer.email payer.document payer.phone payer.address | sim | Os campos do pagador que este gateway exige para cartão. |
return_url_required | boolean | sim | Desde a 0.9.0. true: o gateway deste formulário exige card.return_url na
cobrança — para onde o pagador volta depois de uma autenticação extra do emissor
(3-D Secure). Sem ele, 422 em card.return_url.
|
created_at | string formato date-time | sim |
CardDetails
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
installments | integer de 1 a 24 | sim | |
action_url | string formato uri | não | Só enquanto pending, quando o gateway exige uma ação do pagador (3-D Secure).
O sistema leva o pagador até ela; o resultado chega pelo webhook.
|
PixInstructions
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
copy_paste | string | sim | o código "copia e cola" |
qr_code_image | string | não | Imagem do QR — URL https ou data URI (data:image/png;base64,...). |
expires_at | string formato date-time | não |
BoletoInstructions
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
digitable_line | string | sim | linha digitável |
url | string formato uri | não | endereço do boleto para o pagador |
due_date | string formato date | não |
Notice
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | o id do aviso — estável entre tentativas; o sistema deduplica por ele |
type | string | sim | O tipo do aviso: charge.updated, refund.updated, subaccount.payout ou
recipient.link_updated. Lista aberta: ignore (com 2xx) o tipo que não
conhece. charge e previous_status estão em todo charge.updated e
refund.updated; payout, só em subaccount.payout; recipient_id e
recipient_link, só em recipient.link_updated.
|
created_at | string formato date-time | sim | o instante da mudança — não o do envio, que vai em webhook-timestamp |
previous_status | qualquer valor | não | O status da cobrança antes do fato. Em refund.updated, é igual ao status de
charge quando o estorno não mudou a cobrança.
|
charge | qualquer valor | não | A cobrança como ficou depois desta mudança, no formato da consulta, sem payer e
sem fee — a taxa não gera aviso, e o retrato não a acompanha.
É o retrato daquele momento: dois avisos da mesma cobrança contam a história, não
repetem o estado atual.
|
refund | qualquer valor | não | Só em refund.updated — o estorno como ficou. |
payout | qualquer valor | não | Só em subaccount.payout — o repasse como ficou. |
recipient_id | string formato uuid | não | Só em recipient.link_updated — o recebedor do vínculo. |
recipient_link | qualquer valor | não | Só em recipient.link_updated — o vínculo como ficou. |
CreateRefund
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | integer formato int64 · mínimo 1 | sim | Unidade mínima da moeda da cobrança. Igual ao valor da cobrança é estorno total; menor, parcial. |
reason | string requested_by_customer duplicate fraudulent other | sim | Lista fechada na entrada: fora dela, 422. Pedido do pagador, cobrança duplicada, suspeita de fraude, outro. |
description | string máximo 255 caracteres · padrão ^[^\x00-\x1F\x7F-\x9F]*$ | não | Do sistema: fica no hub e volta na consulta. Nunca é enviada ao gateway — não ponha dado do pagador aqui. |
Refund
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
charge_id | string formato uuid | sim | |
amount | integer formato int64 · mínimo 0 | sim | O valor do estorno, na moeda da cobrança: o pedido, ou o informado pelo gateway no
estorno feito no painel. 0 só em under_review (o gateway não informou o valor).
|
currency | string | sim | |
status | string | sim | Lista aberta. pending (reserva o valor; aguarda o gateway), succeeded
(confirmado e lançado), failed (recusado pelo gateway, com failure_reason; a
reserva é liberada), under_review (estorno do painel sem valor informado:
registrado sem efeito, para investigação — não reserva, não lança).
|
origin | string | sim | Lista aberta. api (pedido por esta API) ou provider_dashboard (feito no
painel do gateway, fora do hub).
|
reason | string | não | Lista aberta na saída: requested_by_customer, duplicate, fraudulent,
other. Ausente em estorno do painel quando o gateway não informa.
|
description | string | sim | a descrição do pedido; texto vazio quando não houve |
failure_reason | string | não | Só em failed. Lista aberta: refund_window_expired (prazo do gateway
vencido), insufficient_balance (saldo insuficiente na conta), refund_not_allowed,
provider_rejected (recusa sem motivo mais específico).
|
external_id | string | não | o id do estorno no gateway, quando conhecido |
created_at | string formato date-time | sim | |
updated_at | string formato date-time | sim | |
confirmed_at | string formato date-time | não | só em succeeded — quando o hub registrou a confirmação do gateway |
split | qualquer valor | não | Desde a 0.11.0. Só no estorno succeeded de cobrança dividida: quanto do valor
lançado saiu da parte do recebedor e quanto saiu da comissão.
|
RefundSplit
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
recipient_amount | integer formato int64 · mínimo 0 | sim | a parte do recebedor devolvida por este estorno |
commission | integer formato int64 · mínimo 0 | sim | a comissão devolvida por este estorno; as duas partes somam o valor lançado |
Wallet
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
provider | string | sim | |
balance | integer formato int64 | sim | O saldo: a soma das partidas da carteira (créditos menos débitos). Desde a 0.7.0,
com as taxas do gateway lançadas, é o líquido — gross − fees, no centavo — e
bate com o que o gateway entrega à conta do sistema.
|
currency | string | sim | |
gross | integer formato int64 | sim | o bruto — capturado menos estornado menos disputa perdida |
fees | integer formato int64 | sim | As taxas do gateway lançadas, correções incluídas (taxa paga). |
pending_fee_charges | integer mínimo 0 | sim | Quantas cobranças capturadas neste gateway e moeda ainda não têm a taxa da captura
informada. Informação: a taxa delas não está em fees nem em balance.
|
pending_fee_gross | integer formato int64 | sim | o bruto dessas cobranças (capturado menos estornado menos disputa perdida) |
Subaccount
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
provider | string | sim | o gateway da conta da plataforma em que o dinheiro está |
currency | string | sim | |
balance | integer formato int64 | sim | A soma dos lançamentos da subconta: capturado − estornado − disputa perdida − taxas lançadas − repassado. Pode ser negativo (estorno ou disputa depois do repasse). |
pending_fee_charges | integer mínimo 0 | sim | Informação, sem lançamento: quantas cobranças desta subconta ainda não têm a taxa
da captura informada pelo gateway. A taxa delas é pendente, não zero, e não
está em balance.
|
pending_fee_gross | integer formato int64 | sim | o bruto dessas cobranças |
open_dispute_charges | integer mínimo 0 | sim | Informação, sem lançamento: quantas cobranças desta subconta estão em disputa aberta. O saldo só muda no desfecho. |
open_dispute_amount | integer formato int64 | sim | o valor dessas cobranças (capturado − estornado) |
SubaccountEntry
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
kind | string | sim | Lista aberta. charge_captured, charge_refunded, dispute_lost,
provider_fee, provider_fee_adjustment, subaccount_payout (repasse),
subaccount_payout_reversal (reverso de um repasse), platform_adjustment
(ajuste de quem opera) e, desde a 0.11.0, subaccount_shortfall_coverage (a
plataforma cobre o saldo que a devolução de uma comissão deixaria negativo).
Tipo desconhecido: some amount como o de qualquer outro.
|
amount | integer formato int64 | sim | o efeito na subconta, com sinal — positivo entra, negativo sai |
currency | string | sim | |
charge_id | string formato uuid | não | a cobrança que causou o lançamento, quando há uma |
refund_id | string formato uuid | não | o estorno que causou o lançamento (ou que é a origem da taxa) |
payout | objeto | não | só nos lançamentos de repasse |
payout.reference | string | sim | a referência da transferência no extrato da conta no gateway |
payout.transferred_on | string formato date | sim | |
payout.status | string | sim | Lista aberta. registered ou reversed. |
counterparty | objeto | sim | |
counterparty.type | string | sim | Lista aberta. Hoje sempre platform_account. |
counterparty.provider | string | sim | |
created_at | string formato date-time | sim |
EntryPageMeta
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
total | integer mínimo 0 | sim | quantos lançamentos a subconta tem |
page | integer mínimo 1 | sim | |
page_size | integer de 1 a 100 | sim |
Payout
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
provider | string | sim | o gateway da conta da plataforma de onde saiu |
currency | string | sim | |
amount | integer formato int64 · mínimo 1 | sim | |
transferred_on | string formato date | sim | |
reference | string | sim | |
status | string | sim | Lista aberta. registered (o repasse foi registrado) ou reversed (um
registro errado foi revertido por inteiro; a mesma referência pode voltar com o
valor certo).
|
LedgerEntry
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string formato uuid | sim | |
charge_id | string formato uuid | sim | |
kind | string | sim | O tipo do lançamento. Lista aberta (ADR 0010): hoje charge_captured
(captura), charge_refunded (estorno — inteiro ou parcial, com refund_id;
lançamentos de antes da 0006 não o têm), dispute_lost (disputa perdida),
provider_fee (a taxa do gateway de uma origem — a captura ou um estorno — pelo
total que ele informou: débito na carteira) e provider_fee_adjustment (a correção
que o gateway fez depois na taxa daquela origem, pela diferença: débito na carteira
para mais, crédito para menos). Um tipo desconhecido é um lançamento genérico:
some as partidas dele como as de qualquer outro, senão o saldo calculado
diverge do de GET /api/v1/wallets.
|
refund_id | string formato uuid | não | Em charge_refunded, o estorno que gerou o lançamento. Em provider_fee e
provider_fee_adjustment, o estorno que é a origem da taxa — ausente quando a
origem é a captura.
|
currency | string | sim | |
postings | lista de objeto mínimo 2 itens | sim | |
postings[].account | string wallet provider_clearing | sim | |
postings[].provider | string | sim | |
postings[].direction | string debit credit | sim | |
postings[].amount | integer formato int64 · mínimo 1 | sim | |
created_at | string formato date-time | sim |
Problem
objeto
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string formato uri | sim | |
title | string | sim | |
status | integer | sim | |
detail | string | não | |
errors | lista de objeto | não | |
errors[].field | string | sim | |
errors[].message | string | sim |