PreTUPS

API Endpoint

PreTUPS

Mobile networks commonly use PreTUPS (Prepaid Top-up Server) to handle integrations like ours. It is an XML-over-HTTP based protocol that facilitates direct topups if you have an account set up.

Note: This is generic documentation. Each specific integration will have its own instance if this service, with unique parameters set up. When interacting with a specific integration, you need to prefix the URL with the name of that service.

For example, the /directtopup endpoint below would be accessed as /safaricom-ke/directtopup for Safaricom subscribers in Kenya.

Direct topup

POST /pretups/directtopup/airtel
Requestsexample 1
Headers
Content-Type: application/json
X-Nomanini-Organisation: nomanini
Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
Body
{
  "msisdn": "27211234567",
  "amount": 1000,
  "source_reference": "314a0bb11871da1437aa"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "msisdn": {
      "type": "string",
      "pattern": "^(\\+[1-9]|[0-9])[0-9]{1,15}$",
      "description": "MSISDN number used to uniquely identify this person"
    },
    "amount": {
      "type": "number",
      "description": "The amount to recharge"
    },
    "source_reference": {
      "type": "string",
      "description": "An internal reference for the transaction. Should ideally be unique, but this is not a strict requirement. This will be converted to a 20 char sha1 hex digest."
    }
  },
  "additionalProperties": false,
  "required": [
    "msisdn",
    "amount",
    "source_reference"
  ]
}
Responses201
Body
{
  "external_transaction_id": "R170112.1419.220002"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "external_transaction_id": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "external_transaction_id"
  ]
}

Direct topup
POST/pretups/directtopup/{provider}

Perform a top up of a specific amount. Although the target is identified by an MSISDN, a number starting with a + will be accepted, and the + will be stripped off.

Permissions: pretups:admin

URI Parameters
HideShow
provider
string (required) Example: airtel

Balance

GET /pretups/balance/airtel
Requestsexample 1
Headers
Content-Type: application/json
X-Nomanini-Organisation: nomanini
Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
Responses200
Body
{
  "balance": 1050.2
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "balance": {
      "type": "number",
      "multipleOf": 0.01
    }
  },
  "additionalProperties": false,
  "required": [
    "balance"
  ]
}

Query current balance
GET/pretups/balance/{provider}

Get the last known balance.

Permissions: pretups:view

URI Parameters
HideShow
provider
string (required) Example: airtel

Generated by aglio on 09 May 2019