Sincronizar pagamento

Use POST /v1/payments/:id/sync quando precisar reconciliar o status salvo na Allya com o status atual do gateway.

Essa rota é útil quando um webhook não chegou, um túnel local caiu durante testes ou o endpoint do cliente ficou indisponível no momento da notificação.

Como funciona

1. A Allya busca o pagamento no ambiente da API key.
2. Consulta o gateway usando o gatewayRef persistido.
3. Atualiza status, gatewayStatus e dados públicos preserváveis, como checkoutUrl ou QR Code quando o gateway retornar.
4. Se o status mudou, registra evento interno e envia o webhook outbound correspondente.

GET /v1/payments/:id não faz consulta ao gateway; ele só retorna o estado salvo na Allya. Use sync apenas quando quiser forçar a reconciliação.

Exemplo

curl --request POST \
  --url https://payments-api.allyasolutions.com/v1/payments/pay_7f3e0c9a12b44d63a9f612c42a8d2b90/sync \
  --header "Authorization: Bearer sk_test_..."

Resposta:

{
  "id": "pay_7f3e0c9a12b44d63a9f612c42a8d2b90",
  "status": "paid",
  "method": "pix",
  "gateway": "asaas",
  "amount": 4990,
  "currency": "BRL",
  "externalId": "pedido_123",
  "gatewayRef": "gateway_payment_id",
  "customer": {
    "name": "Cliente Teste",
    "email": "cliente@example.com",
    "documentLast4": "0000"
  },
  "checkoutUrl": "https://...",
  "pix": {
    "qrCode": "data:image/png;base64,...",
    "qrCodeText": "000201..."
  },
  "card": null
}

Códigos de resposta

Veja também

• Consultar pagamento: leitura sem chamar o gateway (mais barata).
• Status de pagamento: significado dos status normalizados.
• Webhooks: fluxo natural de atualização (sem precisar de sync).
• Troubleshooting: quando rodar sync e quando não adianta.