Criar pagamento PIX
POST/v1/payoutsPaga uma chave PIX com o saldo disponível. Valor e tarifa saem do disponível na hora em que o pedido é aceito, e voltam se o pagamento não for concluído. Escopo da chave: payouts em write.
Cabeçalhos
AuthorizationtextoobrigatórioBearer com a sua chave: sk_test_… no teste, sk_live_… em produção.Idempotency-KeytextoobrigatórioUm valor único por pedido (ex.: o número do pedido), até 255 caracteres visíveis, sem espaços. Mesmo corpo de novo: a resposta guardada, com Idempotent-Replayed: true. Outro corpo: 409. Vale por 7 dias.Content-Typetextoobrigatórioapplication/json
Corpo
amounttextoobrigatórioValor em texto decimal com ponto, ex.: "80.00", maior que zero e com até 2 casas em BRL.currencytextoobrigatório"BRL" para PIX. SPEI (MXN) e COP (Colômbia, em pesos inteiros): em breve.destinationobjetoobrigatórioPara onde vai: um destino avulso, um beneficiário salvo ou uma conta de saque da empresa (veja abaixo).descriptiontextoopcionalAté 140 caracteres. Aparece no extrato.externalIdtextoopcionalO id do pagamento no seu sistema, até 100 caracteres, único por empresa e ambiente. Repetir responde 409 EXTERNAL_ID_CONFLICT (não devolve o existente: busque com GET /v1/payouts?externalId=).
Destino
Mande uma das três formas. A avulsa, com a chave PIX:
railtextoobrigatório"PIX".keyTypetextoobrigatório"CPF", "CNPJ", "EMAIL", "PHONE" ou "EVP" (chave aleatória).keytextoobrigatórioA chave, conferida pelo tipo: CPF/CNPJ com ou sem pontuação, e-mail, telefone brasileiro com DDD (vira +55…) ou a chave aleatória.holderNametextoobrigatórioNome do titular, de 2 a 160 caracteres.holderDocumenttextoopcionalCPF ou CNPJ do titular. Há provedores que exigem para pagar.
// Destino avulso, chave PIX
{ "rail": "PIX", "keyType": "CPF", "key": "111.444.777-35", "holderName": "Carla Lima" }
// Beneficiário salvo (POST /v1/beneficiaries)
{ "beneficiaryId": "ben_7Rq2Lt5Wx9Pd" }
// Conta de saque da própria empresa (cadastrada no painel)
{ "settlementAccountId": "sa_2Vn6Hk9Qs3Zm" }Na Colômbia (em breve), o destino avulso é uma chave Bre-B ou uma conta bancária; os provedores exigem celular e e-mail do titular sempre:
railtextoobrigatório"BREB" (em COP).targettextoobrigatório"KEY" (chave Bre-B) ou "ACCOUNT" (conta bancária).keytextoopcionalCom KEY: a chave Bre-B do recebedor (celular, e-mail, documento ou chave com @).accounttextoopcionalCom ACCOUNT: o número da conta, de 4 a 20 dígitos.bankCodetextoopcionalCom ACCOUNT, obrigatório: o banco da conta, um código de GET /v1/banks?method=PSE.holderNametextoobrigatórioNome do titular, de 2 a 160 caracteres.holderPhonetextoobrigatórioCelular colombiano do titular: 10 dígitos começando com 3, com ou sem +57.holderEmailtextoobrigatórioE-mail do titular.holderDocumentTypetextoopcionalCom ACCOUNT, obrigatório: "CC", "CE", "NIT", "PA", "PPT", "TI", "RC", "TE" ou "DIE".holderDocumenttextoopcionalCom ACCOUNT, obrigatório: o número do documento (o NIT pode vir com o dígito verificador, que é conferido).
- Beneficiários (destinos de terceiros que você paga sempre) se salvam com
POST /v1/beneficiaries, com os mesmos campos do destino avulso; o mesmo destino de novo responde409 CONFLICTcom o id do existente emerror.details.beneficiaryId. - Contas de saque são da própria empresa e só se cadastram no painel; pela API,
GET /v1/settlement-accountslista os ids.
Status
| Status | O que significa |
|---|---|
PENDING_APPROVAL | Esperando outra pessoa da empresa aprovar (regra de aprovação). |
IN_REVIEW | Esperando a análise da plataforma. |
QUEUED | Na fila para ir ao provedor. Ainda dá para cancelar. |
PROCESSING | Aceito pelo provedor, esperando o resultado. |
UNKNOWN | O envio não teve resposta clara: a plataforma consulta o provedor antes de qualquer nova tentativa. Para você, é "processando". |
PAID | Pago. endToEndId e paidAt preenchidos. |
FAILED | Não foi concluído; valor e tarifa voltaram ao disponível. statusReason diz o motivo. |
REJECTED | Recusado na aprovação (empresa ou plataforma); valor e tarifa voltaram. |
CANCELED | Cancelado antes do envio; valor e tarifa voltaram. |
RETURNED | Pago e devolvido depois pelo banco de destino; valor e tarifa voltaram. |
A resposta traz fee (a tarifa) e total (valor + tarifa, o que saiu do disponível). Se o pedido vai para aprovação, veja Aprovações.
Erros
| Código | HTTP | Quando acontece |
|---|---|---|
VALIDATION_ERROR | 422 | Valor, moeda ou destino fora do formato: chave que não bate com o tipo, documento do titular inválido. error.details aponta o campo. |
NOT_FOUND | 404 | O beneficiário ou a conta de saque não existe neste ambiente (ou foi arquivado). |
PAYMENT_METHOD_UNAVAILABLE | 422 | A moeda não é a do trilho (PIX paga em BRL). |
INSUFFICIENT_BALANCE | 422 | O disponível não cobre valor + tarifa. Nada foi criado. |
EXTERNAL_ID_CONFLICT | 409 | Já existe um pagamento com este externalId. |
RISK_DECLINED | 422 | Recusado pela análise de risco. A resposta não diz o motivo. |
IDEMPOTENCY_KEY_REUSED | 409 | A Idempotency-Key já foi usada com outro corpo. |
PAYOUTS_DISABLED | 503 | Pagamentos pausados pela plataforma. Tente mais tarde com a mesma Idempotency-Key. |
PROVIDER_UNAVAILABLE | 503 | Nenhum provedor de saída disponível agora. Tente de novo com a mesma Idempotency-Key. |
Acompanhar e cancelar
payout.createdpayout.approvedpayout.paidpayout.failedpayout.returned
payout.failed vale para falha, recusa e cancelamento: confira data.status. Consulte com GET /v1/payouts/:id ou liste com GET /v1/payouts (filtros status e externalId, com cursor).
Para cancelar, POST /v1/payouts/:id/cancel (escopo payouts em write): vale enquanto o pagamento ainda não foi enviado (PENDING_APPROVAL, IN_REVIEW ou QUEUED). Depois disso, a resposta é 409 CONFLICT.
curl -X POST https://api.averopay.io/v1/payouts/po_8Kd3Mq7Zs2Vb/cancel \
-H "Authorization: Bearer sk_test_..."No ambiente de teste, uma chave PIX com "falha" no texto termina em falha, para você testar o estorno ao saldo.