Receive Payment Notifications

Once you create a virtual account and map it to a specific customer or invoice within your internal systems, Localpayment automatically sends a webhook notification to your server each time a payment is successfully received into that account.

Important: A virtual account functions as a dedicated payment destination. While you manage its internal attribution, the account number itself can receive funds from any payer. The payment notification will contain details of the actual payer, allowing you to reconcile the payment with your internal customer mapping.

These real-time notifications enable you to automatically confirm credits, update balances, and reconcile payments without manual verification.

Before You Begin

Ensure that you have:

Successfully created a Virtual Account through the Create Virtual Account endpoint.
A notification endpoint (webhook URL) configured in your merchant account.
The ability to receive HTTPS POST requests from Localpayment’s servers.
Logic in your backend to validate and parse webhook payloads securely.

How It Works

A payer sends a transfer to the Virtual Account number previously generated by your system.
Once the funds are credited and validated by Localpayment, a PayIn notification is sent to your configured webhook endpoint.
Your system must acknowledge the notification with a 200 OK response.
You can then update your internal records to mark the Virtual Account as paid or the corresponding order as fulfilled.

🗒️
Localpayment guarantees delivery using retries with exponential backoff if your server does not respond with HTTP 200.

Example Notification (Webhook Payload)

Below is a sample payload for a successful payment credited to a Virtual Account:

{
    "transactionType": "PayIn",
    "externalId": "59a61a76-2480-4996-8633-528227e1db10",
    "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1025",
        "flow": "DIRECT"
    },
    "country": "ARG",
    "currency": "ARS",
    "amount": 1.09,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "ARS",
        "fxQuote": 1,
        "amount": 1.09
    },
    "payment": {
        "currency": "ARS",
        "fxQuote": 1,
        "financingFee": 0,
        "amount": 1.09
    },
    "localTaxes": [
        {
            "code": "0001",
            "percentage": 1.2,
            "description": "IDC",
            "currency": "ARS",
            "fxSource": 1193.82,
            "fxQuote": 0,
            "amount": 0.01,
            "account": "{{accountNumber}}"
        }
    ],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "ARS",
        "fxSource": 1170.50002,
        "fxQuote": 1,
        "amount": 0,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "Camilo",
        "lastName": "Sabogal",
        "fullName": "Camilo Sabogal",
        "document": {
            "type": "CUIT",
            "id": "20314567894"
        },
        "bank": {
            "account": {
                "number": "0000369600000000123456"
            }
        },
        "informedName": "Unknown"
    },
    "merchant": {
        "type": "MERCHANT",
        "name": "Localpayment Test",
        "lastName": "
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "Carlos",
        "lastName": "Mendez",
        "fullName": "Carlos Mendez",
        "document": {
            "type": "CUIT",
            "id": "20314567894"
        },
        "email": "[email protected]",
        "bank": {
            "name": "BANCO DE GALICIA Y BUENOS AIRES S.A.U.",
            "code": "007",
            "branch": {},
            "account": {
                "type": "C",
                "number": "0070055930004044654321"
            }
        }
    },
    "date": {
        "creationDate": "2025-04-30T17:26:37.186",
        "processedDate": "2025-04-30T17:26:37.363"
    },
    "errors": [],
    "referenceCode": "DHF2-XOHO-NE77",
    "tracking": {
        "id": "7L8GYKNXWJELWYGP2MPRZ5",
        "reference": "7L8GYKNXWJELWYGP2MPRZ5",
        "concept": "CVU TEST"
    }
}

