Overview
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.
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 |
|---|---|
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
/transactwith the right auth detailsProvider responds with
WaitingForOTPorPendingValidationas may be requiredApp calls
/transact/validateto supply OTP if neededProvider responds with any of the completion codes
SuccessfulorFailed.To query the status of a transaction, the app can call
/transact/queryWhere the provider supports it, the app can call
/transact/reverseto request a reversalTo receive available options for this service, apps can call
/transact/options.
Interface specification - apps
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
}
}
Response
{
"status": "Successful",
"message": "Transaction processed successfully",
"data": {
"provider_response_code": "00",
"provider": "Beeceptor",
"errors": null,
"error": null,
"provider_response": {
"charge_status": "Successful",
"provider_auth_token": "uji876hht",
"auth_token": "uji876hht",
"paymentoptions": []
}
}
}
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 |
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 |
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 - Providers
Request
{
"request_ref":"{{request-ref}}",
"request_type":"collect",
"auth": {
"type": "CARD | BANK.TRANSFER | AIRTIME | WALLET | BANK.ACCOUNT | CASH | VOUCHER | auth_token | provider_auth_token | custom",
"secure": "4if1oYEoHx5Kp+PZj6RibJlXbx8zIKkP",
"auth_provider": "Beeceptor"
},
"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,
"client_info": {
"name": "TrustPay",
"id": null,
"bank_cbn_code": null,
"bank_name": null,
"console_url": null,
"js_background_image": null,
"css_url": null,
"logo_url": "https://trustpay.onepipe.io/img/trustpay_logo_console.png",
"footer_text": "Brought to you by <strong>SunTrust Bank</strong>",
"options": [
"BANK.TRANSFER",
"CARD"
],
"primary_color": "#b37038",
"secondary_color": "#b37038",
"primary_button_color": "#b37038",
"modal_background_color": "linear-gradient(147.44deg, #d8903c 26.99%, #e69921 74.1%)",
"payment_option_color": "rgba(76, 61, 47, 0.08)",
"payment_option_active_color": "rgba(31, 31, 31, 0.25)",
"app_color": "#b37038"
},
"app_info": {
"name": "VictorMotors",
"id": "5cdab3332b7d4100015f0db4",
"beneficiary_account_no": "0001137069",
"extras": {/*this will contain an array of provider override settings*/}
}
}
}
Response
{
"status": "Successful",
"message": "Transaction processed successfully",
"data": {
"provider_response_code": "00",
"provider": "Beeceptor",
"errors": null,
"error": null,
"provider_response": {
"charge_status": "Successful",
"provider_auth_token": "uji876hht",
"auth_token": "uji876hht",
"paymentoptions": []
}
}
}
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.
Add Comment