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": "TRANSFERENCIA-568GYKNXWJELWYGP2MPRZ5",
    "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1025",
        "flow": "DIRECT"
    },
    "country": "ARG",
    "currency": "ARS",
    "amount": 1.09,
    "accountNumber": "{{YourAccountNumber}}",
    "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": "{{YourAccountNumber}}"
        }
    ],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "ARS",
        "fxSource": 1170.50002,
        "fxQuote": 1,
        "amount": 0,
        "account": "{{YourAccountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "Jorge",
        "lastName": "Villagra",
        "document": {
            "type": "CUIT",
            "id": "20337994513"
        },
        "bank": {
            "account": {
                "number": "0000369600000000000161"
            }
        },
        "informedName": "Unknown"
    },
    "merchant": {
        "type": "INDIVIDUAL",
        "name": "Localpayment Test",
        "lastName": "Localpayment Test"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "LUCIANO GONZALEZ",
        "lastName": "LUCIANO GONZALEZ",
        "document": {
            "type": "CUIT",
            "id": "20448710913"
        },
        "email": "NA",
        "bank": {
            "name": "BANCO DE GALICIA Y BUENOS AIRES S.A.U.",
            "code": "007",
            "branch": {},
            "account": {
                "type": "C",
                "number": "0070055930004044938502"
            }
        }
    },
    "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": "{{YourAccountNumber}}",
    "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": "{{YourAccountNumber}}"
        }
    ],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "BRL",
        "fxSource": 5.80427174,
        "fxQuote": 1,
        "amount": 55.55,
        "account": "{{YourAccountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "COMPANY",
        "name": "ACME",
        "lastName": "",
        "document": {
            "type": "",
            "id": ""
        },
        "bank": {
            "code": "450",
            "branch": {},
            "account": {
                "number": "52415985301",
                "alias": "cf226732-139c-4ec8-b672-8aa0fc7ee6ee",
                "aliases": [
                    {
                        "value": "cf406732-139c-4ec8-b672-8aa0fc7ee6ee"
                    }
                ]
            }
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "ACME"
    },
    "payer": {
        "type": "COMPANY",
        "name": "VIAGENS TOUR LTDA",
        "lastName": "",
        "document": {
            "type": "CNPJ",
            "id": "01932559000112"
        },
        "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": "{{YourAccountNumber}}",
    "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": "{{YourAccountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "COMPANY",
        "name": "LocalPayment Test",
        "document": {
            "type": "RUT",
            "id": "77175361-2"
        },
        "bank": {
            "name": "Banco Security",
            "code": "049",
            "branch": {},
            "account": {
                "type": "C",
                "number": "928630996"
            }
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Localpayment Test"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "Victor",
        "lastName": "Lopez",
        "document": {
            "type": "RUT",
            "id": "166165067"
        },
        "email": "[email protected]",
        "bank": {
            "name": "BANCO DE CRÉDITO E INVERSIONES (BCI)",
            "code": "016",
            "branch": {},
            "account": {
                "type": "C",
                "number": "57229333"
            }
        },
        "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": "{{externalId}}",
    "internalId": "{{internalId}}",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1630",
        "flow": "DIRECT"
    },
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{YourAccountNumber}}",
    "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": "{{YourAccountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "Pedro",
        "lastName": "Perez",
        "document": {
            "type": "RFC",
            "id": "LEKF8111118Z5"
        },
        "bank": {
            "account": {
                "number": "646011319800015054"
            }
        },
        "informedName": "LPV3_PayinVA"
    },
    "merchant": {
        "type": "COMPANY",
        "name": "MerchantName"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "José",
        "lastName": "Sandoval",
        "document": {
            "type": "ND",
            "id": "ND"
        },
        "email": "NA",
        "bank": {
            "name": "Sistema de Transferencias y Pagos",
            "code": "646",
            "branch": {},
            "account": {
                "type": "C",
                "number": "646010319800001674"
            }
        }
    },
    "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": "484.484.00000058",
    "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": "484.484.00000060"
    },
    "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": "Localpayment Test"
    },
    "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": "356ea887-97ac-4a59-b014-13d7ced16891",
        "paymentMethod": {
            "type": "BankTransfer",
            "code": "1698",
            "flow": "DIRECT"
        },
        "country": "MEX",
        "currency": "USD",
        "amount": 1,
        "accountNumber": "{{accountNumber}}",
        "confirmed": {
            "currency": "USD",
            "fxQuote": 1,
            "amount": 1
        },
        "payment": {
            "currency": "USD",
            "fxQuote": 1,
            "financingFee": 0,
            "amount": 1
        },
        "localTaxes": [],
        "withHoldings": [],
        "fees": {
            "description": "Fee",
            "currency": "USD",
            "fxSource": 1,
            "fxQuote": 1,
            "amount": 0,
            "account": "{{accountNumber}}"
        },
        "status": {
            "code": "200",
            "description": "COMPLETED",
            "detail": "The payin was credited"
        },
        "merchant": {
            "type": "COMPANY",
            "name": "Localpayment Test",
            "document": {}
        },
        "payer": {
            "type": "COMPANY",
            "name": "Company name",
            "lastName": "",
            "document": {
                "type": "RFC",
                "id": "XXX010101000"
            },
            "email": "[email protected]",
            "bank": {
                "name": "bbva",
                "code": "012",
                "branch": {},
                "account": {
                    "type": "C",
                    "number": "012111111111111111"
                }
            }
        },
        "wireInstructions": {
            "beneficiary": {
                "name": "{{companyName}}",
                "document": {
                    "type": "RFC",
                    "id": "XXX010101000"
                },
                "bank": {
                    "name": "{{bankName}}",
                    "code": "{{bankCode}}",
                    "branch": {},
                    "account": {
                        "type": "C",
                        "number": "000111111111111111"
                    }
                }
            },
            "referenceCode": "XXXX-XXXX-XXXX"
        },
        "date": {
            "creationDate": "2025-11-19T19:44:34Z",
            "processedDate": "2025-11-19T19:44:34Z"
        },
        "errors": [],
        "referenceCode": "XXXX-XXXX-XXXX"
    }
}

{
    "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": {
            "bank": {
                "account": {
                    "number": "92250610000000101234"
                }
            }
        },
        "merchant": {
            "type": "COMPANY",
            "name": "Localpayment Test"
        },
        "payer": {
            "type": "INDIVIDUAL",
            "name": "JOHN",
            "lastName": "DOE",
            "email": "NA",
            "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.
`tracking.id`, `tracking.reference`, `tracking.concept`	Additional metadata to assist reconciliation.
`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": "lpv3_1111-19feb2024-24123",
    "reference": "999999",
    "concept": "concepto pago LPV3_4707"
}

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

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