core-connector-lib/src/api-spec/core-connector-api-spec-dfsp.yml

A connector that facilitates payments between a Mojaloop Connector (SDK Scheme Adapter) and a Core Banking system

openapi: 3.0.1
info:
  title: Core Banking System Core Connector Send Money API
  description: >
    Specification for Core Banking System Core Connectors Send Money API.

    This API is intended to be implemented by the Core Connector. It is used to 
    initiate transfers from a DFSP Operations application.


    **USE CASE AND SCENARIO**


    Assuming a customer in your DFSP wants to send money from their account held
    in your bank to another customer whose account is in another bank in the Mojaloop
    Scheme.
    Once the customer has initaited the transfer using your application, to effect the transfer,
    a POST send-money api call will be sent to this api. This api is to be implemented by the 
    core connector such it can receive requests from your Operations application which will then effectively communicate with your DFSP Hosted Mojaloop
    connector to be able to effect the transfer in the mojaloop switch.


    **Note on terminology:** The term "Switch" is equal to the term "Hub", and
    the term "FSP" is equal to the term "DFSP".
  license:
    name: Apache License Version 2.0, January 2004
    url: https://github.com/mojaloop/documentation/blob/main/LICENSE.md
  version: 1.0.0
paths:
  /:
    get:
      summary: Health check endpoint
      description: >-
        This endpoint allows a user of the SDK scheme adapter to check the
        outbound transfers service is listening.
      tags:
        - Health
      responses:
        "200":
          description: >-
            Returns empty body if the scheme adapter outbound transfers service
            is running.
  /send-money:
    post:
      summary: Send Money endpoint
      description: >-
        The Endpoint used by the DFSP Operations application to initiate send money 
        requests to the mojaloop connector

      operationId: sendMoney
      requestBody:
        description: Send Money request body
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/sendMoneyRequest"
      tags:
        - Send Money
      responses:
        "200":
          description: >-
            Response for send money request. A quote if it is double 
            integration or a payment status response if it is single
            integration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/sendMoneyResponse"
        "400":
          description: >-
            Response for a bad request.
        "500":
          description: >-
            Response for an internal server error
        "504":
          description: >-
            Response for a timed out transfer
  /send-money/{transferId}:
    put:
      summary: Confirm send money
      operationId: sendMoneyUpdate
      parameters:
        - name: transferId
          in: path
          required: true
          description: The ID of the transaction
          schema:
            type: string
            example: "HTX987654321"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmSendMoney"
      tags:
        - Send Money
      responses:
        "200":
          description: Send money confirmed successfully
        "400":
          description: Bad request

  /merchant-payment:
    post:
      summary: Send Money endpoint
      operationId: initiateMerchantPayment
      description: >-
        The Endpoint used by the DFSP Operations application to initiate merchant payment
        requests to the mojaloop connector
      requestBody:
        description: Send Money request body
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/merchantPaymentRequest"
      tags:
        - Merchant Payments
      responses:
        "200":
          description: >-
            Response for send money request. A quote if it is double 
            integration or a payment status response if it is single
            integration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/merchantPaymentResponse"

        "400":
          description: >-
            Response for bad request
        "500":
          description: >-
            Internal Server error
        "504":
          description: >-
            Transfer Timeout.

  /merchant-payment/{id}:
    put:
      summary: Confirm send money
      operationId: updateInitiatedMerchantPayment
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the transaction
          schema:
            type: string
            example: "HTX987654321"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmSendMoney"
      tags:
        - Merchant Payments
      responses:
        "200":
          description: Send money confirmed successfully
        "400":
          description: Bad request

  /callback:
    put:
      operationId: callback
      tags:
        - Callback Endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/callbackPayload"
      responses:
        "200":
          description: Receipt of callback confirmed