{
    "transactionType": "PayIn",
    "externalId": "d96a9440-afe2-453f-a3b5-155a7fb17241",
    "internalId": "d220f7cc-e2cd-4b40-95ae-59d85bf68a7e",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1350",
        "flow": "DIRECT"
    },
    "country": "BRA",
    "currency": "BRL",
    "amount": 55554.63,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "BRL",
        "fxQuote": 1,
        "amount": 55554.63
    },
    "payment": {
        "currency": "BRL",
        "fxQuote": 1,
        "financingFee": 0,
        "amount": 55554.63
    },
    "localTaxes": [
        {
            "code": "0002",
            "percentage": 0.38,
            "description": "IOF",
            "currency": "BRL",
            "fxSource": 5.5813,
            "fxQuote": 0,
            "amount": 211.11,
            "account": "{{accountNumber}}"
        }
    ],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "BRL",
        "fxSource": 5.80427174,
        "fxQuote": 1,
        "amount": 55.55,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "Rafael",
        "lastName": "Oliveira",
        "fullName": "Rafael Oliveira",
        "document": {
            "type": "CPF",
            "id": "12345678909"
        },
        "bank": {
            "code": "450",
            "branch": {},
            "account": {
                "number": "52415912345",
                "alias": "cf226732-139c-4ec8-b672-8aa0fc7ee6ea",
                "aliases": [
                    {
                        "value": "cf406732-139c-4ec8-b672-8aa0fc7ee6ea"
                    }
                ]
            }
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "ACME"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "Rafael",
        "lastName": "Oliveira",
        "fullName": "Rafael Oliveira",
        "document": {
            "type": "CPF",
            "id": "12345678909"
        },
        "email": "[email protected]",
        "bank": {
            "code": "001",
            "branch": {},
            "account": {
                "type": "C",
                "number": "45063"
            }
        }
    },
    "date": {
        "creationDate": "2025-04-17T17:01:52.850",
        "processedDate": "2025-04-17T17:01:53.025"
    },
    "errors": [],
    "referenceCode": "5XWA-MGQ0-ZKZ6",
    "tracking": {
        "id": "E0000000022250417170028008753346",
        "reference": "",
        "concept": "11778498595"
    }
}

{
    "transactionType": "PayIn",
    "externalId": "c3f819ba-240a-47cd-8cbe-e95a43e1552d",
    "internalId": "e8da1f0e-38ef-46b9-8360-4d40f78605af",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "2550",
        "flow": "DIRECT"
    },
    "country": "CHL",
    "currency": "CLP",
    "amount": 100,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "CLP",
        "fxQuote": 1,
        "amount": 100
    },
    "payment": {
        "currency": "CLP",
        "fxQuote": 1,
        "financingFee": 0,
        "amount": 100
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "CLP",
        "fxSource": 967.340406,
        "fxQuote": 1,
        "amount": 0,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "Valentina",
        "lastName": "Rojas",
        "fullName": "Valentina Rojas",
        "document": {
            "type": "RUT",
            "id": "123456789"
        },
        "bank": {
            "name": "Banco Security",
            "code": "049",
            "branch": {},
            "account": {
                "type": "C",
                "number": "928630123"
            }
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Localpayment Test"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "Valentina",
        "lastName": "Rojas",
        "fullName": "Valentina Rojas",
        "document": {
            "type": "RUT",
            "id": "123456789"
        },
        "email": "[email protected]",
        "bank": {
            "name": "BANCO DE CRÉDITO E INVERSIONES (BCI)",
            "code": "016",
            "branch": {},
            "account": {
                "type": "C",
                "number": "57229123"
            }
        },
        "userReference": "Test 928630996"
    },
    "date": {
        "creationDate": "2025-07-16T16:12:50.163",
        "processedDate": "2025-07-16T16:12:50.396"
    },
    "errors": [],
    "referenceCode": "QSR5-FE1Y-DIVT",
    "tracking": {
        "id": "000739531483",
        "reference": "2025-07-16-12.10.09.237295",
        "concept": "Test 928630996"
    }
}

