Criar cobrança

Quick Reference

WhatCriar uma cobrança para qualquer método de pagamento

WhyProcesse pagamentos em 11 métodos, 7 países e 29 adquirentes com um único endpoint

Reading Time10 min

DifficultyBeginner

PrerequisitesAuthentication → Environment

POST/api/v1/bank/wallet/charge/Bearer TokenCriar uma nova cobrança

Quando usar este endpoint

Cenário	Como criar cobrança ajuda
Aceitar um pagamento com cartão de crédito	Defina type_charge: "credit_card" com os campos do cartão ou deixe o SDK/Checkout lidar com eles
Oferecer pagamento instantâneo PIX	Defina type_charge: "pix" — a resposta inclui QR code e código copia e cola
Gerar um Boleto bancário	Defina type_charge: "boleto" — a resposta inclui código de barras e data de vencimento
Aceitar Apple Pay / Google Pay	Defina type_charge: "applepay" ou "googlepay" com dados do token
Configurar cobrança recorrente	Adicione um objeto subscription para criar cobrança + assinatura em uma única chamada
Fluxo somente autorização	Defina capture: false para hotéis, locadoras de veículos, padrões de pré-autorização

---

Escolha seu método de pagamento

Selecione um método abaixo. A página mostrará apenas os campos, código e resposta relevantes para esse método.

---

Parâmetros da requisição (todos os métodos)

Estes campos são obrigatórios para todos os métodos de pagamento:

Campo	Tipo	Obrigatório	Descrição
wallet_uuid	string (UUID)	Sim	Carteira que recebe os fundos
merchant_id	string	Sim	Identificador do merchant
payer_name	string	Sim	Nome completo do pagador
payer_email	string	Sim	E-mail do pagador
payer_tax_id	string	Sim	Documento fiscal (CPF no Brasil, RFC no México, RUT no Chile, CUIT na Argentina)
payer_document_type	string	Condicional	Tipo do documento para payer_tax_id. Obrigatório para PIX e Boleto em BRL quando payer_tax_id é enviado. Recomendado para QRA (ARS) e SPEI/OXXO (MXN). Valores: CPF, CNPJ, DNI, CUIT, CUIL, CURP, RFC, INE, PAS
payer_cell_phone	string	Sim	Celular do pagador com código do país
installment_value	number	Sim	Valor da cobrança por parcela. Para moedas sem decimais (CLP, COP), use inteiros — veja regras de moeda abaixo
installment_count	integer	Sim	Número de parcelas (use 1 para pagamento à vista)
currency	string	Sim	Código de moeda ISO 4217: BRL, MXN, CLP, COP, PEN, ARS
due_date	string	Sim	Data de vencimento no formato YYYY-MM-DD
description	string	Sim	Descrição da cobrança exibida ao pagador
type_charge	string	Sim	Método de pagamento — veja o seletor acima
payer_address	object	Sim	Endereço de cobrança (veja abaixo)

Objeto de endereço do pagador

Campo	Tipo	Obrigatório	Descrição
street	string	Sim	Nome da rua
address_number	string	Sim	Número
complement	string	Sim	Apartamento, sala, andar
neighborhood	string	Sim	Bairro
city	string	Sim	Cidade
state	string	Sim	Código do estado (ex.: SP, CDMX)
postal_code	string	Sim	CEP / Código postal
country	string	Não	ISO 3166-1 alfa-2 (ex.: BR). Padrão: país da carteira

Regras de valor por moeda

Moeda	Decimais	Formato	Exemplo	Comportamento no backend
BRL	2	150.00	"installment_value": 150.00	Armazenado como Numeric(11,2)
MXN	2	2500.00	"installment_value": 2500.00	Armazenado como Numeric(11,2)
USD	2	100.00	"installment_value": 100.00	Armazenado como Numeric(11,2)
PEN	2	350.00	"installment_value": 350.00	Armazenado como Numeric(11,2)
ARS	2	85000.00	"installment_value": 85000.00	Armazenado como Numeric(11,2)
CLP	0	50000	"installment_value": 50000	Truncado para inteiro antes de enviar ao adquirente
COP	0	200000	"installment_value": 200000	Truncado para inteiro antes de enviar ao adquirente

