> ## 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.

# Bpay collection simulator

> Test your payment collection callback with the Beem sandbox simulator.

<Info>
  Your callback URL must be **publicly reachable over HTTPS**. The simulator forwards each request to your endpoint via `https://paysim.beem.africa/`.
</Info>

***

## How to use

<Steps>
  <Step title="Choose a network example">
    Pick **Tigo**, **Airtel**, or **Vodacom** from the examples dropdown. Each sets the correct `network_name` and `mnc_network`.
  </Step>

  <Step title="Set your callback URL">
    Replace `callbackUrl` with your publicly accessible endpoint, then click **Try it**.
  </Step>

  <Step title="Verify your handler">
    Confirm your server returns HTTP 200 with `{ "transaction_id": "...", "successful": "true" }`.
  </Step>
</Steps>

***

## Related

* [Callbacks](/guides/payments-collection/callbacks) — implement your handler
* [Receive payment collection callback](/api-reference/payments-collection/receive-payment-collection-callback) — production callback format


## OpenAPI

````yaml openapi/payments-collection.json POST /
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:
  /:
    post:
      summary: Bpay collection simulator
      description: >-
        Send a test payment collection payload through the Beem sandbox proxy.
        The simulator forwards the request to your callback URL. Set
        `mnc_network` to match your network: 2 for Tigo, 5 for Airtel, 4 for
        Vodacom.
      operationId: bpayCollectionSimulator
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - network_name
                - subscriber_msisdn
                - paybill_number
                - amount_collected
                - reference_number
                - callbackUrl
                - transaction_id
                - timestamp
                - mcc_network
                - mnc_network
                - source_currency
                - target_currency
              properties:
                network_name:
                  type: string
                  enum:
                    - tigotz
                    - airteltz
                    - vodacomtz
                  description: Mobile network operator to simulate.
                subscriber_msisdn:
                  type: string
                  description: Subscriber phone number (12 digits).
                  example: '255673089337'
                paybill_number:
                  type: string
                  description: Merchant or paybill number receiving the payment.
                  example: '123456789098'
                amount_collected:
                  type: string
                  description: Payment amount in Tanzanian shillings.
                  example: '105000'
                reference_number:
                  type: string
                  description: Reference number entered by the subscriber.
                  example: '123455555558'
                callbackUrl:
                  type: string
                  format: uri
                  description: >-
                    Your publicly accessible collection callback endpoint
                    (HTTPS).
                  example: https://your-app.example.com/payment/callback
                transaction_id:
                  type: string
                  description: Unique transaction ID for this test payment.
                  example: a1b2c3d4-e5f6-4789-a012-3456789abcde
                timestamp:
                  type: string
                  format: date-time
                  description: Transaction timestamp (ISO 8601).
                  example: '2024-09-05T10:00:00.000Z'
                mcc_network:
                  type: integer
                  description: Mobile country code. Use 640 for Tanzania.
                  example: 640
                mnc_network:
                  type: integer
                  description: 'Mobile network code: 2 (Tigo), 5 (Airtel), 4 (Vodacom).'
                  example: 2
                source_currency:
                  type: string
                  description: ISO currency code for sending money.
                  example: TZS
                target_currency:
                  type: string
                  description: ISO currency code for receiving money.
                  example: TZS
            examples:
              tigoPayment:
                summary: Tigo collection test
                value:
                  network_name: tigotz
                  subscriber_msisdn: '255673089337'
                  paybill_number: '123456789098'
                  amount_collected: '105000'
                  reference_number: '123455555558'
                  callbackUrl: https://your-app.example.com/payment/callback
                  mcc_network: 640
                  mnc_network: 2
                  target_currency: TZS
                  source_currency: TZS
                  timestamp: '2024-09-05T10:00:00.000Z'
                  transaction_id: a1b2c3d4-e5f6-4789-a012-3456789abcde
              airtelPayment:
                summary: Airtel collection test
                value:
                  network_name: airteltz
                  subscriber_msisdn: '255673089337'
                  paybill_number: '123456789098'
                  amount_collected: '105000'
                  reference_number: '123455555558'
                  callbackUrl: https://your-app.example.com/payment/callback
                  mcc_network: 640
                  mnc_network: 5
                  target_currency: TZS
                  source_currency: TZS
                  timestamp: '2024-09-05T10:00:00.000Z'
                  transaction_id: b2c3d4e5-f6a7-4890-b123-456789abcdef0
              vodacomPayment:
                summary: Vodacom collection test
                value:
                  network_name: vodacomtz
                  subscriber_msisdn: '255673089337'
                  paybill_number: '123456789098'
                  amount_collected: '105000'
                  reference_number: '123455555558'
                  callbackUrl: https://your-app.example.com/payment/callback
                  mcc_network: 640
                  mnc_network: 4
                  target_currency: TZS
                  source_currency: TZS
                  timestamp: '2024-09-05T10:00:00.000Z'
                  transaction_id: c3d4e5f6-a7b8-4901-c234-567890abcdef1
      responses:
        '200':
          description: Response from your callback handler
          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://paysim.beem.africa
          description: Beem Bpay sandbox proxy

````