{
    "transactionType": "PayIn",
    "externalId": "cf194632-7ec4-4a44-9b92-9bbacad5349a",
    "internalId": "b97ac13c-1acb-4bc0-8b2a-067945e26161",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "2006",
        "flow": "DIRECT"
    },
    "country": "COL",
    "currency": "COP",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "COP",
        "fxQuote": 1.0,
        "amount": 1000.0
    },
    "payment": {
        "currency": "COP",
        "fxQuote": 1.0,
        "financingFee": 0.0,
        "amount": 1000.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "COP",
        "fxSource": 3705.82,
        "fxQuote": 1.0,
        "amount": 1.0,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "Andres",
        "lastName": "Herrera",
        "fullName": "Andres Herrera",
        "document": {
            "type": "CC",
            "id": "1020456789"
        },
        "bank": {
            "name": "BANCO DE BOGOTÁ",
            "code": "1001",
            "account": {
                "type": "KEY",
                "number": "@XXXXXXXOXX0000"
            }
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Test company",
        "lastName": ""
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "Andres",
        "lastName": "Herrera",
        "fullName": "Andres Herrera",
        "document": {
            "type": "CC",
            "id": "1020456789"
        },
        "email": "[email protected]",
        "bank": {
            "name": "BANCO POPULAR",
            "code": "1002",
            "account": {
                "type": "BREB",
                "number": "signer:wTUTnHK5mLAQXLgVuhoANKGaKTdgRFmrx7@breb"
            }
        }
    },
    "date": {
        "creationDate": "2026-02-25T18:53:25Z",
        "processedDate": "2026-02-25T18:53:26Z"
    },
    "errors": [],
    "referenceCode": "V0ZO-AIPV-NOD9",
    "tracking": {
        "id": "20260225900504001TFY123451234501234",
        "reference": "20260225900504001TFY123451234501234",
        "concept": "Test payment"
    }
}

{
    "transactionType": "PayIn",
    "externalId": "c2eabb54-6314-414d-9bdc-1004fba09737",
    "internalId": "72b3e90d-22ec-4afd-a360-f3a08301c660",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1630",
        "flow": "DIRECT"
    },
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "MXN",
        "fxQuote": 1,
        "amount": 1000
    },
    "payment": {
        "currency": "MXN",
        "fxQuote": 1,
        "financingFee": 0,
        "amount": 1000
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "MXN",
        "fxSource": 1,
        "fxQuote": 1,
        "amount": 50,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "Juan",
        "lastName": "Perez",
        "fullName": "Juan Perez",
        "document": {
            "type": "RFC",
            "id": "PEPJ800101XXX"
        },
        "bank": {
            "account": {
                "number": "646011319800123456"
            }
        },
        "informedName": "LPV3_PayinVA"
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Test Merchant"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "Alejandra",
        "lastName": "Guzman",
        "fullName": "Alejandra Guzman",
        "document": {
            "type": "RFC",
            "id": "KCWV771228TS4"
        },
        "email": "[email protected]",
        "bank": {
            "name": "Sistema de Transferencias y Pagos",
            "code": "646",
            "branch": {},
            "account": {
                "type": "C",
                "number": "646011319800123456"
            }
        }
    },
    "date": {
        "creationDate": "2024-02-19T20:18:30.373",
        "processedDate": "2024-02-19T20:18:30.601"
    },
    "errors": [],
    "referenceCode": "C2VV-MVVN-QHFI",
    "tracking": {
        "id": "lpv3_1111-19feb2024-2400",
        "reference": "999999",
        "concept": "concepto pago LPV3_4707"
    }
}

{
    "transactionType": "PayIn",
    "externalId": "3fb782c0-9c26-47b8-a66d-6c127934403e",
    "internalId": "b7f7284f-1684-4ec9-a932-5da2aed7e159",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1680",
        "flow": "DIRECT"
    },
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000.01,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "MXN",
        "fxQuote": 1,
        "amount": 1000.01
    },
    "payment": {
        "currency": "MXN",
        "fxQuote": 1,
        "financingFee": 0,
        "amount": 1000.01
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "MXN",
        "fxSource": 18.76902,
        "fxQuote": 1,
        "amount": 0,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "COMPANY",
        "name": "My Company",
        "document": {
            "type": "RUC",
            "id": "200123456789"
        },
        "bank": {
            "name": "{{bankName}}",
            "code": "{{bankCode}}",
            "account": {
                "number": "000000000000000009"
            }
        },
        "informedName": "My Company"
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Localpayment Test",
        "lastName": ""
    },
    "payer": {
        "type": "COMPANY",
        "name": "John",
        "lastName": "Doe",
        "document": {
            "type": "RFC",
            "id": ""
        },
        "email": "NA",
        "bank": {
            "name": "BANCO INBURSA",
            "code": "036",
            "account": {
                "type": "CLABE",
                "number": "00000000000000000001"
            }
        }
    },
    "date": {
        "creationDate": "2025-08-21T15:15:05.113",
        "processedDate": "2025-08-21T15:15:05.346"
    },
    "errors": [],
    "referenceCode": "AHB3-2LHB-8RG1",
    "tracking": {
        "id": "1234-2025",
        "reference": "999999",
        "concept": "Test payment"
    }
}

