> ## 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 在 **Stage 环境** 中提供了一个模拟 endpoint，允许您向任何已激活的虚拟账户触发模拟收款。

该模拟模仿了真实的本地 ACH 转账行为，触发了与生产环境中预期相同的内部状态更新和 webhook 通知。

## 模拟流程

1. **创建虚拟账户**：首先，在测试环境中生成一个虚拟账户。
2. **获取虚拟账户状态**：使用 [获取虚拟账户状态](https://docs.localpayment.com/zh/reference/get-virtual-account-status.md) endpoint 确认账户已成功创建，并从响应中获取 `beneficiary.bank.account.number` 字段。
3. **关联模拟**：在模拟请求中，使用上一步获得的 `beneficiary.bank.account.number`，将模拟付款关联到正确的账户。此外，请提供唯一的 `externalId`——它将作为本次交易所生成的 payin 的 ID；每次模拟请求都请使用不同的 `externalId`。您还必须提供您的 Localpayment **accountNumber**（商户 ID），以识别与模拟支付关联的商户账户。
4. **触发模拟**：调用 [模拟虚拟账户支付](https://docs.localpayment.com/zh/reference/simulate-payin-to-virtual-account.md) endpoint。
5. **接收 Webhook**：Localpayment 将发送一个 `payin.completed`（或类似）webhook 到您配置的 endpoint。
6. **验证状态**：使用交易状态 API 确认模拟交易已达到预期状态。

***

## 技术依赖关系

> [!NOTE]
>
> **顺序要求**：您不能模拟尚未成功创建的账户的付款。如果 [创建虚拟账户](https://docs.localpayment.com/zh/reference/create-virtual-account.md) 调用失败，模拟尝试将返回 404 Not Found 错误。

***

## 代码示例（Stage）

选择您的目标市场，查看完整的 `curl` 示例。请使用创建虚拟账户时提供的相同受益人数据，并为每次模拟请求提供唯一的 `externalId`。

> [tab] 阿根廷
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> 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"
>       }
>     }
>   }
> }
> '
> ```

> [tab] 巴西
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> 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"
>       }
>     }
>   }
> }
> '
> ```

> [tab] 智利
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> 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"
>       }
>     }
>   }
> }
> '
> ```

> [tab] 哥伦比亚
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> 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"
>       }
>     }
>   }
> }
> '
> ```

> [tab] 哥斯达黎加（CRC）
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> 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"
>       }
>     }
>   }
> }
> '
> ```

> [tab] 哥斯达黎加（USD）
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> 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"
>       }
>     }
>   }
> }
> '
> ```

> [tab] 墨西哥（SPEI）
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> 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"
>       }
>     }
>   }
> }
> '
> ```

> [tab] 墨西哥（TEF）
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> 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"
>       }
>     }
>   }
> }
> '
> ```

> [tab] 秘鲁
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> 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` 结构。

```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": "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"
    }
  }
}
```

```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": "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` 相符。 |

***

## 后续步骤

> [card] [验证状态](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 获取实时状态更新以确认模拟交易进度。

> [card] [配置 Webhooks](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 通过实时成功通知验证您的监听器逻辑。


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