openapi: 3.2.0
info:
  title: JGME Pay - OpenAPI 3.1
  description: >-
    This is the minimal API for JGME Pay collection and disbursements API. To
    view a more elaborate documentation see here.


    Some useful links:

    - [Home](https://jgmepay.com)

    - [JGME Pay Documentation](/docs)
  termsOfService: https://jgmepay.com/terms
  contact:
    email: tech@jgmepay.com
  version: 1.0.0
servers:
  - url: https://api.jgmepay.com
    description: Production API Base URL
tags:
  - name: Collections
    description: Everything about your payment collection with JGME Pay
    externalDocs:
      description: Find out more
      url: /docs/collections/inline
  - name: Integrations
    description: Fetch activated payment providers available to your business.
  - name: Disbursements
    description: >
      Find full list of supported Disbursement providers here [Supported
      Providers](/docs/disbursements)

      There are 3 main process to carry out a Disbursement on JGME Pay

      1. Validate A transfer Recipient

      2. Initiate a Disbursement Request

      3. Verify a Disbursement Request
  - name: Wallets
    description: A Little bit about our [wallets here](/docs/concepts/platform-overview)
paths:
  /payments/v1/payments/direct-charge:
    post:
      tags:
        - Collections
      summary: Collection API - Direct
      description: Charge the Customer via API
      operationId: DirectChargeAPI
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DirectChargeAPIRequest"
        required: true
      responses:
        "201":
          description: Request Submitted Successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/DirectChargeAPIResponse"
  /payments/v1/payments/confirm:
    post:
      tags:
        - Collections
      summary: Confirm Direct Charge Customer Input
      description: Submit customer input, such as an OTP, when a Direct Charge
        response returns `action` as `otp`.
      operationId: confirmDirectChargeCustomerInput
      requestBody:
        description: Direct Charge customer input confirmation request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DirectChargeConfirmRequest"
            example:
              reference: DDC20260702112401ZIWGF
              customerInput:
                otp: "445985"
        required: true
      responses:
        "201":
          description: Customer input accepted and payment confirmation is processing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DirectChargeConfirmEnvelope"
              example:
                statusCode: 201
                data:
                  action: processing
                  sessionId: cos-1z3x983b01300
                  provider: qmoney-gambia
                  reference: DDC20260702115234PTIFG
                  providersReference: PIX_44241170102532681668
                  amount: 1000
                  totalAmount: 1000
                  charge: 0
                  status: pending
                  data:
                    message: OTP submitted successfully. Payment confirmation is processing.
                  statusDescription: Awaiting Provider's Feedback
  /payments/v1/payments/verify/{reference}:
    get:
      tags:
        - Collections
      summary: Verify Collection (TSQ)
      description: This is the endpoint to verify a Transaction (TSQ)
      operationId: verifyPaymentTransaction
      parameters:
        - in: path
          name: reference
          schema:
            type: string
          required: true
          description: Reference of the transaction to verify
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/VerifyTransactionResponse"
  /payments/v1/payments:
    get:
      tags:
        - Collections
      summary: Fetch Collection History
      description: Retrieve a paginated list of all collection transactions
      operationId: getAllCheckouts
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 4
          description: Number of records per page
        - in: query
          name: dateFrom
          schema:
            type: string
            format: date
            example: 2024-01-01
          description: Start date for filtering transactions (inclusive)
          required: false
        - in: query
          name: dateTo
          schema:
            type: string
            format: date
            example: 2025-01-01
          description: End date for filtering transactions (inclusive)
          required: false
      responses:
        "200":
          description: Successfully retrieved transactions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetAllCheckoutResponse"
  /payments/v1/checkouts:
    post:
      tags:
        - Collections
      summary: Collections API - Generate Checkout
      description: Generate a Payment Checkout URL for customers to make payment
      operationId: generateCheckoutURL
      requestBody:
        description: Generate A Payment Checkout URL
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateCheckoutURLRequest"
        required: true
      responses:
        "201":
          description: Checkout URL Successfully Generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/GenerateCheckoutURLResponse"
  /integrations/v1/integrations:
    get:
      tags:
        - Integrations
      summary: Fetch Activated Integrations
      description: Retrieve payment providers that have been activated for your
        business. Filter the response by country, currency, and integration
        type.
      operationId: fetchActivatedIntegrations
      parameters:
        - in: query
          name: country
          schema:
            $ref: "#/components/schemas/Country"
          required: false
          description: 2 character country code used to filter integrations.
        - in: query
          name: currency
          schema:
            $ref: "#/components/schemas/Currency"
          required: false
          description: 3 character currency code used to filter integrations.
        - in: query
          name: type
          schema:
            type: string
            enum:
              - payment
              - collection
            example: payment
          required: false
          description: Integration type used to filter activated providers.
      responses:
        "200":
          description: Successfully retrieved activated integrations.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetIntegrationsResponse"
              example:
                statusCode: 200
                data:
                  - id: 6a68b195fa51e96ab2120d45
                    clientId: 6thbridge
                    label: MPesa
                    provider: mpesa-tanzania
                    type: payment
                    status: active
                    logo: https://files.6thbridge.xyz/public/v1/files/payfusion/content/67dc6a5e0abc90dcd853e993
                    description: Send money, pay bills, access loans & more, all with your phone.
                      M-Pesa is for everyone, fast, safe, affordable, and
                      empowering.
                    isOwnKeys: false
                    channels:
                      - mobile-money
                    currencies:
                      - TZS
                    currency: TZS
                    country: TZ
                    chargeVersion: 1
                    charge: null
                    charges: []
                    ownKeys: false
                  - id: 6a68b195fa51e96ab2120d44
                    clientId: 6thbridge
                    label: Halopesa
                    provider: halopesa-tanzania
                    type: payment
                    status: active
                    logo: https://files.6thbridge.xyz/public/v1/files/payfusion/content/67dc6a5e0abc90dcd853e991
                    description: Make digital transactions easily and fast transactions anywhere and
                      at any time, quickly, safely with affordably and
                      conveniently 24/7
                    isOwnKeys: false
                    channels:
                      - mobile-money
                    currencies:
                      - TZS
                    currency: TZS
                    country: TZ
                    chargeVersion: 1
                    charge: null
                    charges: []
                    ownKeys: false
                  - id: 6a427dfee884314a5fc5cd5c
                    clientId: 6thbridge
                    label: Ezy Pesa
                    provider: ezy-pesa-tanzania
                    type: payment
                    status: active
                    logo: https://mintlify.s3.us-west-1.amazonaws.com/shortstack/images/zeepaylogo.png
                    description: Mobile Money
                    isOwnKeys: false
                    channels:
                      - mobile-money
                    currencies:
                      - TZS
                    currency: TZS
                    country: TZ
                    chargeVersion: 1
                    charge: null
                    charges: []
                    ownKeys: false
                  - id: 6931b532710ac03f78a6d64b
                    clientId: 6thbridge
                    label: Airtel
                    provider: airtel-tanzania
                    type: payment
                    status: active
                    logo: https://s3-ap-southeast-1.amazonaws.com/bsy/iportal/images/airtel-logo-white-text-vertical.jpg
                    description: Run a better connected business with our enterprise solutions at
                      Airtel.
                    isOwnKeys: false
                    channels:
                      - mobile-money
                    currencies:
                      - TZS
                    currency: TZS
                    country: TZ
                    chargeVersion: 1
                    charge: null
                    charges: []
                    ownKeys: false
                  - id: 6699e58d7a36e0f743d04c55
                    clientId: 6thbridge
                    label: DigiCash
                    provider: digicash-tanzania
                    type: payment
                    status: active
                    logo: https://static.wixstatic.com/media/5244b5_7ecdb373a1954c59a18291f32ba0c087~mv2.png
                    description: Simplify your customer's payment experience in one integration
                    isOwnKeys: true
                    channels:
                      - mobile-money
                    currencies:
                      - TZS
                    currency: TZS
                    country: TZ
                    chargeVersion: 1
                    charge: null
                    charges: []
                    ownKeys: true
  /payments/v1/payments/direct-charge/{provider}/properties:
    get:
      tags:
        - Collections
      summary: Fetch Provider Properties
      description: This is the endpoint to Fetch properties for provider that needs
        them Direct charge API can be called. E.g Pawapay
      operationId: fetchDirectChargeProviderProperties
      parameters:
        - in: path
          name: provider
          schema:
            type: string
          required: true
          description: This is the provider slug. Find full list of providers here
            [Supported Providers](/docs/collections/direct-charge)
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    oneOf:
                      - $ref: "#/components/schemas/DirectChargeProviderPawapayPropertiesResponse"
  /billing/v1/transfer-recipients/{provider}/properties:
    get:
      tags:
        - Disbursements
      summary: Fetch Provider Properties
      description: This is the endpoint to Fetch properties for provider that needs
        them before a transfer recipient can be created. E.g Paystack (Bank
        Transfer)
      operationId: fetchTransferRecipientProviderProperties
      parameters:
        - in: path
          name: provider
          schema:
            type: string
          required: true
          description: This is the provider slug. Find full list of providers here
            [Supported Providers](/docs/disbursements)
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    oneOf:
                      - $ref: "#/components/schemas/TransferRecipientProviderBankListResponse"
                      - $ref: "#/components/schemas/TransferRecipientProviderPawapayPropertiesResponse"
  /billing/v1/transfer-recipients/validate:
    post:
      tags:
        - Disbursements
      summary: Validate A Transfer Recipient
      description: Create and Validate a Transfer Recipient for Disbursements
      operationId: validateTransferRecipient
      requestBody:
        description: Validate a Transfer Recipient
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidateTransferRecipientRequest"
        required: true
      responses:
        "201":
          description: Transfer Recipient Successfully Validated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/ValidateTransferRecipientResponse"
  /billing/v1/disbursements:
    post:
      tags:
        - Disbursements
      summary: Request a Disbursement
      description: Request a Disbursement to a Transfer Recipient
      operationId: RequestADisbursement
      requestBody:
        description: Request a Disbursement
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestDisbursementRequest"
        required: true
      responses:
        "201":
          description: Request for Disbursement Successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/RequestDisbursementResponse"
    get:
      tags:
        - Disbursements
      summary: Fetch All Disbursements Transaction
      description: Retrieve a paginated list of all disbursement transactions
      operationId: getAllDisbursements
      parameters:
        - in: query
          name: dateFrom
          schema:
            type: string
            format: date
            example: 2025-01-01
          description: Start date for filtering transactions (inclusive)
          required: false
        - in: query
          name: dateTo
          schema:
            type: string
            format: date
            example: 2025-03-31
          description: End date for filtering transactions (inclusive)
          required: false
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 4
          description: Number of records per page
      responses:
        "200":
          description: Successfully retrieved disbursements
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetAllDisbursements"
  /billing/v1/disbursements/verify/{reference}:
    get:
      tags:
        - Disbursements
      summary: Verify a Disbursement
      description: Verify a Disbursement
      operationId: VerifyADisbursement
      parameters:
        - in: path
          name: reference
          schema:
            type: string
          required: true
          description: Reference of the transaction to verify
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/VerifyDisbursementTransactionResponse"
  /billing/v1/wallets:
    get:
      tags:
        - Wallets
      summary: Fetch Wallets
      description: This is the endpoint to Fetch Wallet for a business
      operationId: fetchWallets
      parameters:
        - in: query
          name: country
          schema:
            $ref: "#/components/schemas/Country"
        - in: query
          name: currency
          schema:
            $ref: "#/components/schemas/Currency"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      $ref: "#/components/schemas/WalletBalanceResponse"
components:
  schemas:
    Amount:
      type: integer
      description: Amount should be in the subunit of the supported currency i.e value
        * 100. See [Amount Specification](/docs/concepts/amount-specification).
      format: int64
      example: 100000
      examples:
        - 100000
    Currency:
      type: string
      description: 3 character currency code
      example: USD, NGN, XOF, XAF
      examples:
        - NGN
        - USD
        - XOF
        - XAF
    Country:
      type: string
      description: 2 character country code
      example: US, NG, CI, SN, CA, UK
      examples:
        - NG
        - US
        - CI
        - SN
        - CA
        - UK
    Provider:
      type: string
      description: This is the provider we are validating the account against. Find
        full list of providers here [Supported Providers](/docs/disbursements)
      examples:
        - provider-slug
    IntegrationType:
      type: string
      description: Type of integration available for the provider.
      enum:
        - payment
        - collection
      example: payment
    Integration:
      type: object
      properties:
        id:
          type: string
          example: 6a68b195fa51e96ab2120d45
        clientId:
          type: string
          example: 6thbridge
        label:
          type: string
          example: MPesa
        provider:
          type: string
          description: Provider slug for the activated integration.
          example: mpesa-tanzania
        type:
          $ref: "#/components/schemas/IntegrationType"
        status:
          type: string
          example: active
        logo:
          type: string
          format: uri
          example: https://files.6thbridge.xyz/public/v1/files/payfusion/content/67dc6a5e0abc90dcd853e993
        description:
          type: string
          example: Send money, pay bills, access loans & more, all with your phone. M-Pesa
            is for everyone, fast, safe, affordable, and empowering.
        isOwnKeys:
          type: boolean
          example: false
        channels:
          type: array
          items:
            type: string
          example:
            - mobile-money
        currencies:
          type: array
          items:
            $ref: "#/components/schemas/Currency"
          example:
            - TZS
        currency:
          $ref: "#/components/schemas/Currency"
        country:
          $ref: "#/components/schemas/Country"
        chargeVersion:
          type: integer
          example: 1
        charge:
          type: object
          nullable: true
          additionalProperties: true
          example: null
        charges:
          type: array
          items:
            type: object
            additionalProperties: true
          example: []
        ownKeys:
          type: boolean
          example: false
    GetIntegrationsResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: "#/components/schemas/Integration"
    User:
      type: object
      properties:
        name:
          type: string
          description: customer's name
          example: Example User
          examples:
            - Example User
        email:
          type: string
          description: customer's email
          example: user@example.com
          format: email
          examples:
            - user@example.com
        phoneNumber:
          type: string
          description: customer's phone number
          example: "2347012345678"
          examples:
            - "2347012345678"
    Metadata:
      type: object
      properties:
        merchantName:
          type: string
          example: Karis Clothing
          examples:
            - Karis Clothing
        trafficType:
          type: string
          example: ECOMMERCE
          examples:
            - ECOMMERCE
    GenerateCheckoutURLRequest:
      required:
        - country
        - currency
        - user
        - amount
      type: object
      properties:
        country:
          $ref: "#/components/schemas/Country"
          examples:
            - NG
        currency:
          $ref: "#/components/schemas/Currency"
          description: This is the base currency to be charged in.
          examples:
            - NGN
        amount:
          $ref: "#/components/schemas/Amount"
          description: This is the amount to charge the customer. Amount should be sent in
            the lowest denomination e.g for 100 USD you should send 100 * 100 =
            10000. See [Amount
            Specification](/docs/concepts/amount-specification).
          examples:
            - 10000
        user:
          $ref: "#/components/schemas/User"
          required:
            - phoneNumber
        reference:
          type: string
          description: A reference code you'll generate to identify this transaction. This
            must be unique for every transaction. If you don't pass one, we will
            generate one for you.
        redirectURL:
          type: string
          format: uri
          description: Fully qualified URL to which the customer should be redirected
            after the payment is completed
          example: https://example.com/redirect/success
          examples:
            - https://example.com/redirect/success
        cancelURL:
          type: string
          format: uri
          description: Fully qualified URL to which the customer should be redirected if
            the cancel the payment session
          example: https://example.com/redirect/cancel
          examples:
            - https://example.com/redirect/cancel
        webhook:
          type: string
          format: uri
          description: This is a URL, if this is passed we will send the event webhook
            payload to this endpoint. Use this to override the webhook url
            provided on the dashboard for this transaction. Read more on
            [Webhooks](/docs/collections/webhook)
          example: https://example.com/webhook
          examples:
            - https://example.com/webhook
        metadata:
          $ref: "#/components/schemas/Metadata"
    DirectChargeAPIRequest:
      required:
        - provider
        - amount
        - customerInput
      type: object
      properties:
        provider:
          $ref: "#/components/schemas/Provider"
          description: This is the provider we are routing the request through. Find full
            list of providers here [Supported
            Providers](/docs/collections/direct-charge)
          examples:
            - airtel-smartcash-ng
            - mtn-momo-ivory-coast
        amount:
          $ref: "#/components/schemas/Amount"
          description: Amount should be sent in the lowest denomination e.g for 100 USD
            you should send 100 * 100 = 10000. See [Amount
            Specification](/docs/concepts/amount-specification).
        reference:
          type: string
          description: A reference code you'll generate to identify this transaction. This
            must be unique for every transaction. If you don't pass one, we will
            generate one for you.
        customerInput:
          type: object
          properties:
            phoneNumber:
              type: string
              description: customer's phone number
              example: "2347012345678"
              examples:
                - "2347012345678"
        redirectURL:
          type: string
          format: uri
          description: Fully qualified URL to which the customer should be redirected
            after the payment is completed
          example: https://example.com/redirect/success
          examples:
            - https://example.com/redirect/success
        webhook:
          type: string
          format: uri
          description: This is a URL, if this is passed we will send the event webhook
            payload to this endpoint. Use this to override the webhook url
            provided on the dashboard for this transaction. Read more on
            [Webhooks](/docs/collections/webhook)
          example: https://example.com/webhook
          examples:
            - https://example.com/webhook
        metadata:
          $ref: "#/components/schemas/Metadata"
    GenerateCheckoutURLResponse:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: This is the generated URL the customer should be redirected too for
            payment collection
          examples:
            - https://checkout.jgmepay.com/jgmepay/66579afe04916ddcfcf73e7b
        shortURL:
          type: string
          format: uri
          description: "This is a short version of the generated URL. PS: if you want to
            do a POST request redirection. Please use this"
          examples:
            - https://l.6bd.co/XXXXX
        reference:
          type: string
          description: Transaction Reference
        amount:
          $ref: "#/components/schemas/Amount"
        currency:
          $ref: "#/components/schemas/Currency"
    DirectChargeAPIResponse:
      type: object
      properties:
        reference:
          type: string
          description: Transaction Reference
        status:
          type: string
          description: Transaction Status
        sessionId:
          type: string
          description: Transaction Session ID. This is from the provider.
        amount:
          $ref: "#/components/schemas/Amount"
    DirectChargeConfirmRequest:
      required:
        - reference
        - customerInput
      type: object
      properties:
        reference:
          type: string
          description: Direct Charge transaction reference returned by the initial request.
          example: DDC20260702112401ZIWGF
        customerInput:
          type: object
          required:
            - otp
          properties:
            otp:
              type: string
              description: One-time password collected from the customer.
              example: "445985"
    DirectChargeConfirmResponse:
      type: object
      properties:
        action:
          type: string
          description: Next action required after customer input is submitted.
          example: processing
        sessionId:
          type: string
          description: Transaction session ID.
          example: cos-1z3x983b01300
        provider:
          type: string
          description: Provider slug processing the transaction.
          example: qmoney-gambia
        reference:
          type: string
          description: Transaction reference.
          example: DDC20260702115234PTIFG
        providersReference:
          type: string
          description: Provider-side transaction reference, when available.
          example: PIX_44241170102532681668
        amount:
          $ref: "#/components/schemas/Amount"
          example: 1000
        totalAmount:
          type: integer
          description: Total amount after charges. See [Amount
            Specification](/docs/concepts/amount-specification).
          example: 1000
        charge:
          type: integer
          description: Transaction charge.
          example: 0
        status:
          type: string
          description: Transaction status after customer input is submitted.
          example: pending
        data:
          type: object
          properties:
            message:
              type: string
              example: OTP submitted successfully. Payment confirmation is processing.
        statusDescription:
          type: string
          example: Awaiting Provider's Feedback
    DirectChargeConfirmEnvelope:
      required:
        - statusCode
        - data
      type: object
      properties:
        statusCode:
          type: integer
          description: Application status code returned in the response body.
          example: 201
        data:
          $ref: "#/components/schemas/DirectChargeConfirmResponse"
    VerifyTransactionResponse:
      type: object
      properties:
        clientId:
          type: string
          example: 6thbridge
        status:
          type: string
          description: Status of the transaction
          enum:
            - success
            - failed
            - pending
          example: success
        statusDescription:
          type: string
          example: SUCCESSFUL
        reference:
          type: string
          description: Transaction Reference
          example: DDC20260112090912SALGA
        externalReference:
          type: string
          description: This is the reference sent to us by the merchant when the
            transaction was created
          example: DDC20260112090912SALGA
        providersReference:
          type: string
          example: PIX_57688731248976662631
        currency:
          $ref: "#/components/schemas/Currency"
        charge:
          type: integer
          example: 5
        totalAmount:
          type: integer
          example: 1005
        amount:
          $ref: "#/components/schemas/Amount"
          example: 1000
        user:
          type: object
          properties:
            phoneNumber:
              type: string
              example: "+221786836369"
        metadata:
          type: object
          properties:
            trafficType:
              type: string
              example: CLOTHING
            merchantName:
              type: string
              example: Sample Name
            bankName:
              type: string
              example: CAPITEC BANK
            bankCode:
              type: string
              example: "4700"
        checkoutId:
          type: string
          example: 69651ca8bf1ff6b132d93a47
        provider:
          type: string
          example: wave-senegal
        providerLabel:
          type: string
          example: Wave
        channel:
          type: string
          example: mobile-money
        id:
          type: string
          example: 69651ca8bf1ff6b132d93a47
        paymentCard:
          type: string
          nullable: true
          default: null
        paidAt:
          type: integer
          description: Unix timestamp value for when payment was verified from the provider
          example: 1768234193
    DirectChargeProviderPawapayPropertiesResponse:
      properties:
        networks:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the Network
                example: Airtel
                examples:
                  - Airtel
              value:
                type: string
                description: Value to be sent back when validating a recipient
                example: airtel
                examples:
                  - airtel
    TransferRecipientProviderBankListResponse:
      properties:
        banks:
          type: array
          items:
            type: object
            properties:
              bankName:
                type: string
                description: Name of the bank
                example: Access Bank
                examples:
                  - Access Bank
              bankCode:
                type: string
                description: unique bank code
                example: "044"
                examples:
                  - "044"
    TransferRecipientProviderPawapayPropertiesResponse:
      properties:
        networks:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
                description: Name of the Network
                example: Airtel
                examples:
                  - Airtel
              value:
                type: string
                description: Value to be sent back when validating a recipient
                example: airtel
                examples:
                  - airtel
    MobileMoneyTransferRecipientAccount:
      required:
        - phoneNumber
      properties:
        phoneNumber:
          type: string
          description: customer's phone number
          example: "2347012345678"
          examples:
            - "2347012345678"
    PawapayMobileMoneyTransferRecipientAccount:
      required:
        - phoneNumber
        - network
      type: object
      properties:
        phoneNumber:
          type: string
          description: customer's phone number
          example: "2347012345678"
          examples:
            - "2347012345678"
        network:
          type: string
    BankAccountTransferRecipientAccount:
      required:
        - accountNumber
        - bankCode
      properties:
        accountNumber:
          type: string
          description: customer's account number
          example: "0123456789"
          examples:
            - "0123456789"
        bankCode:
          type: string
          description: customer's bank code. This can be gotten from
          example: "044"
          examples:
            - "044"
    ValidateTransferRecipientRequest:
      required:
        - currency
        - country
        - provider
        - account
      type: object
      properties:
        currency:
          $ref: "#/components/schemas/Currency"
        country:
          $ref: "#/components/schemas/Country"
        provider:
          $ref: "#/components/schemas/Provider"
        account:
          oneOf:
            - $ref: "#/components/schemas/MobileMoneyTransferRecipientAccount"
            - $ref: "#/components/schemas/PawapayMobileMoneyTransferRecipientAccount"
            - $ref: "#/components/schemas/BankAccountTransferRecipientAccount"
    ValidateTransferRecipientResponse:
      type: object
      properties:
        currency:
          $ref: "#/components/schemas/Currency"
        country:
          $ref: "#/components/schemas/Country"
        provider:
          $ref: "#/components/schemas/Provider"
        accountLabel:
          type: string
          description: This is a short label describing the transfer recipient
          example: Bank Transfer | Zenith Bank | Dummy User | 0123456789
          examples:
            - Bank Transfer | Zenith Bank | Dummy User | 0123456789
        account:
          anyOf:
            - $ref: "#/components/schemas/MobileMoneyTransferRecipientAccount"
            - $ref: "#/components/schemas/PawapayMobileMoneyTransferRecipientAccount"
            - $ref: "#/components/schemas/BankAccountTransferRecipientAccount"
    RequestDisbursementRequest:
      type: object
      required:
        - transferRecipientId
        - amount
      properties:
        reference:
          type: string
          description: A reference code you'll generate to identify this transaction. This
            must be unique for every transaction. If you don't pass one, we will
            generate one for you.
        transferRecipientId:
          type: string
          description: id of a transfer recipient gotten from the response of
            TransferRecipient Call
          example: 6659692f019f6a143f7f90db
          examples:
            - 6659692f019f6a143f7f90db
        amount:
          $ref: "#/components/schemas/Amount"
        narration:
          type: string
          example: Transfer of 100
          examples:
            - Transfer of 100
        pin:
          type: string
          description: This is your disbursement pin. This is a form of disbursement
            authorization. Alternative is an Authorization URL
        webhookURL:
          type: string
          format: uri
          description: This is a URL, if this is passed we will send the event webhook
            payload to this endpoint. Use this to override the webhook url
            provided on the dashboard for this transaction. Read more on
            [Webhooks](/docs/collections/webhook)
          example: https://example.com/webhook
          examples:
            - https://example.com/webhook
        metadata:
          $ref: "#/components/schemas/Metadata"
    RequestDisbursementResponse:
      type: object
      properties:
        reference:
          type: string
          description: A reference code you'll generate to identify this transaction. This
            must be unique for every transaction. If you don't pass one, we will
            generate one for you.
        amount:
          $ref: "#/components/schemas/Amount"
        amountPayable:
          $ref: "#/components/schemas/Amount"
          description: This signifies the actual amount sent to the recipient. See [Amount
            Specification](/docs/concepts/amount-specification).
        provider:
          $ref: "#/components/schemas/Provider"
        currency:
          $ref: "#/components/schemas/Currency"
        country:
          $ref: "#/components/schemas/Country"
        status:
          type: string
          enum:
            - processing
            - failed
            - success
    VerifyDisbursementTransactionResponse:
      type: object
      properties:
        status:
          type: string
          description: Status of the transaction
          enum:
            - success
            - failed
            - processing
          examples:
            - success
        reference:
          type: string
          description: Transaction Reference
        externalReference:
          type: string
          description: This is the reference sent to us by the merchant when the
            transaction was created
        amount:
          $ref: "#/components/schemas/Amount"
        currency:
          $ref: "#/components/schemas/Currency"
        user:
          $ref: "#/components/schemas/User"
        provider:
          $ref: "#/components/schemas/Provider"
    WalletBalanceResponse:
      type: object
      properties:
        type:
          type: string
          description: This is the type of wallet
          enum:
            - disbursement
            - deposit
          examples:
            - disbursement
            - deposit
        amount:
          $ref: "#/components/schemas/Amount"
          description: This signifies the actual amount in your wallet. This is in the
            lowest denomination. See [Amount
            Specification](/docs/concepts/amount-specification).
        currency:
          $ref: "#/components/schemas/Currency"
        country:
          $ref: "#/components/schemas/Country"
        status:
          type: string
          enum:
            - active
            - post-no-debit
    GetAllCheckoutResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 200
        total:
          type: integer
          description: Total number of records
          example: 1253
        page:
          type: integer
          description: Current page number
          example: 1
        pages:
          type: integer
          description: Total number of pages
          example: 314
        limit:
          type: integer
          description: Number of records per page
          example: 4
        data:
          type: array
          items:
            type: object
            properties:
              checkoutId:
                type: string
                example: 67ccca10721271b00713d4c3
              clientId:
                type: string
                example: payfusion
              provider:
                type: string
                nullable: true
                example: MTN MoMo
              providerLogo:
                type: string
                nullable: true
                example: https://seeklogo.com/images/M/mtn-logo-40644FC8B0-seeklogo.com.png
              channel:
                type: string
                nullable: true
                example: mobile-money
              reference:
                type: string
                example: D20250308225200TLWNG
              providersReference:
                type: string
                nullable: true
                example: "1690402150"
              currency:
                type: string
                example: KES
              amount:
                type: number
                example: 281400
              user:
                type: object
                properties:
                  name:
                    type: string
                    example: katigbanoma ent
                  email:
                    type: string
                    example: bidemi64@gmail.com
                  phoneNumber:
                    type: string
                    example: "+2348171633912"
              merchantFee:
                type: number
                example: 0
              customerFee:
                type: number
                example: 0
              merchantFeeLabel:
                type: string
                example: KES 0.00
              customerFeeLabel:
                type: string
                example: KES 0.00
              charge:
                type: number
                nullable: true
                example: 0
              paidAt:
                type: number
                nullable: true
                example: 1741188234
              status:
                type: string
                example: success
                enum:
                  - success
                  - abandoned
              availableBalance:
                type: number
                example: 0
              createdAt:
                type: string
                format: date-time
                example: 2025-03-08T22:52:00.729Z
    GetAllDisbursements:
      type: object
      properties:
        statusCode:
          type: integer
          example: 200
        total:
          type: integer
          description: Total number of records
          example: 58
        page:
          type: integer
          description: Current page number
          example: 1
        pages:
          type: integer
          description: Total number of pages
          example: 29
        limit:
          type: integer
          description: Number of records per page
          example: 2
        data:
          type: array
          items:
            type: object
            properties:
              clientId:
                type: string
                example: payfusion
              status:
                type: string
                example: success
              statusDescription:
                type: string
                example: success
              reference:
                type: string
                example: D20250303232852ZSWSJ
              providersReference:
                type: string
                example: pt-D20250303232852ZSWSJ
              externalReference:
                type: string
                example: D20250303231740IWYKI
              currency:
                type: string
                example: XOF
              country:
                type: string
                example: CI
              transferRecipientId:
                type: string
                example: 677696a160f343c392c0449d
              transferRecipientLabel:
                type: string
                example: Wave | +2250538102474
              charge:
                type: integer
                example: 11000
              amount:
                type: integer
                example: 100000
              provider:
                type: string
                example: wave-ivory-coast
              providerLabel:
                type: string
                example: Wave
              providerLogo:
                type: string
                format: uri
                example: https://docs.wave.com/images/business-penguin-a4539369.png
              channel:
                type: string
                example: mobile-money
              integrationId:
                type: string
                example: 6762bcccdd35fc1c7cae5bd6
              id:
                type: string
                example: 67c69da4099fde3f44c85345
  securitySchemes:
    clientId:
      type: apiKey
      name: client-id
      in: header
    clientSecret:
      type: apiKey
      name: client-secret
      in: header
security:
  - clientId: []
    clientSecret: []