Moedas sem decimais

CLP (Peso Chileno) e COP (Peso Colombiano) não possuem unidades fracionárias. O backend converte valores para inteiros antes de enviar aos adquirentes. Enviar 50000.50 para CLP resulta em 50000. Sempre envie números inteiros para essas moedas.

Payment payload (resposta)

Cobranças PIX, QRA, SPEI e OXXO retornam um objeto unificado payment_payload com campos específicos por método. Chaves legadas de resposta (pix_payload, qra_payload, etc.) não são mais retornadas.

type_charge	Campos em payment_payload
pix	payload (copia e cola EMV), qr_code (PNG Base64), expiration_date
qra	qr_code (PNG Base64), expiration_date
spei	clabe, bank_beneficiary_name, bank_concept, bank_reference, expiration, payment_coupon_url
oxxo	payment_code, payment_barcode_url, payment_coupon_url, expiration

Validação de documento

Quando payer_tax_id é enviado, inclua payer_document_type para que a A55 valide o documento conforme o método e a moeda. Se omitido, a A55 tenta auto-detecção quando possível — tipos explícitos são recomendados para métodos LATAM.

Campos opcionais (todos os métodos)

Campo	Tipo	Padrão	Descrição
webhook_url	string	—	Substituir a URL de webhook padrão para esta cobrança
redirect_url	string	—	URL de retorno para onde o pagador é direcionado após concluir a página de checkout ou qualquer fluxo de action_url (desafio 3DS, fingerprint, autorização em e-wallet, etc.). O webhook continua sendo a fonte de verdade para o status final
reference_external_id	string	—	Seu ID de pedido interno para conciliação
is_async	boolean	false	Processamento assíncrono quando suportado
shipping_address	object	—	Endereço de entrega (mesma estrutura de payer_address)

---

Campos específicos de cartão

Campo	Tipo	Obrigatório	Descrição
card_number	string	Somente H2H	PAN do cartão (SDK e Checkout tratam isso)
card_name	string	Somente H2H	Nome impresso no cartão
card_expiry_month	string	Somente H2H	Mês de validade MM
card_expiry_year	string	Somente H2H	Ano de validade YYYY
card_cvv	string	Somente H2H	Código de verificação do cartão
capture	boolean	Não	true (padrão) = captura automática; false = somente autorização
threeds_authentication	boolean	Não	true para forçar autenticação 3DS
device_info	object	3DS	Fingerprint do navegador/dispositivo para 3DS (veja abaixo)
antifraud_info	object	Não	Dados comportamentais para scoring antifraude
subscription	object	Não	Cria uma assinatura recorrente com esta cobrança

Quando os campos do cartão são obrigatórios?

• Integração H2H: Você envia card_number, card_name, card_expiry_month, card_expiry_year, card_cvv diretamente.
• Integração SDK: O SDK coleta os dados do cartão no navegador. Você envia apenas os campos universais.
• Página de Checkout: A página hospedada da A55 coleta tudo. Você envia apenas campos universais + redirect_url.

Objeto de informações do dispositivo (3DS)

Obrigatório quando threeds_authentication: true em fluxos H2H:

Campo	Tipo	Descrição
ip_address	string	Endereço IP do pagador
user_agent	string	String user-agent do navegador
device_id	string	Fingerprint do dispositivo gerado pelo SDK
session_id	string	ID de sessão DDC do emissor
http_accept_content	string	Header Accept do navegador
http_browser_language	string	Idioma do navegador (ex.: pt-BR)
http_browser_java_enabled	boolean	Java habilitado no navegador
http_browser_javascript_enabled	boolean	JavaScript habilitado
http_browser_color_depth	string	Profundidade de cor (ex.: 24)
http_browser_screen_height	string	Altura da tela em pixels
http_browser_screen_width	string	Largura da tela em pixels
http_browser_time_difference	string	Deslocamento UTC (ex.: -3)

Objeto de informações antifraude

Melhora o scoring de fraude e taxas de aprovação:

Campo	Tipo	Descrição
sales_channel	string	web, app, pos, marketplace, link, subscription, api
cardholder_logged_in	boolean	Se o pagador estava logado
cardholder_since_days	integer	Dias desde a criação da conta
purchase_history	integer	Total de compras anteriores
days_since_last_purchase_merchant	integer	Dias desde a última compra com você

