Lookup Customer Reference

Owned by Ope Adeoye
Last updated: Apr 10, 2020
4 min read

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

Model

How it works

Invoice

The client will invoice the calling app periodically for all calls to the endpoint.

Process flows

Sequence of calls

  1. App calls /transact with the right customer reference

  2. Provider responds with WaitingForOTP or PendingValidation as may be required

  3. App calls /transact/validate to supply OTP if needed

  4. 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}}" } ], "reference": "000022200225154318222333334432", "meta":{ "field_key":"field_value", "field_key":"field_value" } } } }

 

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

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 as 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

Interface specification - (OnePipe → Provider)

Read this closely.