---
swagger: "2.0"
info:
  x-ibm-name: partner-beneficiary-management-api
  title: Partner Beneficiary Management API
  version: 2.2.0
  description: "This API is available to Partner Institutions to register RAKMoneyTransfer
    beneficiaries of their customers with the bank. To create a beneficiary, pass
    the details of the beneficiary like name, country of residence, beneficiary bank
    country, transfer type (OutsideUAE or RAKMoneyCashPayout), account/IBAN and the
    identifier codes of the beneficiary bank that were returned in RAKMoneyTransfer
    Beneficiary Banks API. \nOn successful creation, a beneficiary_id will be returned
    which can be used in Partner RAKMoneyTransfer API to make payments to the beneficiary,
    without having to pass all the details of the beneficiary again. The API can also
    be used to view and update existing beneficiaries and also to delete a beneficiary.\n\n\tVersion
    2.1.0\n\t\n  - Added new 422 response_code - 20006, in CreateTransactionById response\n\n\n\tVersion
    2.2.0\n\n  - Added Account_ID as a new customer_id_type to support Beneficiary
    creation for RAKBank account holding customers"
  contact:
    email: apideveloper@rakbank.ae
    name: API developer
  name: ""
schemes:
- https
host: sandboxapi.rakbank.ae
basePath: /v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  oauth:
    type: oauth2
    description: ""
    flow: application
    scopes:
      beneficiary_management: To Manage beneficiaries and to fetch beneficiary details
    tokenUrl: https://sandboxapi.rakbank.ae/sb/api/v1/partner_auth/token
  clientIdHeader:
    type: apiKey
    in: header
    name: X-IBM-Client-Id
security:
- clientIdHeader: []
  oauth:
  - beneficiary_management
x-ibm-configuration:
  testable: true
  enforced: true
  phase: specified
paths:
  /customers/{customer_id_type}:{customer_id}/beneficiaries:
    post:
      responses:
        201:
          description: Created
          schema:
            $ref: '#/definitions/beneficiaries'
        422:
          description: Error Response
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      parameters:
      - name: beneficiary_req
        required: true
        in: body
        schema:
          $ref: '#/definitions/beneficiaries'
        description: Details to create a beneficiary
      description: Creates beneficiary for a particular customer based on customer_id
        and returns the beneficiary_id
      operationId: CreateBeneficiary
      summary: Create a Beneficiary of a customer
    get:
      responses:
        200:
          description: 200 OK
          schema:
            type: array
            items:
              $ref: '#/definitions/beneficiaries'
        422:
          description: Error Response
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      summary: Get Beneficiaries of a customer
      operationId: GetBeneficiaries
      description: This API will return the list of beneficiaries associated with
        a customer_id.
    parameters:
    - name: MsgId
      maxLength: 50
      type: string
      required: true
      in: header
      description: Unique Id sent by the client. Value should be a unique identifier
        of the transaction in UUID format
    - name: customer_id
      type: string
      maxLength: 20
      required: true
      in: path
      description: Customer Id of the customer who wants to create a new beneficiary.
        Masked value should be passed in the UAT and Production environments. For
        information on the masking logic to be followed, see <a href=/sb/api/security#masking-logic>Masking
        Logic</a>
    - name: customer_id_type
      type: string
      enum:
      - Emirates_ID
      - Account_ID
      required: true
      in: path
      description: 'Type of the Customer Id of the customer who wants to update his
        beneficiary details. Allowed values: Emirates_ID - for a prepaid card customer,
        Account_ID - for a RAKBank account customer'
  /customers/{customer_id_type}:{customer_id}/beneficiaries/{beneficiary_id}:
    put:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/beneficiaries'
        422:
          description: Error Response
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      parameters:
      - name: beneficiary_req
        required: true
        in: body
        schema:
          $ref: '#/definitions/beneficiaries'
        description: Beneficiary details to be updated
      description: Updates the beneficiary details of a customer with customer_id
        based on beneficiary_id
      operationId: UpdateBeneficiaryById
      summary: Update Beneficiary of a customer
    delete:
      responses:
        204:
          description: No Content
        422:
          description: Error
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      description: Deletes the beneficiary of a customer by specifying the beneficiary_id
      operationId: DeleteBeneficiaryById
      summary: Delete Beneficiary
    get:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/beneficiaries'
        422:
          description: Error Response
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      operationId: GetBeneficiaryById
      tags: []
      description: Retrieves the beneficiary details of a customer with customer_id
        and beneficiary_id
    parameters:
    - name: customer_id
      type: string
      maxLength: 20
      required: true
      in: path
      description: Customer Id of the customer who wants to fetch/update/delete his
        beneficiary. Masked value should be passed in the UAT and Production environments.
        For information on the masking logic to be followed, see <a href=/sb/api/security#masking-logic>Masking
        Logic</a>
    - name: customer_id_type
      type: string
      enum:
      - Emirates_ID
      - Account_ID
      required: true
      in: path
      description: 'Type of the Customer Id of the customer who wants to fetch/update/delete
        his beneficiary. Allowed values: Emirates_ID - for a prepaid card customer,
        Account_ID - for a RAKBank account customer'
    - name: beneficiary_id
      type: string
      maxLength: 50
      required: true
      in: path
      description: Beneficiary id of the beneficiary to be fetched/updated/deleted
    - name: MsgId
      type: string
      maxLength: 50
      required: true
      in: header
      description: Message id sent from client. Value should be a unique identifier
        of the request in UUID format.
