模拟流程
- 创建虚拟账户:首先,在测试环境中生成一个虚拟账户。
- 获取虚拟账户状态:使用 获取虚拟账户状态 endpoint 确认账户已成功创建,并从响应中获取
beneficiary.bank.account.number字段。 - 关联模拟:在模拟请求中,使用上一步获得的
beneficiary.bank.account.number,将模拟付款关联到正确的账户。此外,请提供唯一的externalId——它将作为本次交易所生成的 payin 的 ID;每次模拟请求都请使用不同的externalId。您还必须提供您的 Localpayment accountNumber(商户 ID),以识别与模拟支付关联的商户账户。 - 触发模拟:调用 模拟虚拟账户支付 endpoint。
- 接收 Webhook:Localpayment 将发送一个
payin.completed(或类似)webhook 到您配置的 endpoint。 - 验证状态:使用交易状态 API 确认模拟交易已达到预期状态。
技术依赖关系
顺序要求:您不能模拟尚未成功创建的账户的付款。如果 创建虚拟账户 调用失败,模拟尝试将返回 404 Not Found 错误。
代码示例(Stage)
选择您的目标市场,查看完整的curl 示例。请使用创建虚拟账户时提供的相同受益人数据,并为每次模拟请求提供唯一的 externalId。
- 阿根廷
- 巴西
- 智利
- 哥伦比亚
- 哥斯达黎加(CRC)
- 哥斯达黎加(USD)
- 墨西哥(SPEI)
- 墨西哥(TEF)
- 秘鲁
curl --request POST \
--url https://api.stage.localpayment.com/api/simulate/va \
--header 'Authorization: Bearer {{access_token}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
"paymentMethod": {
"type": "BankTransfer",
"code": "1025",
"flow": "DIRECT"
},
"country": "ARG",
"currency": "ARS",
"amount": 100.00,
"accountNumber": "{{accountNumber}}",
"beneficiary": {
"type": "INDIVIDUAL",
"name": "Camilo",
"lastName": "Sabogal",
"fullName": "Camilo Sabogal",
"document": {
"type": "CUIT",
"id": "20314567894"
},
"bank": {
"account": {
"number": "3745135018378011718454"
}
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "Carlos",
"lastName": "Mendez",
"fullName": "Carlos Mendez",
"document": {
"type": "CUIT",
"id": "20314567894"
},
"email": "carlos.mendez@email.com",
"bank": {
"name": "Banco Galicia",
"code": "007",
"account": {
"type": "CBU",
"number": "0070001200001234567890"
}
}
}
}
'
curl --request POST \
--url https://api.stage.localpayment.com/api/simulate/va \
--header 'Authorization: Bearer {{access_token}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"externalId": "0d55e796-bba6-4cf0-aead-8d9c1ed31044",
"paymentMethod": {
"type": "BankTransfer",
"code": "1350",
"flow": "DIRECT"
},
"country": "BRA",
"currency": "BRL",
"amount": 100.00,
"accountNumber": "{{accountNumber}}",
"beneficiary": {
"type": "INDIVIDUAL",
"name": "Rafael",
"lastName": "Oliveira",
"fullName": "Rafael Oliveira",
"document": {
"type": "CPF",
"id": "12345678909"
},
"bank": {
"account": {
"number": "00099999-8"
}
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "Rafael",
"lastName": "Oliveira",
"fullName": "Rafael Oliveira",
"document": {
"type": "CPF",
"id": "12345678909"
},
"email": "rafael.oliveira@email.com",
"bank": {
"name": "Itau",
"code": "341",
"account": {
"number": "12345-6"
}
}
}
}
'
curl --request POST \
--url https://api.stage.localpayment.com/api/simulate/va \
--header 'Authorization: Bearer {{access_token}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"externalId": "d2ffc771-2678-4dcc-8819-d446656a19f9",
"paymentMethod": {
"type": "BankTransfer",
"code": "2530",
"flow": "DIRECT"
},
"country": "CHL",
"currency": "CLP",
"amount": 100.00,
"accountNumber": "{{accountNumber}}",
"beneficiary": {
"type": "INDIVIDUAL",
"name": "Valentina",
"lastName": "Rojas",
"fullName": "Valentina Rojas",
"document": {
"type": "RUT",
"id": "123456789"
},
"bank": {
"account": {
"number": "00099999999"
}
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "Valentina",
"lastName": "Rojas",
"fullName": "Valentina Rojas",
"document": {
"type": "RUT",
"id": "123456789"
},
"email": "valentina.rojas@email.com",
"bank": {
"name": "Banco de Chile",
"code": "001",
"account": {
"number": "00112345678"
}
}
}
}
'
curl --request POST \
--url https://api.stage.localpayment.com/api/simulate/va \
--header 'Authorization: Bearer {{access_token}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"externalId": "b3e14f73-8452-49b2-bf3c-b770774edfa8",
"paymentMethod": {
"type": "BankTransfer",
"code": "2006",
"flow": "DIRECT"
},
"country": "COL",
"currency": "COP",
"amount": 100.00,
"accountNumber": "{{accountNumber}}",
"beneficiary": {
"type": "INDIVIDUAL",
"name": "Andres",
"lastName": "Herrera",
"fullName": "Andres Herrera",
"document": {
"type": "CC",
"id": "1020456789"
},
"bank": {
"account": {
"number": "20099999999"
}
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "Andres",
"lastName": "Herrera",
"fullName": "Andres Herrera",
"document": {
"type": "CC",
"id": "1020456789"
},
"email": "andres.herrera@email.com",
"bank": {
"name": "Bancolombia",
"code": "007",
"account": {
"number": "20012345678"
}
}
}
}
'
curl --request POST \
--url https://api.stage.localpayment.com/api/simulate/va \
--header 'Authorization: Bearer {{access_token}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"externalId": "a1c2e3f4-5b6d-47a8-9c0e-1f2a3b4c5d6e",
"paymentMethod": {
"type": "BankTransfer",
"code": "1420",
"flow": "DIRECT"
},
"country": "CRI",
"currency": "CRC",
"amount": 100.00,
"accountNumber": "{{accountNumber}}",
"beneficiary": {
"type": "INDIVIDUAL",
"name": "Carlos",
"lastName": "Mendez",
"fullName": "Carlos Mendez",
"document": {
"type": "CI",
"id": "2-0456-0789"
},
"bank": {
"account": {
"number": "CR91090100000000125311"
}
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastName": "Doe",
"fullName": "John Doe",
"document": {
"type": "CI",
"id": "01-0100-0001"
},
"email": "john.doe@email.com",
"bank": {
"name": "Banco Nacional de Costa Rica",
"code": "0151",
"account": {
"number": "CR99000000000000000003"
}
}
}
}
'
curl --request POST \
--url https://api.stage.localpayment.com/api/simulate/va \
--header 'Authorization: Bearer {{access_token}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"externalId": "b2d3f4a5-6c7e-48b9-a1d0-2f3b4c5d6e7f",
"paymentMethod": {
"type": "BankTransfer",
"code": "1421",
"flow": "DIRECT"
},
"country": "CRI",
"currency": "USD",
"amount": 100.00,
"accountNumber": "{{accountNumber}}",
"beneficiary": {
"type": "INDIVIDUAL",
"name": "Carlos",
"lastName": "Mendez",
"fullName": "Carlos Mendez",
"document": {
"type": "CI",
"id": "2-0456-0789"
},
"bank": {
"account": {
"number": "CR91090100000000125511"
}
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastName": "Doe",
"fullName": "John Doe",
"document": {
"type": "CI",
"id": "01-0100-0001"
},
"email": "john.doe@email.com",
"bank": {
"name": "Banco Nacional de Costa Rica",
"code": "0151",
"account": {
"number": "CR99000000000000000002"
}
}
}
}
'
curl --request POST \
--url https://api.stage.localpayment.com/api/simulate/va \
--header 'Authorization: Bearer {{access_token}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
"paymentMethod": {
"type": "BankTransfer",
"code": "1630",
"flow": "DIRECT"
},
"country": "MEX",
"currency": "MXN",
"amount": 100.00,
"accountNumber": "{{accountNumber}}",
"beneficiary": {
"type": "INDIVIDUAL",
"name": "Juan",
"lastName": "Perez",
"fullName": "Juan Perez",
"document": {
"type": "RFC",
"id": "PEPJ800101XXX"
},
"bank": {
"account": {
"number": "137424104400399999"
}
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "Alejandra",
"lastName": "Guzman",
"fullName": "Alejandra Guzman",
"document": {
"type": "RFC",
"id": "KCWV771228TS4"
},
"email": "alejandra.guzman@email.com",
"bank": {
"name": "BanCoppel",
"code": "137",
"account": {
"type": "C",
"number": "137424104400310004"
}
}
}
}
'
curl --request POST \
--url https://api.stage.localpayment.com/api/simulate/va \
--header 'Authorization: Bearer {{access_token}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"externalId": "b8c924d1-3f7a-4e82-bc1d-9a06fe37510c",
"paymentMethod": {
"type": "BankTransfer",
"code": "1680",
"flow": "DIRECT"
},
"country": "MEX",
"currency": "MXN",
"amount": 100.00,
"accountNumber": "{{accountNumber}}",
"beneficiary": {
"type": "COMPANY",
"name": "Servicios Digitales México S.A.",
"document": {
"type": "RFC",
"id": "HEMJ900101ABC"
},
"bank": {
"account": {
"number": "000000000000000009"
}
}
},
"payer": {
"type": "COMPANY",
"name": "Juan",
"lastName": "Doe",
"fullName": "Juan Doe",
"document": {
"type": "RFC",
"id": "HEMJ900101ABC"
},
"email": "juan.doe@email.com",
"bank": {
"name": "BANCO INBURSA",
"code": "036",
"account": {
"type": "CLABE",
"number": "00000000000000000001"
}
}
}
}
'
curl --request POST \
--url https://api.stage.localpayment.com/api/simulate/va \
--header 'Authorization: Bearer {{access_token}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"externalId": "e6807dd1-e910-41ea-9adc-b240a5509dd3",
"paymentMethod": {
"type": "BankTransfer",
"code": "6100",
"flow": "DIRECT"
},
"country": "PER",
"currency": "PEN",
"amount": 100.00,
"accountNumber": "{{accountNumber}}",
"beneficiary": {
"type": "INDIVIDUAL",
"name": "Lucia",
"lastName": "Torres",
"fullName": "Lucia Torres",
"document": {
"type": "DNI",
"id": "45678901"
},
"bank": {
"account": {
"number": "00219100111111100009"
}
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "Lucia",
"lastName": "Torres",
"fullName": "Lucia Torres",
"document": {
"type": "DNI",
"id": "45678901"
},
"email": "lucia.torres@email.com",
"bank": {
"name": "BCP",
"code": "002",
"account": {
"number": "19400123456789"
}
}
}
}
'
Webhook 通知示例
处理成功后,Localpayment 会向您配置的 endpoint 发送同步的payin.completed 事件。该通知遵循所有支付产品通用的标准高级 PayIn 结构。
{
"transactionType": "PayIn",
"transactionFlow": null,
"country": "MEX",
"data": {
"transactionType": "PayIn",
"externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
"internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
"paymentMethod": {
"type": "BankTransfer",
"code": "1630",
"flow": "DIRECT"
},
"country": "MEX",
"currency": "MXN",
"amount": 100.00,
"accountNumber": "{{accountNumber}}",
"confirmed": {
"currency": "MXN",
"fxQuote": 1.0,
"amount": 100.00
},
"beneficiary": {
"type": "INDIVIDUAL",
"name": "Juan",
"lastName": "Perez",
"fullName": "Juan Perez",
"document": {
"type": "RFC",
"id": "PEPJ800101XXX"
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "Alejandra",
"lastName": "Guzman",
"fullName": "Alejandra Guzman",
"document": {
"type": "RFC",
"id": "KCWV771228TS4"
}
},
"status": {
"code": "200",
"description": "COMPLETED",
"detail": "The payin was credited"
},
"date": {
"creationDate": "2024-03-27T15:00:00Z",
"processedDate": "2024-03-27T15:00:05Z"
}
}
}
{
"transactionType": "PayIn",
"transactionFlow": null,
"country": "MEX",
"data": {
"transactionType": "PayIn",
"externalId": "b8c924d1-3f7a-4e82-bc1d-9a06fe37510c",
"internalId": "e05fc3c3-f739-4393-b275-4a12f5a1af15",
"paymentMethod": {
"type": "BankTransfer",
"code": "1680",
"flow": "DIRECT"
},
"country": "MEX",
"currency": "MXN",
"amount": 1000.01,
"accountNumber": "{{accountNumber}}",
"confirmed": {
"currency": "MXN",
"fxQuote": 1,
"amount": 1000.01
},
"beneficiary": {
"type": "COMPANY",
"name": "Servicios Digitales México S.A.",
"document": {
"type": "RFC",
"id": "HEMJ900101ABC"
},
"bank": {
"name": "Banco Central",
"code": "001",
"account": {
"number": "000000000000000009"
}
}
},
"payer": {
"type": "COMPANY",
"name": "Juan",
"lastName": "Doe",
"fullName": "Juan Doe",
"document": {
"type": "RFC",
"id": "HEMJ900101ABC"
},
"bank": {
"name": "BANCO INBURSA",
"code": "036",
"account": {
"type": "CLABE",
"number": "00000000000000000001"
}
}
},
"status": {
"code": "200",
"description": "COMPLETED",
"detail": "The payin was credited"
},
"date": {
"creationDate": "2024-03-27T15:00:00Z",
"processedDate": "2024-03-27T15:00:05Z"
}
}
}
故障排除
| 错误代码 | 潜在原因 | 推荐修复方案 |
|---|---|---|
| 400 错误请求 | 付款人身份信息无效或缺少字段。 | 确保付款人数据与创建虚拟账户时使用的受益人信息相符。 |
| 404 未找到 | externalId 与任何有效的虚拟账户均不匹配。 | 在模拟之前,请确认虚拟账户已在 Stage 中成功创建。 |
| 401 未授权 | 使用了无效或生产环境令牌。 | 请确认您使用的是 Stage 环境 API 密钥。 |
| 422 无法处理 | 金额或币种不符。 | 请核对币种是否与所选的 paymentMethod.code 相符。 |
后续步骤
验证状态
获取实时状态更新以确认模拟交易进度。
配置 Webhooks
通过实时成功通知验证您的监听器逻辑。