Objeto de assinatura

Cria uma assinatura recorrente vinculada a esta cobrança:

Campo	Tipo	Obrigatório	Descrição
cycle	string	Sim	weekly, biweekly, monthly, quarterly, semiannually, yearly
end_date	string	Não	Data final da assinatura YYYY-MM-DD (omita para indefinido)

Campos do Apple Pay

Campo	Tipo	Obrigatório	Descrição
applepay.type	string	Sim	credit_card ou debit_card
applepay.eci	string	Sim	Indicador de Comércio Eletrônico do token Apple Pay
applepay.cavv	string	Sim	Valor de Verificação de Autenticação do Portador

Token Apple Pay

Seu frontend obtém o token Apple Pay via a API Apple Pay JS. Extraia eci e cavv dos dados de pagamento do token e passe-os aqui. A A55 cuida do restante.

Campos do Google Pay

Campo	Tipo	Obrigatório	Descrição
googlepay.type	string	Sim	credit_card ou debit_card
googlepay.eci	string	Não	Indicador de Comércio Eletrônico
googlepay.cavv	string	Não	Valor de Verificação de Autenticação do Portador

Token Google Pay

Seu frontend obtém o token Google Pay via a API Google Pay. Extraia os dados do criptograma e passe-os aqui. A A55 descriptografa e processa o pagamento.

Comportamento específico do PIX

PIX não requer campos adicionais além dos parâmetros universais. Defina type_charge: "pix" e envie payer_document_type: "CPF" ou "CNPJ" junto com payer_tax_id.

A resposta inclui payment_payload:

Campo	Descrição
payment_payload.payload	String copia e cola EMV (PIX copia e cola)
payment_payload.qr_code	PNG do QR code codificado em Base64
payment_payload.expiration_date	Timestamp de expiração do QR code

PIX é instantâneo

Pagamentos PIX confirmam em segundos. Seu webhook disparará quase imediatamente com status: "paid". Nenhuma etapa de captura é necessária.

Comportamento específico do Boleto

Boleto não requer campos adicionais além dos parâmetros universais. Defina type_charge: "boleto" e a resposta incluirá:

• boleto_barcode — Código de barras numérico (44 dígitos)
• boleto_url — URL para o PDF do boleto bancário imprimível
• boleto_due_date — Prazo de pagamento

Liquidação do Boleto

Pagamentos por Boleto liquidam em 1-3 dias úteis após o pagador pagar em um banco, casa lotérica ou aplicativo bancário. Seu webhook dispara quando o pagamento é confirmado pela rede bancária.

Comportamento específico do SPEI

SPEI não requer campos adicionais além dos parâmetros universais. Defina type_charge: "spei", moeda MXN, e envie payer_document_type (recomendado: CURP, RFC, INE ou PAS) com payer_tax_id.

A resposta inclui payment_payload com CLABE, nome do beneficiário, referência bancária e expiração para o pagador completar a transferência.

Liquidação SPEI

Transferências SPEI no México geralmente liquidam em minutos durante o horário bancário. A A55 monitora o pagamento e envia um webhook quando confirmado.

Comportamento específico do OXXO

OXXO não requer campos adicionais além dos parâmetros universais. Defina type_charge: "oxxo", moeda MXN, e envie payer_document_type (recomendado: CURP, RFC, INE ou PAS) com payer_tax_id.

A resposta inclui payment_payload com payment_code, payment_barcode_url, payment_coupon_url e expiration para o pagador apresentar em qualquer loja OXXO.

Liquidação OXXO

Pagamentos em dinheiro no OXXO liquidam em 1-2 dias úteis após o pagador pagar na loja. A referência expira na due_date.

Comportamento do QR Argentina

QRA não requer campos adicionais além dos parâmetros universais. Defina type_charge: "qra", moeda ARS, e envie payer_document_type (recomendado: DNI, CUIT, CUIL ou PAS) com payer_tax_id.

A resposta inclui payment_payload com qr_code (PNG Base64) e expiration_date para o pagador escanear com o app bancário.

