Skip to content
PayHero Africa

Quickstart

This walks through a first collection (pay-in) in Uganda. For the full path to production, see the Integration guide.

  1. Set your credentials from the dashboard:

    Terminal window
    export PH_API_USERNAME="your-username"
    export PH_API_PASSWORD="your-password"
    export PH_BASE_URL="https://api.payhero.africa"

  2. Discover what Uganda supports:

    Terminal window
    curl "$PH_BASE_URL/api/global/discovery/discover-rails?country=UG" \
      -u "$PH_API_USERNAME:$PH_API_PASSWORD"

    If available_providers is empty, your account has no providers enabled yet — ask PayHero to enable them before continuing.

  3. Choose a rail that is true in rails, a provider code from available_providers, and a network from provider_networks with ramp_type: deposit.

  4. Create the collection, copying the network into provider_config. Note that account_type takes the network’s channel_type:

    Terminal window
    curl -X POST "$PH_BASE_URL/api/global/payments" \
      -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
      -H "Content-Type: application/json" \
      -d '{
        "request_type": "payment",
        "transaction_channel": "momo",
        "provider": "yc",
        "amount": 20000,
        "currency": "UGX",
        "country": "UG",
        "customer": {
          "first_name": "Jane",
          "last_name": "Mukasa",
          "email": "jane@example.com",
          "phone": "+256769759910",
          "country": "UG"
        },
        "vendor_config": { "vendor_id": 63 },
        "provider_config": {
          "network_id": "04a3083a-567c-4a2b-aa39-fa8f19e64341",
          "network_name": "Airtel Mobile Money",
          "network_code": "AIRTEL_UGANDA",
          "channel_id": "e167def0-c4f0-46e2-aaa9-50046f13b0a7",
          "account_type": "momo"
        },
        "payment_config": {
          "reference": "first_collection_001",
          "account_number": "+256769759910",
          "callback_url": "https://your-system.com/webhooks/payhero"
        }
      }'

  5. Read the response. A 200 with a merchant_reference means the payment started:

    {
      "status_code": "200",
      "merchant_reference": "9FD194041588.iI",
      "transaction_type": "payin",
      "success": true,
      "message": "request sent",
      "checkout_request_id": "a8e1c979-3592-5abd-b1cd-dc1dbd34e708"
    }

  6. Wait for the callback. The payer approves the prompt on their phone, and the final result is POSTed to your callback_url. See Callbacks & Webhooks.