This service can be used to get loan offers for a given customer. A loan offer is a loan product available to a customer provided by a specific provider. e.g Provider A can make 2 Loan offers to a Customer B such as NGN5,000 loan, N10,000. When a calling app requests for loan offers with the appropriate payload, the call should return an array of loan offers with details like interest, payable amount, tenure, etc.

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. It’s important to note that this service requires the customer’s consent, so all providers have to implement OTP support.

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. Or, the provider doesn’t apply a surcharge but rather just pays a percentage of the amount as commission to the app owner, OnePipe and Client.
Invoice	The client will invoice the calling app periodically for all calls to the endpoint.

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.

Process flows

Sequence of calls

App [compulsorily] calls /transact/options to get a list of loan offers available by the provider for the customer_ref
Provider responds with WaitingForOTP or PendingValidation as may be required
App calls /transact/validate to supply OTP if needed
Provider responds with OptionsDelivered and an array of loan offers as well as a consent_token to be used in subsequent calls to accept the offer.
App calls /transact with the right auth details, consent_token and the lender_offer_idfrom step #4
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

otp_override should affect the /transact/options call and not the actual /transact call.

INTERFACE SPECIFICATION (APP → ONEPIPE)

Request (/transact/options)

{
  "request_ref":"{{request_ref}}", 
  "request_type":"get_a_loan",
  "auth": {
    "type": "bank.account | card | wallet | null", 
    "secure": "{{encrypted_secure}}",
    "auth_provider": "Beeceptor",
    "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}}", //the customer ref the loans will be based on
    	"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": null
  }
}

Options response (when otp_override = false)

{
    "status": "WaitingForOTP",
    "message": "Please enter the OTP sent to 2348022****08",
    "data": {
        "provider_response_code": "900T0",
        "provider": "Beeceptor",
        "errors": null,
        "error": null,
        "provider_response": null
    }
}

Request (validate otp)

{
  "request_ref":"{{request_ref}}", 
  "request_type":"get_a_loan",
	"auth": {
        "secure": "{{encrypted_otp}}",
        "auth_provider": "Beeceptor" 
    },
    "transaction": {
        "transaction_ref": "70713093460718"
    }
}

Options response (after validating OTP or when otp_override = true)

Request (/transact)

Response (/transact)

Breakdown of the details object

For this service, the details object is expected to be as below.

Field	Description	Possible values

Field	Description	Possible values
lender_code	A unique code representing the lender	Varies. E.g. MNI
lender_product_code	A unique code representing the lender’s product being offered	Varies. E.g. CASH001
lender_offer_id	A unique reference representing this offer, received during the options call	E.g. offer-001
destination_account	The account number of the recipient for the money
destination_bank_code	The CBN code of the recipient bank	E.g. 011

Acceptable values for auth.type

card
bank.account
wallet
null

Possible status response codes

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

Status	Meaning

Status	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`

INTERFACE SPECIFICATION (ONEPIPE → PROVIDER MICRO SERVICE)

Read this closely.

Special notes for OTP override

Whenever a request is to be validated by OTP, the provider microservice should first call the provider, store response info in the database, send an OTP to the corresponding phone number, then respond with WaitingForOTP.
On the OTP validation phase, if user OTP is valid, provider should retrieve info from the database, then respond with a Successful response.
NB: Data should be erased from the DB.

Public wiki

Get A Loan

Commercial model

Special configuration notes

Settlement & fees model

Special configuration notes

Process flows

INTERFACE SPECIFICATION (APP → ONEPIPE)

Request (/transact/options)

Options response (when otp_override = false)

Request (validate otp)

Options response (after validating OTP or when otp_override = true)

Request (/transact)

Response (/transact)

Breakdown of the details object

Acceptable values for auth.type

Possible status response codes

INTERFACE SPECIFICATION (ONEPIPE → PROVIDER MICRO SERVICE)

Special notes for OTP override