Lorum Payments API

openapi: 3.1.0
info:
  title: Fuse Accounts Payments API
  description: 'Lorum (Fuse) clearing, settlement and treasury API: multi-currency accounts, payments, exchanges, transfers, customers/KYC, documents, batch payments and sandbox simulation. Harvested from the provider''s public ReadMe reference (per-operation OpenAPI definitions).'
  contact:
    name: Lorum
    url: https://docs.lorum.com
  license:
    name: Proprietary license
  version: 0.1.0
servers:
- url: https://api.fuse.me
  description: Production
- url: https://api-sandbox.fuse.me
  description: Sandbox
security:
- OAuth2: []
tags:
- name: Payments
paths:
  /v1/accounts/{account_id}/payments:
    post:
      tags:
      - Payments
      summary: Create outbound payment for a customer
      description: Create outbound payment for a customer
      operationId: create_customer_payment
      parameters:
      - name: Idempotency-Key
        in: header
        description: Idempotency key to allow safe retrying of the operation. The value should be a unique UUID for each distinct operation. See our understanding idempotency guide for full details.
        required: true
        schema:
          type: string
          format: uuid
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerPaymentRequest'
        required: true
      responses:
        '202':
          description: Customer payment has been accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentResponse'
        '400':
          description: Unable to complete request with data provided
        '404':
          description: Account not found
        '409':
          description: Idempotency-Key concurrency conflict
        '422':
          description: Idempotency-Key reuse for a different request
  /v1/accounts/{account_id}/payments/estimate-fee/{amount}:
    get:
      tags:
      - Payments
      summary: Estimate the fee for an outbound payment
      description: Estimate the fee for an outbound payment
      operationId: customer_payment_fee_estimate
      parameters:
      - name: account_id
        in: path
        description: The account id where the intended payment will be made from.
        required: true
        schema:
          type: string
          format: uuid
      - name: amount
        in: path
        description: The amount of the payment.
        required: true
        schema:
          type: integer
          format: int64
          minimum: 0
      responses:
        '200':
          description: Request to estimate fee has been successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimateFeeResponse'
        '400':
          description: Unable to complete request with data provided
        '404':
          description: Account not found
