Overview

With this service, the calling apps can carry out account opening operations. Apps will forward details to OnePipe. Apps will supply details required to open an account on behalf of a customer. If authorisation details are required by a provider, apps will have to provide this. OnePipe will in turn forward to the provider’s dedicated implementation.

Commercial model

At agreed settlement cycles, the host will debit the configured beneficiary account of the app for the use of this API and share that fee with all participants. Fees will be determined by the provider.

Special configuration notes

• OTP override: 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.

• SMS handler: All providers that need to do OTP validation can use the Send SMS and Send Email services on OnePipe to send their OTP.

Settlement & fees model

...

Model

...

How it works

...

Invoice

...

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

General idea

Background and problem statement

Today at OnePipe, we create unique workflows within GRB that match a specific CX or use case. At times, these workflows call underlying OnePipe APIs, at times they don’t. But they typically achieve a “jobs-to-be-done” goal for the user. One of the challenges we have always grappled with is how at times these workflows seem to precede the actual OnePipe API. And then we try to (in retrospect) figure out how to make such a workflow become API-first afterwards. Examples are: Account upgrade, GroupMoni Pay4Me, Pay-to-App, etc.

Proposed solution

OneChapp (on which GRB is based) today has a public API with which any channel can invoke and execute intents by following a conversation flow.

1. Send text to an endpoint

2. Text is matched to an intent and a session is established

3. Intent executes and sends back a response

4. Process and present the response in the best way possible

5. Go back to #1 till service/session is completed.

Now, imagine that we can expose this back & forth flow via the standard api.onepipe.io but present it as a “service” that a OnePipe App can simply call to leverage the logic that we have already encapsulated within the intent.

This way, the API caller never needs to get setup as a channel on OneChapp (or learn full details of OneChapp API), and we can feel free to create proper jobs-to-be-done as intents first and OnePipe apps can leverage this flow first while we figure out how to turn these into standard OnePipe services a bit more measuredly. Other advantages:

1. We can iterate (as we currently do) on CX and flows freely in GRB as more facts come to light based on usage

2. We no longer need to overly constraint CX within GRB (because we want to match standard OnePipe API flow at execution time)

3. We can now roll out new service bundles faster to any partner that wants reuse some of our logic. e.g. WeKurnect trying to enable pay4me in their platform (current pay4me logic is deep with non-OnePipe API elements)

Process flows

Sequence of calls

1. App calls /transact with the right auth details

2. In the details object, app inserts the user’s message as text + a callback url

3. Provider responds with WaitingForOTP or PendingValidation as may be requiredApp calls PendingValidation and a details object corresponding to the message from the underlying intent (text, menu, buttons, attachments)

   1. Where the response is delayed: Provider responds via the callback url

4. App calls /transact/validate to supply OTP if neededthe user’s choice/text

5. Provider responds with any of the completion codes Successful or Failed if it has all it needs to finish off the intent. Otherwise go back to #3

6. To query the status of a transaction, the app can call /transact/query

7. Where the provider supports it, the app can call /transact/reverse to request a reversal (if supported)

INTERFACE SPECIFICATION (APP → ONEPIPE)

Request (

...

/transact)

{
    "request_ref": "{{request_ref}}",
    "request_type": "openbenefits_accountintent",
    "auth": {
        "type": null,
        "secure": null,
        "auth_provider": "BeeceptorBenefits",
        "route_mode": null
    },
    "transaction": {
        "mock_mode": "live",
        "transaction_ref": "{{transaction_ref}}",
        "transaction_desc": "A random transaction",
        "transaction_ref_parent": null,
        "amount": 0,
        "customer": {
            "customer_ref": "{{customer_id}}",
            "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": {
            "name_on_accountmessage": "Tobi Olajide",
            "middlename": "Remilekun"{{some kain text to trigger the intent or respond to a message}}",
            "dobcallback_url": "yyyy-MM-dd-HH-mm-ss",
   {{a url to post the response to for long running proceses}}",
            "genderclient_id": "M{{app_code of the app}}", //optional
            "titlesender_id": "Mr{{customer_ref}}", //optional
            "address_line_1channel": "23, Okon street, IkejaOnePipe", //optional
        }
  "address_line_2": "Ikeja",             "city": "lagos",
     }
}

Response

Text

{
      "statestatus": "lagos",Successful | Failed      | PendingValidation",
    "countrymessage": "NG"{{The same value in provider_response.action.message}}",
    }"data": {
   } }

Response (when otp_override = false)

