---
swagger: "2.0"
info:
  x-ibm-name: rakbank-digital-banking-transfers-api
  title: RAKBANK Digital Banking Transfers API
  version: 1.0.0
  description: "The Transfers API allows the client to perform the following operations
    on behalf of the customer:\n\n\t1. Validate a transfer request from the customer's
    account to a beneficiary and also fetch and display the following details to the
    customer on the pre confirmation screen :\n\tcharges, debit amount, total credit
    amount, authentication mode for the transaction & approvers list (whenever
    workflow is applicable for the transaction) \n\t2. Create a transfer to initiate
    a payment from a customer's account to his beneficiary. The Payment Reference
    Id will be returned in the response for a successful payment request initiation.
    \n\t3. Fetch the  details and the status of the transaction.\n\nThis API requires
    beneficiary_id of the customer's beneficiary to be passed in the request
    which can be fetched using the Beneficiaries API."
  contact:
    name: API Developer
    email: apideveloper@rakbank.ae
  name: ""
schemes:
- https
host: sandboxapi.rakbank.ae
basePath: /v1/tpa
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  oauth:
    type: oauth2
    description: ""
    flow: accessCode
    scopes:
      transfers: For creating a payment request and to retrieve details of the payment
        request
    tokenUrl: https://sandboxapi.rakbank.ae/rb/api/v1/customer_signin/oauth2/token
    authorizationUrl: https://sandboxapi.rakbank.ae/rb/api/v1/customer_signin/oauth2/authorize
  clientIdHeader:
    type: apiKey
    in: header
    name: X-IBM-Client-Id
security:
- clientIdHeader: []
  oauth:
  - transfers
x-ibm-configuration:
  testable: true
  enforced: true
  phase: realized
paths:
  /transfers/validate:
    post:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/validate_response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/error_response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/error_response'
        422:
          description: Invalid Request
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      parameters:
      - name: transfers
        required: true
        in: body
        schema:
          $ref: '#/definitions/transfers'
        description: Request details to create a payment transaction.
      - $ref: '#/parameters/MsgId'
      description: 'Validate a transfer request from a custome Account to a beneficiary
        to fetch and display the following details to the customer on the pre confirmation
        screen - charges, debit amount, total credit amount, authentication mode for
        the transaction & approvers list (whenever workflow is applicable for the
        transaction) '
      summary: Validate a Transfer Request
      operationId: ValidateTransferRequest
  /transfers/{transfer_id}:
    put:
      responses:
        201:
          description: 201 Created
          schema:
            $ref: '#/definitions/transfers'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/error_response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/error_response'
        422:
          description: Invalid Request
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      parameters:
      - name: transfers_request
        required: true
        in: body
        schema:
          $ref: '#/definitions/transfers_request'
        description: Request details to create a transfer.
      description: Create a transfer to initiate a payment from a customer's account
        to his beneficiary. The Payment Reference Id will be returned in the response
        for a successful payment request initiation.
      summary: Create a Transfer Request by Id
      operationId: CreateTransferById
    get:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/transfers'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/error_response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/error_response'
        422:
          description: Invalid Request
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      operationId: GetTransferById
      description: Get the transfer details and status by passing the transfer_id.
    parameters:
    - name: transfer_id
      type: integer
      minimum: 1
      maximum: 9999999999
      required: true
      in: path
      description: Unique ID for the transfer that is generated by the client. The
        transfer_id used to create/fetch the transfer.
    - $ref: '#/parameters/MsgId'
