iBanFirst Payments API

openapi: 3.2.0
info:
  version: 1.6.0
  title: iBanFirst Payments API
  description: iBanFirst API for cross-border payments, FX trades, account management, beneficiaries, and webhooks.
servers:
- url: https://api-demo.ibanfirst.com/api
security:
- X-WSSE: []
tags:
- name: Payments
  description: 'Sending funds from one of your iBanFirst accounts to your own external bank account or a third-party recipient involves two steps:


    1.'
paths:
  /payments/options/{walletId}/{externalBankAccountId}:
    get:
      summary: Get payment options
      tags:
      - Payments
      description: 'Before doing any payments, you may use this request to get priority and fee options available for a given account and beneficiary.


        You will also get fee cost for each `priorityPaymentOption` and `feePaymentOption` combinations, and minimal source and target amount for this combination.


        **Note :** you may also use this request to estimate the cost of a payment.'
      parameters:
      - name: walletId
        in: path
        description: 'The source account you want to put your payment debit on.

          '
        required: true
        schema:
          type: string
      - name: externalBankAccountId
        in: path
        description: 'The beneficiary you want to put your payment credit on.

          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentOption'
        default:
          description: ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getPaymentsOptionsByWalletIdByExternalBankAccountId
      x-operation-id-source: derived
  /payments:
    post:
      summary: Create payment
      tags:
      - Payments
      description: You can use this request to schedule a new payment.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sourceWalletId
              - externalBankAccountId
              - amount
              - desiredExecutionDate
              - feeCurrency
              - feePaymentOption
              - priorityPaymentOption
              properties:
                sourceWalletId:
                  $ref: '#/components/schemas/ID'
                externalBankAccountId:
                  $ref: '#/components/schemas/ID'
                amount:
                  $ref: '#/components/schemas/Amount'
                desiredExecutionDate:
                  $ref: '#/components/schemas/Date'
                feeCurrency:
                  $ref: '#/components/schemas/Currency'
                feePaymentOption:
                  description: 'A code representing the charges option to be applied to this payment.

                    '
                  type: string
                  enum:
                  - BEN
                  - OUR
                  - SHARE
                  - SEPA
                  - DSP
                  - RTGS
                priorityPaymentOption:
                  $ref: '#/components/schemas/paymentSpeedOption'
                tag:
                  description: 'A custom reference that you want to link to this payment in the system. This tag is not communicated to the beneficiary.

                    '
                  type: string
                  maxLength: 50
                communication:
                  description: 'A free format string sent to the beneficiary.

                    '
                  type: string
                  maxLength: 76
                verificationOfPayee:
                  type: boolean
                  description: "`true` to verify the beneficiary's IBAN, name and type. If the verification fails, the payment will not be created.\n\n **Note** : the verification of payee process can take up to 8 seconds."
        description: 'The payment to post

          '
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  payment:
                    $ref: '#/components/schemas/PaymentVOP'
        default:
          description: ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorVOP'
      operationId: postPayments
      x-operation-id-source: derived
  /payments/{id}/confirm:
    put:
      summary: Confirm a payment
      tags:
      - Payments
      description: 'Payments that has been scheduled must be confirmed in order to be released.

        If the payment is not confirmed before the end of scheduled date of operation, it will be automatically postponed to the next operation date available.


        ***NOTE**: For an instant SEPA payment confirmation, if the source account does not have sufficient funds, the payment will be automatically rejected..*'
      parameters:
      - name: id
        in: path
        description: "The unique id identifying the payment you want to confirm.\n\n \n\n **Note :** you may use the **[Get payments by status](https://docs.ibanfirst.com/api/clientapi/payments/paths/~1payments~1%7Bstatus%7D/get)** service to get the unique id of your payment. \n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        default:
          description: ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: putPaymentsByIdConfirm
      x-operation-id-source: derived
  /payments/{id}/proofOfTransaction:
    put:
      summary: Upload a proof of transaction for a payment
      tags:
      - Payments
      description: 'We may ask you to provide a proof of transaction under specific terms. You can anticipate our request and send us your invoice or the ID of the beneficiary to avoid any request from us and fully automate your payment process.

        To send a file with this request, you have to extract the content of the file with a binary format, and encode it with a base64 algorithm to put in in the “file” field.'
      parameters:
      - name: id
        in: path
        description: 'The unique id of the payment you want to update.

          '
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - documentType
              - tag
              - file
              properties:
                documentType:
                  description: "The type of document to submit for a transaction. \n"
                  type: string
                  enum:
                  - invoice
                  - identity
                tag:
                  description: 'The name of the document to be attached.

                    '
                  type: string
                file:
                  description: 'The binary content of the file, encoded with a base64 algorithm.

                    '
                  type: string
        description: 'The proof of transaction to upload

          '
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        default:
          description: ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: putPaymentsByIdProofOfTransaction
      x-operation-id-source: derived
  /payments/{status}:
    get:
      summary: Get payments by status
      tags:
      - Payments
      description: Request a list of payments filtered by status.
      parameters:
      - name: status
        in: path
        description: 'A code representing the status of the payments you want to get.

          '
        required: true
        schema:
          type: string
          enum:
          - all
          - planified
          - rejected
          - finalized
          - canceled
          - refused
          - blocked
          - waitingconfirmation
          - waitingsignature
      - name: fromDate
        in: query
        description: 'The starting date to search for payments.

          '
        required: false
        schema:
          type: string
          format: YYYY-MM-DD
      - name: toDate
        in: query
        description: 'The ending date to search for payments.

          '
        required: false
        schema:
          type: string
          format: YYYY-MM-DD
      - name: page
        in: query
        description: 'Index of the page.

          '
        required: false
        schema:
          type: string
          default: '1'
      - name: per_page
        in: query
        description: 'Number of items returned.

          '
        required: false
        schema:
          type: string
          default: '50'
      - name: sort
        in: query
        description: 'A code representing the order of rendering objects.

          '
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
        '204':
          description: No payments found
        default:
          description: ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getPaymentsByStatus
      x-operation-id-source: derived
  /payments/{id}:
    get:
      summary: Get payment details
      tags:
      - Payments
      description: Retrieve the details of a specific payment.
      parameters:
      - name: id
        in: path
        description: "The unique id of the payment.\n\n **Note :** you may use the **Get payments by status** service to get the unique id of your payment .\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  payment:
                    $ref: '#/components/schemas/Payment'
        default:
          description: ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getPaymentsById
      x-operation-id-source: derived
    delete:
      summary: Delete a payment
      tags:
      - Payments
      description: Allows you to delete a scheduled payment.
      parameters:
      - name: id
        in: path
        description: 'The code identifying the payment you want to delete.

          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        default:
          description: ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: deletePaymentsById
      x-operation-id-source: derived