{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "MEX",
  "data": {
    "transactionType": "PayIn",
    "externalId": "1f6b6f3a-3c3f-4e08-ba14-ac0d2a521ad5",
    "internalId": "43aa5b5b-7566-4630-b86f-afb8486ccab4",
    "paymentMethod": {
      "type": "BankTransfer",
      "code": "1698",
      "flow": "DIRECT"
    },
    "country": "MEX",
    "currency": "USD",
    "amount": 3,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
      "currency": "USD",
      "fxQuote": 1,
      "amount": 3
    },
    "payment": {
      "currency": "USD",
      "fxQuote": 1,
      "financingFee": 0,
      "amount": 3
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
      "description": "Fee",
      "currency": "USD",
      "fxSource": 1,
      "fxQuote": 1,
      "amount": 0.01,
      "account": "{{accountNumber}}"
    },
    "status": {
      "code": "200",
      "description": "COMPLETED",
      "detail": "The payin was credited"
    },
    "beneficiary": {
      "type": "COMPANY",
      "name": "Test Company",
      "document": {
        "type": "RFC",
        "id": "XXX010101000"
      },
      "bank": {
        "account": {
          "number": "000111111111111111"
        }
      },
      "informedName": "Company name"
    },
    "merchant": {
      "type": "COMPANY",
      "name": "Localpayment Test"
    },
    "payer": {
      "type": "INDIVIDUAL",
      "name": "John",
      "lastName": "Doe",
      "document": {
        "type": "RFC",
        "id": "XXX010101000"
      },
      "email": "NA",
      "bank": {
        "name": "{{bankName}}",
        "code": "{{bankCode}}",
        "branch": {
          "code": "",
          "name": ""
        },
        "account": {
          "type": "C",
          "number": "000111111111111111"
        }
      }
    },
    "date": {
      "creationDate": "2026-01-26T15:10:03Z",
      "processedDate": "2026-01-26T15:10:03Z"
    },
    "errors": [],
    "referenceCode": "XXXX-XXXX-XXXX",
    "tracking": {
      "id": "111XXX1X1",
      "reference": "XXXX",
      "concept": "TEST"
    }
  }
}

{
    "transactionType": "PayIn",
    "transactionFlow": null,
    "country": "PER",
    "data": {
        "transactionType": "PayIn",
        "externalId": "ff9178f7-fcda-1e38-acaa-3cbe2c5d4976",
        "internalId": "902127f8-35b3-47a7-b24a-1e39411740e5",
        "paymentMethod": {
            "type": "BankTransfer",
            "code": "6100",
            "flow": "DIRECT"
        },
        "country": "PER",
        "currency": "PEN",
        "amount": 5,
        "accountNumber": "{{accountNumber}}",
        "confirmed": {
            "currency": "PEN",
            "fxQuote": 1,
            "amount": 5
        },
        "payment": {
            "currency": "PEN",
            "fxQuote": 1,
            "financingFee": 0,
            "amount": 5
        },
        "localTaxes": [
            {
                "code": "0006",
                "percentage": 0.005,
                "description": "ITF",
                "currency": "PEN",
                "fxSource": 3.742498,
                "fxQuote": 0,
                "amount": 0,
                "account": "{{accountNumber}}"
            }
        ],
        "withHoldings": [],
        "fees": {
            "description": "Fee",
            "currency": "PEN",
            "fxSource": 3.386033,
            "fxQuote": 1,
            "amount": 1,
            "account": "{{accountNumber}}"
        },
        "status": {
            "code": "200",
            "description": "COMPLETED",
            "detail": "The payin was credited"
        },
        "beneficiary": {
            "type": "INDIVIDUAL",
            "name": "Lucia",
            "lastName": "Torres",
            "fullName": "Lucia Torres",
            "document": {
                "type": "DNI",
                "id": "45678901"
            },
            "bank": {
                "account": {
                    "number": "92250610000000101234"
                }
            }
        },
        "merchant": {
            "type": "COMPANY",
            "name": "Localpayment Test"
        },
        "payer": {
            "type": "INDIVIDUAL",
            "name": "Lucia",
            "lastName": "Torres",
            "fullName": "Lucia Torres",
            "document": {
                "type": "DNI",
                "id": "45678901"
            },
            "email": "[email protected]",
            "bank": {
                "name": "INTERBANK (BANCO INTERNACIONAL DEL PERÚ)",
                "code": "003",
                "branch": {},
                "account": {
                    "type": "C",
                    "number": "00310701315123456789"
                }
            }
        },
        "date": {
            "creationDate": "2025-10-20T16:07:50Z",
            "processedDate": "2025-10-20T16:07:50Z"
        },
        "errors": [],
        "referenceCode": "6WXD-CXLO-U8UN",
        "tracking": {
            "id": "2025102011074908084191797675",
            "reference": "00100000297079044806",
            "concept": ""
        }
    }
}

