> ## 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 un pago de impuestos, facturas o servicios

Crea un payout de pago de impuestos, facturas o servicios en México, con ejemplos de solicitud/respuesta, manejo de errores y webhooks.

Esta guía muestra cómo crear un payout de pago de impuestos, facturas o servicios mediante la API: la estructura de la solicitud, las descripciones de los campos, la gestión de respuestas y las notificaciones de webhook. Lee primero [Resumen de pagos de impuestos, facturas y servicios](https://docs.localpayment.com/es/docs/bill-pay-overview.md) para conocer el alcance y el flujo de pago.

## Antes de comenzar

* [Credenciales API](https://docs.localpayment.com/es/docs/api-keys-and-environments.md) válidas (token de acceso).
* Una cuenta específica financiada para el pago de impuestos y facturas.
* El `billType` que planeas pagar, validado con el [catálogo de BillType](https://docs.localpayment.com/es/docs/bill-pay-overview.md#billtype-catalog).
* La referencia de la factura (por ejemplo, una referencia de pago del SAT para México) obtenida del contribuyente o del emisor de la factura.

***

## Endpoint

Para crear un payout de pago de impuestos, facturas o servicios, envía una solicitud `POST` al endpoint **[Create a Payout](https://docs.localpayment.com/es/reference/create-a-payout.md)** con `paymentMethod.type` establecido en `"BillPay"`.

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

### Encabezados obligatorios

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

***

## Solicitud

```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 clave de la solicitud

La solicitud requiere varios objetos clave. Consulta la referencia **[Create a Payout](https://docs.localpayment.com/es/reference/create-a-payout.md)** para ver la lista completa de campos, incluidos `sender` y `merchant`.

| Campo | Descripción | Requerido |
| - | - | - |
| `paymentMethod.type` | Establecer en BillPay. | ✅ |
| `paymentMethod.code` | Código del proveedor. Actualmente disponible: 0119. | ✅ |
| beneficiary.billType | Código que identifica el tipo de impuesto o servicio. Consulta el [catálogo de BillType](https://docs.localpayment.com/es/docs/bill-pay-overview.md#billtype-catalog). | ✅ |
| beneficiary.billReference | Referencia oficial emitida por la autoridad fiscal o el emisor de la factura (para México, la referencia de pago del SAT). Consulta [Consideraciones sobre la referencia de la factura](#bill-reference-considerations). | ✅ |
| amount | Debe coincidir con el monto codificado en beneficiary.billReference. | ✅ |
| requireAuth | Si es true, la transacción permanece en PendingAuth hasta que tú llames al [endpoint de autorización](https://docs.localpayment.com/es/docs/approvals-and-double-signature.md). | — |

***

## Gestión de la respuesta

### Respuesta exitosa

```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 respuesta clave

| Campo | Descripción |
| - | - |
| internalId | Identificador único de transacción de Localpayment. Úsalo para soporte y verificaciones de idempotencia. |
| externalId | Tu número de referencia, devuelto tal cual desde la solicitud. |
| `status.description` | Estado actual de la transacción. Consulta [Estados de la transacción](https://docs.localpayment.com/es/docs/bill-pay-overview.md#transaction-states). |
| date.processedDate | Momento en que comenzó el procesamiento de la transacción. |

### Respuesta de error

```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"
      }
    ]
  }
]
```

Consulta la lista completa de códigos de estado y de error en [Payout Status and Error Codes](https://docs.localpayment.com/es/reference/payout-status-error-codes.md).

***

## Consideraciones sobre la referencia de la factura

En México, el `billReference` es la referencia de pago del SAT: una clave alfanumérica de 20 caracteres que identifica de forma única el concepto fiscal, el contribuyente y el periodo fiscal.

> [!WARNING]
>
> * Una referencia de pago del SAT tiene una ventana de vigencia limitada establecida por el SAT. Localpayment rechaza una referencia vencida solo una vez que ha sido validada contra el SAT, por lo que esta verificación no es necesariamente instantánea y es posible que el webhook de rechazo no se dispare de inmediato.
> * Localpayment no valida que `amount` coincida con el valor codificado en la referencia, y una referencia no puede reutilizarse una vez que ha sido pagada. Tu integración debe validar estas condiciones antes de enviar la solicitud.

***

## Pruebas en Stage

Para que puedas validar el flujo de extremo a extremo antes de salir a producción, Localpayment simula la respuesta del emisor de la factura en **Stage** siempre que el `beneficiary.billReference` que tú envíes coincida con una de las líneas de captura fijas del catálogo siguiente.

| Línea de captura (billReference) | Resultado simulado |
| - | - |
| 0100000000000000001 | COMPLETED |
| 0100000000000000002 | COMPLETED |
| 0100000000000000003 | Rechazado: error 741, InvalidBillReference - BillReference not found or invalid |
| 0100000000000000004 | Rechazado: error 741, InvalidBillReference - BillReference not found or invalid |
| 0100000000000000005 | Rechazado: error 811, Invalid amount |

Consulta [Payout Status and Error Codes](https://docs.localpayment.com/es/reference/payout-status-error-codes.md) para ver la lista completa.

> [!WARNING]
>
> * Estas líneas de captura solo funcionan en **Stage**. No están habilitadas en Producción.
> * Cualquier `billReference` fuera de este catálogo no se resolverá en Stage: como no existe un sandbox real del lado del emisor de la factura contra el cual validar, la transacción permanece en `IN_PROGRESS` indefinidamente. Utiliza uno de los valores anteriores para tus pruebas en Stage.

***

## Webhooks

Localpayment te notifica el estado final de la transacción mediante webhook, con la misma estructura de payload que la respuesta anterior. La notificación incluye el `status` final, el `externalId` y el objeto `beneficiary` con `billType` y `billReference`. Consulta [Webhooks](https://docs.localpayment.com/es/docs/webhooks.md) para ver ejemplos de payload, validación de firma y configuración.

### Reintentos

* Localpayment reintenta una entrega fallida del webhook hasta 3 veces con retroceso exponencial.
* Tu endpoint debe responder con HTTP 200 para confirmar la recepción. Cualquier otro código de estado cuenta como una entrega fallida.
* Si fallan los 3 reintentos, la transacción permanece en su estado final y tú puedes recuperarla manualmente a través de la API.

***

## Próximos pasos

> [card] [Resumen de pagos de impuestos, facturas y servicios](https://docs.localpayment.com/es/docs/bill-pay-overview.md)
>
> Alcance, flujo de pago y estados de la transacción.

> [card] [Aprobaciones y doble firma](https://docs.localpayment.com/es/docs/approvals-and-double-signature.md)
>
> Aprende cómo autorizar un payout creado con requireAuth.


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