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 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 implementation.

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's.

Settlement & fees model

Depending on the provider implementation, this service supports any of the 3 models.

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.

Process flows

Sequence of calls

App calls /transact with the right auth details
Provider responds with Successful or Failed as may be required
To query the status of a transaction, the app can call /transact/query

Interface specification - (App → OnePipe)

Request

{
  "request_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", 
    "transaction_ref_parent": null, 
    "amount": 0,
    "customer":{
    	"customer_ref": "{{customer_id}}",
    	"firstname": "Uju",
         "surname": "Usmanu",
    	"email": "ujuusmanu@gmail.com",//the recipient of the invoice
    	"mobile_no": "234802343132"//the recipeint of the invoice
    },
    "meta":{
    	"a_key":"a_meta_value_1",
    	"another_key":"a_meta_value_2"
    },
    "details": {
      "invoice_number": "00001",
      "due_date": "09-08-2020",
      "amount_due": "150000",
    }
  }
}

Responses

{
    "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
              "payment_link": "http://pages.onepipe.io/p/7uL21J"
              "reference": "000022200225154318222333334432",
              "meta":{
            }
        }
    }
}

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.
bank.transfer	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 `response.message` will contain the prompt.

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

Interface specification - (OnePipe → Provider)

Read this closely.

Special notes for providers

This should be seen as a standard payments service. All providers are required to execute settlement per agreed contracts to the account designated by the client bank.

Send Invoice