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

# 模拟虚拟账户支付

此接口允许您模拟向虚拟账户支付款项。**仅在 Stage 环境中可用。**它旨在帮助商家测试其集成的端到端流程，包括接收付款通知和验证交易状态，而无需实际进行银行转账。

> **环境限制**
>
> 此接口仅在 **Stage 环境**中可用，且仅用于测试目的。

### 付款人身份

使用创建虚拟账户时提供的相同受益人数据，包括姓名、文件类型和文件 ID。无需单独的测试身份；该接口会将付款人数据与账户创建期间登记的信息进行比对验证。


## OpenAPI

````yaml openapi/zh/localpayment.json POST /api/simulate/va
openapi: 3.1.0
info:
  version: '1.0'
  title: Localpayment
  contact:
    name: Support
    url: mailto:support@localpayment.com
servers:
  - url: https://api.stage.localpayment.com
    description: Stage
security:
  - token: []
paths:
  /api/simulate/va:
    post:
      summary: 模拟虚拟账户支付
      operationId: simulate-payin-to-virtual-account
      parameters:
        - name: Authorization
          in: header
          description: 用于身份验证的 Bearer 访问令牌。可从[获取访问令牌](/zh/reference/get-token)endpoint 获取。
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                externalId:
                  type: string
                  description: 模拟充值交易的唯一标识符。此值用作本次模拟生成的充值 ID，且每次请求必须不同。我们建议使用 UUID4 格式。
                paymentMethod:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - BankTransfer
                      description: 所模拟的支付方式类型。
                    code:
                      type: string
                      description: >-
                        支付方式的国家/地区专属代码（例如，ARG 为 `1025`，BRA 为 `1350`，COL 为
                        `2006`，MEX 的 SPEI 为 `1630`、TEF 为 `1680`，PER 为 `6100`，CHL
                        为 `2530`）。
                    flow:
                      type: string
                      enum:
                        - DIRECT
                      description: 交易流程。
                  required:
                    - type
                    - code
                    - flow
                country:
                  type: string
                  enum:
                    - ARG
                    - BRA
                    - COL
                    - MEX
                    - PER
                    - CHL
                  description: 虚拟账户所在的国家/地区（ISO 3166-1 alpha-3）。
                currency:
                  type: string
                  enum:
                    - ARS
                    - BRL
                    - COP
                    - MXN
                    - PEN
                    - CLP
                  description: 支付货币（ISO 4217）。
                amount:
                  type: number
                  description: 要模拟的支付金额。
                accountNumber:
                  type: string
                  description: Localpayment 与商家关联的账号，每个账号都是唯一的。
                beneficiary:
                  type: object
                  description: 资金接收方的相关信息。
                  properties:
                    type:
                      type: string
                      enum:
                        - INDIVIDUAL
                        - COMPANY
                      description: 受益人类型（INDIVIDUAL 或 COMPANY）。
                    name:
                      type: string
                      description: 受益人的名字。
                    lastName:
                      type: string
                      description: 受益人的姓氏。
                    fullName:
                      type: string
                      description: 受益人的全名（name 与 lastName 的拼接）。
                    document:
                      type: object
                      description: 受益人的官方身份证明文件。
                      properties:
                        type:
                          type: string
                          description: 证件类型（例如 CUIT、CPF、RFC）。
                        id:
                          type: string
                          description: 文件编号。
                      required:
                        - type
                        - id
                    bank:
                      type: object
                      description: 收款人的银行账户详细信息。
                      properties:
                        account:
                          type: object
                          description: 账户详细信息。
                          properties:
                            number:
                              type: string
                              description: >-
                                从[获取虚拟账户状态](/zh/reference/get-virtual-account-status)响应的
                                `beneficiary.bank.account.number`
                                字段中获得的虚拟账号。此值将模拟付款与正确的虚拟账户关联起来。
                          required:
                            - number
                      required:
                        - account
                  required:
                    - type
                    - name
                    - lastName
                    - fullName
                    - document
                    - bank
                payer:
                  type: object
                  description: 关于模拟付款人的信息。使用与创建虚拟账户时为受益人提供的相同数据——姓名、文件类型和文件 ID。
                  properties:
                    type:
                      type: string
                      enum:
                        - INDIVIDUAL
                        - COMPANY
                      description: 付款人类型（INDIVIDUAL 或 COMPANY）。
                    name:
                      type: string
                      description: 付款人的名字。
                    lastName:
                      type: string
                      description: 付款人的姓氏。
                    fullName:
                      type: string
                      description: 付款人的全名（name 与 lastName 的拼接）。
                    document:
                      type: object
                      description: 付款人的官方身份证明文件。
                      properties:
                        type:
                          type: string
                          description: 证件类型（例如 CUIT、CPF、RFC）。
                        id:
                          type: string
                          description: 文件编号。
                      required:
                        - type
                        - id
                    email:
                      type: string
                      description: 付款人的电子邮件地址。
                    bank:
                      type: object
                      description: 用于模拟付款的银行账户详细信息。
                      properties:
                        name:
                          type: string
                          description: 银行名称。
                        code:
                          type: string
                          description: 本地银行代码。
                        account:
                          type: object
                          description: 账户详细信息。
                          properties:
                            type:
                              type: string
                              description: 账户类型（例如 CBU、CLABE、AccountNumber）。
                            number:
                              type: string
                              description: 付款人的账号。
                          required:
                            - number
                        branch:
                          type: object
                          description: 银行网点详细信息。巴西必填。
                          properties:
                            code:
                              type: string
                              description: 分行代码的格式因银行而异。
                          required:
                            - code
                      required:
                        - name
                        - code
                        - account
                  required:
                    - type
                    - name
                    - lastName
                    - fullName
                    - document
                    - email
                    - bank
              required:
                - externalId
                - paymentMethod
                - country
                - currency
                - amount
                - accountNumber
                - beneficiary
                - payer
            examples:
              ARG Example:
                value:
                  externalId: de14bcf2-15ee-22e3-ab59-99c3fcba31e8
                  paymentMethod:
                    type: BankTransfer
                    code: '1025'
                    flow: DIRECT
                  country: ARG
                  currency: ARS
                  amount: 11000
                  accountNumber: '{{accountNumber}}'
                  beneficiary:
                    type: INDIVIDUAL
                    name: Carlos
                    lastName: Mendez
                    fullName: Carlos Mendez
                    document:
                      type: CUIT
                      id: '20314567894'
                    bank:
                      account:
                        number: '{{beneficiary.bank.account.number}}'
                  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'
              MEX Example:
                value:
                  externalId: f059a032-9253-4607-9b8e-2948ed18d595
                  paymentMethod:
                    type: BankTransfer
                    code: '1630'
                    flow: DIRECT
                  country: MEX
                  currency: MXN
                  amount: 500
                  accountNumber: '{{accountNumber}}'
                  beneficiary:
                    type: INDIVIDUAL
                    name: Juan
                    lastName: Perez
                    fullName: Juan Perez
                    document:
                      type: RFC
                      id: PEPJ800101XXX
                    bank:
                      account:
                        number: '{{beneficiary.bank.account.number}}'
                  payer:
                    type: INDIVIDUAL
                    name: Juan
                    lastName: Perez
                    fullName: Juan Perez
                    document:
                      type: RFC
                      id: PEPJ800101XXX
                    email: juan.perez@email.com
                    bank:
                      name: BanCoppel
                      code: '137'
                      account:
                        type: C
                        number: '137424104400310004'
              MEX TEF Example:
                value:
                  externalId: b8c924d1-3f7a-4e82-bc1d-9a06fe37510c
                  paymentMethod:
                    type: BankTransfer
                    code: '1680'
                    flow: DIRECT
                  country: MEX
                  currency: MXN
                  amount: 1000.01
                  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'
              BRA Example:
                value:
                  externalId: 0d55e796-bba6-4cf0-aead-8d9c1ed31044
                  paymentMethod:
                    type: BankTransfer
                    code: '1350'
                    flow: DIRECT
                  country: BRA
                  currency: BRL
                  amount: 100
                  accountNumber: '{{accountNumber}}'
                  beneficiary:
                    type: INDIVIDUAL
                    name: Rafael
                    lastName: Oliveira
                    fullName: Rafael Oliveira
                    document:
                      type: CPF
                      id: '12345678909'
                    bank:
                      account:
                        number: '{{beneficiary.bank.account.number}}'
                  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
              PER Example:
                value:
                  externalId: e6807dd1-e910-41ea-9adc-b240a5509dd3
                  paymentMethod:
                    type: BankTransfer
                    code: '6100'
                    flow: DIRECT
                  country: PER
                  currency: PEN
                  amount: 200
                  accountNumber: '{{accountNumber}}'
                  beneficiary:
                    type: INDIVIDUAL
                    name: Lucia
                    lastName: Torres
                    fullName: Lucia Torres
                    document:
                      type: DNI
                      id: '45678901'
                    bank:
                      account:
                        number: '{{beneficiary.bank.account.number}}'
                  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'
              CHL Example:
                value:
                  externalId: d2ffc771-2678-4dcc-8819-d446656a19f9
                  paymentMethod:
                    type: BankTransfer
                    code: '2530'
                    flow: DIRECT
                  country: CHL
                  currency: CLP
                  amount: 50000
                  accountNumber: '{{accountNumber}}'
                  beneficiary:
                    type: INDIVIDUAL
                    name: Valentina
                    lastName: Rojas
                    fullName: Valentina Rojas
                    document:
                      type: RUT
                      id: '123456789'
                    bank:
                      account:
                        number: '{{beneficiary.bank.account.number}}'
                  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'
              COL Example:
                value:
                  externalId: b3e14f73-8452-49b2-bf3c-b770774edfa8
                  paymentMethod:
                    type: BankTransfer
                    code: '2006'
                    flow: DIRECT
                  country: COL
                  currency: COP
                  amount: 100000
                  accountNumber: '{{accountNumber}}'
                  beneficiary:
                    type: INDIVIDUAL
                    name: Andres
                    lastName: Herrera
                    fullName: Andres Herrera
                    document:
                      type: CC
                      id: '1020456789'
                    bank:
                      account:
                        number: '{{beneficiary.bank.account.number}}'
                  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'
              CRI Example:
                value:
                  externalId: a1c2e3f4-5b6d-47a8-9c0e-1f2a3b4c5d6e
                  paymentMethod:
                    type: BankTransfer
                    code: '1420'
                    flow: DIRECT
                  country: CRI
                  currency: CRC
                  amount: 100
                  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
              CRI USD Example:
                value:
                  externalId: b2d3f4a5-6c7e-48b9-a1d0-2f3b4c5d6e7f
                  paymentMethod:
                    type: BankTransfer
                    code: '1421'
                    flow: DIRECT
                  country: CRI
                  currency: USD
                  amount: 100
                  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
      responses:
        '201':
          description: 创建完成 - 模拟已成功触发。
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionType:
                    type: string
                    description: 交易类型（例如，PayIn）。
                    example: PayIn
                  externalId:
                    type: string
                    description: 唯一标识符（`externalId` ）由商家提供，用于跟踪交易。
                  internalId:
                    type: string
                    format: uuid
                    description: 唯一标识符（`internalId` ) 由 Localpayment 分配给该交易。
                  paymentMethod:
                    type: object
                    description: 模拟交易中使用的支付方式。
                    properties:
                      type:
                        type: string
                        description: 支付方式类型。
                      code:
                        type: string
                        description: 支付方式的国家/地区特定代码。
                      flow:
                        type: string
                        description: 交易流程。
                  country:
                    type: string
                    description: 交易发生的国家。
                  currency:
                    type: string
                    description: 交易货币。
                  amount:
                    type: number
                    description: 交易金额。
                  accountNumber:
                    type: string
                    description: 商家的账号。
                  status:
                    type: object
                    description: 模拟交易的状态。
                    properties:
                      code:
                        type: string
                        description: 状态码。
                      description:
                        type: string
                        description: 简要描述现状。
                      detail:
                        type: string
                        description: 详细信息。
              examples:
                MEX Example:
                  value:
                    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
                    accountNumber: '{{accountNumber}}'
                    status:
                      code: '200'
                      description: COMPLETED
                      detail: The payin was credited
                ARG Example:
                  value:
                    transactionType: PayIn
                    externalId: de14bcf2-15ee-22e3-ab59-99c3fcba31e8
                    internalId: 5aced5da-40c1-4bec-85ff-c8cd1bcb4526
                    paymentMethod:
                      type: BankTransfer
                      code: '1025'
                      flow: DIRECT
                    country: ARG
                    currency: ARS
                    amount: 100
                    accountNumber: '{{accountNumber}}'
                    status:
                      code: '200'
                      description: COMPLETED
                      detail: The payin was credited
                BRA Example:
                  value:
                    transactionType: PayIn
                    externalId: 0d55e796-bba6-4cf0-aead-8d9c1ed31044
                    internalId: 5aced5da-40c1-4bec-85ff-c8cd1bcb4526
                    paymentMethod:
                      type: BankTransfer
                      code: '1350'
                      flow: DIRECT
                    country: BRA
                    currency: BRL
                    amount: 100
                    accountNumber: '{{accountNumber}}'
                    status:
                      code: '200'
                      description: COMPLETED
                      detail: The payin was credited
                PER Example:
                  value:
                    transactionType: PayIn
                    externalId: e6807dd1-e910-41ea-9adc-b240a5509dd3
                    internalId: 5aced5da-40c1-4bec-85ff-c8cd1bcb4526
                    paymentMethod:
                      type: BankTransfer
                      code: '6100'
                      flow: DIRECT
                    country: PER
                    currency: PEN
                    amount: 100
                    accountNumber: '{{accountNumber}}'
                    status:
                      code: '200'
                      description: COMPLETED
                      detail: The payin was credited
                CHL Example:
                  value:
                    transactionType: PayIn
                    externalId: d2ffc771-2678-4dcc-8819-d446656a19f9
                    internalId: 5aced5da-40c1-4bec-85ff-c8cd1bcb4526
                    paymentMethod:
                      type: BankTransfer
                      code: '2530'
                      flow: DIRECT
                    country: CHL
                    currency: CLP
                    amount: 50000
                    accountNumber: '{{accountNumber}}'
                    status:
                      code: '200'
                      description: COMPLETED
                      detail: The payin was credited
                COL Example:
                  value:
                    transactionType: PayIn
                    externalId: b3e14f73-8452-49b2-bf3c-b770774edfa8
                    internalId: 5aced5da-40c1-4bec-85ff-c8cd1bcb4526
                    paymentMethod:
                      type: BankTransfer
                      code: '2006'
                      flow: DIRECT
                    country: COL
                    currency: COP
                    amount: 100000
                    accountNumber: '{{accountNumber}}'
                    status:
                      code: '200'
                      description: COMPLETED
                      detail: The payin was credited
                CRI Example:
                  value:
                    transactionType: PayIn
                    externalId: a1c2e3f4-5b6d-47a8-9c0e-1f2a3b4c5d6e
                    internalId: c06bbea8-48d1-4659-9664-633b7f9f080d
                    paymentMethod:
                      type: BankTransfer
                      code: '1420'
                      flow: DIRECT
                    country: CRI
                    currency: CRC
                    amount: 100
                    accountNumber: '{{accountNumber}}'
                    status:
                      code: '200'
                      description: COMPLETED
                      detail: The payin was credited
                CRI USD Example:
                  value:
                    transactionType: PayIn
                    externalId: b2d3f4a5-6c7e-48b9-a1d0-2f3b4c5d6e7f
                    internalId: e05fc3c3-f739-4393-b275-4a12f5a1af16
                    paymentMethod:
                      type: BankTransfer
                      code: '1421'
                      flow: DIRECT
                    country: CRI
                    currency: USD
                    amount: 100
                    accountNumber: '{{accountNumber}}'
                    status:
                      code: '200'
                      description: COMPLETED
                      detail: The payin was credited
        '400':
          description: 错误请求 - 参数或账号无效。
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP状态码。
                  error:
                    type: string
                    description: 简短的错误名称。
                  message:
                    type: string
                    description: 易于理解的错误信息。
                  path:
                    type: string
                    description: 发生错误的 API 路径。
              examples:
                Bad Request:
                  value:
                    status: 400
                    error: Bad Request
                    message: Invalid payer identity or missing mandatory fields.
                    path: /api/simulate/va
        '401':
          description: 未授权 - 令牌无效或已过期。
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 说明令牌无效原因的详细错误消息。
                  code:
                    type: string
                    description: 机器可读的错误代码。
                  messages:
                    type: array
                    description: 提供有关身份验证失败更多背景信息的消息列表。
                    items:
                      type: object
                      properties:
                        token_class:
                          type: string
                          description: 令牌的类别（例如 AccessToken）。
                        token_type:
                          type: string
                          description: 令牌类型（例如 access）。
                        message:
                          type: string
                          description: 特定于令牌的错误消息。
              examples:
                Unauthorized:
                  value:
                    detail: Given token not valid for any token type
                    code: token_not_valid
                    messages:
                      - token_class: AccessToken
                        token_type: access
                        message: Token is invalid or expired
        '404':
          description: 未找到 - 未找到虚拟帐户。
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP状态码。
                  error:
                    type: string
                    description: 简短的错误名称。
                  message:
                    type: string
                    description: 易于理解的错误信息。
                  path:
                    type: string
                    description: 发生错误的 API 路径。
              examples:
                Not Found:
                  value:
                    status: 404
                    error: Not Found
                    message: >-
                      Virtual Account with externalId
                      de14bcf2-15ee-22e3-ab59-99c3fcba31e8 not found.
                    path: /api/simulate/va
        '500':
          description: 服务器内部错误。
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP状态码。
                  error:
                    type: string
                    description: 简短的错误名称。
                  message:
                    type: string
                    description: 易于理解的错误信息。
                  path:
                    type: string
                    description: 发生错误的 API 路径。
              examples:
                Server Error:
                  value:
                    status: 500
                    error: Internal Server Error
                    message: An unexpected error occurred while simulating the payment.
                    path: /api/simulate/va
      security:
        - token: []
      servers:
        - url: https://api.stage.localpayment.com
          description: Stage
components:
  securitySchemes:
    token:
      type: http
      scheme: bearer

````

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