Comportamento do Pago Facil

Pago Facil não requer campos adicionais além dos parâmetros universais. Defina type_charge: "pfc" e a moeda como ARS. A resposta inclui um comprovante de pagamento e número de referência para o pagador apresentar em qualquer unidade Pago Facil.

Comportamento da Carteira Digital

Carteira Digital não requer campos adicionais além dos parâmetros universais. Defina type_charge: "e_wallet". A resposta inclui uma URL de redirecionamento ou deep link para o aplicativo do provedor da carteira para o pagador autorizar o pagamento.

---

Exemplos de código

Cobrança com cartão de crédito

cURL

curl -s -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "Maria Silva",
    "payer_email": "maria@example.com",
    "payer_tax_id": "123.456.789-09",
    "payer_cell_phone": "+5511999999999",
    "installment_value": 150.00,
    "installment_count": 3,
    "currency": "BRL",
    "due_date": "2026-12-31",
    "description": "Order #42 — 3x installments",
    "type_charge": "credit_card",
    "card_number": "4024007153763191",
    "card_name": "MARIA SILVA",
    "card_expiry_month": "12",
    "card_expiry_year": "2030",
    "card_cvv": "123",
    "capture": true,
    "webhook_url": "https://your-app.com/webhooks/a55",
    "payer_address": {
      "street": "Av. Paulista",
      "address_number": "1000",
      "complement": "Sala 101",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR"
    }
  }'

Python

import requests

charge = requests.post(
    "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
    json={
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "merchant_id": "11111111-1111-1111-1111-111111111111",
        "payer_name": "Maria Silva",
        "payer_email": "maria@example.com",
        "payer_tax_id": "123.456.789-09",
        "payer_cell_phone": "+5511999999999",
        "installment_value": 150.00,
        "installment_count": 3,
        "currency": "BRL",
        "due_date": "2026-12-31",
        "description": "Order #42 — 3x installments",
        "type_charge": "credit_card",
        "card_number": "4024007153763191",
        "card_name": "MARIA SILVA",
        "card_expiry_month": "12",
        "card_expiry_year": "2030",
        "card_cvv": "123",
        "capture": True,
        "webhook_url": "https://your-app.com/webhooks/a55",
        "payer_address": {
            "street": "Av. Paulista",
            "address_number": "1000",
            "complement": "Sala 101",
            "neighborhood": "Bela Vista",
            "city": "São Paulo",
            "state": "SP",
            "postal_code": "01310-100",
            "country": "BR",
        },
    },
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
).json()

print(f"Charge: {charge['charge_uuid']} — Status: {charge['status']}")
print(f"Total: {charge['installment_count']}x R$ {charge['installments'][0]['local_currency']}")

JavaScript

const charge = await fetch(
  "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      merchant_id: "11111111-1111-1111-1111-111111111111",
      payer_name: "Maria Silva",
      payer_email: "maria@example.com",
      payer_tax_id: "123.456.789-09",
      payer_cell_phone: "+5511999999999",
      installment_value: 150.0,
      installment_count: 3,
      currency: "BRL",
      due_date: "2026-12-31",
      description: "Order #42 — 3x installments",
      type_charge: "credit_card",
      card_number: "4024007153763191",
      card_name: "MARIA SILVA",
      card_expiry_month: "12",
      card_expiry_year: "2030",
      card_cvv: "123",
      capture: true,
      webhook_url: "https://your-app.com/webhooks/a55",
      payer_address: {
        street: "Av. Paulista",
        address_number: "1000",
        complement: "Sala 101",
        neighborhood: "Bela Vista",
        city: "São Paulo",
        state: "SP",
        postal_code: "01310-100",
        country: "BR",
      },
    }),
  }
).then(r => r.json());

console.log(`Charge: ${charge.charge_uuid} — Status: ${charge.status}`);
console.log(`Total: ${charge.installment_count}x R$ ${charge.installments[0].local_currency}`);

Cobrança com cartão de débito

cURL

