Purchase

This is the main endpoint of the API and allows purchase of all types of products, from different categories and vendors.

Description: Process a VAS purchase transaction

Path: POST /purchase

Authentication Required: ✅

Who Can Call This Endpoint

Only users at the Merchant or Sub-Merchant level can call /purchase. Partner and Vendor users will receive 403 Forbidden. See Access & Permissions.

Product Eligibility

You can only purchase products that are active under your merchant account. Attempts to purchase any other product return responseCode: "1009" (This product is not available for your account). See Product Availability.

Use the product catalog endpoints to discover what is available to you.

Headers

Authorization: Bearer <YOUR_BEARER_TOKEN>
Content-Type: application/json

Request Body

{
  "productCode": "AIR-VOD-001",
  "amount": 50.0,
  "mobileNumber": "+27821234567",
  "paymentMethod": "cash",
  "channelId": "YOUR_CHANNEL_ID",
  "meterNumber": "0008958825192",
  "merchantReference": "INV-2026-04-000123",
  "additionalInfo": {
    "additionalProp1": "string",
    "additionalProp2": "string"
  }
}

Field	Required	Description
productCode	Yes	Code of the product to purchase. See Product Code Format.
amount	Yes	Amount in ZAR. Must be within the product's minAmount/maxAmount (or match fixedAmount).
mobileNumber	Cond.	Customer mobile number in +27... format. Required for airtime, data, SMS, etc.
meterNumber	Cond.	Required for electricity products.
paymentMethod	Yes	Payment method (e.g. cash).
channelId	Yes	Your channel identifier. See How To Find Your Channel ID below.
merchantReference	Yes	Acts as the idempotency key. See Idempotency below.
additionalInfo	No	Optional key/value object for any additional information needed by the product.

For products in other categories, additional fields may be required. Always call GET /products/categories/{categoryId}/fields to discover what fields are required for a given product.

How To Find Your Channel ID

Your channelId is shown in the Pagamio merchant dashboard:

Sign in → My User → Channels tab

If you have multiple channels, use the channel that matches the integration you're building. If your account has only one channel, use that one.

Idempotency

The merchantReference field is the idempotency key for the purchase endpoint.

• Always set a unique merchantReference per logical purchase attempt. A UUID or your own deterministic reference (e.g. "INV-2026-04-000123") is recommended.
• If you submit a request with a merchantReference that has been used before, the API returns the result of the original transaction instead of creating a new one. This makes it safe to retry on network errors.
• Do not reuse a merchantReference for a different purchase. Reuse implies "this is the same transaction I already submitted".

For a full retry pattern, see the Idempotency & Retries guide.

Success Response (200 OK)

{
  "transactionId": "b9871532-3252-4920-b99e-081dc1488494",
  "responseCode": "0",
  "responseMessage": "Purchase successful",
  "responseDateTime": "2026-04-21T12:57:51.831786006",
  "successful": true,
  "receipt": {
    "amount": 50.0,
    "reference": "b9871532-3252-4920-b99e-081dc1488494",
    "pin": "1234567890",
    "serialNumber": "SN123456",
    "expiryDate": "2025-12-31"
  }
}

Electricity Products

{
    "transactionId": "bdf82429-9ab5-4f1a-bb9a-e469f4f05f05",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-10-21T12:57:51.831786006",
    "successful": true,
    "receipt": {
        "unitType": "kWh",
        "units": 100,
        "transactionNumber": 5346883805,
        "receiptNumber": "16252/861882",
        "taxAmount": 18.42,
        "exclusiveAmount": 150,
        "name": "Test Utility",
        "address": "27 Meteren Crescent Avondale",
        "meterNumber": "0008958825192",
        "token": "12341234123412341234",
        "tokenDescription": "FBE Token",
        "amount": 3000,
        "aggregator": "FLASH"
    }
}

Error Responses

Insufficient balance:

{
  "responseCode": "1103",
  "responseMessage": "Insufficient balance. Available: R0.00"
}

Product not available for your account:

{
  "responseCode": "1009",
  "responseMessage": "This product is not available for your account",
  "rejectionCode": "1009",
  "rejectionReason": "This product is not available for your account"
}

For the full list of error codes, see the Error Code Reference.

Non-Terminal Responses

If the response returns responseCode: "PENDING" or "PROCESSING" (or HTTP 202 Accepted), the transaction is in flight. Poll POST /transactions with the transactionId until the status reaches a terminal state (COMPLETED or FAILED).

---

Last updated: April 2026