Quick Start Guide

Get up and running in 5 minutes with this quick start guide.

Environments & Base URLs

Pagamio provides two environments for integration:

Sandbox Environment (Testing)

• Base URL: https://vas-sandbox-api.pagamio.tech/api/v1
• Portal: https://vas-sandbox.pagamio.tech
• Purpose: Testing and development
• Transactions: Simulated (no real money)
• Use when: Developing and testing your integration

Production Environment (Live)

• Base URL: https://vas-api.pagamio.tech/api/v1
• Portal: https://vas.pagamio.tech
• Purpose: Live transactions with real money
• Requirements: Approved merchant account
• Use when: Your integration is tested and ready for live transactions

tip

For this guide, we'll use the sandbox environment for safe testing. Simply change the BASE_URL to production when you're ready to go live.

Step 1: Set Your Credentials

Set up your Bearer token as an environment variable:

# Set your credentials
export PAGAMIO_BEARER_TOKEN="your_bearer_token_here"
export PAGAMIO_CHANNEL_ID="your_channel_id"
export BASE_URL="https://vas-sandbox-api.pagamio.tech/api/v1"

Step 2: Test Authentication

Verify your credentials by fetching the product categories:

curl -X GET $BASE_URL/products/categories \
  -H "Authorization: Bearer $PAGAMIO_BEARER_TOKEN"

Expected Response:

[
  {
    "id": 1001,
    "name": "Airtime",
    "imageUrl": "https://pagamio-assets.ams3.digitaloceanspaces.com/vas-uat/1756973467304-1756973463756_1q3x24.png",
    "orderOfAppearance": 1,
    "parentId": null,
    "meta": {
      "fields": [
        { "name": "amount", "type": "number", "required": true },
        { "name": "mobileNumber", "type": "string", "required": true },
        { "name": "paymentMethod", "type": "string", "required": true }
      ],
      "receiptFields": [
        "rechargeDetails.rechargeType",
        "rechargeDetails.callCentre",
        "rechargeDetails.rechargeVendor",
        "amount"
      ]
    }
  },
  {
    "id": 1003,
    "name": "Electricity",
    "imageUrl": "https://i.postimg.cc/4x8KsmZq/electricity.jpg",
    "orderOfAppearance": 3,
    "parentId": null,
    "meta": {
      "fields": [
        { "name": "meterNumber", "type": "string", "required": true },
        { "name": "amount", "type": "number", "required": true },
        { "name": "paymentMethod", "type": "string", "required": true }
      ],
      "receiptFields": [
        "meterInfo.meterNumber",
        "billingInfo.units",
        "tokens[0].token"
      ]
    }
  }
]

Note: The response above shows only a subset of categories for illustration. The actual API response will include all available categories in the system.

Step 3: Make Your First Purchase

Purchase R5 Cellc Data:

curl -X POST $BASE_URL/purchase \
  -H "Authorization: Bearer $PAGAMIO_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "DAT-CLC-001",
    "amount": 5,
    "mobileNumber": "840012300",
    "paymentMethod" : "cash",
    "channelId": "'$PAGAMIO_CHANNEL_ID'"
  }'

Expected Response:

{
    "transactionId": "3d8c7882-1eba-480e-877c-b79b0b7a8777",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-10-21T10:15:16.018555017",
    "successful": true,
    "receipt": {
        "amount": 500,
        "aggregator": "BLUE_LABEL"
    }
}

Next Steps

Now that you've made your first successful transaction:

1. Explore the API Reference for all available endpoints
2. Review Integration Guides for best practices
3. Test different Product Categories
4. Set up Webhook Configuration for real-time updates

---

Last updated: October 2025