With this service, the calling app can make a payment for a data bundle or subscription on behalf of a customer, using authorization details supplied by the customer as well as the details of the data bundle provider or Telco. Apps will collect authorisation details and forward to OnePipe to execute a debit, OnePipe will in turn forward to the provider’s dedicated implementation.

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
Commission	The provider surcharges the payer with an extra fee and pays a share of that surcharge to the app owner, OnePipe and Client The provider simply offers a percentage of the transaction value as commission. Provider pays a share of that 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 telco or biller
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)

Please note that this services supports querying for options via a /transact/options call to obtain values to put the actual /transaction call.

Request (/transact or /transact/options)

{
  "request_ref":"{{request-ref}}", 
  "request_type":"buy_data",
  "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}}", //the unique payment ref with the biller or telco
    	"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": {
      "biller_id": "{{code representing the biller}}",
      "biller_item_id": "{{code representing the biller's specific product}}",
      "order_reference": "101638163628490752",//can be null during the options call but mandatory during the /transact
    }
  }
}

Response (/transact/options)

{
  "status": "OptionsDelivered",
  "message": "Transaction processed successfully",
  "data": {
    "provider_response_code": "00",
    "provider": "Beeceptor",
    "errors": null,
    "error": null,
    "provider_response": {
      "products": [
        {
          "order_reference": "101638163628490752",
          "biller_item_id": "101638163628490752",          
          "biller_item_code": "RAC01",
          "biller_item_name": "40GB Daily",
          "biller_item_description": "This is 40GB Daily bundle. So lovely",
          "biller_item_image_url": "{{url to an image}}",
          "biller_item_prompt": "Please enter your phone number",
          "customer_name": "Kola Uju Abubakar Premium",
          "biller_item_meta": {}
          "amount": "500000",
          "currency": "566",
          "terms": "{{some HTML content}}",
          "terms_url": "{{some url}}"
        },
        {
          "order_reference": "101638163628490752",
          "biller_item_id": "101638163628490752",
          "biller_item_code": "RAC01",
          "biller_item_name": "40GB Daily",
          "biller_item_description": "This is 40GB Daily bundle. So lovely",
          "biller_item_image_url": "{{url to an image}}",
          "biller_item_prompt": "Please enter your phone number",
          "customer_name": "Kola Uju Abubakar Premium",
          "biller_item_meta": {}
          "amount": "500000",
          "currency": "566",
          "terms": "{{some HTML content}}",
          "terms_url": "{{some url}}"
        }
      ],
      "reference": "000022200225154318222333334432",
      "meta":{
        "field_key":"field_value",
        "field_key":"field_value"
      }
    }
  }
}

Response (/transact)

{
  "status": "Successful",
  "message": "Transaction processed successfully",
  "data": {
    "provider_response_code": "00",
    "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
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
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.
OptionsDelivered	To determine that options have been delivered on the first call. This should be the response of `/transact/options`

Breakdown of the details object

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

Field	Description	Possible values
biller_id	A unique code representing the biller or telco	Varies. E.g. 0803
biller_item_id	A unique code representing the biller or telco item being paid for	Varies. E.g. RAC01
order_reference	A unique reference issued to the app upon a `/transact/options` call which should be passed back in a `transact` to help link an inquiry with the actual payment	String.

Interface specification - (OnePipe → Provider)

Read this closely.

Buy Data