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

# 批量创建虚拟账户

此接口允许您同时创建多个虚拟账户，从而简化处理大量账户时的账户创建流程。您可以通过数组创建 10 到 5000 个虚拟账户。


## OpenAPI

````yaml openapi/zh/localpayment.json POST /api/virtual-account-batch
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/virtual-account-batch:
    post:
      summary: 批量创建虚拟账户
      operationId: request-batch
      parameters:
        - name: Authorization
          in: header
          description: >-
            用于身份验证的 Bearer
            访问令牌。该令牌可从[获取访问令牌](/zh/reference/get-token)或[刷新访问令牌](/zh/reference/refresh-token)endpoint
            获取。
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                externalId:
                  type: string
                  description: 您为整个批处理流程提供的唯一标识符。此 ID 将用于跟踪和引用整个批处理操作。
                accountNumber:
                  type: string
                  description: Localpayment账号。
                country:
                  type: string
                  enum:
                    - ARG
                    - BRA
                    - CHL
                    - MEX
                  description: '[国家](/zh/reference/country-codes)。ISO 3166-1 alpha-3。'
                name:
                  type: string
                accounts:
                  type: array
                  items:
                    type: object
                    properties:
                      externalId:
                        type: string
                        description: >-
                          您为批次内特定虚拟账户提供的唯一标识符。在今后的所有操作（例如查询状态、停用）中，此 ID
                          将作为该单个账户的主要参考依据。
                      beneficiary:
                        type: object
                        description: 接收存入此虚拟账户资金的个人或实体。受益人是资金的最终接收者，但不一定是虚拟账户本身的合法所有者或持有人。
                        properties:
                          type:
                            type: string
                            enum:
                              - COMPANY
                              - INDIVIDUAL
                            description: 受益人类型。
                          name:
                            type: string
                            description: >-
                              受益人名称。允许的字符取决于 `type` 字段：对于
                              `individual`，允许字母（包括带重音符号的字符）、空格和点（`.`）；对于
                              `company`，允许相同字符集，另外还允许数字、下划线（`_`）和连字符（`-`）。
                            minLength: 2
                            maxLength: 255
                          document:
                            type: object
                            description: 受益人文件。
                            properties:
                              type:
                                type: string
                                description: >-
                                  根据签发国家/地区的不同，[身份证明文件类型](/zh/reference/identity-document-types)可能包括国民身份证号码、社会保障号码或驾驶执照。
                                examples:
                                  - RUC
                              id:
                                type: string
                                description: 身份证件号码（通常为数字）。该号码必须符合特定证件类型的有效规定。
                                examples:
                                  - '1791234561009'
                            required:
                              - type
                              - id
                            examples:
                              - type: RUC
                                id: '1791234561009'
                          lastName:
                            type: string
                            description: >-
                              受益人的姓氏。当 `type` 为 `individual` 时必填，当 `type` 为
                              `company` 时忽略。允许的字符取决于 `type`：对于
                              `individual`，允许字母（包括带重音符号的字符）、空格和点（`.`）；对于
                              `company`，允许相同字符集，另外还允许数字、下划线（`_`）和连字符（`-`）。
                            minLength: 2
                            maxLength: 255
                          address:
                            type: object
                            description: 受益人地址。
                            properties:
                              street:
                                type: string
                                description: 街道名称。
                                examples:
                                  - Independencia
                              number:
                                type: string
                                description: 街道号码。
                                examples:
                                  - '123'
                              city:
                                type: string
                                description: 城市。
                                examples:
                                  - Cordoba
                              state:
                                type: string
                                description: 州/省。
                                examples:
                                  - Cordoba
                              country:
                                type: string
                                description: 地址所在国家/地区。
                                examples:
                                  - Argentina
                              zipCode:
                                type: string
                                description: 邮政编码。
                                examples:
                                  - X5000IUO
                              comment:
                                type: string
                                description: 其他地址信息。
                                examples:
                                  - Sucursal 123
                            examples:
                              - street: Independencia
                                number: '123'
                                city: Cordoba
                                state: Cordoba
                                country: ARG
                                zipCode: X5000IUO
                                comment: Sucursal 123
                        required:
                          - type
                          - name
                          - document
                        examples:
                          - type: INDIVIDUAL
                            name: John
                            document:
                              type: RUC
                              id: '1791234561009'
                            lastName: Doe
                            address:
                              street: Independencia
                              number: '123'
                              city: Cordoba
                              state: Cordoba
                              country: ARG
                              zipCode: X5000IUO
                              comment: Sucursal 123
                    required:
                      - beneficiary
              required:
                - externalId
                - accountNumber
                - country
                - accounts
              x-examples:
                Example 1:
                  externalId: '{{$guid}}'
                  accountNumber: '{{YourAccountNumber}}'
                  country: MEX
                  name: Virtual Account
                  accounts:
                    - externalId: 1111111111-1
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                        address:
                          city: city
                          state: state
                          zipcode: zipcode
                          street: street
                          number: number
                          country: country
                    - externalId: 1111111111-2
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                    - externalId: 1111111111-3
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                        address:
                          city: city
                          state: state
                          zipcode: zipcode
                          street: street
                          number: number
                          country: country
                    - externalId: 1111111111-4
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                    - externalId: 1111111111-5
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                        address:
                          city: city
                          state: state
                          zipcode: zipcode
                          street: street
                          number: number
                          country: country
                    - externalId: 1111111111-6
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                    - externalId: 1111111111-7
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          type: RFC
                          id: EXTF900101NI1
                        address:
                          city: city
                          state: state
                          zipcode: zipcode
                          street: street
                          number: number
                          country: country
                    - externalId: 1111111111-8
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                    - externalId: 1111111111-9
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                        address:
                          city: city
                          state: state
                          zipcode: zipcode
                          street: street
                          number: number
                          country: country
                    - externalId: 1111111111-10
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                    - externalId: 1111111111-11
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                        address:
                          city: city
                          state: state
                          zipcode: zipcode
                          street: street
                          number: number
                          country: country
                    - externalId: 1111111111-12
                      beneficiary:
                        type: INDIVIDUAL
                        name: BeneficiaryName
                        lastname: BeneficiaryLastname
                        document:
                          id: EXTF900101NI1
                          type: RFC
                        address:
                          city: city
                          state: state
                          zipcode: zipcode
                          street: street
                          number: number
                          country: country
            examples:
              100 - Batch Process Virtual Account in progress.:
                value:
                  externalId: de14bcf2-45ee-22e3-ab59-99c3fcba31e8
                  accountNumber: '{{yourLocalpaymentAccountNumber}}'
                  country: MEX
                  name: Virtual Account
                  accounts:
                    - externalId: 9210b519-5c29-4419-8d28-04f7543a914f
                      beneficiary:
                        type: INDIVIDUAL
                        name: Zhang
                        lastname: Wei
                        document:
                          id: EXTF900101NI1
                          type: RFC
                    - externalId: e4914217-41bc-49a5-b2f8-df950bf9bae7
                      beneficiary:
                        type: INDIVIDUAL
                        name: John
                        lastname: Doe
                        document:
                          id: EXTF900101NI2
                          type: RFC
              300 - Invalid params.:
                value:
                  externalId: de14bcf2-45ee-22e3-ab59-99c3fcba31e8
                  accountNumber: '{{accountNumber}}'
                  country: MEX
                  name: Virtual Account
                  accounts:
                    - externalId: 9210b519-5c29-4419-8d28-04f7543a914f
                    - externalId: e4914217-41bc-49a5-b2f8-df950bf9bae7
                      beneficiary:
                        type: INDIVIDUAL
                        name: John
                        lastname: Doe
                        document:
                          id: EXTF900101NI2
                          type: RFC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  externalId:
                    type: string
                    description: 此批处理进程的唯一标识符。它与您在请求中提供的 externalId 相同，用于确认您正在查询的批处理操作。
                  internalId:
                    type: string
                    description: Localpayment交易标识符。
                  accountNumber:
                    type: string
                    description: Localpayment账号。
                  status:
                    $ref: '#/components/schemas/status'
                  comment:
                    type: string
                    description: 附加信息。
                  errors:
                    type: array
                    description: 其他错误信息。
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: 错误代码。
                        detail:
                          type: string
                          description: 错误详情。
                x-examples:
                  Example 1:
                    externalId: 7facbbbf-d279-4ab5-9aeb-7583fa3f35ec
                    internalId: 1748f8f8-dcac-45d7-b1fc-7d6569245d84
                    accountNumber: '{{YourAccountNumber}}'
                    status:
                      code: '100'
                      description: INPROGRESS
                      detail: Batch Process Virtual Account in progress
                    comment: >-
                      For obtaining the asynchronous response, kindly submit a
                      request to the service after a brief interval. GET
                      {api_environment_url}/api/virtual-account-batch/7facbbbf-d279-4ab5-9aeb-7583fa3f35ec
              examples:
                100 - Batch Process Virtual Account in progress.:
                  value:
                    externalId: 7facbc4f-4c79-4a15-caeb-75833a3f35ec
                    internalId: 1748f8f8-dcac-4547-b3fb-7d6529245d84
                    accountNumber: '{{yourLocalpaymentAccountNumber}}'
                    status:
                      code: '100'
                      description: INPROGRESS
                      detail: Batch Process Virtual Account in progress
                    comment: >-
                      For obtaining the asynchronous response, kindly submit a
                      request to the service after a brief interval. GET
                      {api_environment_url}/api/virtual-account-batch/7facbbbf-d279-4ab5-9aeb-7583fa3f35ec
                300 - Invalid params.:
                  value:
                    externalId: 2f3cb0ac-1c4b-471d-a43f-1af10867d716
                    status:
                      code: '300'
                      description: REJECTED
                      detail: Invalid param + [document.id] + verification failed
                    errors:
                      - code: '300'
                        detail: Invalid param + [document.id] + verification failed
                501 - Country not found.:
                  value:
                    externalId: 75743a87-6d5e-42c4-a2ff-c596a6a27182
                    status:
                      code: '501'
                      description: REJECTED
                      detail: Country not found
                    errors:
                      - code: '501'
                        detail: Country not found
        '400':
          description: 错误的请求。
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    description: 服务执行时间。
                  status:
                    type: integer
                    description: 错误状态码。
                  error:
                    type: string
                    description: 错误描述。
                  message:
                    type: string
                    description: 包含补充信息的消息。
                  path:
                    type: string
                    description: 服务路径。
                x-examples:
                  Example 1:
                    timestamp: '2025-01-03T14:52:43.271+00:00'
                    status: 400
                    error: Bad Request.
                    message: Count can not be blank
                    path: /virtual-account/batch
              examples:
                400 - Count can not be blank.:
                  value:
                    timestamp: '2025-01-03T14:52:43.271+00:00'
                    status: 400
                    error: Bad Request.
                    message: Count can not be blank
                    path: /virtual-account/batch
                400 - External ID already used - Duplication.:
                  value:
                    timestamp: '2025-01-03T22:03:39.657+00:00'
                    status: 400
                    error: Bad Request.
                    message: External ID already used - Duplication
                    path: /virtual-account/batch
        '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: Token 类。
                        token_type:
                          type: string
                          description: 令牌类型。
                        message:
                          type: string
                          description: 包含补充信息的消息。
                x-examples:
                  Example 1:
                    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
              examples:
                401 - Token is invalid or expired:
                  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
        '500':
          description: 内部服务器错误
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    description: 服务执行时间。
                  status:
                    type: integer
                    description: 错误状态码。
                  error:
                    type: string
                    description: 错误描述。
                  message:
                    type: string
                    description: 包含补充信息的消息。
                  path:
                    type: string
                    description: 服务路径。
                x-examples:
                  Example 1:
                    timestamp: '2025-01-03T22:02:09.745+00:00'
                    status: 500
                    error: Internal Server Error
                    message: >-
                      query did not return a unique result: 12; nested exception
                      is javax.persistence.NonUniqueResultException: query did
                      not return a unique result: 12
                    path: /virtual-account/batch
              examples:
                500 - Query did not return a unique result.:
                  value:
                    timestamp: '2025-01-03T22:02:09.745+00:00'
                    status: 500
                    error: Internal Server Error
                    message: >-
                      query did not return a unique result: 12; nested exception
                      is javax.persistence.NonUniqueResultException: query did
                      not return a unique result: 12
                    path: /virtual-account/batch
      security:
        - token: []
      servers:
        - url: https://api.stage.localpayment.com
          description: Stage
components:
  schemas:
    status:
      type: object
      title: 状态
      description: 操作状态。
      properties:
        code:
          type: string
          description: 状态码。
        description:
          type: string
          description: 状态描述。
        detail:
          type: string
          description: 更多状态信息。
  securitySchemes:
    token:
      type: http
      scheme: bearer

````

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