Getting Started

Create a Payonify Account

Go to payonify.co.zw and click Sign Up. Enter your email address and create a password.

Create Your First Project

After signing up, you'll be guided through creating your first project:

• Step 1: Enter your project name, description, and select the project type:

  • pos - Point of Sale
  • web - Web application
  • mobile - Mobile application
  • ussd - USSD application

• Step 2: Choose your mobile money merchant:

  • Use Payonify's test merchant (recommended for getting started)
  • Or add your own merchant credentials

• Step 3: Add a webhook URL to receive payment notifications (e.g., https://yourapp.com/webhooks/payonify)

Get Your API Keys

Once your project is created, you'll be taken to the dashboard where you can access your API keys:

• Navigate to Developer Settings > API Keys
• Copy your test keys:
  • Publishable Key (pk_test_...) - Identifies your account
  • Secret Key (sk_test_...) - Authenticates API requests

A verification email will be sent to confirm your email address, but you can start using the API immediately.

Make Your First API Request

Test your API keys by listing charges:

Code
 
curl https://api.payonify.com/v1/charges \
  -u "pk_test_abc123...:sk_test_xyz789..."

Response:

Response
 
{
  "object": "list",
  "data": [],
  "paging": {
    "has_previous_page": false,
    "has_next_page": false,
    "start_cursor": null,
    "end_cursor": null,
    "page_size": 10
  }
}

Process a Test Payment

Create your first charge using EcoCash mobile money:

Code
 
curl https://api.payonify.com/v1/charges \
  -u "pk_test_abc123...:sk_test_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 6605,
    "currency": "usd",
    "source": "pos",
    "description": "Small Granite Chips",
    "payment_method": {
      "mobile_money": {
        "ecocash": {
          "mobile_number": "771111111"
        }
      }
    },
    "metadata": {
      "order_id": "7",
      "order_description": "Ergonomic Granite Shoes"
    },
    "receipt_email": "Mathias_Hane@yahoo.com",
    "shipping": {
      "name": "Caroline",
      "carrier": "Fedex",
      "tracking_number": "6n0hk430kpyuvl5dhb7f",
      "phone": "1-732-402-2396",
      "address": {
        "city": "Aleenmouth",
        "country": "ZW",
        "line1": "658 Goldner Spur",
        "line2": "Apt. 820",
        "province": "Texas"
      }
    },
    "return_url": "http://irving.net",
    "statement_descriptor": "bifurcated",
    "confirm": true
  }'

Response:

Response
 
{
  "id": "ch_a7eryb3kdb6ljkzqe5vg3jbf",
  "object": "charge",
  "status": "requires_authorization",
  "amount": {
    "value": 6605,
    "currency": "usd"
  },
  "description": "Small Granite Chips",
  "metadata": {
    "order_id": "7",
    "order_description": "Ergonomic Granite Shoes"
  },
  "paid": false,
  "payment_method": "mobile_money",
  "receipt_email": "Mathias_Hane@yahoo.com",
  "return_url": "http://irving.net",
  "shipping": {
    "name": "Caroline",
    "carrier": "Fedex",
    "tracking_number": "6n0hk430kpyuvl5dhb7f",
    "phone": "1-732-402-2396",
    "address": {
      "city": "Aleenmouth",
      "country": "ZW",
      "line1": "658 Goldner Spur",
      "line2": "Apt. 820",
      "province": "Texas"
    }
  },
  "statement_descriptor": "bifurcated",
  "client_secret": "ch_a7eryb3kdb6ljkzqe5vg3jbf_secret_egb5nyqrkjifmg6t6rttf4kdxpaltlpr",
  "livemode": "false",
  "payment_method_details": {
    "type": "mobile_money",
    "mobile_money": {
      "type": "c2b",
      "brand": "ecocash",
      "customer_number": "771111111",
      "merchant_code": "028538",
      "merchant_number": "789643586",
      "merchant_name": "Payonify Test Merchant",
      "head_name": "Payonify Test Merchant",
      "network": "Econet",
      "reference": null
    }
  },
  "created": 1763144144,
  "cancelled_at": null,
  "cancellation_reason": null,
  "refund_reference": null
}

The charge is created with status requires_authorization, meaning it's waiting for the customer to authorize the payment on their mobile phone.

Receive Webhook Notification

When the customer authorizes the payment, Payonify sends a webhook event to your configured URL:

Webhook Event
 
{
  "id": "evt_tlm32crpf2yx6sih5ffa",
  "object": "event",
  "type": "charge.succeeded",
  "created": 1763144160,
  "livemode": "false",
  "data": {
    "object": {
      "id": "ch_a7eryb3kdb6ljkzqe5vg3jbf",
      "object": "charge",
      "status": "succeeded",
      "amount": {
        "value": 6605,
        "currency": "usd"
      },
      "description": "Small Granite Chips",
      "metadata": {
        "order_id": "7",
        "order_description": "Ergonomic Granite Shoes"
      },
      "paid": true,
      "payment_method": "mobile_money",
      "receipt_email": "Mathias_Hane@yahoo.com",
      "return_url": "http://irving.net",
      "shipping": {
        "name": "Caroline",
        "carrier": "Fedex",
        "tracking_number": "6n0hk430kpyuvl5dhb7f",
        "phone": "1-732-402-2396",
        "address": {
          "city": "Aleenmouth",
          "country": "ZW",
          "line1": "658 Goldner Spur",
          "line2": "Apt. 820",
          "province": "Texas"
        }
      },
      "statement_descriptor": "bifurcated",
      "client_secret": "ch_a7eryb3kdb6ljkzqe5vg3jbf_secret_egb5nyqrkjifmg6t6rttf4kdxpaltlpr",
      "livemode": "false",
      "failure_code": null,
      "failure_reason": null,
      "payment_method_details": {
        "type": "mobile_money",
        "mobile_money": {
          "type": "c2b",
          "brand": "ecocash",
          "customer_number": "771111111",
          "merchant_code": "028538",
          "merchant_number": "789643586",
          "merchant_name": "Payonify Test Merchant",
          "head_name": "Payonify Test Merchant",
          "network": "Econet",
          "reference": "MP251122.1330.F11728"
        }
      },
      "created": 1763144144,
      "cancelled_at": null,
      "cancellation_reason": null,
      "refund_reference": null
    }
  }
}

The charge.succeeded event confirms the payment was successful. The payment_method_details.mobile_money.reference contains the transaction reference from EcoCash.