---
swagger: "2.0"
info:
  x-ibm-name: partner-external-bank-transfers-api
  title: Partner External Bank Transfers API
  version: 1.1.1
  description: "This API is available to Partner Institutions to provide external
    bank transfers including IPI, UAEFTS and SWIFT to their customers. Partner can
    initiate an ad-hoc transfer from their customer's account to an external
    bank account i.e. a non-RAKBANK account, by passing all details of the beneficiary
    in the request. The API does not require the beneficiary to be pre-registered.
    The Payment Reference Id will be returned in the response for a successful payment
    request initiation. \nThe API should be invoked only before the daily cutoff time.
    Any transfers requests initiated by the customer on the partner App/ Web application
    after the cut-off time must be held at the client's side and posted at BOD
    (Beginning Of Day) the next business day. There are also daily transaction limits
    applicable for the API which needs to be enforced by the client on their App/
    Web application. For information on applicable currency-wise cutoff & BOD
    times and daily transaction limits, see <a href="/faq-page/#external-transfers">FAQ</a>.\n\nThe
    API also allows to fetch the status of the previously created transaction.\n\n\tVersion
    1.1.0\n\t\n  - Added mandatory field customer_category and optional fields intermediary_bank_BIC,
    intermediary_bank_name & remarks in the request.\n  - Allowing retry based
    on same transaction_id. In case of timeout or 500 errors, you may retry upto 3
    times with an interval of 60 seconds between every retry. Please ensure to pass
    the same transaction_id in the path for retry requests. If the previous transaction
    with the same transaction_id was posted successfully, then the previous response
    would be echoed for the retries. If the previous transaction was unsuccessful,
    then the system will try to reprocess the transaction.\n\n\t\t\n<h3>OAuth
    Metadata details</h3>\nOAuth metadata parameter to be passed at the time
    of generating access token using <a href="/partner-authentication">Partner
    Authentication API</a> for client credential grant type is mentioned below.
    For information on OAuth Metadata, see <a href="/security/#oauth-metadata-partnerauth">About
    the OAuth Metadata</a>\n<p class="oauth_metadata">oauth_metadata.account_id
    : {account_id}</p>"
  contact:
    name: API Developer
    email: apideveloper@rakbank.ae
  name: ""
schemes:
- https
host: sandboxapi.rakbank.ae
basePath: /v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  oauth:
    type: oauth2
    description: ""
    flow: application
    scopes:
      external_transfers: For creating a payment to an external account i.e. a non-RAKBank
        account and to retrieve status of the payment request
    tokenUrl: https://sandboxapi.rakbank.ae/sb/api/v1/partner_auth/token
  clientIdHeader:
    type: apiKey
    in: header
    name: X-IBM-Client-Id
security:
- clientIdHeader: []
  oauth:
  - external_transfers
x-ibm-configuration:
  testable: true
  enforced: true
  phase: realized
paths:
  /external_transfers/{transaction_id}:
    put:
      responses:
        201:
          description: 201 Created
          schema:
            $ref: '#/definitions/external_transfers_response'
        422:
          description: Error
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      parameters:
      - name: external_transfers
        required: true
        in: body
        schema:
          $ref: '#/definitions/external_transfers'
        description: Request details to create a payment transaction.
      description: Creates a transaction to initiate payment from a RAKBANK account
        to an external bank account by providing details of the beneficiary. A payment
        request is created and a payment ref Id and charges are returned in the response.
      summary: Create Transaction Request
      operationId: CreateTransactionById
    parameters:
    - $ref: '#/parameters/MsgId'
    - $ref: '#/parameters/transaction_id'
  /external_transfers/{transaction_id}/transaction_status:
    get:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/transaction_status'
        422:
          description: Error
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Sever Error
          schema:
            $ref: '#/definitions/error_response'
      operationId: GetTransactionStatus
      description: Get Transaction status by passing the transaction_id.
    parameters:
    - $ref: '#/parameters/MsgId'
    - $ref: '#/parameters/transaction_id'
