Entrar Começar
Docs Referência da API

Bem-vindo à A4therPay

Gateway de pagamentos brasileiro com API REST para PIX, webhooks com retry automático e SDKs em sete linguagens.

v1 PIX Última atualização

O que é a A4therPay #

A4therPay é uma camada de pagamentos sobre PIX. Você cria uma cobrança pela nossa API, e nós cuidamos do resto: geração do PIX, conciliação, webhooks com retry, saques e transferências entre contas A4therPay.

Hoje a A4therPay processa PIX.

Cartão e boleto estão no roadmap, ainda sem data. A documentação abaixo cobre apenas o que a API faz hoje.

Base URL

# Producao e sandbox usam o mesmo host. O modo vem do prefixo da chave.
https://a4therpay-api.discloud.app/api/v1

Quickstart #

O cadastro do lojista é feito no site a4therpay.com; não há endpoint de API para isso. Depois de criar a conta, gere uma chave de teste no painel da A4therPay. As chaves a4ther_test_* são gratuitas e ilimitadas.

1. Instale o SDK

npm install a4therpay

2. Crie a primeira cobrança

# Cria uma cobranca PIX de R$ 49,90
curl -X POST https://a4therpay-api.discloud.app/api/v1/charges/ \
  -H "Authorization: Bearer a4ther_test_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 4990,
    "description": "Pedido 1042",
    "customer": { "name": "Ana Lima", "email": "ana@empresa.com" }
  }'

3. Resposta

201 Created · application/json
{
  "id": "chg_test_aB3kfP9XmZ8s2nQwRtY7",
  "merchant_id": "01HXY2Z3...",
  "status": "pending",
  "amount_cents": 4990,
  "currency": "BRL",
  "payment_method": "pix",
  "pix_copy_paste": "00020126...",
  "pix_qr_code": "data:image/png;base64,iVBORw0KGgo...",
  "fee_processor_cents": 49,
  "fee_platform_cents": 35,
  "net_amount_cents": 4906,
  "customer": { "name": "Ana Lima", "email": "ana@empresa.com" },
  "metadata": {},
  "expires_at": "2026-06-08T19:42:18+00:00",
  "created_at": "2026-06-08T19:27:18+00:00",
  "updated_at": "2026-06-08T19:27:18+00:00"
}

Pronto. O webhook charge.paid chega logo em seguida.

No sandbox, qualquer valor (exceto magic values) é aprovado em poucos segundos. Configure o endpoint que recebe os webhooks no painel da A4therPay.

Autenticação #

Toda chamada server-to-server usa API Keys via header Authorization: Bearer a4ther_(test|live)_xxx. O modo é derivado automaticamente do prefixo:

PrefixoModoComportamento
a4ther_test_SandboxNenhuma transação real, dados isolados em cache com TTL 30 dias.
a4ther_live_ProduçãoCobra de verdade. Liquidação imediata via PIX.

A API Key é criada no painel da A4therPay; não há endpoint público para gerá-la. O cadastro e o login do lojista também ficam no painel e usam JWT, fora do escopo desta referência de integração.

Nunca exponha chaves no front-end.

Cada chave carrega apenas os escopos que você atribuiu (veja Escopos). Use sempre no servidor (server-to-server).

Escopos

Toda chamada com API Key valida os escopos da chave contra o escopo exigido pelo endpoint. Sem o escopo, a resposta é 403 com API_KEY_INSUFFICIENT_SCOPE. Atribua só o necessário a cada chave.

EscopoPermite
payments.createCriar cobranças PIX (POST /charges/)
payments.readListar e consultar cobranças (GET /charges/, GET /charges/{id})
withdrawals.createCriar saques e transferências internas (POST /withdrawals/, POST /internal-transfers/)
withdrawals.readListar e consultar saques (GET /withdrawals/, GET /withdrawals/{id})
transfers.readListar e consultar transferências internas (GET /internal-transfers/, GET /internal-transfers/{id})