components:
  schemas:
    Datetime:
      type: string
      pattern: ^((19[0,99]|2[0-9]{3})\-(0[1-9]|1[012])\-([012][0-9]|3[01])\ ([01][0-9]|2[0-3])\:([0-5][0-9])\:([0-5][0-9]))$
      format: ^((19[0,99]|2[0-9]{3})\-(0[1-9]|1[012])\-([012][0-9]|3[01])\ ([01][0-9]|2[0-3])\:([0-5][0-9])\:([0-5][0-9]))$
      example: '2016-01-01 00:00:00'
      description: 'A String representing a date by its year, month, day in month, hour, minute and second.

        '
    Amount:
      type:
      - object
      - 'null'
      description: 'Representation of an amount.

        '
      required:
      - value
      - currency
      properties:
        value:
          $ref: '#/components/schemas/QuotedDecimal'
        currency:
          $ref: '#/components/schemas/Currency'
    paymentSpeedOption:
      description: 'A code representing the speed option.

        '
      type: string
      enum:
      - 48H
      - 24H
      - 1H
      - instant
    CurrencyPair:
      type: string
      pattern: ^[A-Z]{6}$
      format: ^[A-Z]{6}$
      example: EURUSD
      description: "A String representing two concatenated Three-digit ISO 4217 Currency Code of a currency. This String only contains capitalized letters.\n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n"
    ErrorVOP:
      type: object
      description: 'Representation of an error.

        '
      properties:
        errorCode:
          type: number
          format: int
          description: 'The code referring the error.

            '
        errorType:
          type: string
          description: 'A short description identifying a general category for the error that occurred.

            '
        errorMessage:
          type: string
          description: 'Error description. '
        link:
          type: string
          description: 'An hyperlink to access the page that describes more accurately the error.

            '
        payeeVerification:
          type: object
          description: ''
          properties:
            status:
              type: string
              enum:
              - PARTIAL
              - FAILED
              description: ''
            message:
              type: string
              description: Verification of payee result details.
            corrections:
              type: object
              description: Proposed modification regarding the beneficiary information.
              properties:
                account_holder_name:
                  type: string
                  description: Expected beneficiary name.
                account_holder_type:
                  type: string
                  enum:
                  - Individual
                  - Corporate
                  description: Expected beneficiary type.
    paymentPriorityOption:
      description: 'A code representing whether this payment has a standard priority, or a priority treatment.

        '
      type: string
      enum:
      - normal
      - urgent
    PaymentVOP:
      type: object
      description: 'Representation of a payment.

        '
      properties:
        id:
          $ref: '#/components/schemas/ID'
        status:
          type: string
          description: 'The code identifying the payment status.

            '
          enum:
          - planified
          - rejected
          - finalized
          - canceled
          - refused
          - blocked
          - awaitingconfirmation
          - waitingsignature
          - processing
        createdDate:
          $ref: '#/components/schemas/Datetime'
        desiredExecutionDate:
          $ref: '#/components/schemas/Date'
        executionDate:
          $ref: '#/components/schemas/Date'
        amount:
          $ref: '#/components/schemas/Amount'
        counterValue:
          $ref: '#/components/schemas/Amount'
        rate:
          $ref: '#/components/schemas/Rate'
        tag:
          type: string
          maxLength: 50
          description: 'The custom reference related to the payment. (For internal use only, not communicated to the beneficiary).

            '
        externalBankAccountId:
          $ref: '#/components/schemas/ID'
        sourceWalletId:
          $ref: '#/components/schemas/ID'
        communication:
          type: string
          maxLength: 50
          description: 'The wording of the payment.

            '
        priorityPaymentOption:
          $ref: '#/components/schemas/paymentPriorityOption'
        feePaymentOption:
          type: string
          description: 'The code identifying the charges option for this payment.

            '
          enum:
          - BEN
          - OUR
          - SHARE
          - SEPA
          - DSP
          - RTGS
        speedOption:
          $ref: '#/components/schemas/paymentSpeedOption'
        feePaymentAmount:
          $ref: '#/components/schemas/Amount'
        tracker:
          type: string
          description: 'Payment tracker link. For SWIFT payment only. Not available for payments pending confirmation or signature. '
        payeeVerification:
          type: object
          description: "Verification of payee result. \n\n **Note** : check default error response if the verification failed for more details.\n"
          properties:
            status:
              type: string
              description: '`SUCCESS` if the beneficiary IBAN and name are verified.'
            message:
              type: string
              description: '`Match` if the beneficiary IBAN and name are a perfect match.'
    Error:
      type: object
      description: 'Representation of an error.

        '
      properties:
        errorCode:
          type: number
          format: int
          description: 'The code referring the error.

            '
        errorType:
          type: string
          description: 'A short description identifying a general category for the error that occurred.

            '
        errorMessage:
          type: string
          description: Error description.
        link:
          type: string
          description: 'An hyperlink to access the page that describes more accurately the error.

            '
    Rate:
      type: object
      description: 'Representation of a Rate.

        '
      properties:
        currencyPair:
          $ref: '#/components/schemas/CurrencyPair'
        midMarket:
          $ref: '#/components/schemas/QuotedDecimal'
        date:
          $ref: '#/components/schemas/Datetime'
        coreAsk:
          $ref: '#/components/schemas/QuotedDecimal'
        coreBid:
          $ref: '#/components/schemas/QuotedDecimal'
        appliedAsk:
          $ref: '#/components/schemas/QuotedDecimal'
        appliedBid:
          $ref: '#/components/schemas/QuotedDecimal'
    Date:
      type: string
      pattern: ^[0-9]{4}\-[0-9]{2}\-[0-9]{2}$
      format: ^[0-9]{4}\-[0-9]{2}\-[0-9]{2}$
      example: '2016-01-01'
      description: "A String representing a date by its year, month and day in month.\n    \n"
    QuotedDecimal:
      type: string
      pattern: ^((\-)?)[0-9]{12}((\.[0-9]{1,7})?)$
      format: ^((\-)?)[0-9]{12}((\.[0-9]{1,7})?)$
      example: '2.257'
      description: 'A String representing a formatted floating number.

        '
    Currency:
      type: string
      pattern: ^[A-Z]{3}$
      format: ^[A-Z]{3}$
      example: USD
      description: 'A String representing the Three-digit ISO 4217 Currency Code of a currency. This String only contains capitalized letters.

        '
    PaymentOption:
      type: object
      description: 'The representation of a payment option object. This object contains information about priorityPaymentOption and feePaymentOption for a payment.

        '
      properties:
        paymentOption:
          type: object
          properties:
            externalBankAccountId:
              $ref: '#/components/schemas/ID'
            sourceWalletId:
              $ref: '#/components/schemas/ID'
            options:
              description: 'An array containing all priorityPaymentOptions for the payment, and then, all the feePaymentOptions for this priorityPaymentOptions

                '
              type: array
              items:
                type: object
                properties:
                  priorityPaymentOption:
                    $ref: '#/components/schemas/paymentSpeedOption'
                  feePaymentOption:
                    description: The fee option
                    type: string
                    enum:
                    - BEN
                    - OUR
                    - SHARE
                    - SEPA
                    - DSP
                    - RTGS
                  priorityCost:
                    $ref: '#/components/schemas/Amount'
                  feeCost:
                    $ref: '#/components/schemas/Amount'
                  minimumAmountSource:
                    $ref: '#/components/schemas/Amount'
                  minimumAmountTarget:
                    $ref: '#/components/schemas/Amount'
    Payment:
      type: object
      description: 'Representation of a payment.

        '
      properties:
        id:
          $ref: '#/components/schemas/ID'
        status:
          type: string
          description: 'The code identifying the payment status.

            '
          enum:
          - awaitingconfirmation
          - planified
          - rejected
          - finalized
          - canceled
          - refused
          - blocked
          - waitingsignature
          - processing
        createdDate:
          $ref: '#/components/schemas/Datetime'
        desiredExecutionDate:
          $ref: '#/components/schemas/Date'
        executionDate:
          $ref: '#/components/schemas/Date'
        amount:
          $ref: '#/components/schemas/Amount'
        counterValue:
          $ref: '#/components/schemas/Amount'
        rate:
          $ref: '#/components/schemas/Rate'
        tag:
          type:
          - string
          - 'null'
          maxLength: 50
          description: 'The custom reference related to the payment. (For internal use only, not communicated to the beneficiary).

            '
        externalBankAccountId:
          $ref: '#/components/schemas/ID'
        sourceWalletId:
          $ref: '#/components/schemas/ID'
        communication:
          type:
          - string
          - 'null'
          maxLength: 76
          description: 'The wording of the payment.

            '
        priorityPaymentOption:
          $ref: '#/components/schemas/paymentPriorityOption'
        feePaymentOption:
          type: string
          description: 'The code identifying the charges option for this payment.

            '
          enum:
          - BEN
          - OUR
          - SHARE
          - SEPA
          - DSP
          - RTGS
        speedOption:
          $ref: '#/components/schemas/paymentSpeedOption'
        feePaymentAmount:
          $ref: '#/components/schemas/Amount'
        tracker:
          type: string
          description: Payment tracker link. For SWIFT payment only. Not available for payments pending confirmation or signature.
    ID:
      type: string
      pattern: ^[A-Za-z0-9]+$
      format: ^[A-Za-z0-9]+$
      example: Na5Dv6E
      description: 'A String representing the id of an object. This string contains alpha-numeric characters, including the capital ones.

        '
  securitySchemes:
    X-WSSE:
      type: apiKey
      in: header
      name: X-WSSE
      description: 'X-WSSE token-based authentication. The header value must be computed fresh for every request (tokens expire in ~5 minutes).


        Header value format:

        ```

        UsernameToken Username="<username>", PasswordDigest="<digest>", Nonce="<nonce_b64>", Created="<timestamp>"

        ```


        Algorithm:

        1. Generate a random nonce: ≥ 32 lowercase hex characters.

        2. Get current UTC timestamp in ISO 8601: `YYYY-MM-DDTHH:MM:SSZ`.

        3. Compute `PasswordDigest = Base64( SHA-1( nonce_bytes + created_bytes + secret_bytes ) )` — SHA-1 over the raw UTF-8 bytes concatenated in that order, result must be the binary digest before Base64 encoding.

        4. Compute `Nonce = Base64( nonce_utf8_bytes )`.


        See the `info.description` field at the top of this spec for full code samples in Python, JavaScript, PHP, Java, and Go.'