> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar pagamento de imposto, conta ou serviço

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](https://docs.localpayment.com/pt-br/docs/bill-pay-overview.md) para conhecer o escopo e o fluxo de pagamento.

## Antes de começar

* [Credenciais de API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md) 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](https://docs.localpayment.com/pt-br/docs/bill-pay-overview.md#billtype-catalog).
* 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](https://docs.localpayment.com/pt-br/reference/create-a-payout.md)** com `paymentMethod.type` definido como `"BillPay"`.

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST https://api.stage.localpayment.com/api/payout/
```

### Cabeçalhos obrigatórios

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
Content-Type: application/json
```

***

## Requisição

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "country": "MEX",
  "currency": "MXN",
  "amount": 100.00,
  "accountNumber": "{{accountNumber}}",
  "paymentMethod": {
    "type": "BillPay",
    "code": "0119",
    "flow": "DIRECT"
  },
  "beneficiary": {
    "billType": "0098",
    "billReference": "20260713000000000001"
  },
  "sender": {
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastName": "Doe"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Merchant Name"
  }
}'
```

### Parâmetros-chave da solicitação

A requisição exige vários objetos principais. Consulte a referência **[Create a Payout](https://docs.localpayment.com/pt-br/reference/create-a-payout.md)** para a lista completa de campos, incluindo `sender` e `merchant`.

| Campo | Descrição | Obrigatório |
| - | - | - |
| `paymentMethod.type` | Defina como BillPay. | ✅ |
| `paymentMethod.code` | Código do provedor. Atualmente disponível: 0119. | ✅ |
| beneficiary.billType | Código que identifica o tipo de imposto ou serviço. Consulte o [catálogo de BillType](https://docs.localpayment.com/pt-br/docs/bill-pay-overview.md#billtype-catalog). | ✅ |
| beneficiary.billReference | Referência oficial emitida pela autoridade fiscal ou pelo emissor da cobrança (para o México, a referência de pagamento do SAT). Consulte [Considerações sobre a referência da conta](#bill-reference-considerations). | ✅ |
| amount | Deve corresponder ao valor codificado em beneficiary.billReference. | ✅ |
| requireAuth | Se true, a transação permanece em PendingAuth até que você chame o [endpoint de autorização](https://docs.localpayment.com/pt-br/docs/approvals-and-double-signature.md). | — |

***

## Tratamento da resposta

### Resposta bem-sucedida

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "paymentMethod": {
        "code": "0119",
        "name": "BILLPAY",
        "description": "string",
        "paymentMethodType": "BillPay"
    },
    "country": "MEX",
    "currency": "MXN",
    "amount": 100.00,
    "accountNumber": "{{accountNumber}}",
    "clientCode": "0001",
    "clientName": "Acme",
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payout was processed successfully"
    },
    "beneficiary": {
        "billType": "0098",
        "billReference": "20260713000000000001"
    },
    "sender": {
        "type": "INDIVIDUAL",
        "name": "Jane",
        "lastname": "Doe"
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Merchant Name"
    },
    "date": {
        "creationDate": "2026-07-13T15:04:22.0000000Z",
        "processedDate": "2026-07-13T15:04:23.0000000Z"
    },
    "errors": null
}
```

### Campos de resposta principais

| Campo | Descrição |
| - | - |
| internalId | Identificador de transação exclusivo da Localpayment. Use-o para suporte e verificações de idempotência. |
| externalId | Seu número de referência, devolvido da requisição. |
| `status.description` | Estado atual da transação. Consulte [Estados da transação](https://docs.localpayment.com/pt-br/docs/bill-pay-overview.md#transaction-states). |
| date.processedDate | Quando a transação começou a ser processada. |

### Resposta de erro

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "status": {
      "code": "801",
      "description": "Rejected",
      "detail": "Params error"
    },
    "errors": [
      {
        "code": "300",
        "description": "Invalid param + [beneficiary.billReference] + reference is expired"
      }
    ]
  }
]
```

Veja a lista completa de códigos de status e de erro em [Payout Status and Error Codes](https://docs.localpayment.com/pt-br/reference/payout-status-error-codes.md).

***

## 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.

> [!WARNING]
>
> * 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.

| Linha de captura (billReference) | Resultado simulado |
| - | - |
| 0100000000000000001 | COMPLETED |
| 0100000000000000002 | COMPLETED |
| 0100000000000000003 | Rejeitado: erro 741, InvalidBillReference - BillReference not found or invalid |
| 0100000000000000004 | Rejeitado: erro 741, InvalidBillReference - BillReference not found or invalid |
| 0100000000000000005 | Rejeitado: erro 811, Invalid amount |

Veja [Payout Status and Error Codes](https://docs.localpayment.com/pt-br/reference/payout-status-error-codes.md) para a lista completa.

> [!WARNING]
>
> * 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](https://docs.localpayment.com/pt-br/docs/webhooks.md) 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

> [card] [Visão geral de impostos, contas e pagamentos de serviços](https://docs.localpayment.com/pt-br/docs/bill-pay-overview.md)
>
> Escopo, fluxo de pagamento e estados da transação.

> [card] [Aprovações e dupla assinatura](https://docs.localpayment.com/pt-br/docs/approvals-and-double-signature.md)
>
> Aprenda como autorizar um Payout criado com requireAuth.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.