Send a Tax, Bill, or Service Payment

This guide shows how to create a tax, bill, or service payment payout using the API: the request structure, field descriptions, response handling, and webhook notifications. Read Tax, Bill and Service Payments Overview first for scope and the payment flow.

Before You Begin

Valid API credentials (access token).
A dedicated account funded for tax and bill payments.
The billType you plan to pay, validated against the BillType catalog.
The bill reference (for example, a SAT payment reference for Mexico) obtained from the taxpayer or biller.

Endpoint

To create a tax, bill, or service payment payout, send a POST request to the Create a Payout endpoint with paymentMethod.type set to "BillPay".

POST https://api.stage.localpayment.com/api/payout/

Required Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json

Request

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"
  }
}'

Key Request Parameters

The request requires several key objects. See the Create a Payout reference for the full field list, including sender and merchant.

Field	Description	Required
`paymentMethod.type`	Set to `BillPay`.	✅
`paymentMethod.code`	Provider code. Currently available: `0119`.	✅
`beneficiary.billType`	Code identifying the tax or service type. See the BillType catalog.	✅
`beneficiary.billReference`	Official reference issued by the tax authority or biller (for Mexico, the SAT payment reference). See Bill Reference Considerations.	✅
`amount`	Must match the amount encoded in `beneficiary.billReference`.	✅
`requireAuth`	If `true`, the transaction stays in `PendingAuth` until you call the authorization endpoint.	—

Handle the Response

Successful Response

{
    "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
}

Key Response Fields

Field	Description
`internalId`	Localpayment's unique transaction identifier. Use it for support and idempotency checks.
`externalId`	Your reference number, echoed back from the request.
`status.description`	Current transaction state. See Transaction States.
`date.processedDate`	When the transaction began processing.

Error Response

[
  {
    "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"
      }
    ]
  }
]

See the full list of status and error codes in Payout Status and Error Codes.

Bill Reference Considerations

For Mexico, the billReference is the SAT payment reference: a 20-character alphanumeric key that uniquely identifies the tax concept, taxpayer, and fiscal period.

⚠️

A SAT payment reference has a limited validity window set by the SAT. Localpayment rejects an expired reference only once it has been validated against the SAT, so this check is not necessarily instant and the rejection webhook may not fire immediately.

Localpayment does not validate that amount matches the value encoded in the reference, and a reference cannot be reused once it has been paid. Your integration must validate these conditions before submitting the request.

Testing in Stage

To let you validate the end-to-end flow before going live, Localpayment simulates the biller's response in Stage whenever the beneficiary.billReference you submit matches one of the fixed capture lines in the catalog below.

Capture line (`billReference`)	Simulated result
`0100000000000000001`	`COMPLETED`
`0100000000000000002`	`COMPLETED`
`0100000000000000003`	`Rejected`: error `741`, `InvalidBillReference - BillReference not found or invalid`
`0100000000000000004`	`Rejected`: error `741`, `InvalidBillReference - BillReference not found or invalid`
`0100000000000000005`	`Rejected`: error `811`, `Invalid amount`

See Payout Status and Error Codes for the full list.

⚠️

These capture lines only work in Stage. They are not enabled in Production.

Any billReference outside this catalog will not resolve in Stage: since there is no real sandbox on the biller's side to validate against, the transaction stays IN_PROGRESS indefinitely. Use one of the values above for your Stage testing.

Webhooks

Localpayment notifies you of the final transaction status by webhook, using the same payload structure as the response above. The notification includes the final status, the externalId, and the beneficiary object with billType and billReference. See Webhooks for payload examples, signature validation, and setup.

Retries

Localpayment retries a failed webhook delivery up to 3 times with exponential backoff.
Your endpoint must respond with HTTP 200 to confirm receipt. Any other status code counts as a delivery failure.
If all 3 retries fail, the transaction stays at its final status and you can retrieve it manually through the API.

Next Steps

Tax, Bill and Service Payments Overview

Scope, payment flow, and transaction states.

Approvals & Double Signature

Authorize a payout created with requireAuth.