Pular para o conteúdo principal
Crie um Payout de pagamento de imposto, conta ou serviço no México, com exemplos de requisição/resposta, tratamento de erros e webhooks. Este guia mostra como criar um Payout de pagamento de imposto, conta ou serviço usando a API: a estrutura da requisição, as descrições dos campos, o tratamento da resposta e as notificações de webhook. Leia primeiro Visão geral de impostos, contas e pagamentos de serviços para conhecer o escopo e o fluxo de pagamento.

Antes de começar

  • Credenciais de API válidas (token de acesso).
  • Uma conta dedicada, financiada para o pagamento de impostos e contas.
  • O billType que você pretende pagar, validado em relação ao catálogo de BillType.
  • A referência da conta (por exemplo, uma referência de pagamento do SAT para o México) obtida junto ao contribuinte ou ao emissor da cobrança.

Endpoint

Para criar um Payout de pagamento de imposto, conta ou serviço, envie uma requisição POST ao endpoint Create a Payout com paymentMethod.type definido como "BillPay".

Cabeçalhos obrigatórios


Requisição

curl

Parâmetros-chave da solicitação

A requisição exige vários objetos principais. Consulte a referência Create a Payout para a lista completa de campos, incluindo sender e merchant.

Tratamento da resposta

Resposta bem-sucedida

Campos de resposta principais

Resposta de erro

Veja a lista completa de códigos de status e de erro em Payout Status and Error Codes.

Considerações sobre a referência da conta

Para o México, o billReference é a referência de pagamento do SAT: uma chave alfanumérica de 20 caracteres que identifica de forma única o conceito de imposto, o contribuinte e o período fiscal.
  • Uma referência de pagamento do SAT tem um prazo de validade limitado, definido pelo SAT. A Localpayment só rejeita uma referência expirada depois que ela é validada junto ao SAT; portanto, essa verificação não é necessariamente instantânea e o webhook de rejeição pode não ser disparado imediatamente.
  • A Localpayment não valida se amount corresponde ao valor codificado na referência, e uma referência não pode ser reutilizada depois de paga. Sua integração deve validar essas condições antes de enviar a requisição.

Testando no Stage

Para permitir que você valide o fluxo de ponta a ponta antes de entrar em produção, a Localpayment simula a resposta do emissor da cobrança no Stage sempre que o beneficiary.billReference enviado corresponder a uma das linhas de captura fixas do catálogo abaixo. Veja Payout Status and Error Codes para a lista completa.
  • Essas linhas de captura só funcionam no Stage. Elas não estão habilitadas em Produção.
  • Qualquer billReference fora deste catálogo não será resolvido no Stage: como não há um sandbox real do lado do emissor da cobrança para validar, a transação permanece IN_PROGRESS indefinidamente. Use um dos valores acima para os seus testes no Stage.

Webhooks

A Localpayment notifica você sobre o status final da transação por webhook, usando a mesma estrutura de payload da resposta acima. A notificação inclui o status final, o externalId e o objeto beneficiary com billType e billReference. Consulte Webhooks para ver exemplos de payload, validação de assinatura e configuração.

Novas tentativas

  • A Localpayment tenta novamente uma entrega de webhook com falha até 3 vezes, com backoff exponencial.
  • Seu endpoint deve responder com HTTP 200 para confirmar o recebimento. Qualquer outro código de status conta como falha de entrega.
  • Se as 3 novas tentativas falharem, a transação permanece no status final e você pode recuperá-la manualmente por meio da API.

Próximos passos

Visão geral de impostos, contas e pagamentos de serviços

Escopo, fluxo de pagamento e estados da transação.

Aprovações e dupla assinatura

Aprenda como autorizar um Payout criado com requireAuth.
Última modificação em 10 de novembro de 2026