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.

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.

Settlement & fees model

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

Model	How it works

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 WaitingForOTP or PendingValidation as may be required
App calls /transact/validate to supply OTP if needed
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
To receive available options for this service, apps can call /transact/options.

Interface specification - (App → OnePipe)

Request

{
  "request_ref":"{{request-ref}}", 
  "request_type":"collect",
  "auth": {
    "type": "bank.account", 
    "secure": "4if1oYEoHx5Kp+PZj6RibJlXbx8zIKkP",
    "auth_provider": "Beeceptor",
    "route_mode":"provider | options | null"
  },
  "transaction": {
    "mock_mode": "live", 
    "transaction_ref": "{{transaction-ref}}", 
    "transaction_desc": "A random transaction", 
    "transaction_ref_parent": "", 
    "amount": 10000,
    "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": null
  }
}

Responses

Successful

{
  "status": "Successful",
  "message": "Transaction processed successfully",
  "data": {
    "provider_response_code": "00",
    "provider": "Beeceptor",
    "errors": null,
    "error": null,
    "provider_response": {
      "provider_auth_token": null,
      "paymentoptions": [],
      "transaction_final_amount": 1000, //amount in kobo
      "reference": "897465522772655",
      "meta": {}
    }
  }
}

Waiting for OTP or Validation

{
  "status": "WaitingForOTP | PendingValidation | Proccessing",
  "message": "Kindly enter the OTP sent to 08142*****67",
  "data": {
    "provider_response_code": "900TO",
    "provider": "Beeceptor",
    "errors": null,
    "error": null,
    "provider_response": null
  }
}

Failed

Note that this service supports that the details object is null

Acceptable values for `auth.type`

Type	Description

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

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

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.

Public wiki

Collect

Commercial model

Special configuration notes

Settlement & fees model

Process flows

Interface specification - (App → OnePipe)

Request

Responses

Successful

Waiting for OTP or Validation

Failed

Acceptable values for `auth.type`

Possible response codes

Breakdown of the details object

Interface specification - (OnePipe → Provider)

Special notes for providers

Commercial model

Special configuration notes

Settlement & fees model

Process flows

Interface specification - (App → OnePipe)

Request

Responses

Successful

Waiting for OTP or Validation

Failed

Acceptable values for auth.type

Possible response codes

Breakdown of the details object

Interface specification - (OnePipe → Provider)

Special notes for providers

Acceptable values for `auth.type`