With “With this service, the calling app can request or initiate payment from a customer. Apps will collect authorisation details and forward to OnePipe to execute a debit, OnePipe the underlying provider to generate (and optionally send) an invoice to a customer for a specific payment or service. Apps will pass in the details of the items to be paid for as well as the payer’s details and any authorisation details that may be required. OnePipe will in turn forward to the provider’s dedicated implementation. Providers will support a wide array of payment methods and optionally prompt for any extra auth details specific to their implementationbe required to respond the details of the invoice generated and a link with which the App can access it digitally.
| Info |
|---|
Before you proceed: Please read this. |
Commercial model
Providers will be required to settle monies collected to a designated account by the client bank, less their fees. The client bank will handle secondary settlement to the apps, less their own fee and OnePipe'scan bill the calling App for every invoice generated.
Settlement & fees model
Depending on the provider implementationAs a result of the commercial model, this service supports any of the 3 modelsonly supports 1 fees model.
Model | How it works |
|---|---|
Amount | The provider removes a percentage or flat fee from the amount as fee and settles the difference to the app owner (via the client). |
Commission | The provider surcharges the payer with an extra fee and pays a share of that surcharge to the app owner, OnePipe and Client|
Invoice | The client will invoice the calling app periodically for all calls to the endpoint. |
...
App calls
/transactwith the right auth details (or null as the case may be)Provider responds with
SuccessfulorFailedas may be requiredTo query the status of a transaction, the app can call
/transact/query
...
...
Interface specification - (App → OnePipe)
...
| Code Block | ||
|---|---|---|
| ||
{
"requestre
quest_ref":"{{request_ref}}",
"request_type":"send_invoice",
"auth": {
"type": "null",
"secure": "{{null}}",
"auth_provider": "OnePipe",
"route_mode": null
},
"transaction": {
"mock_mode": "live",
"transaction_ref": "{{transaction_ref}}",
"transaction_desc": "A random transaction", //description that shouldcarry to the invoice
"transaction_ref_parent": null,
"amount": 0,//amoun expected to be paid
"customer":{
"customer_ref": "{{customer_id}}",
"firstname": "Uju",
"surname": "Usmanu",
"email": "ujuusmanu@gmail.com",//the recipient of the invoice
"mobile_no": "234802343132"//the recipeintrecipient of the invoice
},
"meta":{
"a_key":"a_meta_value_1",
"another_key":"a_meta_value_2"
},
"details": {
"invoice_number": "00001",//optional. Provider can generate one
"due_date": "09-08-2020",
"page_id": "{{SMP Page ID}}" //optional.
"payment_items": [
{
"item_description": "A big blag bag",
"item_code": "ITEM001",
"item_amount": 2000000
},
{
"item_description": "A big blag bag",
"item_code": "ITEM001",
"item_amount_due": "150000",": 2000000
}
],
"reminders": [
{
"reminder_date": "09-08-2020",
"reminder_title": "It's been 8 days, pay up!"
"reminder_message": "The quick brown fox jumps over the lazy dog"
},
{
"reminder_date": "09-08-2020",
"reminder_title": "It's been 8 days, pay up!"
"reminder_message": "The quick brown fox jumps over the lazy dog"
}
]
}
}
}
|
Responses
| Code Block | ||
|---|---|---|
| ||
{
"status": "Successful",
"message": "Transaction processed successfully",
"data": {
"provider_response_code": "00",
"provider": "Beeceptor",
"errors": null,
"error": null,
"provider_response": {
"delivery_status": "delivered | failed | pending",
"cost": "1500",//in kobo
"invoice_number": "00001",
"due_date": "09-08-2020",
"amount_due": "150000",//in kobo
"paymentinvoice_link": "http://pages.onepipe.io/p/7uL21J"
"reference": "000022200225154318222333334432",
"meta":{
}
}
}
}
|
| Info |
|---|
Note that this service supports that the details object is null |
Acceptable values for auth.type
...
Type
...
Description
...
card
...
Takes card details for debit.
...
bank.account
...
Takes bank account details for debit.
...
cash
...
Will simply flag the transaction, as awaiting transaction_notification
...
custom
...
Takes a unique transaction ref. This mode is for when OnePipe.js or some other UI processes the payment and passes in a ref for validation of the payment.
...
voucher
...
Takes a voucher code for debit.
...
airtime
...
Takes MSISDN and debits the airtime on it.
...
wallet
...
Takes a wallet ID for debit.
...
...
Simply instructs the provider to generate bank transfer instructions.
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 |
Breakdown of the details object
For this service, the details object will be set to null
Field | Description | Possible values | null | N/A | N/A|
|---|---|---|---|---|---|
invoice_number | The calling App may set the invoice number | ||||
due_date | Expected payment date of the invoice | ||||
payment_items | An array of items that make up the invoice | ||||
reminders | An array of scheduled reminders - if the provider supports that functionality |
Interface specification - (OnePipe → Provider)
Read this closely.
Special notes for providers
...
.