---
swagger: "2.0"
info:
  x-ibm-name: forex-rate-and-charges-api
  title: Forex Rate and Charges API
  version: 2.1.2
  description: "This is a utilitarian API that allows to fetch forex rate and charges
    for a RAKMoneyTransfer or Electronic Funds Transfer (SWIFT) transaction. When
    only forex rate is required pass the charges flag as "false".\n\n\n\tVersion
    2.1.0\n\n  - Fxrate has been enhanced to allow clients to fetch rate and charges
    for BankTransfer type of transactions\n        \n\n     Version 2.1.1\n\n  - purpose_desc
    field has been removed since it is not required.\n\n\n\tVersion 2.1.2\n\n  - Added
    a field to.other_account_currency which needs to be always passed when  transaction_type
    is BankTransfer"
  contact:
    name: API Developer
    email: apideveloper@rakbank.ae
  name: ""
schemes:
- https
host: sandboxapi.rakbank.ae
basePath: /v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  oauth:
    type: oauth2
    description: ""
    flow: application
    scopes:
      utility_fxrate: To retrieve fxrate and  transaction charges
    tokenUrl: https://sandboxapi.rakbank.ae/sb/api/v1/partner_auth/token
  clientId:
    type: apiKey
    in: header
    name: X-IBM-Client-Id
security:
- clientId: []
  oauth:
  - utility_fxrate
x-ibm-configuration:
  testable: true
  enforced: true
  phase: realized
paths:
  /fx_rates/query:
    post:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/fxrate_query_response'
        422:
          description: Error Response
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      parameters:
      - name: MsgId
        type: string
        maxLength: 50
        required: true
        in: header
        description: Unique Id sent from client. Value should be a unique identifier
          of the request in UUID format.
      - name: fxrate_query_request
        required: true
        in: body
        schema:
          $ref: '#/definitions/fxrate_query_request'
        description: Request details to fetch fxrate and charges
      operationId: GetFxRate
      description: Retrieve fx rate values and transaction charges for a specific
        country code, transaction_type and transfer_type