Webhook Fields for Matching

The webhook notification contains specific fields that serve as identifiers. Use the table below to match the incoming payment to your internal records.

Field	Description
`accountNumber`	Merchant account number.
`amount`	Amount received.
`payer.name` and `payer.lastName`	Full name of the payer.
`payer.document.id`	Payer’s national ID (if available).
`payer.bank.account.number`	Originating account number used by the payer.
`beneficiary.name` and `beneficiary.document.id`	Name and ID of the virtual account holder.
`beneficiary.bank.account.number`	The local account number of the virtual account that received the payment (CVU for Argentina, CLABE for Mexico, CCI for Peru, etc.). Use this field to match the incoming payment to the specific virtual account in your records.
`referenceCode`	A Localpayment-generated reference in the format `XXXX-XXXX-XXXX` (three four-character alphanumeric blocks). Use for human-readable reference only. For idempotency and deduplication, use `internalId` or `externalId`.
`tracking.id`	Identifier generated by the payment rail or payer's bank. Format varies by country. For Colombia Bre-B, this is the authoritative reconciliation reference.
`tracking.reference`	Also rail/bank-generated. Not guaranteed to be present or unique across rails. In Mexico, it is a shorter bank reference entered by the payer; in Peru it may be empty.
`tracking.concept`	Intended to carry the payment description. Often contains system-generated strings rather than payer free text. Use as supplementary context only.
`date.creationDate` and `date.processedDate`	The `date` object provides the UTC timestamps tracing the transaction from its creation in the system (`creationDate`) to its final financial settlement (`processedDate`).

Using Payment References

Payers can add a reference (e.g., an order number) to their transfer. This data appears in the webhook's tracking object for direct matching.

⚠️
Important

Availability: The tracking object is only available in webhooks, not in transaction reports or the API.

For Mexico (SPID), the externalId corresponds to Banco de México's tracking key (Clave de Rastreo), making it the authoritative field for reconciliation.

Tracking Object Example

"tracking": {
    "id": "7L8GYKNXWJELWYGP2MPRZ5",
    "reference": "7L8GYKNXWJELWYGP2MPRZ5",
    "concept": "CVU TEST"
}

"tracking": {
    "id": "E0000000022250417170028001234567",
    "reference": "",
    "concept": "11778498533"
}

"tracking": {
    "id": "000739531234",
    "reference": "2025-07-16-12.10.09.237212",
    "concept": "Test 928630123"
}

"tracking": {
            "id": "20260225900504001TFY123451234500001",
            "reference": "20260225900504001TFY123451234500001",
            "concept": "Transfer via BRE-B"
        }

"tracking": {
    "id": "lpv3_1111-19feb2024-24123",
    "reference": "999999",
    "concept": "concepto pago LPV3_4707"
}

"tracking": {
    "id": "20251020110749080841911234567",
    "reference": "00100000297079041234",
    "concept": ""
}

Key Identifiers in the Notification

The notification includes several reference and tracking fields generated by different parties. Understanding the source and reliability of each helps you build a robust reconciliation strategy.

