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

# 接收付款通知

每次虚拟账户收到付款时，您都会收到即时 Webhook 通知，从而自动更新您的系统并确认到账。

一旦您创建了虚拟账户并将其映射到内部系统中的特定客户或发票，每当该账户成功收到付款时，Localpayment 都会自动向您的服务器发送 Webhook 通知。

**重要提示**：虚拟账户用作专用的付款目的地。您可自行管理其内部归属信息，但该账号本身可接收任何付款人的款项。付款通知将包含实际付款人的详细信息，方便您将付款与内部客户映射进行核对。

这些实时通知使您能够自动确认到账、更新余额并核对付款，而无需人工验证。

***

## 开始之前

请确保您已具备以下条件：

* 已通过[创建虚拟账户](https://docs.localpayment.com/zh/reference/create-virtual-account.md)endpoint 成功创建虚拟账户。
* 在您的商户账户中配置了通知 endpoint（Webhook URL）。
* 能够接收来自 Localpayment 服务器的 HTTPS POST 请求。
* 后端具备安全地验证和解析 Webhook 有效载荷的逻辑。

***

## 工作原理

1. 付款人向您的系统先前生成的虚拟账户号码发送转账。
2. 资金到账并经 Localpayment 验证后，系统会向您配置的 Webhook endpoint 发送 PayIn 通知。
3. 您的系统必须以 200 OK 响应确认该通知。
4. 然后，您可以更新内部记录，将虚拟账户标记为已付款，或将相应的订单标记为已完成。

> [!NOTE]
>
> ###
>
> 如果您的服务器没有响应 HTTP 200，Localpayment 将使用指数退避重试来保证送达。

***

## 示例通知（Webhook 有效载荷）

以下是成功支付到虚拟账户的示例有效载荷：

```json ARG theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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"
      }
  }
}
```

```json BRA theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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"
      }
  }
}
```

```json CHL theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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"
      }
  }
}
```

```json COL theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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"
      }
  }
}
```

```json CRI-CRC theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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_____"
    }
  }
}
```

```json CRI-USD theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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_____"
    }
  }
}
```

```json MEX (SPEI) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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"
      }
  }
}
```

```json MEX (TEF) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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"
      }
  }
}
```

```json MEX (SPID) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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"
    }
  }
}
```

```json PER theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "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` 对象中，用于直接匹配。

> [!WARNING]
>
> ###
>
> **重要提示**
>
> * **可用性：** `tracking` 对象**仅在 Webhook 中可用**，在交易报告或 API 中不可用。
> * 对于**墨西哥（SPID）**，`externalId` 对应于墨西哥银行（Banco de México）的跟踪码（Clave de Rastreo），使其成为对账的权威字段。

### 跟踪对象示例

```json ARG theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
    "id": "7L8GYKNXWJELWYGP2MPRZ5",
    "reference": "7L8GYKNXWJELWYGP2MPRZ5",
    "concept": "CVU TEST"
}
```

```json BRA theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
    "id": "E0000000022250417170028001234567",
    "reference": "",
    "concept": "11778498533"
}
```

```json CHL theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
    "id": "000739531234",
    "reference": "2025-07-16-12.10.09.237212",
    "concept": "Test 928630123"
}
```

```json COL theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
            "id": "20260225900504001TFY123451234500001",
            "reference": "20260225900504001TFY123451234500001",
            "concept": "Transfer via BRE-B"
        }
```

```json MEX (SPEI and TEF) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
    "id": "lpv3_1111-19feb2024-24123",
    "reference": "999999",
    "concept": "concepto pago LPV3_4707"
}
```

```json PER theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"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` 用作关键字段，也不要假定其包含付款人输入的自由文本。仅将其视为补充信息。

***

## 特定国家/地区

使用虚拟账户时，您必须考虑一些重要的国家/地区特定细节。这些细节会影响付款通知的处理方式以及交易对账方式。以下是某些市场已知差异的概述：

<table>
  <thead>
    <tr>
      <th>
        国家/付款方式
      </th>

      <th>
        Webhook 注意事项
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **哥斯达黎加（SINPE）**
      </td>

      <td>
        * `tracking.concept` 字段包含付款人在转账时输入的描述。此值可能会**被发起银行截断**，因此您可能会看到末尾的下划线（例如 `"Steph_test_____"`）。
      </td>
    </tr>

    <tr>
      <td>
        **哥伦比亚（Bre-B）**
      </td>

      <td>
        * 对于 Bre-B 虚拟账户收款，`paymentMethod.code` 始终为 `"2006"`。
        * `payer.bank.account.type` 始终为 `"BREB"` — 确认付款人通过 Bre-B 网络发送了资金。
        * `beneficiary.bank.account.type` 始终为 `"KEY"` — 即分配给您的虚拟账户的接收 Bre-B 密钥。
        * Bre-B 实时结算：唯一的收款状态是 `"200" COMPLETED`。没有中间状态。
        * `tracking.id` 和 `tracking.reference` 包含 Bre-B 网络交易 ID — 请将这些 ID 作为对账的权威参考。
        * `tracking.concept` 可能包含付款人输入的描述，但通常包含系统生成的字符串（例如 `"Transfer via BRE-B"`）。请勿将其视为付款人输入的自由文本。
      </td>
    </tr>

    <tr>
      <td>
        **墨西哥（SPID）**
      </td>

      <td>
        * SPID 转账**仅限公司付款人使用**。
        * `externalId` 字段对应于墨西哥银行（Banco de México）分配的**跟踪码（Clave de Rastreo）**。
        * 请使用 `externalId` 作为对账的权威参考。
      </td>
    </tr>

    <tr>
      <td>
        **秘鲁**
      </td>

      <td>
        * 某些金融机构**不**提供付款人的全名。详情请参见：[无法提供付款人全名的金融机构](#financial-institutions-without-payer-full-name-availability)。
      </td>
    </tr>
  </tbody>
</table>

### 无法提供付款人全名的金融机构

* **秘鲁**：部分秘鲁金融机构在交易详情中不提供付款人的全名。由于这些机构发送的结算数据中缺少此信息，您可能无法正确识别付款人。

> [accordion] 金融机构名单
>
> * 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

***

## 处理通知

您的服务器必须按如下方式处理每条通知：

1. **验证请求签名**。
2. **验证 **`internalId`** 或 **`externalId`，以确保幂等性；切勿对同一通知处理两次。
3. **更新您的系统**，将相应的发票、钱包或订单标记为已付款。
4. **返回 **`HTTP 200 OK` 以确认收到。

***

## 确认收到通知

只有当您的服务器响应以下内容时，Localpayment 才认为 Webhook 已成功送达：

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
HTTP/1.1 200 OK
Content-Type: application/json
```

如果未收到确认，Localpayment 将以逐渐增加的间隔重试通知数次。


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