With this service, the calling app can collect a payment and top up a customer’s mobile number with airtime at the same time. It uses the authorisation details supplied by the customer as well as a code to (optionally) identify the Telco. Apps will collect authorisation details and forward to OnePipe to execute a debit and topup, OnePipe will in turn forward to the provider’s dedicated implementation. Supported auth types vary by provider.

Before you proceed: Please read this.

Commercial model

Option 1: Providers will pay the commissions due the app directly to the app while OnePipe just charges a fee per API call.
Option 2: Providers send the due commission to OnePipe (via the host settlement account) for onward split with all parties.

Special configuration notes

All providers of this service should implement OTP, but support the configuration of otp_override such that based on this configuration, they could be instructed to bypass the OTP requirement for an app if they support such configuration.

Settlement & fees model

Depending on the provider implementation, this service supports any or both of the 2 models.

Model	How it works

Model	How it works
Commission	The provider surcharges the payer with an extra fee and pays a share of that surcharge to the app owner, OnePipe and Client. Or, the provider doesn’t apply a surcharge but rather just pays a percentage of the amount as commission to the app owner, OnePipe and Client.
Invoice	The client will invoice the calling app periodically for all calls to the endpoint.

Process flows

Sequence of calls

App [optionally] calls /transact/options to get a list of products available by the provider for the biller or Telco
App calls /transact with the right auth details
Provider responds with WaitingForOTP or PendingValidation as may be required
App calls /transact/validate to supply OTP if needed
Provider responds with any of the completion codes Successful or Failed.
To query the status of a transaction, the app can call /transact/query
Where the provider supports it, the app can call /transact/reverse to request a reversal

Interface specification - (App → OnePipe)

Request (/transact)

{
  "request_ref":"{{request-ref}}", 
  "request_type":"buy_airtime",
  "auth": {
    "type": "bank.account | card | wallet | airtime | token", 
    "secure": "{{encrypted secure}}",
    "auth_provider": "Beeceptor",
    "route_mode":"provider | options | null"
  },
  "transaction": {
    "mock_mode": "live", 
    "transaction_ref": "{{transaction-ref}}", 
    "transaction_desc": "A random transaction", 
    "transaction_ref_parent": "", 
    "amount": 10000,
    "customer":{
    	"customer_ref": "{{customer id}}",
    	"firstname": "Uju",
        "surname": "Usmanu",
    	"email": "ujuusmanu@gmail.com",
    	"mobile_no": "234802343132"
    },
    "meta":{
    	"a_key":"a_meta_value_1",
    	"another_key":"a_meta_value_2"
    },
    "details": {
      "telco_code": "{{code representing the telco}}",
      "fulfillment_msisdn": "{{msisdn}}" //the phone number to top up
    }
  }
}

Response (/transact)

{
  "status": "Successful",
  "message": "Transaction processed successfully",
  "data": {
    "provider_response_code": "00 | 91 | NF001",
    "provider": "Beeceptor",
    "errors": null,
    "error": null,
    "provider_response": {
      "payment_status": Successful | Failed | Processing",
      "fulfillment_status": "Succesful | Failed | Processing",
      "transaction_final_amount": 20000,//in kobo
      "transaction_fee": 5000,//in kobo
      "narration": "My narration",
      "reference": "000022200225154318222333334432",
      "meta":{
        "field_key":"field_value",
        "field_key":"field_value"
      }
    }
  }
}

Acceptable values for `auth.type`

Type	Description

Type	Description
card	Takes card details for debit.
bank.account	Takes bank account details for debit.
voucher	Takes a voucher code for debit.
airtime	Takes MSISDN and debits the airtime on it.
wallet	Takes a wallet ID for debit.

Possible response codes

For this service, these are the possible responses a client can receive

Response code	Meaning

Response code	Meaning
Successful	Standard success code
Failed	Standard failure code
WaitingForOTP	To signify that this provider has requested an OTP from the customer and it should be supplied.
PendingValidation	To signify that this provider needs some extra information to be provided. The `response.message` will contain the prompt.

Breakdown of the details object

For this service, the details object will be set to null

Field	Description	Possible values

Field	Description	Possible values
telco_code	A unique code representing the Telco	Varies. E.g. mtn
fulfillment_msisdn	Msisdn to be recharged with airtime	A phone number possibly with country code.

Interface specification - (OnePipe → Provider)

Read this closely.

Supported Billers

Billers	Onepipe Biller Id

Billers	Onepipe Biller Id
MTN	MTN
GLO	GLO
9mobile	9mobile
Airtel	Airtel

Public wiki

Buy Airtime

Commercial model

Special configuration notes

Settlement & fees model

Process flows

Interface specification - (App → OnePipe)

Request (/transact)

Response (/transact)

Acceptable values for `auth.type`

Possible response codes

Breakdown of the details object

Interface specification - (OnePipe → Provider)

Buy Airtime

Commercial model

Special configuration notes

Settlement & fees model

Process flows

Interface specification - (App → OnePipe)

Request (/transact)

Response (/transact)

Acceptable values for auth.type

Possible response codes

Breakdown of the details object

Interface specification - (OnePipe → Provider)

Acceptable values for `auth.type`