curl -s -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "João Santos",
    "payer_email": "joao@example.com",
    "payer_tax_id": "987.654.321-00",
    "payer_cell_phone": "+5511988888888",
    "installment_value": 89.90,
    "installment_count": 1,
    "currency": "BRL",
    "due_date": "2026-12-31",
    "description": "Order #43 — Debit",
    "type_charge": "debit_card",
    "card_number": "5155901222280001",
    "card_name": "JOAO SANTOS",
    "card_expiry_month": "06",
    "card_expiry_year": "2029",
    "card_cvv": "456",
    "webhook_url": "https://your-app.com/webhooks/a55",
    "payer_address": {
      "street": "Rua Augusta", "address_number": "500",
      "complement": "Apt 42", "neighborhood": "Consolação",
      "city": "São Paulo", "state": "SP",
      "postal_code": "01304-000", "country": "BR"
    }
  }'

Python

charge = requests.post(
    "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
    json={
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "merchant_id": "11111111-1111-1111-1111-111111111111",
        "payer_name": "João Santos",
        "payer_email": "joao@example.com",
        "payer_tax_id": "987.654.321-00",
        "payer_cell_phone": "+5511988888888",
        "installment_value": 89.90,
        "installment_count": 1,
        "currency": "BRL",
        "due_date": "2026-12-31",
        "description": "Order #43 — Debit",
        "type_charge": "debit_card",
        "card_number": "5155901222280001",
        "card_name": "JOAO SANTOS",
        "card_expiry_month": "06",
        "card_expiry_year": "2029",
        "card_cvv": "456",
        "webhook_url": "https://your-app.com/webhooks/a55",
        "payer_address": {
            "street": "Rua Augusta", "address_number": "500",
            "complement": "Apt 42", "neighborhood": "Consolação",
            "city": "São Paulo", "state": "SP",
            "postal_code": "01304-000", "country": "BR",
        },
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()
print(f"Status: {charge['status']}")

JavaScript

const charge = await fetch("https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    merchant_id: "11111111-1111-1111-1111-111111111111",
    payer_name: "João Santos", payer_email: "joao@example.com",
    payer_tax_id: "987.654.321-00", payer_cell_phone: "+5511988888888",
    installment_value: 89.9, installment_count: 1,
    currency: "BRL", due_date: "2026-12-31",
    description: "Order #43 — Debit", type_charge: "debit_card",
    card_number: "5155901222280001", card_name: "JOAO SANTOS",
    card_expiry_month: "06", card_expiry_year: "2029", card_cvv: "456",
    webhook_url: "https://your-app.com/webhooks/a55",
    payer_address: {
      street: "Rua Augusta", address_number: "500", complement: "Apt 42",
      neighborhood: "Consolação", city: "São Paulo", state: "SP",
      postal_code: "01304-000", country: "BR",
    },
  }),
}).then(r => r.json());
console.log(`Status: ${charge.status}`);

Cobrança PIX

cURL

curl -s -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "Ana Costa",
    "payer_email": "ana@example.com",
    "payer_tax_id": "111.222.333-44",
    "payer_cell_phone": "+5521977777777",
    "installment_value": 49.90,
    "installment_count": 1,
    "currency": "BRL",
    "due_date": "2026-12-31",
    "description": "Order #44 — PIX",
    "type_charge": "pix",
    "webhook_url": "https://your-app.com/webhooks/a55",
    "payer_address": {
      "street": "Av. Rio Branco", "address_number": "200",
      "complement": "Sala 301", "neighborhood": "Centro",
      "city": "Rio de Janeiro", "state": "RJ",
      "postal_code": "20040-002", "country": "BR"
    }
  }'

Python

