> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Beneficiary

> Create a payout beneficiary for local bank transfers



## OpenAPI

````yaml post /v1/beneficiaries
openapi: 3.1.1
info:
  title: HitPay API
  description: >-
    Accept PayNow, FPX, QRIS, GrabPay, cards, and 40+ payment methods with a
    single API. Production base URL: https://api.hit-pay.com, Sandbox:
    https://api.sandbox.hit-pay.com
  version: '1.0'
servers:
  - url: https://api.hit-pay.com
    description: Production
  - url: https://api.sandbox.hit-pay.com
    description: Sandbox
security: []
paths:
  /v1/beneficiaries:
    post:
      summary: Create a new beneficiary
      description: >-
        A beneficiary is a person or business receiving the funds. HitPay
        currently supports local beneficiaries, enabling payouts within the same
        country and region.
      operationId: create-beneficiary
      parameters:
        - name: X-BUSINESS-API-KEY
          in: header
          required: true
          style: simple
          explode: false
          schema:
            type: string
            example: b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/beneficiary-sqd-fast'
                  title: Singapore / SGD / FAST
                - $ref: '#/components/schemas/beneficiary-bd-local'
                  title: Bangladesh / BDT / Local bank transfer
                - $ref: '#/components/schemas/beneficiary-bd-upay'
                  title: Bangladesh / BDT / Upay
                - $ref: '#/components/schemas/beneficiary-bd-bkash'
                  title: Bangladesh / BDT / bKash
                - $ref: '#/components/schemas/beneficiary-bd-tap'
                  title: Bangladesh / BDT / TAP
                - $ref: '#/components/schemas/beneficiary-php-local'
                  title: Philippines / PHP / Local bank transfer
            examples:
              Singapore / SGD / FAST:
                value:
                  country: sg
                  transfer_method: bank_transfer
                  transfer_type: local
                  currency: sgd
                  holder_type: individual
                  holder_name: John Tan
                  bank_id: BOFASG2XXXX[7065]
                  account_number: '1409827'
              Bangladesh / BDT / Local bank transfer:
                value:
                  country: bd
                  transfer_method: bank_transfer
                  transfer_type: local
                  currency: bdt
                  holder_type: individual
                  holder_name: SHAH ALAM HERA
                  bank_id: brc-20
                  bank_routing_number: '060261726'
                  account_number: '1503201781283001'
              Bangladesh / BDT / Upay:
                value:
                  country: bd
                  transfer_method: upay
                  currency: bdt
                  holder_type: individual
                  holder_name: Moulude Hossain
                  district: BD-03
                  account_number: '+8801914538413'
              Bangladesh / BDT / bKash:
                value:
                  country: bd
                  transfer_method: bkash
                  currency: bdt
                  holder_type: individual
                  holder_name: Rashid
                  district: BD-03
                  account_number: '+8801721940130'
              Bangladesh / BDT / TAP:
                value:
                  country: bd
                  transfer_method: tap
                  currency: bdt
                  holder_type: individual
                  holder_name: Moulude Hossain
                  district: BD-04
                  account_number: '+8801914538413'
              Philippines / PHP / Local bank transfer:
                value:
                  country: ph
                  transfer_method: bank_transfer
                  transfer_type: local
                  currency: php
                  holder_type: individual
                  holder_name: Ben Yu
                  bank_id: '10419995'
                  account_number: '14098377'
                  address:
                    street: Pedro Gil, cor Adriatico St
                    postcode: '1000'
                    city: Manila
      responses:
        '201':
          description: '201'
          content:
            application/json:
              examples:
                Result:
                  value:
                    id: 9ec01865-7af1-4937-813d-7801912d2cd1
                    status: approved
                    country: sg
                    currency: sgd
                    transfer_method: bank_transfer
                    transfer_type: local
                    nickname: null
                    remark: null
                    holder_name: John Test
                    holder_type: individual
                    account_number: '1409828'
                    bank_name: BANK OF AMERICA
                    bank_id: BOFASG2XXXX[7065]
                    email: null
                    bank_swift_code: BOFASG2XXXX
                    is_favourite: false
                    created_by:
                      id: 98566f58-1c76-4b8b-8f75-d20bba2bc7f8
                      display_name: TestingSG
                      first_name: QA
                      last_name: SG
                    created_at: '2025-04-24T15:13:22+08:00'
                    updated_at: '2025-04-24T15:13:22+08:00'
                    deleted_at: null
        '422':
          description: '201'
          content:
            application/json:
              examples:
                Result:
                  value:
                    message: The Country field is required. (and 4 more errors)
                    errors:
                      country:
                        - The Country field is required.
                      transfer_method:
                        - The Transfer Method field is required.
                      currency:
                        - The Currency field is required.
                      holder_type:
                        - The Entity Type field is required.
                      holder_name:
                        - The Account Holder Name field is required.
      deprecated: false