referenceCode

Generated by Localpayment. It always follows the format XXXX-XXXX-XXXX — three four-character alphanumeric blocks — across every country and rail, which confirms the notification originated from Localpayment.

referenceCode is a human-readable Localpayment reference, not an idempotency key. For deduplication and idempotency, use internalId or externalId.

tracking.id

Generated by the payment rail or the payer's bank, not by Localpayment. The format varies by country:

Country	Format
Argentina	Long alphanumeric key (e.g., `7L8GYKNXWJELWYGP2MPRZ5`)
Brazil (PIX)	E-number (e.g., `E0000000022250417170028008753346`)
Chile	Short numeric (e.g., `000739531483`)
Colombia (Bre-B)	Bre-B network transaction ID — authoritative reconciliation reference
Mexico	Key assigned by the originating bank
Peru	Short numeric — not guaranteed unique

Do not treat tracking.id as universally unique across all rails. Use it as the primary rail-side identifier for Colombia Bre-B; for other countries, treat it as a supporting reference.

tracking.reference

Also generated by the rail or bank. Its content and availability vary:

Argentina, Chile, Colombia: mirrors tracking.id.
Mexico (SPEI/TEF): a shorter bank reference that the payer enters at the time of transfer.
Peru: may be empty or contain "NO REF".

Do not rely on tracking.reference as a guaranteed or unique identifier.

tracking.concept

Intended to carry the payment description. In practice, this field frequently contains system-generated or placeholder strings rather than payer free text:

Country	Typical value
Chile	`"Sin mensaje"`
Colombia (Bre-B)	`"Transfer via BRE-B"` (rail-generated)
Peru	`"payin generated by virtual account"`

Do not use tracking.concept as a key field or assume it contains free text entered by the payer. Treat it as supplementary context only.

Country Specific

When using Virtual Accounts, there are important country-specific details you must consider. These can affect how payment notifications are processed and how you reconcile transactions. Below is a summary of known differences across certain markets:

Country / Payment Method	Webhook Considerations
Colombia (Bre-B)	`paymentMethod.code` is always `"2006"` for Bre-B Virtual Account payins. `payer.bank.account.type` is always `"BREB"` — confirms the payer sent funds via the Bre-B network. `beneficiary.bank.account.type` is always `"KEY"` — the receiving Bre-B key assigned to your Virtual Account. Bre-B settles in real time: the only payin status is `"200" COMPLETED`. There are no intermediate states. `tracking.id` and `tracking.reference` contain the Bre-B network transaction ID — use these as the authoritative reference for reconciliation. `tracking.concept` may contain a description entered by the payer, but often carries a system-generated string (e.g., `"Transfer via BRE-B"`). Do not treat it as guaranteed payer-entered free text.
Mexico (SPID)	SPID transfers are exclusively available for Company payers. The `externalId` field corresponds to the tracking key (Clave de Rastreo) assigned by Banco de México. Use `externalId` as the authoritative reference for reconciliation.
Peru	Certain financial institutions do not return the payer’s full name. For details, see: Financial institutions without payer full-name availability.

Financial institutions without payer full-name availability

Peru: Certain Peruvian financial institutions do not provide the payer’s full name in the transaction details. Because this information is not available in the settlement data sent by these entities, you may be unable to correctly identify the payer.

Financial Institutions List

007 – CITIBANK DEL PERU S.A.
- 056 – BANCO SANTANDER PERU S.A.
- 805 – CAJA MUNICIPAL DE AHORRO Y CRÉDITO SULLANA
- 813 – CAJA MUNICIPAL DE AHORRO Y CRÉDITO TACNA

Handling the Notification

Your server must process each notification as follows:

Verify the request signature.
Validate the internalId or externalId to ensure idempotency; never process the same notification twice.
Update your system to mark the corresponding invoice, wallet, or order as paid.
Return HTTP 200 OK to acknowledge receipt.

Acknowledging the Notification

Localpayment considers the webhook successfully delivered only when your server responds with:

HTTP/1.1 200 OK
Content-Type: application/json

If no acknowledgment is received, Localpayment retries the notification up to several times with increasing intervals.