openapi: 3.0.1
info:
  title: Africa's Talking Airtime Payments API
  description: 'Unified REST API for Africa''s Talking communications products: SMS (single, bulk, premium, subscriptions), USSD callbacks, Voice (call, transfer, media upload, queue status), Airtime, Mobile Data, and Payments (mobile C2B checkout, B2C, B2B). Requests authenticate with an `apiKey` header and a `username` parameter. Hosts differ per product: messaging, airtime, and subscriptions live under api.africastalking.com/version1; voice under voice.africastalking.com; mobile data under bundles.africastalking.com; and payments under payments.africastalking.com. Sandbox equivalents insert `.sandbox.` into each host.'
  termsOfService: https://africastalking.com/terms
  contact:
    name: Africa's Talking Support
    url: https://help.africastalking.com
  version: version1
servers:
- url: https://api.africastalking.com/version1
  description: Messaging, Airtime and Subscription production host
- url: https://api.sandbox.africastalking.com/version1
  description: Messaging, Airtime and Subscription sandbox host
- url: https://voice.africastalking.com
  description: Voice production host
- url: https://bundles.africastalking.com
  description: Mobile Data production host
- url: https://payments.africastalking.com
  description: Payments production host
security:
- apiKey: []
tags:
- name: Payments
  description: Mobile C2B checkout, B2C, and B2B mobile money transfers.
paths:
  /mobile/checkout/request:
    post:
      operationId: mobileCheckout
      tags:
      - Payments
      summary: Mobile C2B checkout
      description: Initiate a mobile money checkout (customer-to-business) prompting the subscriber to authorize payment. Served from payments.africastalking.com.
      servers:
      - url: https://payments.africastalking.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileCheckoutRequest'
      responses:
        '201':
          description: Checkout initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileCheckoutResponse'
  /mobile/b2c/request:
    post:
      operationId: mobileB2C
      tags:
      - Payments
      summary: Mobile B2C payment
      description: Send money from your payment wallet to one or more mobile subscribers.
      servers:
      - url: https://payments.africastalking.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileB2CRequest'
      responses:
        '201':
          description: B2C request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileB2CResponse'
  /mobile/b2b/request:
    post:
      operationId: mobileB2B
      tags:
      - Payments
      summary: Mobile B2B payment
      description: Send money from your business to another business over mobile money rails.
      servers:
      - url: https://payments.africastalking.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileB2BRequest'
      responses:
        '201':
          description: B2B request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileB2BResponse'
components:
  schemas:
    MobileB2BResponse:
      type: object
      properties:
        status:
          type: string
          example: Queued
        transactionId:
          type: string
        transactionFee:
          type: string
        providerChannel:
          type: string
    MobileB2CRequest:
      type: object
      required:
      - username
      - productName
      - recipients
      properties:
        username:
          type: string
        productName:
          type: string
        recipients:
          type: array
          items:
            type: object
            required:
            - phoneNumber
            - currencyCode
            - amount
            properties:
              phoneNumber:
                type: string
              currencyCode:
                type: string
                example: KES
              amount:
                type: number
              reason:
                type: string
                description: Purpose of payment, e.g. SalaryPayment, BusinessPayment.
              metadata:
                type: object
                additionalProperties:
                  type: string
    MobileB2BRequest:
      type: object
      required:
      - username
      - productName
      - provider
      - transferType
      - currencyCode
      - amount
      - destinationChannel
      - destinationAccount
      properties:
        username:
          type: string
        productName:
          type: string
        provider:
          type: string
          description: Mobile money provider, e.g. Mpesa, Athena.
        transferType:
          type: string
          description: e.g. BusinessBuyGoods, BusinessPayBill, DisburseFundsToBusiness, BusinessToBusinessTransfer.
        currencyCode:
          type: string
          example: KES
        amount:
          type: number
        destinationChannel:
          type: string
          description: Paybill or till channel of the receiving business.
        destinationAccount:
          type: string
          description: Account name of the receiving business.
        metadata:
          type: object
          additionalProperties:
            type: string
    MobileCheckoutRequest:
      type: object
      required:
      - username
      - productName
      - phoneNumber
      - currencyCode
      - amount
      properties:
        username:
          type: string
        productName:
          type: string
        phoneNumber:
          type: string
          example: +254711XXXYYY
        currencyCode:
          type: string
          description: 3-letter ISO currency code.
          example: KES
        amount:
          type: number
          example: 100.5
        providerChannel:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
    MobileCheckoutResponse:
      type: object
      properties:
        status:
          type: string
          example: PendingConfirmation
        description:
          type: string
          example: Waiting for user input
        transactionId:
          type: string
          example: ATPid_SampleTxnId123
    MobileB2CResponse:
      type: object
      properties:
        numQueued:
          type: integer
          example: 1
        totalValue:
          type: string
          example: KES 100.0000
        totalTransactionFee:
          type: string
        entries:
          type: array
          items:
            type: object
            properties:
              phoneNumber:
                type: string
              status:
                type: string
                example: Queued
              provider:
                type: string
              providerChannel:
                type: string
              value:
                type: string
              transactionId:
                type: string
              transactionFee:
                type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: apiKey
      description: Africa's Talking API key generated from your account dashboard.