{
  "title": "Pesatrotal Merchant API \u2014 JSON samples",
  "version": "1.0.0",
  "updated": "2026-08-18",
  "hosts": {
    "sandbox": "https://sandbox.thetrotal.com",
    "production": "https://pesa.thetrotal.com"
  },
  "networks": [
    "MPESA_TZ",
    "AIRTEL_MONEY_TZ",
    "MIXX_BY_YAS_TZ",
    "HALOPESA_TZ",
    "AZAMPESA_TZ"
  ],
  "mpesa_ussd_steps": [
    "Select 1 to proceed",
    "Enter PIN",
    "Select 1 to confirm payment"
  ],
  "samples": {
    "oauth_token_response": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example",
      "token_type": "Bearer",
      "expires_in": 3600,
      "scope": "collections payment_links balances bills",
      "environment": "sandbox",
      "application_id": "2df41544-259a-455f-b345-63612b5307d6"
    },
    "collection_create_request": {
      "amount": 1000,
      "currency": "TZS",
      "msisdn": "255748778109",
      "network": "MPESA_TZ",
      "merchant_reference": "inv_48291",
      "description": "Invoice 48291",
      "customer_name": "Customer Name"
    },
    "collection_create_response_processing": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "merchant_reference": "inv_48291",
      "amount": 1000,
      "currency": "TZS",
      "msisdn": "255748778109",
      "network": "MPESA_TZ",
      "status": "PROCESSING",
      "external_id": "att_5f834f2279974bdaae9026d7f51272d1",
      "provider_transaction_id": "01a00fa73a9e731ba3794a6e5f6213bf"
    },
    "collection_create_response_succeeded": {
      "id": "9137a2bf-8352-4408-b7e1-b8ddcd8ccb43",
      "status": "SUCCEEDED",
      "amount": 1000,
      "currency": "TZS",
      "network": "HALOPESA_TZ"
    },
    "merchant_webhook_payment_succeeded": {
      "event": "payment.status_changed",
      "payment_id": "9137a2bf-8352-4408-b7e1-b8ddcd8ccb43",
      "status": "SUCCEEDED",
      "amount": 1000,
      "currency": "TZS",
      "direction": "collection"
    },
    "error_response": {
      "code": "validation_error",
      "message": "network must be one of MPESA_TZ, AIRTEL_MONEY_TZ, \u2026"
    },
    "provider_callback_success": {
      "message": "SUCCESS",
      "transactionstatus": "success",
      "operator": "Halopesa",
      "utilityref": "att_ef2f9346ead644009891a77e7878d3ca",
      "amount": "1000",
      "msisdn": "0621728109",
      "mnoreference": "260817wDbVV5rS4"
    },
    "provider_callback_failure_mpesa": {
      "message": "USSDCallbackCancel-Failed",
      "transactionstatus": "failure",
      "operator": "Mpesa",
      "utilityref": "att_5f834f2279974bdaae9026d7f51272d1",
      "amount": "1000",
      "msisdn": "0748778109",
      "mnoreference": "N/A"
    }
  },
  "endpoints": {
    "oauth_token": "POST /oauth/token",
    "create_collection": "POST /v1/collections",
    "get_collection": "GET /v1/collections/{id}",
    "list_collections": "GET /v1/collections",
    "balances": "GET /v1/balances?currency=TZS"
  }
}