definitions:
  error_response:
    properties:
      status:
        type: string
        description: HTTP Status
      response_code:
        type: string
        description: API specific error code
      property:
        type: string
        description: ""
      response_message:
        type: string
        description: breif details of the error
      description:
        type: string
        description: detailed description of the error
    additionalProperties: false
    required:
    - response_message
    - response_code
    - status
    description: Response in case of error
  beneficiaries:
    description: beneficiary object
    type: object
    properties:
      href:
        type: string
        description: Read only field. href value to fetch the resource with the specific
          beneficiary_id.
        example: https://sandboxapi.rakbank.ae/sb/api/v2/customers/Emirates_ID:123456789012345/beneficiaries/52347890
      beneficiary_id:
        type: string
        minLength: 0
        maxLength: 15
        description: Read only field. Id of the beneficiary.
        example: 52347890
      first_name:
        type: string
        minLength: 1
        maxLength: 50
        description: First Name of the beneficiary
        example: James
      last_name:
        type: string
        minLength: 1
        maxLength: 50
        description: Last Name of the beneficiary
        example: Gordan
      transfer_type:
        type: string
        enum:
        - OutsideUAE
        - RAKMoneyCashPayout
        description: 'Type of the beneficiary. Allowed values: OutsideUAE - beneficiary
          account is outside UAE, RAKMoneyCashPayout - RAKMoney Cash payout beneficiary'
        example: OutsideUAE
      address:
        $ref: '#/definitions/address'
        description: Residence address of the beneficiary.
      documents:
        description: Documents. Field added for future use.
        type: array
        items:
          $ref: '#/definitions/documents'
      other_bank_name:
        type: string
        minLength: 1
        maxLength: 100
        description: Read only field. Bank Name  of the beneficiary bank.
        example: ICICI
      other_branch_name:
        type: string
        minLength: 1
        maxLength: 100
        description: Read only field. Branch name of the beneficiary name.
        example: VADODARA - KARELIBAUG
      other_bank_country:
        type: string
        minLength: 1
        maxLength: 2
        description: ISO 2 character country code of the beneficiary bank or RAKMoney
          Cash Payout country.
        example: IN
      identifier_code1:
        type: string
        minLength: 1
        maxLength: 30
        description: Identifier code1 of the beneficiary bank that was returned in
          RAKMoneyTransfer Beneficiary Banks API, for the beneficiary bank selected
          by the customer. Mandatory when transfer_type selected is OutsideUAE.
        example: ICIC0000248
      identifier_code1_name:
        type: string
        minLength: 1
        maxLength: 100
        description: Read only field. Name of the Routing scheme associated with identifier_code1.
        example: IFSC
      identifier_code2:
        type: string
        minLength: 1
        maxLength: 30
        description: Identifier code2 of the beneficiary bank that were returned in
          RAKMoneyTransfer Beneficiary Banks API. Must be passed for transfer_type=OutsideUAE,
          when returned in RAKMoneyTransfer Beneficiary Banks API for the bank selected
          by the customer.
        example: ICICI4354
      identifier_code2_name:
        type: string
        minLength: 1
        maxLength: 100
        description: Read only field. Name of the Routing scheme associated with identifier_code2.
        example: Branch Code
      other_account_id:
        type: string
        minLength: 1
        maxLength: 50
        description: Account id of the beneficiary. Can hold IBAN No if other_bank_country
          is PK (Pakistan).This field is mandatory when transfer_type= OutsideUAE.
        example: "963521478"
    example:
      first_name: James
      last_name: Gordan
      transfer_type: OutsideUAE
      address:
        country: IN
      other_bank_country: IN
      identifier_code1: ICIC0000248
      other_account_id: "963521478"
    additionalProperties: false
    required:
    - first_name
    - last_name
    - other_bank_country
    - transfer_type
  documents:
    properties:
      type:
        type: string
        minLength: 1
        maxLength: 30
        example: Passport
        description: Type of the document
      number:
        type: string
        minLength: 1
        maxLength: 30
        description: Number of the document
        example: IGT32434
    additionalProperties: false
    required:
    - number
    - type
    description: documents
  address:
    properties:
      line_1:
        type: string
        minLength: 1
        maxLength: 100
        description: Address line 1 of the beneficiary. Field added for future use.
        example: Line 1
      line_2:
        type: string
        minLength: 1
        maxLength: 100
        description: Address line 2 of the beneficiary. Field added for future use.
        example: Line 2
      line_3:
        type: string
        minLength: 1
        maxLength: 100
        description: Address line 3 of the beneficiary. Field added for future use.
        example: Line 3
      city:
        type: string
        minLength: 1
        maxLength: 100
        description: City of the beneficiary. Field added for future use.
        example: Mumbai
      state:
        type: string
        minLength: 1
        maxLength: 100
        description: State of the beneficiary. Field added for future use.
        example: Maharashtra
      district:
        type: string
        minLength: 1
        maxLength: 100
        description: District of the beneficiary. Field added for future use.
        example: Mumbai
      country:
        type: string
        minLength: 1
        maxLength: 2
        description: Country of the residence of the beneficiary. ISO 2 Character
          Country Code.
        example: IN
    additionalProperties: false
    required:
    - country
tags: []
x-ibm-endpoints:
- endpointUrl: https://sandboxapi.rakbank.ae/sb/api
  type:
  - production
  - development
...