charge = requests.post(
    "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
    json={
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "merchant_id": "11111111-1111-1111-1111-111111111111",
        "payer_name": "Ana Costa",
        "payer_email": "ana@example.com",
        "payer_tax_id": "111.222.333-44",
        "payer_cell_phone": "+5521977777777",
        "installment_value": 49.90,
        "installment_count": 1,
        "currency": "BRL",
        "due_date": "2026-12-31",
        "description": "Order #44 — PIX",
        "type_charge": "pix",
        "webhook_url": "https://your-app.com/webhooks/a55",
        "payer_address": {
            "street": "Av. Rio Branco", "address_number": "200",
            "complement": "Sala 301", "neighborhood": "Centro",
            "city": "Rio de Janeiro", "state": "RJ",
            "postal_code": "20040-002", "country": "BR",
        },
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()
print(f"PIX QR Code URL: {charge.get('charge_payment_url')}")
print(f"Status: {charge['status']}")

JavaScript

const charge = await fetch("https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    merchant_id: "11111111-1111-1111-1111-111111111111",
    payer_name: "Ana Costa", payer_email: "ana@example.com",
    payer_tax_id: "111.222.333-44", payer_cell_phone: "+5521977777777",
    installment_value: 49.9, installment_count: 1,
    currency: "BRL", due_date: "2026-12-31",
    description: "Order #44 — PIX", type_charge: "pix",
    webhook_url: "https://your-app.com/webhooks/a55",
    payer_address: {
      street: "Av. Rio Branco", address_number: "200", complement: "Sala 301",
      neighborhood: "Centro", city: "Rio de Janeiro", state: "RJ",
      postal_code: "20040-002", country: "BR",
    },
  }),
}).then(r => r.json());
console.log(`PIX QR Code URL: ${charge.charge_payment_url}`);

Cobrança com método alternativo

O payload é o mesmo dos campos universais. Apenas altere type_charge e currency para corresponder ao seu método e país.

cURL

curl -s -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "YOUR_WALLET_UUID",
    "merchant_id": "YOUR_MERCHANT_UUID",
    "payer_name": "Payer Name",
    "payer_email": "payer@example.com",
    "payer_tax_id": "TAX_ID",
    "payer_cell_phone": "+PHONE",
    "installment_value": 100.00,
    "installment_count": 1,
    "currency": "BRL",
    "due_date": "2026-12-31",
    "description": "Order description",
    "type_charge": "boleto",
    "webhook_url": "https://your-app.com/webhooks/a55",
    "payer_address": {
      "street": "Street", "address_number": "123",
      "complement": "Suite", "neighborhood": "District",
      "city": "City", "state": "ST",
      "postal_code": "00000-000", "country": "BR"
    }
  }'

Python

charge = requests.post(
    "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
    json={
        "wallet_uuid": "YOUR_WALLET_UUID",
        "merchant_id": "YOUR_MERCHANT_UUID",
        "payer_name": "Payer Name",
        "payer_email": "payer@example.com",
        "payer_tax_id": "TAX_ID",
        "payer_cell_phone": "+PHONE",
        "installment_value": 100.00,
        "installment_count": 1,
        "currency": "BRL",
        "due_date": "2026-12-31",
        "description": "Order description",
        "type_charge": "boleto",  # altere para: spei, oxxo, qra, pfc, e_wallet
        "webhook_url": "https://your-app.com/webhooks/a55",
        "payer_address": {
            "street": "Street", "address_number": "123",
            "complement": "Suite", "neighborhood": "District",
            "city": "City", "state": "ST",
            "postal_code": "00000-000", "country": "BR",
        },
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

JavaScript

const charge = await fetch("https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    wallet_uuid: "YOUR_WALLET_UUID",
    merchant_id: "YOUR_MERCHANT_UUID",
    payer_name: "Payer Name", payer_email: "payer@example.com",
    payer_tax_id: "TAX_ID", payer_cell_phone: "+PHONE",
    installment_value: 100.0, installment_count: 1,
    currency: "BRL", due_date: "2026-12-31",
    description: "Order description",
    type_charge: "boleto", // altere para: spei, oxxo, qra, pfc, e_wallet
    webhook_url: "https://your-app.com/webhooks/a55",
    payer_address: {
      street: "Street", address_number: "123", complement: "Suite",
      neighborhood: "District", city: "City", state: "ST",
      postal_code: "00000-000", country: "BR",
    },
  }),
}).then(r => r.json());

Cobrança Apple Pay / Google Pay

cURL

