This service can be used to to book a buy now pay later (BNPL) payment for a given customer. A customer is evaluated for eligibility for a particular payment by a provider and and if customer agrees to the term, the provider will make the payment to the API caller and book the loan (usually with a grace period) against the customer. Every loan booked in this category will have terms like grace period, service charge, 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 charge a fee to the app (percent or flat), who in turn will charge it to the customer. The app collects this fee before booking the Pay4Me transaction with the provider. OnePipe will collect this fee from the app and split with the provider.
Option 2: Providers will charge a fee to the app (percent or flat), who will NOT charge it to the customer. The app will receive the payment from the Pay4Me transaction in full but get a charge at settlement. OnePipe will collect this fee from the app and split with the provider.

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
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.
Service charge: Configuration to determine what the service charge is. Can be determined per app
Service charge bearer: Configuration to determine if the app should bear the service charge or the customer.

Process flows

Sequence of calls

App [compulsorily] calls /transact/options to determine eligibility for the customer_ref and transaction described in the details object
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 and terms 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":"pay4me",
  "auth": {
    "type": "bvn | id | custom", //the govt-approved KYC info the credit will be assigned to
    "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": 10000, //the value of the transaction request
    "customer":{
    	"customer_ref": "{{customer_id}}", //the customer ref the credit will be based on
       	"firstname": "Uju",
  		"surname": "Usmanu",
    	"email": "ujuusmanu@gmail.com",
    	"mobile_no": "234802343132"
    },
    "meta":{
      "order_items": [//This is recommended to make eligibility assessment more accurate
            {
                "item_id": "101638163628490752",
                "item_description": "A box of noodles",
                "item_code": "RAC01",
                "item_category": "Food",
                "distributor_name": "Olaniyi & Sons",
                "item_amount": "500000",
                "currency": "NGN",
                "item_meta": {
                    "a_meta_element": "***********"
                }
            },
            {
                "item_id": "101638163628490752",
                "item_description": "A box of noodles",
                "item_code": "RAC01",
                "item_category": "Food",
                "distributor_name": "Olaniyi & Sons",
                "item_amount": "500000",
                "currency": "NGN",
                "item_meta": {
                    "a_meta_element": "***********"
                }
            }
        ],
      "order_history": [//This is recommended to make eligibility assessment more accurate
            {
                "order_id": "101638163628490752",
                "order_status": "PAID-CASH | PAID-TRANSFER | UNPAID | CASH-DEPOSITED | PAID-PAY4ME",
                "order_description": "A box of noodles",
                "retailer_id": "9090905",
                "distributor_id": "RAC01",
                "distributor_name": "Olaniyi & Sons",
                "distributor_account_number": "0987654321",
                "distributor_bank_code": "038",
                "amount_due": "500000",
                "fee": 5000,
                "currency": "NGN",
                "order_rank": 1,
                "order_meta": {
                    "narration_prefix": "000123",
                    "order_timestamp": "yyyy-MM-dd-hh-mm-ss",
                }
            },
            {
                "order_id": "101638163628490752",
                "order_status": "PAID-CASH | PAID-TRANSFER | UNPAID | CASH-DEPOSITED | PAID-PAY4ME",
                "order_description": "A box of noodles",
                "retailer_id": "101638163628490752",
                "distributor_id": "RAC01",
                "distributor_name": "Olaniyi & Sons",
                "distributor_account_number": "0987654321",
                "distributor_bank_code": "038",
                "amount_due": "500000",
                "fee": 5000,
                "currency": "NGN",
                "order_rank": 1,
                "order_meta": {
                    "narration_prefix": "000124",
                    "order_timestamp": "yyyy-MM-dd-hh-mm-ss",
                }
            }
        ],
    	"a_key":"a_meta_value_1",
    	"another_key":"a_meta_value_2"
    },
    "details": {
        "order_id": "0987654321",
        "customer_location_state": "Lagos",
        "customer_location_lga": "Eti Osa",
        "customer_location_gps": null, //GPS coordinates when the request was made
        "customer_guarantor_id": "+448099876543", //for lenders that require a guarantor
        "app_industry": "retail"
    }
  }
}

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":"pay4me",
	"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
consent_token	A unique code that was returned in the /options call	ASDGTR43221

Acceptable values for auth.type

bvn
id
custom
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
Processing	In some cases, an application may not be responded to in real-time. This would return this response and the app needs to make a `/query` call to get the update. Although, if the application for Pay4Me succeeds, the app would have received a `transaction notification` in any case
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.

Pay4Me

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