O extrato (GET /transactions/) aceita qualquer um entre payments.read, transfers.read ou withdrawals.read.

Sandbox #

Use chaves a4ther_test_* para simular pagamentos sem cobrar ninguém. O sandbox dispara webhooks reais com a mesma assinatura HMAC SHA-256 da produção.

Magic values

O amount_cents determina o resultado simulado da cobrança. Os valores exatos são publicados pela API pública (abaixo); use sempre a resposta dela como verdade:

ValorEm R$Resultado
1R$ 0,01cobrança fica paid
2R$ 0,02cobrança fica expired
3R$ 0,03cobrança fica refunded
qualquer outro-cobrança fica paid

Lista atualizada em tempo real via API pública:

curl https://a4therpay-api.discloud.app/api/v1/test/scenarios

Resetar dados sandbox

Apaga todos os charges de teste do merchant atual:

curl -X POST https://a4therpay-api.discloud.app/api/v1/test/reset \
  -H "Authorization: Bearer a4ther_test_xxx"

Saques e transferências não têm sandbox.

Os endpoints /withdrawals/ e /internal-transfers/ (e o extrato /transactions/) recusam chaves a4ther_test_ com 403 SANDBOX_NOT_SUPPORTED_FOR_WITHDRAWALS / SANDBOX_NOT_SUPPORTED_FOR_TRANSFERS. Teste-os apenas com chave a4ther_live_.

Idempotência #

Os endpoints de escrita aceitam o header Idempotency-Key com um identificador único por operação (recomendamos UUID v4 ou ULID):

Por que isso importa

Em redes instáveis, retry automático do seu cliente HTTP pode duplicar cobranças. Idempotency-Key garante que só uma vai pra frente, mesmo com 10 retries.

Rate limits #

Aplicamos limites por chave de API numa janela rolante curta. Os limites de escrita são mais apertados que os de leitura.

Quando o limite é excedido, retornamos 429 com RATE_LIMITED e o header Retry-After em segundos. Respeite o Retry-After e use backoff exponencial nos retries.

Tratamento de erros #

Erros sempre vêm em application/json com a seguinte estrutura. details é uma lista (pode estar vazia ou ausente) e cada item traz field, message e type:

422 Unprocessable Entity · application/json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados inválidos",
    "details": [
      { "field": "amount_cents", "message": "Input should be greater than or equal to 100", "type": "greater_than_equal" }
    ],
    "trace_id": "01HV3K2N9PXY7M..."
  }
}

Códigos de erro

O campo code usa valores canônicos estáveis. Trate sempre pelo code, não pela message (que pode mudar):

CódigoHTTPSignificado
VALIDATION_ERROR422Payload ou parâmetros inválidos. Veja details.
AUTHENTICATION_REQUIRED401Header de autenticação ausente.
INVALID_CREDENTIALS401Chave ou token inválido/expirado.
PERMISSION_DENIED403Conta sem permissão para a ação.
API_KEY_INSUFFICIENT_SCOPE403A chave não tem o escopo exigido pelo endpoint.
SANDBOX_NOT_SUPPORTED_FOR_WITHDRAWALS403Saque tentado com chave a4ther_test_.
SANDBOX_NOT_SUPPORTED_FOR_TRANSFERS403Transferência interna tentada com chave a4ther_test_.
NOT_FOUND404Recurso inexistente ou de outro merchant.
CONFLICT409Estado conflitante com a operação.
IDEMPOTENCY_CONFLICT409Idempotency-Key reutilizada com payload diferente.
INSUFFICIENT_BALANCE422Saldo insuficiente para saque/transferência.
RATE_LIMITED429Limite de requisições excedido. Veja Retry-After.
UPSTREAM_ERROR502Falha temporária no processador. Tente de novo com backoff.
INTERNAL_ERROR500Falha do nosso lado. Tente de novo com backoff.

Status codes

