With this service, the calling app can find out details of a specific customer or customer reference, typically as relates to a subscription or bill payment service. For instance, given a decoder number, find out how much is due for payment or the name of the customer. Apps will collect the reference and forward to OnePipe which will in turn forward to the provider’s dedicated implementation.

Before you proceed: Please read this.

Commercial model

Host clients will simply collect a fee per API call from the calling app and share with OnePipe, Providers and ISO.

Special configuration notes

NIL.

Settlement & fees model

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

Model	How it works
Invoice	The client will invoice the calling app periodically for all calls to the endpoint.

Process flows

Sequence of calls

App calls /transact with the right customer reference
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.

Interface specification - (App → OnePipe)

Request

{
  "request_ref":"{{request-ref}}", 
  "request_type":"lookup_customer_reference",
  "auth": {
    "type": null,
    "secure": null,
    "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 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}}"
    }
  }
}

Response

{
  "status": "Successful",
  "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}}"
        }
      ],
      "meta":{}
    }
  }
}

Acceptable values for `auth.type`

Null. This service needs no auth details to be sent.

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.

Breakdown of the details object

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

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

Interface specification - (OnePipe → Provider)

Read this closely.

Lookup Customer Reference