Overview
With this service, the calling app can request for a fixed amount of money be held from a customer’s account or wallet or other store of value. Apps will collect authorisation details and forward to OnePipe to execute a debit, OnePipe will in turn forward to the provider’s dedicated implementation.
Before you proceed: Please read this.
Commercial model
Host clients will simply charge a fee to the calling app, and share it with the provider, OnePipe and ISO.
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
This service can only support one mode.
Model | How it works |
|---|---|
Invoice | The client will invoice the calling app periodically for all calls to the endpoint. |
Process flows
Sequence of calls
Getting consent
App calls
/transactwith the relevant auth detailsProvider responds with
WaitingForOTPorPendingValidationas may be requiredApp calls
/transact/validateto supply OTPProvider responds with any of the completion codes
SuccessfulorFailed. If successful, provider also has to respond with aprovider_token
Placing a hold
App calls
/transactwithauth.typeset toprovider_tokenand passing a prior received token.Provider responds with any of the completion codes
SuccessfulorFailed.
Interface specification - (App → OnePipe)
Request
{
"request_ref":"{{request-ref}}",
"request_type":"hold_funds",
"auth": {
"type": "bank.account",
"secure": "encrypted(bank.account;bankcode)",
"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": {
"reference": "000022200225154318222333334432",
"payment_id": "136FTTP200590171",
"destination_institution_code": "000016",
"beneficiary_account_name": "JOHN DOE JAMES",
"beneficiary_account_number": "3056433222",
"beneficiary_kyc_level": "3",
"originator_account_name": "James Jane",
"originator_account_number": "0001131256",
"originator_kyc_level": "1",
"narration": "My narration",
"transaction_final_amount": 1000 //amount in kobo
}
}
}
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 - (OnePipe → Provider)
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": {
"reference": "000022200225154318222333334432",
"payment_id": "136FTTP200590171",
"destination_institution_code": "000016",
"beneficiary_account_name": "JOHN DOE JAMES",
"beneficiary_account_number": "3056433222",
"beneficiary_kyc_level": "3",
"originator_account_name": "James Jane",
"originator_account_number": "0001131256",
"originator_kyc_level": "1",
"narration": "My narration",
"transaction_final_amount": 1000 //amount in kobo
}
}
}
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.
0 Comments