StatusSignificadoQuando ocorre
200OKGET ou PATCH bem sucedido
201CreatedPOST criou novo recurso
204No ContentDELETE bem sucedido
400Bad RequestBody inválido, campo obrigatório faltando
401UnauthorizedToken ausente ou expirado
403ForbiddenEscopo insuficiente, conta sem permissão, ou sandbox não suportado
404Not FoundRecurso inexistente ou não pertence ao merchant
409ConflictIdempotency-Key reutilizada com payload diferente
422UnprocessableValidação de schema falhou ou estado impeditivo (ex: saldo insuficiente)
429Rate LimitedExcedeu rate limit. Veja header Retry-After
5xxServer ErrorFalha do nosso lado. Tente novamente com backoff

Endpoints: Charges #

Criar charge

POST /api/v1/charges/

Cria uma cobrança PIX. Escopo exigido: payments.create. Use Idempotency-Key para garantir não-duplicação em retries. Suporta sandbox (o modo vem do prefixo da chave). O body é validado com schema estrito: campos fora da lista abaixo são rejeitados com 422.

CampoTipoObrigatórioDescrição
amount_centsintsimValor em centavos. Min 100 (R$ 1,00), max 100.000 (R$ 1.000,00).
descriptionstringnãoTexto curto que aparece pro pagador (max 500 caracteres).
customerobjectnãoIdentificação do pagador: name, email, document, phone.
expires_in_secondsintnãoTempo até a cobrança expirar (60 a 604800). Default do processador.
pass_fee_to_payerboolnãoDefault true. Soma a taxa no valor cobrado, você recebe bruto. Quando false, a taxa sai do seu valor.
affiliate_codestringnãoCódigo de afiliado. Se válido, registra comissão quando paga.
split_rule_idstringnãoID de uma regra de split do merchant (criada no painel da A4therPay). Se setado e ativo, divide o valor líquido entre os recebedores quando a cobrança for paga.
metadataobjectnãoObjeto livre persistido na cobrança. Devolvido em todos os reads e webhooks.
# Cria uma cobranca PIX de R$ 49,90
curl -X POST https://a4therpay-api.discloud.app/api/v1/charges/ \
  -H "Authorization: Bearer a4ther_test_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 4990,
    "description": "Pedido 1042",
    "customer": { "name": "Ana Lima", "email": "ana@empresa.com" },
    "pass_fee_to_payer": true
  }'

Buscar charge

GET /api/v1/charges/{charge_id}

Retorna estado atual da cobrança. Escopo exigido: payments.read.

curl https://a4therpay-api.discloud.app/api/v1/charges/chg_test_aB3k... \
  -H "Authorization: Bearer a4ther_test_xxx"

Listar charges

GET /api/v1/charges/

Listagem paginada. Escopo exigido: payments.read. Filtros: status (pending, paid, expired, cancelled, refunded), page, per_page (max 100), sort (ex: -created_at). A resposta usa o envelope { data, page, per_page, total, has_next, has_prev }.

curl "https://a4therpay-api.discloud.app/api/v1/charges/?status=paid&page=1&per_page=20" \
  -H "Authorization: Bearer a4ther_test_xxx"

Endpoints: Transactions #

Extrato

GET /api/v1/transactions/

Lista lançamentos do extrato (créditos por cobrança paga, débitos por saque/transferência, taxas, ajustes). Escopo exigido: qualquer um entre payments.read, transfers.read ou withdrawals.read. Não suporta sandbox: chaves a4ther_test_ recebem 403. Filtros: page, per_page (max 100), sort. Envelope { data, page, per_page, total, has_next, has_prev }.

curl "https://a4therpay-api.discloud.app/api/v1/transactions/?page=1" \
  -H "Authorization: Bearer a4ther_live_xxx"

Detalhe da transação

GET /api/v1/transactions/{tx_id}

Retorna um lançamento por ID. Mesmos escopos do extrato. Não suporta sandbox.

