Skip to content
PayHero Africa

Quickstart

This guide walks you through your first collection (pay-in).

  1. Get your API key from the dashboard and set it as environment variables:

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

  2. Discover available providers for your country so you know which provider and provider_config to use:

    Terminal window
    curl "$PH_BASE_URL/api/global/discovery/payment-world/country?country=KE" \
      -u "$PH_API_USERNAME:$PH_API_PASSWORD"

  3. Create a collection with request_type: payment:

    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": "yellowcard",
        "amount": 5500,
        "currency": "KES",
        "country": "KE",
        "reason": "Order payment for invoice INV-2025-001",
        "source": "api",
        "customer": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "phone": "+254712345678",
          "country": "KE"
        },
        "vendor_config": { "vendor_id": 63 },
        "payment_config": {
          "account_number": "+254712345678",
          "callback_url": "https://your-system.com/webhooks/payhero"
        }
      }'

  4. Handle the response. A 200 means the request was accepted and queued:

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

  5. Wait for the callback. The final result is POSTed to your callback_url. See Callbacks & Webhooks.