components:
  schemas:
    beneficiary-sqd-fast:
      type: object
      required:
        - country
        - transfer_method
        - currency
        - transfer_type
        - holder_type
        - holder_name
        - account_number
      properties:
        country:
          type: string
          description: Beneficiary bank country/region
          example: sg
          enum:
            - sg
        transfer_method:
          type: string
          description: >-
            The transfer method needs to be specified to ensure that accurate
            banking details are captured and validated for the specified
            transfer method. This is required for timely and accurate delivery
            of funds to the beneficiary account
          enum:
            - bank_transfer
          example: bank_transfer
        transfer_type:
          type: string
          enum:
            - local
          example: local
        currency:
          type: string
          enum:
            - sgd
          example: sgd
          description: It is beneficiary bank account currency.
        holder_type:
          type: string
          description: The Holder Type
          enum:
            - individual
          example: individual
        holder_name:
          type: string
          required: true
          description: The Holder Name
          example: John Doe
          maxLength: 255
        bank_swift_code:
          type: string
          required: true
          description: >-
            It's bank swift code. To obtain a list of supported SWIFT codes,
            call `Get the API schema` API with the following parameters:
            `country: sg`, currency: `sgd`,transfer_method: `bank_transfer`,
            transfer_type: `local` and holder_type: `individual`.
          maxLength: 255
          example: BOFASG2XXXX
        account_number:
          type: string
          required: true
          description: The account number
          maxLength: 255
          example: '1409827'
        nickname:
          type: string
          description: Nickname
          maxLength: 255
        remark:
          type: string
          description: Remark
          maxLength: 255
          example: This is a remark
        is_favourite:
          type: boolean
        email:
          type: string
          format: email
          description: Email address
          example: abc@gmail.com
      example:
        country: sg
        transfer_method: bank_transfer
        transfer_type: local
        currency: sgd
        holder_type: individual
        holder_name: John Tan
        bank_id: BOFASG2XXXX[7065]
        account_number: '1409827'
    beneficiary-bd-local:
      type: object
      required:
        - country
        - transfer_method
        - currency
        - transfer_type
        - holder_type
        - holder_name
        - bank_id
        - bank_routing_number
        - account_number
      properties:
        country:
          type: string
          required: true
          description: Beneficiary bank country/region
          enum:
            - bd
        transfer_method:
          type: string
          required: true
          description: >-
            The transfer method needs to be specified to ensure that accurate
            banking details are captured and validated for the specified
            transfer method. This is required for timely and accurate delivery
            of funds to the beneficiary account
          enum:
            - bank_transfer
          example: bank_transfer
        transfer_type:
          type: string
          required: true
          enum:
            - local
          value: local
        currency:
          type: string
          required: true
          enum:
            - bdt
          value: bdt
          description: It is beneficiary bank account currency.
        holder_type:
          type: string
          required: true
          enum:
            - individual
          example: individual
          description: The Holder Type
        holder_name:
          type: string
          required: true
          description: The Holder Name
          example: John Doe
          maxLength: 255
        bank_id:
          type: string
          required: true
          description: >-
            It's bank id. To obtain a list of supported values for `bank_id`,
            call `Get the API schema` API with the following parameters:
            `country: bd`, currency: `bdt`,transfer_method: `bank_transfer`,
            transfer_type: `local` and holder_type: `individual` to get the the
            correct supported bank id.
          example: brc-20
          maxLength: 255
        bank_routing_number:
          type: string
          required: true
          description: Bank Rounting Number
          maxLength: 255
          example: '060261726'
        account_number:
          type: string
          required: true
          description: The account number
          maxLength: 255
          example: '1503201781283001'
        nickname:
          type: string
          description: Nickname
          maxLength: 255
        remark:
          type: string
          description: Remark
          maxLength: 255
          example: This is a remark
        is_favourite:
          type: boolean
          description: Remark
        email:
          type: string
          format: email
          description: Email address
          example: abc@gmail.com
      example:
        country: bd
        transfer_method: bank_transfer
        transfer_type: local
        currency: bdt
        holder_type: individual
        holder_name: SHAH ALAM HERA
        bank_id: brc-20
        bank_routing_number: '060261726'
        account_number: '1503201781283001'
    beneficiary-bd-upay:
      type: object
      required:
        - country
        - transfer_method
        - currency
        - holder_type
        - holder_name
        - district
        - account_number
      properties:
        country:
          type: string
          required: true
          description: Beneficiary bank country/region
          enum:
            - bd
        transfer_method:
          type: string
          required: true
          description: >-
            The transfer method needs to be specified to ensure that accurate
            banking details are captured and validated for the specified
            transfer method. This is required for timely and accurate delivery
            of funds to the beneficiary account
          enum:
            - upay
          example: upay
        currency:
          type: string
          required: true
          enum:
            - bdt
          example: bdt
          description: It is beneficiary bank account currency.
        holder_type:
          type: string
          required: true
          enum:
            - individual
          example: individual
          description: The Holder Type
        holder_name:
          type: string
          required: true
          description: The Holder Name
          example: John Doe
          maxLength: 255
        district:
          type: string
          required: true
          description: District
          maxLength: 255
          example: BD-03
        account_number:
          type: string
          required: true
          description: The account number
          maxLength: 255
          example: '+8801914538413'
        nickname:
          type: string
          example: John
          description: Nickname
          maxLength: 255
        remark:
          type: string
          description: Remark
          maxLength: 255
          example: This is a remark
        is_favourite:
          type: boolean
          description: Remark
        email:
          type: string
          format: email
          description: Email address
          example: abc@gmail.com
      example:
        country: bd
        transfer_method: upay
        currency: bdt
        holder_type: individual
        holder_name: Moulude Hossain
        district: BD-03
        account_number: '+8801914538413'
    beneficiary-bd-bkash:
      type: object
      required:
        - country
        - transfer_method
        - currency
        - holder_type
        - holder_name
        - district
        - account_number
      properties:
        country:
          type: string
          required: true
          description: Beneficiary bank country/region
          enum:
            - bd
        transfer_method:
          type: string
          required: true
          description: >-
            The transfer method needs to be specified to ensure that accurate
            banking details are captured and validated for the specified
            transfer method. This is required for timely and accurate delivery
            of funds to the beneficiary account
          enum:
            - bkash
          example: bkash
        currency:
          type: string
          required: true
          emum:
            - bdt
          example: bdt
          description: It is beneficiary bank account currency.
        holder_type:
          type: string
          required: true
          enum:
            - individual
          example: individual
          description: The Holder Type
        holder_name:
          type: string
          required: true
          example: Rashid
          description: The Holder Name
          maxLength: 255
        district:
          type: string
          required: true
          description: District
          maxLength: 255
          example: BD-03
        account_number:
          type: string
          required: true
          example: '+8801721940130'
          description: The account number
          maxLength: 255
        nickname:
          type: string
          example: John
          description: Nickname
          maxLength: 255
        remark:
          type: string
          description: Remark
          maxLength: 255
          example: This is a remark
        is_favourite:
          type: boolean
          description: Remark
        email:
          type: string
          format: email
          description: Email address
          example: abc@gmail.com
      example:
        country: bd
        transfer_method: bkash
        currency: bdt
        holder_type: individual
        holder_name: Rashid
        district: BD-03
        account_number: '+8801721940130'
    beneficiary-bd-tap:
      type: object
      required:
        - country
        - transfer_method
        - currency
        - holder_type
        - holder_name
        - district
        - account_number
      properties:
        country:
          type: string
          required: true
          description: Beneficiary bank country/region
          enum:
            - bd
        transfer_method:
          type: string
          required: true
          description: >-
            The transfer method needs to be specified to ensure that accurate
            banking details are captured and validated for the specified
            transfer method. This is required for timely and accurate delivery
            of funds to the beneficiary account
          enum:
            - tap
          example: tap
        currency:
          type: string
          required: true
          emum:
            - bdt
          example: bdt
          description: It is beneficiary bank account currency.
        holder_type:
          type: string
          required: true
          enum:
            - individual
          example: individual
          description: The Holder Type
        holder_name:
          type: string
          required: true
          example: Rashid
          description: The Holder Name
          maxLength: 255
        district:
          type: string
          required: true
          description: District
          maxLength: 255
          example: BD-03
        account_number:
          type: string
          required: true
          example: '+8801721940130'
          description: The account number
          maxLength: 255
        nickname:
          type: string
          example: John
          description: Nickname
          maxLength: 255
        remark:
          type: string
          description: Remark
          maxLength: 255
          example: This is a remark
        is_favourite:
          type: boolean
          description: Remark
        email:
          type: string
          format: email
          description: Email address
          example: abc@gmail.com
      example:
        country: bd
        transfer_method: tap
        currency: bdt
        holder_type: individual
        holder_name: Moulude Hossain
        district: BD-04
        account_number: '+8801914538413'
    beneficiary-php-local:
      type: object
      required:
        - country
        - transfer_method
        - currency
        - holder_type
        - holder_name
        - bank_id
        - account_number
        - address
      properties:
        country:
          type: string
          required: true
          description: Beneficiary bank country/region
          enum:
            - ph
        transfer_method:
          type: string
          required: true
          description: >-
            The transfer method needs to be specified to ensure that accurate
            banking details are captured and validated for the specified
            transfer method. This is required for timely and accurate delivery
            of funds to the beneficiary account
          enum:
            - bank_transfer
          example: bank_transfer
        transfer_type:
          type: string
          required: true
          enum:
            - local
          example: local
        currency:
          type: string
          required: true
          enum:
            - php
          description: It is beneficiary bank account currency.
        holder_type:
          type: string
          required: true
          enum:
            - individual
          example: individual
          description: The Holder Type
        holder_name:
          type: string
          required: true
          description: The Holder Name
          example: John Doe
          maxLength: 255
        bank_id:
          type: string
          required: true
          description: >-
            It's bank id. To obtain a list of supported values for `bank_id`,
            call `Get the API schema` API with the following parameters:
            `country: ph`, currency: `php`,transfer_method: `bank_transfer`,
            transfer_type: `local` and holder_type: `individual` to get the the
            correct supported bank id.
          example: '10419995'
          maxLength: 255
        account_number:
          type: string
          required: true
          example: '14098377'
          description: The account number
          maxLength: 255
        address:
          type: object
          required:
            - street
            - postcode
            - city
          properties:
            street:
              type: string
              example: Pedro Gil, cor Adriatico St
            postcode:
              type: string
              example: '1000'
            city:
              type: string
              example: Manila
        nickname:
          type: string
          example: John
          description: Nickname
          maxLength: 255
        remark:
          type: string
          description: Remark
          maxLength: 255
          example: This is a remark
        is_favourite:
          type: boolean
        email:
          type: string
          format: email
          description: Email address
          example: abc@gmail.com
      example:
        country: ph
        transfer_method: bank_transfer
        transfer_type: local
        currency: php
        holder_type: individual
        holder_name: Ben Yu
        bank_id: '10419995'
        account_number: '14098377'
        address:
          street: Pedro Gil, cor Adriatico St
          postcode: '1000'
          city: Manila

````