With this service, the calling app can make bill payment calls.

Before you proceed: Please read this.

Commercial model

Option 1: Providers will pay the commissions due to 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
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
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":"pay_tv",
  "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
    	"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
    }
  }
}

If biller_id is not available, return all the list of Billers.

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": "DSTV Premium",
          "biller_item_description": "This is DSTV Premium that is lovely",
          "biller_item_image_url": "{{url to an image}}",
          "biller_item_prompt": "Please neter your smartcard 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": "DSTV Premium",
          "biller_item_description": "This is DSTV Premium that is lovely",
          "biller_item_image_url": "{{url to an image}}",
          "biller_item_prompt": "Please neter your smartcard 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": {
      "reference": "000022200225154318222333334432",
      "payment_status": Successful | Failed | Processing",
      "fulfillment_status": "Succesful | Failed | Processing",
      "transaction_final_amount": 20000,//in kobo
      "transaction_fee": 5000,//in kobo
      "narration": "My narration"
    }
  }
}

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.
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 and needs to be one of those below

Field	Description	Possible values

Field	Description	Possible values
biller_id	A unique code representing the biller	Varies. E.g. DSTV
biller_item_id	A unique code representing the biller item being paid for	Varies. E.g. DSTV Premium
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.

Supported Billers

Biller Name	Onepipe Biller Id

Biller Name	Onepipe Biller Id
DSTV	DSTV
GOTV	GOTV
LITV	Linda Ikeji TV
Iroko TV	IrokoTV
Kwese TV	KweseTV
TSTV	TSTV
StarTimes	Startimes
Mytv	MYTV

Interface specification - (OnePipe → Provider)

Read this closely.

Public wiki

Generic Service

Commercial model

Special configuration notes

Settlement & fees model

Process flows

Interface specification - (App → OnePipe)

Request (/transact or /transact/options)

Response (/transact/options)

Response (/transact)

Acceptable values for `auth.type`

Possible response codes

Breakdown of the details object

Interface specification - (OnePipe → Provider)

Generic Service

Commercial model

Special configuration notes

Settlement & fees model

Process flows

Interface specification - (App → OnePipe)

Request (/transact or /transact/options)

Response (/transact/options)

Response (/transact)

Acceptable values for auth.type

Possible response codes

Breakdown of the details object

Interface specification - (OnePipe → Provider)

Acceptable values for `auth.type`