curl -s -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "Carlos Mendes",
    "payer_email": "carlos@example.com",
    "payer_tax_id": "555.666.777-88",
    "payer_cell_phone": "+5511966666666",
    "installment_value": 299.00,
    "installment_count": 1,
    "currency": "BRL",
    "due_date": "2026-12-31",
    "description": "Order #45 — Apple Pay",
    "type_charge": "applepay",
    "applepay": {
      "type": "credit_card",
      "eci": "05",
      "cavv": "AAABBJg0VhI0VniQEjRWAAAAAAA="
    },
    "webhook_url": "https://your-app.com/webhooks/a55",
    "payer_address": {
      "street": "Av. Faria Lima", "address_number": "3000",
      "complement": "18 andar", "neighborhood": "Itaim Bibi",
      "city": "São Paulo", "state": "SP",
      "postal_code": "04538-132", "country": "BR"
    }
  }'

Python

charge = requests.post(
    "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/",
    json={
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "merchant_id": "11111111-1111-1111-1111-111111111111",
        "payer_name": "Carlos Mendes",
        "payer_email": "carlos@example.com",
        "payer_tax_id": "555.666.777-88",
        "payer_cell_phone": "+5511966666666",
        "installment_value": 299.00,
        "installment_count": 1,
        "currency": "BRL",
        "due_date": "2026-12-31",
        "description": "Order #45 — Apple Pay",
        "type_charge": "applepay",
        "applepay": {"type": "credit_card", "eci": "05", "cavv": "AAABBJg0VhI0VniQEjRWAAAAAAA="},
        "webhook_url": "https://your-app.com/webhooks/a55",
        "payer_address": {
            "street": "Av. Faria Lima", "address_number": "3000",
            "complement": "18 andar", "neighborhood": "Itaim Bibi",
            "city": "São Paulo", "state": "SP",
            "postal_code": "04538-132", "country": "BR",
        },
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

JavaScript

const charge = await fetch("https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    merchant_id: "11111111-1111-1111-1111-111111111111",
    payer_name: "Carlos Mendes", payer_email: "carlos@example.com",
    payer_tax_id: "555.666.777-88", payer_cell_phone: "+5511966666666",
    installment_value: 299.0, installment_count: 1,
    currency: "BRL", due_date: "2026-12-31",
    description: "Order #45 — Apple Pay", type_charge: "applepay",
    applepay: { type: "credit_card", eci: "05", cavv: "AAABBJg0VhI0VniQEjRWAAAAAAA=" },
    webhook_url: "https://your-app.com/webhooks/a55",
    payer_address: {
      street: "Av. Faria Lima", address_number: "3000", complement: "18 andar",
      neighborhood: "Itaim Bibi", city: "São Paulo", state: "SP",
      postal_code: "04538-132", country: "BR",
    },
  }),
}).then(r => r.json());

---

Resposta

Ciclo de vida da cobrança

Campos da resposta

Campo	Tipo	Descrição
charge_uuid	string	Identificador único da cobrança
status	string	issued, pending, confirmed, paid, error, canceled, refunded
local_currency	number	Valor na moeda de liquidação da carteira
currency	string	Código de moeda ISO 4217
usd_currency	number	Valor equivalente em USD
eur_currency	number	Valor equivalente em EUR
type	string	Método de pagamento utilizado
date	string	Data de criação da cobrança
description	string	Descrição da cobrança
due_date	string	Data de vencimento do pagamento
installment_count	integer	Número de parcelas
installments	array	Detalhamento por parcela
charge_payment_url	string	URL de pagamento Checkout/SDK (quando aplicável)
action_url	string/null	URL de redirecionamento para ação do pagador (desafio 3DS ou fingerprint). Quando presente, status é pending — redirecione o pagador para concluir o fluxo. Após conclusão, o pagador retorna para redirect_url e um webhook é enviado para webhook_url

| reference_external_id | string | ID de referência externa fornecido pelo merchant | | is_async | boolean | Se a cobrança foi processada de forma assíncrona | | message | array/null | Detalhes do erro quando status: "error" | | subscription | object | Detalhes da assinatura (quando subscription foi incluído) |