components:
  schemas:
    BeneficiaryBank:
      type: object
      description: Bank details of payment beneficiary bank.
      properties:
        branch:
          type:
          - string
          - 'null'
          format: string
          description: The branch of the bank where the beneficiary account is held.
          maxLength: 50
        code:
          type:
          - string
          - 'null'
          description: 'The BIC code of the bank where the beneficiary account is held.

            Optional for AED payments. Mandatory for USD payments.'
          minLength: 8
        intermediary_bank:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/IntermediaryBank'
            description: The intermediary bank details.
    uae_id:
      type: object
      required:
      - number
      properties:
        number:
          type: string
          format: string
          maxLength: 50
    CreateCustomerPaymentRequest:
      type: object
      description: Parameters required to create a payment.
      required:
      - amount
      - beneficiary
      - external_reference
      - purpose
      properties:
        amount:
          type: integer
          format: int64
          description: Payment amount.
          minimum: 0
        beneficiary:
          $ref: '#/components/schemas/PaymentDetails'
          description: External account identifier of the beneficiary.
        external_id:
          type:
          - string
          - 'null'
          format: string
          description: 'External ID set by the customer. The external ID will be available

            on all resources related to the transaction if set when creating

            the transaction.'
          maxLength: 36
        external_reference:
          type: string
          description: Payment reference for the payment.
          maxLength: 100
        purpose:
          $ref: '#/components/schemas/PurposeCode'
          description: Reason for the transaction.
    PaymentDetails:
      type: object
      description: Account details of the payment beneficiary.
      required:
      - account_holder_name
      - account_identifier
      - address
      - type
      properties:
        account_holder_name:
          type: string
          format: string
          description: 'Name of the beneficiary account.


            **Note:** When the `beneficiary_type` is `individual`, the name may not contain any digits.

            **Note:** When the payment currency is `USD`, max length 35 characters.'
          maxLength: 140
        account_identifier:
          $ref: '#/components/schemas/AccountDetailsIdentifier'
          description: External account identifier of the beneficiary account.
        address:
          $ref: '#/components/schemas/Address'
          description: 'Address of the beneficiary account.


            **Note:** When the payment currency is `USD`, the following field restrictions apply:

            - **Line 1:** Required, maximum length 35 characters.

            - **Line 2:** Required, maximum length 35 characters.

            - **Line 3:** Optional, maximum length 20 characters (city or postcode/zipcode recommended).)'
        bank:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/BeneficiaryBank'
            description: The bank details where the beneficiary account is held.
        date_of_birth:
          type:
          - string
          - 'null'
          format: date
        email:
          type:
          - string
          - 'null'
          format: string
          description: The beneficiary's email address.
        identification:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Identification'
        nationality:
          type:
          - string
          - 'null'
          format: string
        phone:
          type:
          - string
          - 'null'
          format: string
          description: The beneficiary's phone number.
        type:
          $ref: '#/components/schemas/CounterpartType'
      example: {}
    CounterpartType:
      type: string
      enum:
      - individual
      - business
    AccountDetailsIdentifier:
      oneOf:
      - type: object
        title: IBAN
        required:
        - iban
        properties:
          iban:
            type: string
            format: string
      - type: object
        title: Wire
        required:
        - wire
        properties:
          wire:
            $ref: '#/components/schemas/WireBankDetails'
      - type: object
        title: SCAN
        required:
        - scan
        properties:
          scan:
            $ref: '#/components/schemas/ScanDetails'
    ScanDetails:
      type: object
      required:
      - sort_code
      - account_number
      properties:
        account_number:
          type: string
          format: string
          maxLength: 8
        sort_code:
          type: string
          format: string
          maxLength: 6
    BicCode:
      type: string
      description: BIC Code to identify a bank.
    CreatePaymentResponse:
      type: object
      required:
      - transaction_id
      properties:
        transaction_id:
          type: string
          format: uuid
          description: Id of the created payment.
    Address:
      type: object
      required:
      - line_1
      - country_code
      properties:
        country_code:
          type: string
          format: string
          maxLength: 2
          minLength: 2
        line_1:
          type: string
          format: string
          maxLength: 50
        line_2:
          type:
          - string
          - 'null'
          format: string
          description: '***optional*** for `AED` payments but ***mandatory*** for `USD` payments'
          maxLength: 50
        line_3:
          type:
          - string
          - 'null'
          format: string
          maxLength: 50
        line_4:
          type:
          - string
          - 'null'
          format: string
          maxLength: 50
    WireBankDetails:
      type: object
      required:
      - account_number
      - routing_number
      properties:
        account_number:
          type: string
          format: string
          maxLength: 27
        routing_number:
          type: string
          format: string
          maxLength: 12
    EstimateFeeResponse:
      type: object
      required:
      - account_id
      - instructed_amount
      - fee_amount
      - amount_with_fee
      - currency
      - estimated_at
      properties:
        account_id:
          type: string
          format: uuid
        amount_with_fee:
          type: integer
          format: int64
          minimum: 0
        currency:
          $ref: '#/components/schemas/Currency'
        estimated_at:
          type: string
          format: date-time
        fee_amount:
          type: integer
          format: int64
          minimum: 0
        instructed_amount:
          type: integer
          format: int64
          minimum: 0
    passport:
      type: object
      required:
      - number
      - country_of_issue
      properties:
        country_of_issue:
          type: string
          format: string
        number:
          type: string
          format: string
          maxLength: 50
    Identification:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/uae_id'
        - type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - uae_id
      - allOf:
        - $ref: '#/components/schemas/passport'
        - type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - passport
      description: The identification field is **not** required. When provided, then all UAE_ID fields or PASSPORT fields are required.
    Currency:
      type: string
      enum:
      - AED
      - USD
      - JOD
      - EGP
      - SAR
      - GBP
      - EUR
      - HKD
      - CNH
      - SGD
    IntermediaryBank:
      type: object
      required:
      - code
      properties:
        account_number:
          type:
          - string
          - 'null'
          format: string
          maxLength: 25
        code:
          $ref: '#/components/schemas/BicCode'
    PurposeCode:
      type: string
      description: Enum representing different payment purposes.
      enum:
      - charity
      - commercial_investment
      - corporate_card
      - credit_card
      - dividend
      - family
      - financial_services
      - goods_sold
      - goods_bought
      - government
      - insurance
      - intergroup_transfer
      - intra_group_dividends
      - information_technology
      - leasing
      - loan_charges
      - merchant_settlement
      - mobile_wallet
      - non_resident_transfer_between_accounts
      - none
      - pension
      - personal_expenses
      - prepaid_cards
      - professional
      - rental
      - resident_transfer_between_accounts
      - salaries
      - tax
      - telecommunications
      - travel
      - utility_bill
  securitySchemes:
    OAuth2:
      type: http
      scheme: bearer
      bearerFormat: JWT