Entenda como funcionam cobranças na API Worldfy
Cobranças representam transações de pagamento na Worldfy. Cada cobrança está associada a um método de pagamento, a uma moeda (currency, padrão BRL) e segue um ciclo de vida específico.
A API suporta os seguintes métodos:
| Método | Identificador | Descrição |
|---|---|---|
| Cartão de Crédito | credit_card | Pagamento com cartão de crédito, com suporte a parcelamento |
| Cartão de Débito | debit_card | Pagamento com cartão de débito, sem parcelamento |
| PIX | pix | Transferência instantânea via QR Code |
| Boleto | boleto | Boleto bancário com data de vencimento |
| Apple Pay | apple_pay | Carteira digital concluída no checkout seguro da Worldfy |
| Google Pay | google_pay | Reservado para evolução futura; não disponível nesta fase |
| Status | Descrição |
|---|---|
pending | Cobrança criada, aguardando processamento |
authorized | Pagamento autorizado (cartão de crédito ou débito) |
captured | Pagamento capturado/confirmado |
partially_refunded | Estornada parcialmente |
refunded | Estornada totalmente |
voided | Cancelada antes da captura |
failed | Falha no processamento |
expired | Expirada (PIX, boleto ou checkout de carteira não concluído no prazo) |
authorized)captured)authorized)captured)Cobranças de cartão de débito não suportam parcelamento — o valor é sempre cobrado em parcela única.
capturedexpiredcapturedexpiredpending e retorna uma checkout_urliframeA checkout_url é opaca e fornecida pela Worldfy. O domínio da sua loja não precisa hospedar um botão de carteira nem fazer configuração adicional para esse fluxo. Google Pay permanece pausado.
Veja o passo a passo em Carteiras Digitais.
Independente do método de pagamento, toda cobrança exige:
| Campo | Tipo | Descrição |
|---|---|---|
amount | integer | Valor em centavos (ex: R$ 100,00 = 10000) |
currency | string | Moeda ISO 4217 de três letras (opcional, padrão BRL) |
payment_method | string | Método de pagamento |
product_type | string | physical ou digital |
customer | object | Dados do cliente (nome, e-mail, CPF/CNPJ, telefone) |
items | array | Lista de itens do pedido |
return_url)Alguns fluxos de pagamento podem redirecionar o navegador do comprador durante a autorização. O campo opcional return_url define para onde o comprador pode seguir ao fim do fluxo.
| Campo | Tipo | Descrição |
|---|---|---|
return_url | string | URL absoluta HTTPS para onde o comprador é redirecionado após o fluxo. Máximo de 2048 caracteres. |
{
"amount": 15000,
"payment_method": "debit_card",
"product_type": "digital",
"return_url": "https://sualoja.com.br/checkout/retorno?pedido=123",
"customer": { "...": "..." },
"items": [{ "...": "..." }]
}Por segurança, a return_url precisa ser HTTPS, apontar para um host público (endereços privados, localhost e domínios internos são recusados) e não pode conter credenciais (https://usuario:senha@...). URLs fora dessas regras retornam 400 com o código INVALID_RETURN_URL. Essa restrição evita que a API seja usada como redirecionador aberto.
Para Apple Pay, return_url não substitui a checkout_url: redirecione primeiro o comprador para a URL retornada pela API. Não considere o retorno do navegador como confirmação de pagamento; use o status da cobrança e os webhooks. O fluxo 3DS do SDK (client-side, via client.threeds.authenticate) não usa return_url — veja Autenticação 3DS.
Além de criar, listar e buscar cobranças, a API oferece endpoints de apoio:
| Endpoint | Descrição |
|---|---|
GET /v1/charges/methods?currency={moeda} | Métodos efetivamente disponíveis para o merchant e a moeda; consulte antes de oferecer Apple Pay |
GET /v1/charges/summary | Métricas agregadas das cobranças (aceita date_from, date_to e currency) |