Quickstart

Integre com a API Xfin ONRAMP em menos de 5 minutos. Clientes pagam em BRL via PIX e recebem USDT na carteira crypto deles.

Pré-requisitos

• API Key emitida pela Xfin (solicite ao seu gerente de conta).
• Endereço de carteira USDT (Arbitrum, chain ID 42161) do cliente.
• Chave PIX do pagador (email, CPF, CNPJ, telefone ou chave aleatória).

Configure as variáveis no terminal antes de começar:

API_KEY="sua-api-key-aqui"
BASE_URL="https://xfin-payouts-ys3int7llq-rj.a.run.app"

Note

O header de autenticação é X-Api-Key. Nomes de headers HTTP são case-insensitive — X-Api-Key e X-API-Key são tratados da mesma forma pelo servidor.

Limites

Parâmetro	Restrição
amount_brl	Deve ser > 0 e suficiente para que o USDT cotado (amount_brl / taxa) seja ao menos 0,01 USDT.
Precisão BRL	Tratado com 2 casas decimais.
Moeda de liquidação	USDT na rede Arbitrum (chain ID 42161).

1. Obtenha uma API Key

   Entre em contato com o time Xfin para criar sua conta de parceiro e receber sua API Key. Guarde-a em segurança — ela só é exibida uma vez.

2. Crie um payout

   Faça um POST /v1/payouts com o valor em BRL, a carteira do recebedor e a chave PIX do pagador:

   curl -s -X POST "$BASE_URL/v1/payouts" \
     -H "Content-Type: application/json" \
     -H "X-Api-Key: $API_KEY" \
     -d '{
       "amount_brl": 100.00,
       "receiver_wallet": "0xEnderecoCarteiraDoCLiente",
       "pix_key": "pagador@email.com",
       "pix_key_type": "EMAIL"
     }'

   Resposta de sucesso (201 Created):

   {
     "id": "550e8400-e29b-41d4-a716-446655440000",
     "partner_id": "partner-abc",
     "status": "PENDING",
     "amount_brl": 100.00,
     "min_amount_usdt": 18.37,
     "settled_amount_usdt": 0,
     "pix_key": "pagador@email.com",
     "pix_key_type": "EMAIL",
     "receiver_wallet": "0xEnderecoCarteiraDoCLiente",
     "pix_copy_paste": "00020101021226930014br.gov.bcb.pix0136pagador@email.com...",
     "blockchain_network": "",
     "blockchain_chain_id": 0,
     "blockchain_tx_id": "",
     "block_explorer_url": "",
     "created_at": "2026-06-14T20:00:00Z",
     "updated_at": "2026-06-14T20:00:00Z"
   }

   Tip

   Salve o id do payout e entregue o pix_copy_paste ao pagador — é o código “PIX copia e cola” que ele usará no app bancário para realizar o pagamento. Os campos paid_at e confirmed_at aparecem apenas após a confirmação pelo provedor.

3. Apresente o PIX ao pagador

   O campo pix_copy_paste da resposta contém a string EMV do PIX. Exiba-a como texto copiável ou gere um QR code no seu frontend para que o cliente escaneie com o aplicativo do banco.

4. Acompanhe o status

   Consulte o payout pelo ID até que chegue a um estado terminal:

   PAYOUT_ID="550e8400-e29b-41d4-a716-446655440000"
   
   curl -s "$BASE_URL/v1/payouts/$PAYOUT_ID" \
     -H "X-Api-Key: $API_KEY"

   status	Significado
   PENDING	Cobrança PIX aguardando pagamento
   PROCESSING	Pagamento recebido; transferência USDT em andamento
   COMPLETED	USDT liquidado — confira blockchain_tx_id e block_explorer_url
   FAILED	Falha — entre em contato com o suporte

   Loop de polling simples (ajuste o intervalo ao seu SLA):

   while true; do
     STATUS=$(curl -s "$BASE_URL/v1/payouts/$PAYOUT_ID" \
       -H "X-Api-Key: $API_KEY" \
       | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
     echo "$(date -u +%H:%M:%S) Status: $STATUS"
     if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then
       break
     fi
     sleep 10
   done

   Quando status == COMPLETED, a resposta inclui:

   {
     "id": "550e8400-e29b-41d4-a716-446655440000",
     "status": "COMPLETED",
     "amount_brl": 100.00,
     "min_amount_usdt": 18.37,
     "settled_amount_usdt": 19.38,
     "blockchain_network": "Arbitrum",
     "blockchain_chain_id": 42161,
     "blockchain_tx_id": "0xabc123...",
     "block_explorer_url": "https://arbiscan.io/tx/0xabc123...",
     "paid_at": "2026-06-14T20:15:00Z",
     "confirmed_at": "2026-06-14T20:17:30Z",
     "created_at": "2026-06-14T20:00:00Z",
     "updated_at": "2026-06-14T20:17:30Z"
   }

Listando seus payouts

curl -s "$BASE_URL/v1/payouts?limit=20" \
  -H "X-Api-Key: $API_KEY"

Resposta:

{
  "payouts": [],
  "count": 0
}

Resultados ordenados do mais recente para o mais antigo. limit padrão é 50 (máximo 100).

Tipos de chave PIX

pix_key_type	Formato
CPF	11 dígitos, ex: 12345678901
CNPJ	14 dígitos, ex: 12345678000195
EMAIL	Email válido, ex: pagador@email.com
PHONE	10-11 dígitos com +55 opcional, ex: 11987654321
RANDOM	UUID, ex: 123e4567-e89b-12d3-a456-426614174000

Respostas de erro

Todos os erros retornam o mesmo formato:

{ "error": "mensagem descritiva do erro" }

Status HTTP	Causa
400	Falha de validação (ex: amount_brl ≤ 0, formato de chave PIX inválido)
401	Header X-Api-Key ausente ou inválido
404	Payout não encontrado ou não pertence à sua conta
409	Conflito de idempotência (duplicata em voo)
429	Rate limit excedido (100 rpm); aguarde o header Retry-After