开始之前
请确保您已具备以下条件:- 已通过创建虚拟账户endpoint 成功创建虚拟账户。
- 在您的商户账户中配置了通知 endpoint(Webhook URL)。
- 能够接收来自 Localpayment 服务器的 HTTPS POST 请求。
- 后端具备安全地验证和解析 Webhook 有效载荷的逻辑。
工作原理
- 付款人向您的系统先前生成的虚拟账户号码发送转账。
- 资金到账并经 Localpayment 验证后,系统会向您配置的 Webhook endpoint 发送 PayIn 通知。
- 您的系统必须以 200 OK 响应确认该通知。
- 然后,您可以更新内部记录,将虚拟账户标记为已付款,或将相应的订单标记为已完成。
示例通知(Webhook 有效载荷)
以下是成功支付到虚拟账户的示例有效载荷:{
"transactionType": "PayIn",
"transactionFlow": null,
"country": "ARG",
"data": {
"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": "John",
"lastName": "Doe",
"fullName": "John Doe",
"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": "carlos.mendez@email.com",
"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",
"transactionFlow": null,
"country": "BRA",
"data": {
"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": "rafael.oliveira@email.com",
"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",
"transactionFlow": null,
"country": "CHL",
"data": {
"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": "valentina.rojas@email.com",
"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",
"transactionFlow": null,
"country": "COL",
"data": {
"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": "andres.herrera@email.com",
"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",
"transactionFlow": null,
"country": "CRI",
"data": {
"transactionType": "PayIn",
"externalId": "bc56ff3e-5291-40e9-89e1-ef258b6095a9",
"internalId": "c06bbea8-48d1-4659-9664-633b7f9f080d",
"paymentMethod": {
"type": "BankTransfer",
"code": "1420",
"flow": "DIRECT"
},
"country": "CRI",
"currency": "CRC",
"amount": 500,
"accountNumber": "{{accountNumber}}",
"confirmed": {
"currency": "CRC",
"fxQuote": 1.0,
"amount": 500.0
},
"payment": {
"currency": "CRC",
"fxQuote": 1.0,
"financingFee": 0.0,
"amount": 500.0
},
"localTaxes": [],
"withHoldings": [],
"grossingUps": [],
"fees": {
"description": "Fee",
"currency": "CRC",
"fxSource": 453.811158,
"fxQuote": 1.0,
"amount": 0.0,
"account": "{{accountNumber}}"
},
"status": {
"code": "200",
"description": "COMPLETED",
"detail": "The payin was credited"
},
"beneficiary": {
"type": "COMPANY",
"name": "LP MERGE SRL",
"document": {
"type": "CEJ",
"id": "3100000001"
},
"bank": {
"account": {
"number": "CR99000000000000000001"
}
}
},
"merchant": {
"type": "COMPANY",
"name": "LP MERGE SRL"
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastName": "Doe",
"document": {
"type": "CI",
"id": "01-0100-0001"
},
"email": "NA",
"bank": {
"name": "Banco Nacional de Costa Rica",
"code": "0102",
"branch": {
"code": "",
"name": ""
},
"account": {
"number": "CR99000000000000000002"
}
}
},
"date": {
"creationDate": "2026-06-22T14:46:18Z",
"processedDate": "2026-06-22T14:46:19Z"
},
"errors": [],
"referenceCode": "IQCT-J9P2-WZRG",
"tracking": {
"id": "2026062210222010504969350",
"reference": "26736337",
"concept": "Steph_test_____"
}
}
}
{
"transactionType": "PayIn",
"transactionFlow": null,
"country": "CRI",
"data": {
"transactionType": "PayIn",
"externalId": "bc56ff3e-5291-40e9-89e1-ef258b6095a9",
"internalId": "c06bbea8-48d1-4659-9664-633b7f9f080d",
"paymentMethod": {
"type": "BankTransfer",
"code": "1421",
"flow": "DIRECT"
},
"country": "CRI",
"currency": "USD",
"amount": 500,
"accountNumber": "{{accountNumber}}",
"confirmed": {
"currency": "USD",
"fxQuote": 1.0,
"amount": 500.0
},
"payment": {
"currency": "USD",
"fxQuote": 1.0,
"financingFee": 0.0,
"amount": 500.0
},
"localTaxes": [],
"withHoldings": [],
"grossingUps": [],
"fees": {
"description": "Fee",
"currency": "USD",
"fxSource": 453.811158,
"fxQuote": 1.0,
"amount": 0.0,
"account": "{{accountNumber}}"
},
"status": {
"code": "200",
"description": "COMPLETED",
"detail": "The payin was credited"
},
"beneficiary": {
"type": "COMPANY",
"name": "LP MERGE SRL",
"document": {
"type": "CEJ",
"id": "3100000001"
},
"bank": {
"account": {
"number": "CR99000000000000000001"
}
}
},
"merchant": {
"type": "COMPANY",
"name": "LP MERGE SRL"
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastName": "Doe",
"document": {
"type": "CI",
"id": "01-0100-0001"
},
"email": "NA",
"bank": {
"name": "Banco Nacional de Costa Rica",
"code": "0102",
"branch": {
"code": "",
"name": ""
},
"account": {
"number": "CR99000000000000000002"
}
}
},
"date": {
"creationDate": "2026-06-22T14:46:18Z",
"processedDate": "2026-06-22T14:46:19Z"
},
"errors": [],
"referenceCode": "IQCT-J9P2-WZRG",
"tracking": {
"id": "2026062210222010504969350",
"reference": "26736337",
"concept": "Steph_test_____"
}
}
}
{
"transactionType": "PayIn",
"transactionFlow": null,
"country": "MEX",
"data": {
"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": "alejandra.guzman@email.com",
"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",
"transactionFlow": null,
"country": "MEX",
"data": {
"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": "lucia.torres@email.com",
"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 字段
Webhook 通知包含用作标识符的特定字段。请使用下表将收到的付款与您的内部记录进行匹配。| 字段 | 描述 |
|---|---|
accountNumber | 商户账号。 |
amount | 收到的金额。 |
payer.name and payer.lastName | 付款人全名。 |
payer.document.id | 付款人国民身份证(如有)。 |
payer.bank.account.number | 付款人使用的原始账号。 |
beneficiary.name and beneficiary.document.id | 虚拟账户持有人的姓名和 ID。 |
beneficiary.bank.account.number | 收到付款的虚拟账户的本地账号(例如,阿根廷的 CVU、墨西哥的 CLABE、秘鲁的 CCI 等)。使用此字段可将收到的付款与您记录中的特定虚拟账户进行匹配。 |
referenceCode | Localpayment 生成的参考编号,格式为 XXXX-XXXX-XXXX(三个四字符字母数字块)。仅供人工阅读参考。如需幂等性和去重,请使用 internalId 或 externalId。 |
tracking.id | 由支付渠道或付款人银行生成的标识符。格式因国家/地区而异。对于哥伦比亚 Bre-B,这是权威的对账参考号。 |
tracking.reference | 同样由支付渠道或银行生成。不保证一定存在,也不保证在不同支付渠道间唯一。在墨西哥,它是付款人输入的较短的银行参考信息;在秘鲁,它可能为空。 |
tracking.concept | 用于记录付款说明。通常包含系统生成的字符串,而非付款人自由输入的文本。仅用作补充信息。 |
date.creationDate and date.processedDate | date 对象提供 UTC 时间戳,用于追踪交易从其在系统中创建(creationDate)直至最终财务结算(processedDate)的整个过程。 |
使用付款参考
付款人可以在转账时添加参考信息(例如订单号)。此数据会显示在 Webhook 的tracking 对象中,用于直接匹配。
跟踪对象示例
"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": ""
}
通知中的关键标识符
该通知包含由不同方生成的多个参考字段和跟踪字段。了解每个字段的来源和可靠性有助于您构建可靠的对账策略。referenceCode
由 Localpayment 生成。在每个国家/地区和每个支付渠道中,它始终遵循XXXX-XXXX-XXXX 格式(三个四字符字母数字块),这可以确认通知源自 Localpayment。
referenceCode 是供人工阅读的 Localpayment 参考编号,而不是幂等键。如需去重和幂等性,请使用 internalId 或 externalId。
tracking.id
由支付渠道或付款人银行生成,而非由 Localpayment 生成。格式因国家/地区而异:| 国家/地区 | 格式 |
|---|---|
| 阿根廷 | 长字母数字键(例如 7L8GYKNXWJELWYGP2MPRZ5) |
| 巴西(PIX) | E 编码(例如 E0000000022250417170028008753346) |
| 智利 | 简短数字(例如 000739531483) |
| 哥伦比亚(Bre-B) | Bre-B 网络交易 ID — 权威对账参考 |
| 墨西哥 | 发起银行分配的密钥 |
| 秘鲁 | 简短数字 — 不保证唯一 |
tracking.id 视为在所有支付渠道中都具有全局唯一性。对于哥伦比亚 Bre-B,请将其用作支付渠道侧的主要标识符;对于其他国家/地区,请将其作为辅助参考。
tracking.reference
同样由支付渠道或银行生成。其内容和可用性各不相同:
- 阿根廷、智利、哥伦比亚:与
tracking.id相同。 - 墨西哥(SPEI/TEF):付款人在转账时输入的较短的银行参考号。
- 秘鲁:可能为空,或包含
"NO REF"。
tracking.reference 作为有保证的或唯一的标识符。
tracking.concept
用于记录付款说明。但实际上,该字段通常包含系统生成的字符串或占位符字符串,而不是付款人自由填写的文本:
| 国家/地区 | 典型值 |
|---|---|
| 智利 | "Sin mensaje" |
| 哥伦比亚(Bre-B) | "Transfer via BRE-B"(支付渠道生成) |
| 秘鲁 | "payin generated by virtual account" |
tracking.concept 用作关键字段,也不要假定其包含付款人输入的自由文本。仅将其视为补充信息。
特定国家/地区
使用虚拟账户时,您必须考虑一些重要的国家/地区特定细节。这些细节会影响付款通知的处理方式以及交易对账方式。以下是某些市场已知差异的概述:| 国家/付款方式 | Webhook 注意事项 |
|---|---|
| 哥斯达黎加(SINPE) |
|
| 哥伦比亚(Bre-B) |
|
| 墨西哥(SPID) |
|
| 秘鲁 |
|
无法提供付款人全名的金融机构
- 秘鲁:部分秘鲁金融机构在交易详情中不提供付款人的全名。由于这些机构发送的结算数据中缺少此信息,您可能无法正确识别付款人。
金融机构名单
金融机构名单
- 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
处理通知
您的服务器必须按如下方式处理每条通知:- 验证请求签名。
- 验证
internalId或externalId,以确保幂等性;切勿对同一通知处理两次。 - 更新您的系统,将相应的发票、钱包或订单标记为已付款。
- 返回
HTTP 200 OK以确认收到。
确认收到通知
只有当您的服务器响应以下内容时,Localpayment 才认为 Webhook 已成功送达:HTTP/1.1 200 OK
Content-Type: application/json