Endpoints: Saques (Withdrawals) #

Saque PIX do saldo da sua conta A4therPay para uma chave PIX. Os endpoints de saque não suportam sandbox: chaves a4ther_test_ recebem 403 SANDBOX_NOT_SUPPORTED_FOR_WITHDRAWALS.

Criar saque

POST /api/v1/withdrawals/

Escopo exigido: withdrawals.create. Header Idempotency-Key recomendado (UUID/ULID único por operação). Saldo insuficiente retorna 422 INSUFFICIENT_BALANCE.

CampoTipoObrigatórioDescrição
amount_centsintsimValor bruto em centavos. Min 100 (R$ 1,00), max 10.000.000 (R$ 100.000,00).
pix_keystringsimChave PIX de destino (1 a 140 chars).
pix_key_typeenumsimUm de cpf, cnpj, email, phone, evp.
descriptionstringnãoTexto livre (max 140 chars).
curl -X POST https://a4therpay-api.discloud.app/api/v1/withdrawals/ \
  -H "Authorization: Bearer a4ther_live_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 50000,
    "pix_key": "financeiro@empresa.com",
    "pix_key_type": "email",
    "description": "Saque semanal"
  }'

A resposta traz id, status (pending, processing, completed, failed), amount_cents, fee_cents, net_cents, pix_key, pix_key_type, completed_at e failure_reason quando aplicável.

Listar saques

GET /api/v1/withdrawals/

Escopo exigido: withdrawals.read. Filtros: limit (max 100), offset, status (pending, processing, completed, failed). Envelope { data, limit, offset, total }.

Buscar saque

GET /api/v1/withdrawals/{withdrawal_id}

Retorna um saque por ID. Escopo exigido: withdrawals.read.

Endpoints: Transferências internas #

Transferência de saldo entre duas contas A4therPay. Identifique o destinatário por recipient_email ou recipient_merchant_id (exatamente um dos dois). Os endpoints não suportam sandbox: chaves a4ther_test_ recebem 403 SANDBOX_NOT_SUPPORTED_FOR_TRANSFERS.

Criar transferência

POST /api/v1/internal-transfers/

Escopo exigido: withdrawals.create. Header Idempotency-Key recomendado. Saldo insuficiente retorna 422 INSUFFICIENT_BALANCE.

CampoTipoObrigatórioDescrição
amount_centsintsimValor em centavos. Min 100 (R$ 1,00), max 10.000.000 (R$ 100.000,00).
recipient_emailstringcondicionalEmail da conta destinatária. Use este OU recipient_merchant_id.
recipient_merchant_idstringcondicionalID ULID do merchant destinatário (26 chars).
descriptionstringnãoTexto livre (max 140 chars).
curl -X POST https://a4therpay-api.discloud.app/api/v1/internal-transfers/ \
  -H "Authorization: Bearer a4ther_live_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 25000,
    "recipient_email": "parceiro@empresa.com",
    "description": "Repasse parceria"
  }'

A resposta traz id, from_merchant_id, to_merchant_id, to_merchant_name, amount_cents, status (completed, failed, reversed) e created_at.

Listar transferências

GET /api/v1/internal-transfers/

Escopo exigido: transfers.read. Filtros: direction (sent ou received, default sent), limit (max 100), offset. Envelope { data, limit, offset, total }.

Buscar transferência

GET /api/v1/internal-transfers/{transfer_id}

Retorna uma transferência por ID. Escopo exigido: transfers.read.

Endpoints: Test/Sandbox #

Reset sandbox

POST /api/v1/test/reset

Apaga todos os charges sandbox do merchant. Só aceita chaves a4ther_test_*.

Listar magic values

GET /api/v1/test/scenarios

Endpoint público (sem auth). Útil para pessoas e ferramentas de validação.

Webhooks #

Os webhooks são configurados no painel da A4therPay (Configurações > Webhooks); aqui documentamos os eventos disponíveis e a verificação de assinatura.