{     "statusprovider_response_code": "PendingValidation00",
        "messageprovider": "Please enter the OTP sent to 2348022****08"Benefits",
        "errors": null,
        "dataerror": {null,
        "provider_response_code": "900T0", {
            "providerreference": "Beeceptor263636363633777",
            "errorsaction": {
null,          "error": null,
        "provider_responserecipientId": null"2347083108908",
    } }

Response (when otp_override = true)

{     "status": "Successful",     "message": {
"Transaction processed successfully",     "data": {         "provider_response_code   "type": "00text",
        "provider": "Beeceptor",            "errorstext": null,"How much do you need?"         "error": null,      
  "provider_response": {             "reference":"263636363633777"},
            "account_number": "2233305555",
}
            "contract_codemeta":{}
 null,       }
    }
"account_reference}

Menu

{
    "status": "48214462006092",Successful | Failed | PendingValidation",
        "account_name": "Akinkunmi Olunloye"message": "{{The same value in provider_response.action.message}}",
    "data": {
        "currencyprovider_response_code": "NGN00",
            "customer_email"provider": "akin@onepipe.ioBenefits",
   
        "bank_nameerrors": null,
            "bank_code""error": null,
 
          "accountprovider_typeresponse": null,{
            "statusreference": "ACTIVE263636363633777",
            "created_onaction": "2020-04-05 23:08:01",{
                "metarecipientId":{} "2347083108908",
         }     } }

Request (validate with otp)

{
  "request_ref":"{{request_ref}}", 
  "request_type":"open_account",
	"auth": { "message": {
                    "securetype": "{{encrypted_otp}}",menu",
                    "auth_providertext": "Beeceptor"Welcome, how can I help you today?",
     },     "transaction": {         "transaction_refmenu": [
 "70713093460718"     }
}

Acceptable values for auth.type

...

Type

...

Description

...

bvn

...

Specifies that encrypted value in auth.secure is a customer bvn. It can also be null.

...

null

...

To open this account, it can be done without a BVN

Breakdown of the details object

For this service, the details object will have the following:

...

Field

...

Type

...

Requirement

...

Description

...

otp_override

...

boolean

...

optional

...

Defaults to false. If set to true, request will not be validated by OTP.

...

middlename

...

string

...

optional

...

Middle name of the customer.

...

name_on_account

...

string

...

compulsory

...

The name that should be on the account.

...

dob

...

string

...

compulsory

...

Date string for date of birth

...

gender

...

string

...

compulsory

...

Gender of the customer. This can be set to either M or F

...

title

...

string

...

compulsory

...

Gender of the customer. This can be set to either Mr, Mrs, Ms

...

address_line_1

...

string

...

compulsory

...

Address of customer

...

address_line_2

...

string

...

optional

...

Address of customer

...

city

...

string

...

compulsory

...

City

...

state

...

string

...

compulsory

...

State

...

country

...

string

...

compulsory

...

                  {
                            "id": "1",
                            "item": "Account Statement"
                        },
                        {
                            "id": "2",
                            "item": "Ask A Question"
                        },
                        {
                            "id": "3",
                            "item": "Balance Enquiry"
                        },
                        {
                            "id": "4",
                            "item": "Bill Payment"
                        }
                    ]
                },
            }
            "meta":{}
        }
    }
}

Buttons

{
    "status": "Successful | Failed | PendingValidation",
    "message": "{{The same value in provider_response.action.message}}",
    "data": {
        "provider_response_code": "00",
        "provider": "Benefits",
        "errors": null,
        "error": null,
        "provider_response": {
            "reference":"263636363633777",
            "action": {
                "recipientId": "2347083108908",
                "message": {
                    "type": "buttons",
                    "text": "Choose a password:",
                    "buttons": [
                        {
                            "title": "Enter password",
                            "url": "https://f31ac10a.ngrok.io/u/eb087"
                        }
                    ]
                },
            }
            "meta":{}
        }
    }
}

Attachments

{
    "status": "Successful | Failed | PendingValidation",
    "message": "{{The same value in provider_response.action.message}}",
    "data": {
        "provider_response_code": "00",
        "provider": "Benefits",
        "errors": null,
        "error": null,
        "provider_response": {
            "reference":"263636363633777",
            "action": {
                "recipientId": "2347083108908",
                "message": {
                    "type": "attachments",
                    "text": "Hi user, here are some sample attachments.",
                    "attachments": [
                        {
                            "type": "pdf",
                            "url": "http://164.100.133.129:81/econtent/Uploads/Session3%20Classification%20of%20Car%20by%20Body%20Style.pdf"
                        },
                        {
                            "type": "image",
                            "url": "https://www.summerhilllandscapes.com/wp-content/uploads/2016/10/SFrances_160726_3934_A.jpg"
                        }
                    ]
                },
            }
            "meta":{}
        }
    }
}

Request (validate with otp)

{
  "request_ref":"{{request_ref}}", 
  "request_type":"benefits_intent",
	"auth": {
        "secure": "{{the message or selection from the user}}",
        "auth_provider": "Benefits" 
    },
    "transaction": {
        "transaction_ref": "70713093460718"
    }
}

Acceptable values for auth.type

Possible status response codes

For this service, these are the possible responses a client can receive

INTERFACE SPECIFICATION (ONEPIPE → PROVIDER MICRO SERVICE)

Read this closely.

Special notes for OTP override

...

INTERFACE SPECIFICATION (ONEPIPE → PROVIDER MICRO SERVICE)

Read this closely.

Settlement & fees model

We can choose to charge a small fee like N2 for each completed intent. But if a OnePipe API is used underneath, it will carry it’s own pricing logic.