# Beneficiary Add

> Create a beneficiary that can be used in later Transfer payouts.

```yaml
openapi: 3.1.0
info:
  title: Beneficiary Add
  version: 1.0.0
  description: Create a beneficiary that can be used in later Transfer payouts.
paths:
  /api/v1/beneficiary/add:
    post:
      summary: Beneficiary Add
      description: Create a beneficiary that can be used in later Transfer payouts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantNo:
                  type: string
                  description: Merchant number assigned by Onerway. Retrieve it from the merchant
                    portal or onboarding material after your sandbox or
                    production account is created.
                merchantRefId:
                  type: string
                  description: Merchant-side user or beneficiary reference ID used for mapping,
                    search, or internal reconciliation.
                bankCountry:
                  type: string
                  description: Destination country of the beneficiary.
                payoutCurrency:
                  type: string
                  description: Payout currency used by the beneficiary.
                entityType:
                  type: string
                  description: Beneficiary entity type. `0` for business and `1` for individual.
                paymentMethod:
                  type: string
                  description: Payout method used for this beneficiary. It must match the country,
                    currency, and entity type selected for the beneficiary.
                receiverInfo:
                  type: string
                  description: Beneficiary identity information encoded as a JSON string. Include
                    every identity field required by the selected payout method.
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      companyName:
                        type: string
                        description: companyName field.
                      lastName:
                        type: string
                        description: lastName field.
                      firstName:
                        type: string
                        description: firstName field.
                      areaCode:
                        type: string
                        description: areaCode field.
                      phone:
                        type: string
                        description: phone field.
                      birthDate:
                        type: string
                        description: birthDate field.
                      email:
                        type: string
                        description: email field.
                      identityType:
                        type: string
                        description: identityType field.
                      identityNumber:
                        type: string
                        description: identityNumber field.
                      vatNumber:
                        type: string
                        description: vatNumber field.
                  x-onerway-format: json_string
                address:
                  type: string
                  description: Beneficiary address information encoded as a JSON string, including
                    country, state, city, and address lines when required.
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      countryCode:
                        type: string
                        description: countryCode field.
                      state:
                        type: string
                        description: state field.
                      city:
                        type: string
                        description: city field.
                      townName:
                        type: string
                        description: townName field.
                      addressLine1:
                        type: string
                        description: addressLine1 field.
                      addressLine2:
                        type: string
                        description: addressLine2 field.
                      addressLine3:
                        type: string
                        description: addressLine3 field.
                      postalCode:
                        type: string
                        description: postalCode field.
                  x-onerway-format: json_string
                accountInfomation:
                  type: string
                  description: Beneficiary account information encoded as a JSON string. Include
                    the account fields required by the selected payout method.
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      cardNumber:
                        type: string
                        description: cardNumber field.
                      accountType:
                        type: string
                        description: accountType field.
                      swiftCode:
                        type: string
                        description: swiftCode field.
                      bankName:
                        type: string
                        description: bankName field.
                      sortCode:
                        type: string
                        description: sortCode field.
                      branchCode:
                        type: string
                        description: branchCode field.
                      bankHolderName:
                        type: string
                        description: bankHolderName field.
                      bankAccount:
                        type: string
                        description: bankAccount field.
                      walletType:
                        type: string
                        description: walletType field.
                      walletPhone:
                        type: string
                        description: walletPhone field.
                      pickUpBankName:
                        type: string
                        description: pickUpBankName field.
                      pickUpBankBranchName:
                        type: string
                        description: pickUpBankBranchName field.
                      pickUpBankBranchId:
                        type: string
                        description: pickUpBankBranchId field.
                      pickUpBankBranchAddress:
                        type: string
                        description: pickUpBankBranchAddress field.
                  x-onerway-format: json_string
                sign:
                  type: string
                  description: Request signature string. Generate it according to the Transfer
                    request-signing rules with your merchant private key.
              required:
                - merchantNo
                - bankCountry
                - payoutCurrency
                - entityType
                - paymentMethod
                - receiverInfo
                - address
                - accountInfomation
                - sign
            examples:
              create-ewallet-beneficiary:
                summary: Create an e-wallet beneficiary
                value:
                  accountInfomation: '{"walletType":"EASYPAISA","walletPhone":"03001234567"}'
                  address: '{"countryCode":"PK","state":"Punjab","city":"Lahore","addressLine1":"12
                    Demo Street","postalCode":"54000"}'
                  bankCountry: PK
                  entityType: "1"
                  merchantNo: "801129"
                  merchantRefId: bene_demo_001
                  paymentMethod: E_WALLET
                  payoutCurrency: PKR
                  receiverInfo: '{"firstName":"Beta","lastName":"Tester","areaCode":"+92","phone":"3001234567","email":"beneficiary@example.com","identityType":"NID","identityNumber":"3520212345671"}'
                  sign: "{{SIGN}}"
      responses:
        "200":
          description: Beneficiary created
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: Response code returned by Onerway.
                  respMsg:
                    type:
                      - string
                      - "null"
                    description: Response message returned by Onerway.
                    x-onerway-value:
                      nullable: true
                      when:
                        en: No response message is returned.
                        zh: 未返回响应信息时为 `null`。
                  data:
                    type: object
                    properties:
                      beneficiaryId:
                        type: string
                        description: Beneficiary ID returned after successful creation.
                      payeeStatus:
                        type: string
                        description: Initial beneficiary review status. Use it to determine whether the
                          beneficiary can be used immediately or still requires
                          review or updates.
                    description: Created beneficiary result.
              examples:
                beneficiary-created:
                  summary: Beneficiary created
                  value:
                    respCode: "20000"
                    respMsg: null
                    data:
                      beneficiaryId: "1984102812163112960"
                      payeeStatus: unnecessary
```