Eventos disponíveis

São oito eventos:

EventoQuando dispara
charge.createdCobrança criada
charge.paidPIX confirmado pelo banco recebedor
charge.expiredCobrança expirou sem pagamento
charge.cancelledCobrança cancelada
charge.refundedCobrança reembolsada
payout.createdSaque registrado
payout.completedSaque concluído (PIX enviado)
payout.failedSaque falhou

Estrutura do payload

O corpo é entregue como JSON. Você recebe o evento e o objeto relacionado (cobrança ou saque):

corpo do webhook · application/json
{
  "event": "charge.paid",
  "charge": {
    "id": "chg_01HV...",
    "status": "paid",
    "amount_cents": 4990,
    "paid_at": "2026-06-08T19:27:23+00:00"
  }
}

Verificar assinatura HMAC

Cada entrega chega com estes headers:

O <hex> é o HMAC SHA-256 calculado com o segredo do webhook (começa com whsec_, exibido só na criação) sobre a string "{X-A4therPay-Timestamp}." + corpo_cru. Use o corpo bruto da requisição (não o JSON re-serializado):

import crypto from "node:crypto";

function verify(rawBody, timestamp, signature, secret) {
  const v1 = signature.replace("v1=", "");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Tolerância de timestamp.

Também rejeite requests com timestamp mais de 5 minutos no passado pra evitar replay attacks.

Política de retry

Se seu endpoint não responder com 2xx, reentregamos a mesma notificação algumas vezes, com backoff exponencial crescente (tipicamente de alguns segundos até horas entre tentativas). Após esgotar as tentativas, a entrega é marcada como falha e você pode reenviá-la manualmente pelo painel.

Use o X-A4therPay-Delivery-Id para deduplicar: a mesma entrega pode chegar mais de uma vez se a sua resposta demorar.

Objetos #

Charge

CampoTipoDescrição
idstringID único da cobrança
merchant_idstringID do merchant dono da cobrança
statusenumpending, paid, expired, cancelled, refunded
amount_centsintegerValor em centavos
currencystringISO 4217 (só BRL por enquanto)
payment_methodstringSempre pix
customerobject | nullDados do pagador (name, email, document, phone)
pix_copy_pastestring | nullCódigo copia-e-cola PIX (BR Code EMV)
pix_qr_codestring | nullImagem do QR Code em base64
fee_processor_centsintegerTaxa do processador, em centavos
fee_platform_centsintegerTaxa da plataforma, em centavos
net_amount_centsinteger | nullValor líquido após taxas, em centavos
metadataobjectCampos custom devolvidos em reads e webhooks
created_atISO 8601-
updated_atISO 8601-
expires_atISO 8601 | nullQuando a cobrança expira
paid_atISO 8601 | nullPreenchido quando status vira paid

Transaction

CampoTipoDescrição
idstringID único do lançamento
merchant_idstringID do merchant
typeenumcharge, refund, payout, fee, adjustment, transfer_internal, crypto_payout
directionenumcredit ou debit
amount_centsintegerValor bruto do lançamento, em centavos
fee_centsintegerTaxa do lançamento, em centavos
net_amount_centsintegerValor líquido, em centavos
statusenumpending, completed, failed
charge_idstring | nullReferência da cobrança, quando aplicável
created_atISO 8601-

Webhook

Configurado no painel da A4therPay. Campos principais: id, url, events (lista), secret_prefix (só primeiros 8 chars), active, created_at.

SDKs oficiais #

Sete SDKs oficiais, um por linguagem, todos publicados nos registries: Node.js (npm), Python (PyPI), PHP (Packagist), Ruby (RubyGems), .NET (NuGet) e Java (Maven Central). Go instala via go get.

Changelog #

Mantemos compatibilidade da v1. Mudanças breaking entram numa versão maior, com guia de migração. Acompanhe o changelog em a4ther.com/docs#changelog.