> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beem.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Receive payment collection callback

> Webhook your application must implement. When a subscriber initiates a mobile money payment, Bpay POSTs transaction details to your callback URL. Respond with successful true to accept or false to decline. Replace the server URL with your own HTTPS endpoint.



## OpenAPI

````yaml /openapi/payments-collection.json post /callback
openapi: 3.0.3
info:
  title: Beem Payments Collection API
  version: 1.0.0
  description: >-
    Bpay Payments Collection: customer-hosted payment callbacks and credit
    balance checks via the shared Topup service (app_name=BPAY).
  contact:
    name: Beem
    url: https://beem.africa
    email: support@beem.africa
servers:
  - url: https://apitopup.beem.africa/v1
    description: Topup API — credit balance
security: []
tags: []
paths:
  /callback:
    post:
      summary: Receive payment collection callback
      description: >-
        Webhook your application must implement. When a subscriber initiates a
        mobile money payment, Bpay POSTs transaction details to your callback
        URL. Respond with successful true to accept or false to decline. Replace
        the server URL with your own HTTPS endpoint.
      operationId: receivePaymentCollectionCallback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - transaction_id
                - amount_collected
                - source_currency
                - target_currency
                - subscriber_msisdn
                - reference_number
                - paybill_number
                - timestamp
                - mcc_network
                - mnc_network
                - network_name
              properties:
                transaction_id:
                  type: string
                  description: Unique transaction ID generated by Beem.
                amount_collected:
                  type: string
                  description: Amount of money collected from the subscriber.
                source_currency:
                  type: string
                  description: ISO currency code for sending money (default TZS).
                target_currency:
                  type: string
                  description: ISO currency code for receiving money (default TZS).
                subscriber_msisdn:
                  type: string
                  description: >-
                    Subscriber mobile number in international format without the
                    plus symbol, e.g. 255444444444.
                reference_number:
                  type: string
                  description: Reference number entered by the subscriber.
                paybill_number:
                  type: string
                  description: Merchant or paybill number the payment was received into.
                timestamp:
                  type: string
                  description: Transaction timestamp (ISO 8601).
                mcc_network:
                  type: integer
                  description: Mobile country code identifying the network.
                mnc_network:
                  type: integer
                  description: Mobile network code identifying the network.
                network_name:
                  type: string
                  description: Carrier name, e.g. tigotz, airteltz, vodacomtz.
            examples:
              vodacomPayment:
                summary: Vodacom collection callback
                value:
                  transaction_id: 121w
                  amount_collected: '4000'
                  source_currency: TZS
                  target_currency: TZS
                  subscriber_msisdn: '2557777777'
                  reference_number: 6cc545R
                  paybill_number: '2233'
                  timestamp: '2024-09-05T10:00:00.000Z'
                  mcc_network: 640
                  mnc_network: 4
                  network_name: vodacomtz
              tigoPayment:
                summary: Tigo collection callback
                value:
                  transaction_id: a1b2c3d4-e5f6-4789-a012-3456789abcde
                  amount_collected: '105000'
                  source_currency: TZS
                  target_currency: TZS
                  subscriber_msisdn: '255673089337'
                  reference_number: '123455555558'
                  paybill_number: '123456789098'
                  timestamp: '2024-09-05T10:00:00.000Z'
                  mcc_network: 640
                  mnc_network: 2
                  network_name: tigotz
      responses:
        '200':
          description: Acknowledge and accept or reject the payment
          content:
            application/json:
              schema:
                type: object
                required:
                  - transaction_id
                  - successful
                properties:
                  transaction_id:
                    type: string
                    description: Echo the transaction_id from the callback request.
                  successful:
                    type: string
                    enum:
                      - 'true'
                      - 'false'
                    description: >-
                      Set to true to accept the payment. If false, the
                      transaction is declined and funds are refunded to the
                      subscriber.
              examples:
                accepted:
                  summary: Accept transaction
                  value:
                    transaction_id: 121w
                    successful: 'true'
                rejected:
                  summary: Reject transaction
                  value:
                    transaction_id: 121w
                    successful: 'false'
      servers:
        - url: https://example.com
          description: Your callback server — replace with your URL

````