Exemplo de resposta de cartão

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "local_currency": 150.00,
  "currency": "BRL",
  "usd_currency": 26.90,
  "eur_currency": 23.58,
  "type": "credit_card",
  "date": "2026-03-20",
  "description": "Order #42 — 3x installments",
  "due_date": "2026-12-31",
  "status": "confirmed",
  "message": null,
  "installment_count": 3,
  "installments": [
    {
      "local_currency": 50.00,
      "currency": "BRL",
      "usd_currency": 8.97,
      "eur_currency": 7.86,
      "due_date": "2026-12-31",
      "status": "confirmed",
      "installment_number": 1
    },
    {
      "local_currency": 50.00,
      "currency": "BRL",
      "usd_currency": 8.97,
      "eur_currency": 7.86,
      "due_date": "2027-01-31",
      "status": "confirmed",
      "installment_number": 2
    },
    {
      "local_currency": 50.00,
      "currency": "BRL",
      "usd_currency": 8.97,
      "eur_currency": 7.86,
      "due_date": "2027-02-28",
      "status": "confirmed",
      "installment_number": 3
    }
  ]
}

Exemplo de resposta pendente (action_url)

Quando a cobrança requer um desafio 3DS ou coleta de fingerprint, a resposta inclui action_url com status: "pending". Redirecione o pagador para action_url para concluir o fluxo.

{
  "charge_uuid": "fe5e2c1e-b3fb-4cc4-bb28-004da37d5804",
  "local_currency": 159.8,
  "currency": "EUR",
  "usd_currency": 185.52,
  "type": "credit_card",
  "date": "2026-04-01",
  "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
  "due_date": "2025-10-11",
  "status": "pending",
  "message": null,
  "installment_count": 1,
  "installments": [],
  "charge_payment_url": null,
  "action_url": "https://acquirer.example/payment/69cd4a32e367...",
  "reference_external_id": "e4e3ec12-b51a-4ea2-aceb-2b41602a5a84",
  "is_async": false
}

Exemplo de resposta PIX

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "local_currency": 49.90,
  "currency": "BRL",
  "usd_currency": 8.95,
  "eur_currency": 7.85,
  "type": "pix",
  "date": "2026-03-20",
  "description": "Order #44 — PIX",
  "due_date": "2026-12-31",
  "status": "issued",
  "installment_count": 1,
  "installments": [
    {
      "local_currency": 49.90,
      "currency": "BRL",
      "due_date": "2026-12-31",
      "status": "issued",
      "installment_number": 1
    }
  ],
  "payment_payload": {
    "qr_code": "iVBORw0KGgoAAAANSUhEU...",
    "payload": "00020126580014br.gov.bcb.pix0136f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "expiration_date": "2026-03-21 14:30:00.000000"
  },
  "charge_payment_url": "https://pay.a55.tech/charge/51dcca6e-7310-4b73-a94c-90835408f2ff"
}

Exemplo de resposta

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "local_currency": 100.00,
  "currency": "BRL",
  "usd_currency": 17.93,
  "eur_currency": 15.72,
  "type": "boleto",
  "date": "2026-03-20",
  "description": "Order description",
  "due_date": "2026-12-31",
  "status": "issued",
  "installment_count": 1,
  "installments": [
    {
      "local_currency": 100.00,
      "currency": "BRL",
      "due_date": "2026-12-31",
      "status": "issued",
      "installment_number": 1
    }
  ],
  "charge_payment_url": "https://pay.a55.tech/charge/51dcca6e-7310-4b73-a94c-90835408f2ff"
}

Resposta de erro

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "status": "error",
  "message": [
    {
      "code": "error_threeds_authentication",
      "source": "authentication",
      "description": "Issuing bank declined the authentication"
    }
  ]
}

---

Códigos de erro

Código	Significado	O que fazer
INVALID_TYPE_CHARGE	Valor de type_charge não suportado	Verifique os valores permitidos no seletor acima
errors.wallet.not_found	UUID da carteira não existe	Verifique o wallet_uuid
errors.unexpected	Erro interno do servidor	Tente novamente com backoff exponencial; entre em contato com o suporte se persistir
error_threeds_authentication	Autenticação 3DS falhou	Peça ao pagador para tentar novamente ou usar outro cartão

Sempre use webhooks

Nunca dependa apenas da resposta síncrona para o status final do pagamento. A cobrança pode passar por vários estados assincronamente. Defina webhook_url e trate o webhook como a fonte da verdade.

Consultar cobrança →Consultar status da cobrança por UUID.Capturar cobrança →Capturar um pagamento de cartão previamente autorizado.Webhooks →Receber atualizações de status em tempo real.