definitions:
  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:
      name:
        type: string
        minLength: 1
        maxLength: 64
        description: Name of the beneficiary.
        example: Gordan
      other_account_id:
        type: string
        minLength: 1
        maxLength: 50
        description: Account id of the beneficiary. Will hold IBAN when other_bank_country=AE.
        example: "963521478"
      other_account_currency:
        type: string
        minLength: 1
        maxLength: 3
        description: Currency of the beneficiary account. Same as Remitting curreny.
        example: AED
      other_bank_name:
        type: string
        minLength: 1
        maxLength: 35
        description: Bank Name of the beneficiary bank.
        example: ICICI
      other_bank_BIC:
        type: string
        minLength: 1
        maxLength: 12
        description: BIC code of the beneficiary bank. Mandatory in the request for
          within UAE AED transactions, i.e. when other_bank_country=AE and other_account_currency=AED.
          For all other types of transactions, must be passed if beneficiary bank
          BIC was provided by the customer.
        example: ADCBAEAAXXX
      other_branch_name:
        type: string
        minLength: 1
        maxLength: 35
        description: Branch Name of the beneficiary bank. Mandatory in the request
          when other_bank_country is not AE. Default value '001' to be sent in the
          request when other_bank_country=AE and other_account_currency is not AED.
          Not required when other_bank_country=AE and other_account_currency=AED.
        example: PB-POTHUHERA.
      other_branch_addr1:
        type: string
        minLength: 1
        maxLength: 100
        description: Address of the beneficiary bank.
        example: 15th Main,
      other_branch_addr2:
        type: string
        minLength: 1
        maxLength: 32
        description: City of the beneficiary bank. Mandatory in the request when other_bank_country
          is not AE. Default value 'AE' to be sent in the request when other_bank_country=AE
          and other_account_currency is not AED. Not required when other_bank_country=AE
          and other_account_currency=AED.
        example: Colombo
      other_bank_country:
        type: string
        minLength: 1
        maxLength: 2
        description: ISO 2 character country code of the beneficiary bank.
      address:
        $ref: '#/definitions/address'
        description: Address of residence or incorporation of the beneficiary.
      intermediary_bank_name:
        type: string
        minLength: 1
        maxLength: 35
        description: Intermediary Bank Name.
        example: AXIS Bank
      intermediary_bank_BIC:
        type: string
        minLength: 1
        maxLength: 12
        description: Intermediary Bank BIC.
        example: AXISINBB
    additionalProperties: false
    required:
    - name
    - other_account_id
    - other_account_currency
    - other_bank_name
    - other_bank_country
    - address
    description: This will contain the details of the external account.
  from:
    properties:
      customer_id_type:
        type: string
        enum:
        - Account_ID
        description: Type of the Customer id of the customer who initiates the transaction.
          Allowed values - Account_ID
        example: Account_ID
      customer_id:
        type: string
        minLength: 1
        maxLength: 20
        example: 1234xxxxxx567
        description: Customer id of the customer, corresponding to the customer_id_type,
          who initiates the transaction. Masked value should be passed in the UAT
          and Production environments. For information on the masking logic to be
          followed, see <a href="/security/#masking-logic">Masking Logic</a>
    additionalProperties: false
    required:
    - customer_id
    - customer_id_type
    description: This will contain the details of the remitter
  value:
    properties:
      currency:
        type: string
        minLength: 1
        maxLength: 3
        description: Currency
        example: AED
      amount:
        type: string
        pattern: ^((\d{1}|\d{2}|\d{3}|\d{4}|\d{5}|\d{6}|\d{7}|\d{8}|\d{9}|\d{10}|\d{11}|\d{12}|\d{13}|\d{14}|\d{15}|\d{16})?\.?(\d{1}|\d{2}|\d{3})?)$
        minLength: 1
        maxLength: 20
        description: Amount Value
        example: 2001
    additionalProperties: false
    required:
    - currency
    - amount
    description: Transaction amount details
  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 residence or incorporation of the Beneficiary. ISO
          2 Character Country Code.
    additionalProperties: false
    required:
    - country
  external_transfers:
    properties:
      from:
        $ref: '#/definitions/from'
      to:
        $ref: '#/definitions/to'
      value:
        $ref: '#/definitions/value'
      purpose_code:
        type: string
        minLength: 1
        maxLength: 40
        description: code for the Purpose of the remittance. Should be one of the
          values provided in the Master data.
        example: "8"
      rate:
        type: string
        description: Fx Rate that will apply for the transfer. This should be the
          rate returned in Forex Rate & Charges API. However, this will only be an
          indicative rate. The actual rate applied for the transaction may differ
          in the scenario where the rate in the system has changed at the time of
          processing of the transaction, i.e. after the transaction has cleared AML
          screening.
        example: "2.957223"
      rate_code:
        type: string
        minLength: 1
        maxLength: 5
        description: Fx Rate Code that will apply for the transfer. This should be
          the rate_code returned in Fx Rate & Charges API.
        example: TTS
      charges_type:
        type: string
        enum:
        - BEN
        - SHA
        - OUR
        description: 'Charge Type selected by the customer. Valid options: BEN - All
          charges to Beneficiary, SHA - Share the charges, OUR - All charges to be
          charged to the customer.'
        example: BEN
      is_CBWSI_payment:
        type: string
        enum:
        - "Y"
        - "N"
        description: 'Flag to identify if customer has selected Immediate Payment
          option for WithinUAE transactions. Valid options: Y - Immediate Payment,
          N - UAEFTS/SWIFT Payment. Applicable for payments up to AED 10,000 initiated
          by individual customers, when payments are made to eligible banks only and
          when Remitting Currency is AED, i.e. other_account_currency=AED, and with
          an eligible Purpose code. For information on eligible banks and eligilble
          purpose codes, see <a href="/faq-page/#external-transfers">FAQ</a>. If not
          passed, transaction will be routed through UAEFTS. '
      remarks:
        type: array
        items:
          type: string
          minLength: 1
          maxLength: 32
        minItems: 1
        maxItems: 3
        description: Optional Transaction Remarks line1, line2 and line3.
        example:
        - line1
        - line2
        - line3
      customer_category:
        type: string
        enum:
        - Individual
        - Business
        description: 'Category of the customer initiating the transfer. Valid options:
          Individual - for Individual customers, Business - for business customers.'
        example: Individual
    additionalProperties: false
    required:
    - from
    - to
    - value
    - purpose_code
    - charges_type
    - customer_category
  external_transfers_response:
    description: Response object
    properties:
      transaction_id:
        type: string
        maxLength: 20
        description: The client's unique id for the transaction.
        example: "58215225"
      payment_ref_id:
        type: string
        maxLength: 25
        description: The bank's unique id for the transaction.
        example: "14091746202"
      end_date:
        type: string
        description: Date when the transaction is executed.
        example: "2017-09-14"
        format: date
      total_debit_amount:
        type: string
        minLength: 0
        maxLength: 20
        description: Total amount that will be debited for this transaction, including
          charges.
        example: "2020.00"
      debit_currency_code:
        type: string
        minLength: 1
        maxLength: 3
        description: Currency code of the total_debit_amount.
        example: AED
      transaction_status:
        description: Transaction status object.
        $ref: '#/definitions/transaction_status'
    additionalProperties: false
    required:
    - transaction_id
    - payment_ref_id
    - end_date
    - total_debit_amount
    - debit_currency_code
  transaction_status:
    description: Transaction status object. The PUT method will only return the href
      to the associated transaction_status resource.
    properties:
      status:
        type: string
        maxLength: 5
        description: Status of the transaction. This is only returned in the response
          of GetTransactionStatus operation. |  - S = (Success) indicates the reciept
          of ACK from SWIFT/UAEFTS server,  - F = (Failure) indicates the reciept
          of NACK from SWIFT/UAEFTS server,  - P = (Processing) indicates any other
          status (Eg. Ready, Awaiting Authorization, etc…) from SWIFT/UAEFTS server
        example: S
      status_desc:
        type: string
        maxLength: 254
        description: Description of the transaction status. This is only returned
          in the response of GetTransactionStatus operation.
        example: Success
      href:
        type: string
        example: https://testapi.rakbank.ae/rb/api/v1/external_transfers/1232144/transaction_status
        description: href value to fetch the transaction status of a specific transaction_id.
    additionalProperties: false
tags: []
parameters:
  transaction_id:
    name: transaction_id
    type: string
    maxLength: 20
    required: true
    in: path
    description: Unique transaction ID that is generated by the client. The transaction_id
      used to create the payment transaction. This must not repeat atleast for a period
      of six months. Please ensure to pass the same transaction_id in the path for
      retry requests.
  MsgId:
    name: MsgId
    type: string
    maxLength: 50
    required: true
    in: header
    description: Unique Id sent by client. Value should be a unique identifier of
      the request in UUID format.
x-ibm-endpoints:
- endpointUrl: https://sandboxapi.rakbank.ae/sb/api
  type:
  - production
  - development
...