With this service, the calling app can make a payment for a TV service on behalf of a customer, using authorization details supplied by the customer as well as the details of the biller to be paid. 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

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_electricity",
  "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
    }
  }
}

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 enter 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",
      "token": "1253-1167-5843-6580-4889" //Token/Pin  generated from provider
    }
  }
}

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 will be set to null

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

Billers	Onepipe Biller Id

Billers	Onepipe Biller Id
Abuja Electricity Distribution Company Prepaid	AEDCPR
Abuja Electricity Distribution Company Postpaid	AEDCPP
Benin Electricity Distribution Company Prepaid	BEDCPR
Benin Electricity Distribution Company Postpaid	BEDCPP
Eko Electricity Distribution PrePaid	EKEDCPR
Eko Electricity Distribution PostPaid	EKEDCPP
Enugu Electricity Distribution PrePaid	EEDCPR
Enugu Electricity Distribution PostPaid	EEDCPP
Ibadan Electricity Distribution PostPaid	IBEDCPR
Ibadan Electricity Distribution PostPaid	IBEDCPP
Ikeja Electricity Distribution PrePaid	IKEDCPR
Ikeja Electricity Distribution PostPaid	IKEDCPP
Jos Electricity Distribution PrePaid	JEDCPR
Jos Electricity Distribution PostPaid	JEDCPP
Kaduna Electricity Distribution PrePaid	KEDCPR
Kaduna Electricity Distribution Post Paid	KEDCPP
Kano Electricity Distribution PrePaid	KAEDCPR
Kano Electricity Distribution Post Paid	KAEDCPP
Port Harcourt Electricity Distribution PrePaid	PHEDPR
Port Harcourt Electricity Distribution Post Paid	PHEDPP
Yola Electricity Distribution Prepaid	YEDPR

Interface specification - (OnePipe → Provider)

Read this closely.

Public wiki

Pay Electricity

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)

Pay Electricity

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`