tags: []
definitions:
  error_response:
    properties:
      status:
        type: string
        description: HTTP Status
        example: "422"
      response_code:
        type: string
        description: API specific error code
        example: "20006"
      property:
        type: string
      response_message:
        type: string
        description: type of the error
        example: business exception
      description:
        type: string
        description: detailed description of the error
        example: beneficiary_id not found
    additionalProperties: false
    required:
    - response_message
    - response_code
    - status
    description: Error Response details
  charges:
    additionalProperties: false
    properties:
      currency:
        type: string
        minLength: 1
        maxLength: 3
        description: Currency code of the charges.
        example: AED
      amount:
        type: string
        minLength: 1
        maxLength: 20
        description: Charge Amount.
        example: "50.00"
      tax:
        type: string
        minLength: 0
        maxLength: 20
        description: Tax levied for the transaction.
        example: "15.00"
      discount:
        type: string
        minLength: 0
        maxLength: 20
        description: Discount on the charges.
      total:
        type: string
        minLength: 1
        maxLength: 20
        description: Total charges applied for the transaction.
    required:
    - currency
    - amount
    - total
    description: Details of the transaction charges
  fx_rates:
    properties:
      rate:
        type: string
        pattern: ^\d{20}.\d{10}$
        description: 'Exchange rate. Rate format: 1 unit of "to_currency_code" = "rate"
          units of AED'
        example: "0.053539"
      rate_code:
        type: string
        minLength: 1
        maxLength: 5
        description: Exchange rate code.
        example: TTS
      currency:
        type: string
        example: INR
        description: Converted Amount currency.
      converted_amount:
        description: Converted Amount value. Converted Amount in "from_currency_code"
          when "value.currency" = "to_currency_code" OR Converted Amount in "to_currency_code"
          when "value.currency" = "from_currency_code".
        type: string
        example: "112067.84"
    additionalProperties: false
    required:
    - converted_amount
    - currency
    - rate
    description: Details of the transaction rate
  fxrate_query_response:
    properties:
      from_currency_code:
        type: string
        minLength: 1
        maxLength: 3
        example: AED
        description: Currency code of the debit account.
      to_currency_code:
        type: string
        minLength: 1
        maxLength: 3
        example: INR
        description: Currency code of the credit account.
      value:
        $ref: '#/definitions/value'
      date:
        type: string
        minLength: 1
        example: ""
        description: Current datetime.
        format: date-time
      fx_rates:
        type: array
        items:
          $ref: '#/definitions/fx_rates'
      charges:
        $ref: '#/definitions/charges'
      total_credit_amount:
        type: string
        minLength: 0
        maxLength: 20
        description: Total credit amount.
        example: "50000.00"
      total_debit_amount:
        type: string
        minLength: 0
        maxLength: 20
        description: Total debit amount.
        example: "2020.00"
      per_transaction_limit:
        type: string
        minLength: 0
        maxLength: 20
        description: Per transaction limit in 'to' currency. Provided when beneficiary_id
          is provided in the request.
        example: "40000"
      limit_exceeded_indicator:
        type: boolean
        description: Returns "true" if requested amount exceeds the per transaction
          limit. Provided when beneficiary_id is provided in the request.
    additionalProperties: false
    required:
    - from_currency_code
    - to_currency_code
    - value
    - total_credit_amount
    - fx_rates
    - date
    description: This defines the details of the rate and charges that would be applicable
      for a remittance transaction.
  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. Only Decimal(16,3) values allowed.
        example: "2001"
    additionalProperties: false
    required:
    - currency
    - amount
    description: This contains the transaction amount details
  fxrate_query_request:
    properties:
      from_currency_code:
        type: string
        minLength: 1
        maxLength: 3
        description: Debit curency code.
        example: AED
      to_currency_code:
        type: string
        minLength: 1
        maxLength: 3
        description: Credit currency code.
        example: INR
      value:
        $ref: '#/definitions/value'
      charges:
        type: boolean
        description: 'Indicates whether to fetch the transaction charges. Possible
          values: true or false'
        example: true
      other_bank_country:
        example: IN
        type: string
        minLength: 1
        maxLength: 2
        description: ISO 2 character country code of the other bank. Mandatory in
          the request for transaction_type=RAKMoney. Not required for transaction_type=BankTranfer.
      transaction_type:
        type: string
        enum:
        - RAKMoney
        - BankTransfer
        description: Type of the Transaction. Select 'RAKMoney' - in case of RAK Money
          Transfer and 'BankTranfer' in case of SWIFT or UAEFTS transfers.
        example: RAKMoney
      transfer_type:
        type: string
        enum:
        - OutsideUAE
        - RAKMoneyCashPayout
        description: Type of the beneficiary. Allowed values are 'OutsideUAE' - beneficiary
          account is outside UAE, 'RAKMoneyCashPayout' - RAKMoney Cash payout beneficiary.
          Mandatory in the request for transaction_type=RAKMoney. Not required for
          transaction_type=BankTranfer.
        example: OutsideUAE
      beneficiary_id:
        type: string
        minLength: 1
        maxLength: 15
        description: Id of the beneficiary to be passed when exact charges are required
          for RAKMoneyTransfer remittances i.e. when transaction_type=RAKMoney. Will
          be ignored if 'charges' is set to false. Not required for transaction_type=BankTranfer.
      from:
        $ref: '#/definitions/from'
        description: This will contain the details of the remitter. Mandatory in the
          request when charges are required for SWIFT/UAEFTS remittances i.e. when
          transaction_type=BankTranfer. Not required for transaction_type=RAKMoney.
      to:
        $ref: '#/definitions/to'
        description: This will contain the details of the beneficiary. Mandatory in
          the request when charges are required for SWIFT/UAEFTS remittances i.e.
          when transaction_type=BankTranfer. Not required for transaction_type=RAKMoney.
      purpose_code:
        type: string
        minLength: 1
        maxLength: 20
        description: Code for the Purpose of the remittance. Must be passed when charges
          are required for SWIFT/UAEFTS remittances i.e. when transaction_type=BankTranfer.
          Not required for transaction_type=RAKMoney.
        example: "8"
      charges_type:
        type: string
        enum:
        - BEN
        - SHA
        - OUR
        description: Charge Type selected by the customer. Valid options are BEN -
          All charges to Beneficiary, SHA - Share the charges, OUR - All charges to
          be charged to the customer. Mandatory in the request when charges are required
          for SWIFT/UAEFTS remittances i.e. when transaction_type=BankTranfer. Not
          required for transaction_type=RAKMoney.
        example: BEN
    additionalProperties: false
    description: This definition contains the parameters used to fetch the forex rate
      and charges for remittance transactions.
    required:
    - from_currency_code
    - to_currency_code
    - value
    - charges
    - transaction_type
  to:
    properties:
      name:
        type: string
        minLength: 1
        maxLength: 80
        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: 100
        description: Bank Name  of the beneficiary bank.
        example: ICICI
      other_branch_name:
        type: string
        maxLength: 75
        description: Branch Name of the other 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
        maxLength: 100
        description: Address of the beneficiary bank.
        example: 15th Main,
      other_branch_addr2:
        type: string
        maxLength: 100
        description: City of the other bank. 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.
    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 beneficiary. Mandatory in the
      request when charges are required for SWIFT/UAEFTS remittances i.e. when transaction_type=BankTranfer.
      Not required for transaction_type=RAKMoney.
  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 - RAKBank Account Id of the customer'
        example: Account_ID
      customer_id:
        type: string
        minLength: 1
        maxLength: 20
        example: "123243543654654"
        description: Customer id of the customer, corresponding to the customer_id_type,
          who initiates the transaction.
    additionalProperties: false
    required:
    - customer_id
    - customer_id_type
    description: This will contain the details of the remitter. Mandatory in the request
      when charges are required for SWIFT/UAEFTS remittances i.e. when transaction_type=BankTranfer.
      Not required for transaction_type=RAKMoney.
  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 residence or incorporation of the beneficiary.
          ISO 2 Character Country Codes.
    additionalProperties: false
    required:
    - country
x-ibm-endpoints:
- endpointUrl: https://sandboxapi.rakbank.ae/sb/api
  type:
  - production
  - development
...