components:
  schemas:
    callbackPayload:
      type: object
      properties:
        transaction:
          type: object
          properties:
            id:
              type: string
              example: BBZMiscxy
              description: Unique identifier for the transaction.
            message:
              type: string
              example: Paid UGX 5,000 to TECHNOLOGIES LIMITED Charge UGX 140, Trans ID MP210603.1234.L06941.
              description: Transaction message detailing payment, charges, and transaction ID.
            status_code:
              type: string
              example: TS
              description: Status code of the transaction.
            airtel_money_id:
              type: string
              example: MP210603.1234.L06941
              description: Airtel money transaction ID.
          required:
            - id
            - message
            - status_code
            - airtel_money_id
    merchantPaymentRequest:
      type: object
      properties:
        homeTransactionId:
          type: string
          example: "HTX123456789"
        payeeId:
          type: string
          example: "16135551212"
        payeeIdType:
          type: string
          example: "MSISDN"
        sendAmount:
          type: string
          example: "150.00"
        sendCurrency:
          type: string
          example: "UGX"
        receiveCurrency:
          type: string
          example: "KES"
        transactionDescription:
          type: string
          example: "Payment for services"
        transactionType:
          type: string
          example: "TRANSFER"
        payer:
          type: object
          properties:
            name:
              type: string
              example: "John Doe"
            payerId:
              type: string
              example: "9876543210"
            DateAndPlaceOfBirth:
              type: object
              properties:
                BirthDt:
                  type: string
                  example: "20-09-2001"
                PrvcOfBirth:
                  type: string
                  example: "ProvinceOfBirth"
                CityOfBirth:
                  type: string
                  example: "Kampala"
                CtryOfBirth:
                  type: string
                  example: "Uganda"
              required:
                - BirthDt
                - CityOfBirth
                - CtryOfBirth
          required:
            - name
            - payerId
      required:
        - homeTransactionId
        - payeeId
        - payeeIdType
        - sendAmount
        - sendCurrency
        - receiveCurrency
        - transactionType
        - payer
      

    merchantPaymentResponse:
      type: object
      properties:
        payeeDetails:
          type: object
          properties:
            idType:
              type: string
              example: "MSISDN"
            idValue:
              type: string
              example: "990454454"
            fspId:
              type: string
              example: "airtelzambia"
            firstName:
              type: string
              example: "Niza"
            lastName:
              type: string
              example: "Tembo"
            dateOfBirth:
              type: string
              example: "1997/09/04"

        receiveAmount:
          type: string
          example: "140.00"
        receiveCurrency:
          type: string
          example: "EUR"
        fees:
          type: string
          example: "10.00"
        feeCurrency:
          type: string
          example: "USD"
        transactionId:
          type: string
          example: "42fdb186-2a36-46f1-9be9-8989a9e0aeb4"
    sendMoneyResponse:
      type: object
      properties:
        payeeDetails:
          type: object
          properties:
            idType:
              type: string
              example: "MSISDN"
            idValue:
              type: string
              example: "990454454"
            fspId:
              type: string
              example: "airtelzambia"
            firstName:
              type: string
              example: "Niza"
            lastName:
              type: string
              example: "Tembo"
            dateOfBirth:
              type: string
              example: "1997/09/04"

        receiveAmount:
          type: string
          example: "140.00"
        receiveCurrency:
          type: string
          example: "EUR"
        fees:
          type: string
          example: "10.00"
        feeCurrency:
          type: string
          example: "USD"
        transactionId:
          type: string
          example: "42fdb186-2a36-46f1-9be9-8989a9e0aeb4"
    sendMoneyRequest:
      type: object
      properties:
        homeTransactionId:
          type: string
          example: "HTX123456789"
        payeeId:
          type: string
          example: "16135551212"
        payeeIdType:
          type: string
          example: "MSISDN"
        sendAmount:
          type: string
          example: "150.00"
        sendCurrency:
          type: string
          example: "UGX"
        receiveCurrency:
          type: string
          example: "KES"
        transactionDescription:
          type: string
          example: "Payment for services"
        transactionType:
          type: string
          example: "TRANSFER"
        payer:
          type: object
          properties:
            name:
              type: string
              example: "John Doe"
            payerId:
              type: string
              example: "9876543210"
            DateAndPlaceOfBirth:
              type: object
              properties:
                BirthDt:
                  type: string
                  example: "20-09-2001"
                PrvcOfBirth:
                  type: string
                  example: "ProvinceOfBirth"
                CityOfBirth:
                  type: string
                  example: "Kampala"
                CtryOfBirth:
                  type: string
                  example: "Uganda"
              required:
                - BirthDt
                - CityOfBirth
                - CtryOfBirth
          required:
            - name
            - payerId
      required:
        - homeTransactionId
        - payeeId
        - payeeIdType
        - sendAmount
        - sendCurrency
        - receiveCurrency
        - transactionType
        - payer

    ConfirmSendMoney:
      type: object
      properties:
        acceptQuote:
          type: boolean
        msisdn:
          type: string
          example: "777503758"
        amount:
          type: string
          example: "500"