definitions:
  transfers:
    properties:
      href:
        type: string
        example: https://sandboxapi.rakbank.ae/rb/api/v1/tpa/transfers/123456789
        description: href value to fetch the resource with the specific id. Read-only
          field.
      transfer_id:
        type: integer
        minimum: 1
        maximum: 9999999999
        description: The client's unique id for the transfer. Read-only field.
        example: "123456789"
      payment_ref_id:
        type: integer
        minimum: 1
        maximum: 9999999999
        description: The bank's unique id for the transaction. Read-only field.
        example: "14091746"
      from:
        $ref: '#/definitions/from'
      to:
        $ref: '#/definitions/to'
      transaction_date:
        type: string
        description: Date when the transaction is submitted.
        example: "2017-09-14"
        format: date
      transaction_amount:
        $ref: '#/definitions/value'
        description: Transaction Amount and currency as entered by customer.
      debit_amount:
        $ref: '#/definitions/value'
        description: Total transaction amount in home currency (AED). Read-only field.
      remittance_currency:
        type: string
        minLength: 1
        maxLength: 3
        description: Remittance currency selected by customer.
        example: AED
      purpose_code:
        type: string
        minLength: 1
        maxLength: 20
        description: Code for the Purpose of the remittance selected by customer.
          Not be sent for WithinRAKBANK transfers. Mandatory for all other transfer
          types.
        example: FS
      remarks:
        type: array
        items:
          type: string
          minLength: 1
          maxLength: 33
        minItems: 1
        maxItems: 3
        description: Optional Transaction Remarks line1, line2 and line3.
        example:
        - line1
        - line2
        - line3
      charges_type:
        description: Customer selected charge indicator. Optional only for WithinRAKBANK
          transfers. O - All Charges to my Account B - All charges to Beneficiary's
          Account S - Local charges to Me and Outside UAE charges to Beneficiary.
        type: string
        enum:
        - O
        - B
        - S
      approver_id:
        type: string
        minLength: 1
        maxLength: 250
        description: User selected approver_id from the approvers list returned in
          Validate response. Mandatory when workflow_mode = ENT in Validate response.
        example: MACORP2
      transfer_status:
        description: Transfer status object. Read-only field.
        $ref: '#/definitions/transfer_status'
    additionalProperties: false
    required:
    - from
    - to
    - transaction_date
    - transaction_amount
    - remittance_currency
  error_response:
    properties:
      status:
        type: string
        description: HTTP Status
      response_code:
        type: string
        description: API specific error code
      property:
        type: string
      response_message:
        type: string
        description: brief type of the error
        example: ""
      description:
        type: string
        description: detailed description of the error
    additionalProperties: false
    required:
    - response_code
    - status
    - response_message
    description: Response in case of error
  to:
    properties:
      href:
        type: string
        example: https://sandboxapi.rakbank.ae/rb/api/v1/tpa/customers/Account_ID:1234xxxxxx423/beneficiaries/759400045
        description: href value to fetch the resource with a specific beneficiary_id
          for a registered beneficiary. Read-only field.
      beneficiary_id:
        type: integer
        maximum: 9999999999
        example: "759400045"
        description: Beneficiary id of a registered beneficiary.
      name:
        type: string
        minLength: 1
        maxLength: 80
        description: Name of the beneficiary. Read-only field.
        example: James Gordan
      nick_name:
        type: string
        minLength: 1
        maxLength: 80
        description: Nick Name of the beneficiary. Read-only field.
        example: James
      other_account_id:
        type: string
        minLength: 1
        maxLength: 34
        description: Account id or IBAN of the beneficiary. Read-only field.
        example: "963521478"
      other_account_currency:
        type: string
        minLength: 1
        maxLength: 3
        description: Currency of the beneficiary account. Mandatory for WithinRAKBANK
          beneficiaries.
        example: AED
      address:
        $ref: '#/definitions/address'
        description: Beneficiary Residence Address. Mandatory for OutsideUAE beneficiaries
          who’s resident country is not returned in Beneficiaries API.
    additionalProperties: false
    required:
    - beneficiary_id
    description: This will contain the details of the beneficiary.
  from:
    properties:
      account_id:
        type: string
        minLength: 1
        maxLength: 34
        description: 'Account id of the customer. Only MASKED value to be passed.
          Masking logic to be followed :  - First 4 and last 3 characters to be unmasked.
          All chracters in between to be masked by replacing with ''''x''''. e.g.
          1234xxxxxx567'
        example: 1234xxxxxx567
      account_currency:
        type: string
        minLength: 1
        maxLength: 3
        description: Currency of the customer account.
        example: AED
    additionalProperties: false
    required:
    - account_id
    - account_currency
    description: This will contain the details of the remitter
  value:
    properties:
      currency:
        type: string
        maxLength: 3
        description: Currency
        example: AED
      amount:
        type: string
        pattern: ^\d{0,18}.\d{0,3}$
        description: 'Amount Value. Number (18,3). [ Mantissa (18), Decimal Precision
          (3), excluding dot]. Example: 50.05 AED, 10.25, USD 3.099 BHD and 10 JPY'
        example: 50.050000
    additionalProperties: false
    required:
    - currency
    - amount
    description: Transaction amount details
  transfer_status:
    properties:
      status:
        type: string
        maxLength: 5
        description: Status of the transfer. Read-only field.
        example: SUC
    additionalProperties: false
    required:
    - status
  address:
    description: Beneficiary Residence Address
    properties:
      line_1:
        type: string
        minLength: 1
        maxLength: 100
        description: Address line 1 of the beneficiary
      line_2:
        type: string
        minLength: 1
        maxLength: 100
        description: Address line 2 of the beneficiary
      line_3:
        type: string
        minLength: 1
        maxLength: 100
        description: Address line 3 of the beneficiary
      city:
        type: string
        minLength: 1
        maxLength: 100
        description: City of the beneficiary
      state:
        type: string
        minLength: 1
        maxLength: 100
        description: State of the beneficiary
      district:
        type: string
        minLength: 1
        maxLength: 100
        description: District of the beneficiary
      country:
        type: string
        minLength: 1
        maxLength: 2
        description: Country of the beneficiary. ISO 2 Character Country Codes.
        example: IN
    additionalProperties: false
    required:
    - country
  transfers_request:
    properties:
      transfers:
        $ref: '#/definitions/transfers'
      transaction_authentication:
        $ref: '#/definitions/transaction_authentication'
    additionalProperties: false
    required:
    - transfers
  transaction_authentication:
    description: Mandatory when auth_mode is returned in Validate response
    properties:
      customer_hard_token:
        type: number
        description: Field to hold RAK token in case auth_mode in Validate response
          is STKN.
        example: 4324
      sms_otp:
        type: number
        description: Field to hold sms  otp in case auth_mode in Validate response
          is SOTP
        example: 242356
    additionalProperties: false
  validate_response:
    description: Validate response
    properties:
      transaction_date:
        type: string
        description: Date when the transaction is submitted.
        example: "2017-09-14"
        format: date
      transaction_amount:
        $ref: '#/definitions/value'
        description: Transaction Amount and currency as entered by customer.
      debit_amount:
        $ref: '#/definitions/value'
        description: Total transaction amount in home currency (AED).
      total_credit_amount:
        $ref: '#/definitions/value'
        description: Total credit amount in remittance currency.
      charges:
        $ref: '#/definitions/value'
        description: Total charges in home currency (AED).
      auth_mode:
        description: 'Field to hold the Authorization modes. If this tag is not present
          then there is no authorization code required for transaction submit.  Possible
          values are :  SOTP – SMS OTP  STKN – 2FA Token'
        type: string
        enum:
        - SOTP
        - STKN
      workflow_mode:
        description: Workflow mode.  AUT - When there is no workflow for the transactions
          ENT - When workflow present for the transaction
        type: string
        enum:
        - AUT
        - ENT
      approvers:
        type: array
        items:
          $ref: '#/definitions/approvers'
    additionalProperties: false
    required:
    - transaction_amount
    - debit_amount
    - total_credit_amount
    - transaction_date
  approvers:
    description: List of approvers to be displayed to the user when workflow_mode
      is returned as 'ENT' in Validate response
    properties:
      approver_id:
        type: string
        minLength: 0
        maxLength: 10
        description: Field to hold the approver id of the next elligble approver.
        example: MACORP2
      display_name:
        type: string
        minLength: 1
        maxLength: 80
        description: Display name of the approver in First Name Last Name
        example: FIRST NAME LAST NAME
      role_desc:
        type: string
        minLength: 1
        maxLength: 80
        description: Role description of the user returned in the Approver list
        example: approver
    additionalProperties: false
    required:
    - approver_id
    - display_name
    - role_desc
tags: []
parameters:
  MsgId:
    name: MsgId
    type: string
    maxLength: 50
    required: true
    in: header
    description: Unique Id sent by the client. Value should be a unique identifier
      of the transaction in UUID format
x-ibm-endpoints:
- endpointUrl: https://sandboxapi.rakbank.ae/sb/api
  type:
  - production
  - development
...