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. For this service, apps are required to obtain consent to hold funds from the customer (likely at a prior time before the time the hold is required).

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'sHost 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

Depending on the provider implementation, this service supports any of the 3 modelsThis service can only support one mode.

Process flows

Sequence of calls

1. Getting consent

   1. App calls /transact with the

   right

   1. relevant auth details

   2. Provider responds with WaitingForOTP or PendingValidation as may be required

   3. App calls /transact/validate to supply OTP

   if needed

   2. Provider responds with any of the completion codes Successful or Failed.

2. To query the status of a transaction, the app can call /transact/query

3. Where the provider supports it, the app can call /transact/reverse to request a reversal

4. To receive available options for this service, apps can call /transact/options

   1. If successful, provider also has to respond with a provider_token

5. Placing a hold

   1. App calls /transact with auth.type set to provider_token and passing a prior received token.

   2. Provider responds with any of the completion codes Successful or Failed.

6. Releasing a hold

   1. App calls /transact/reverse with the transaction_ref of used while placing a hold to release a hold.

Interface specification - (App → OnePipe)

Consent Request

This would perform a hold and return a token with app can execute a hold in future. Ideal use scenario is to hold a small amount (e.g. N1.00) to get a provider_token to use in future. All tokens will have expiry.

Request 1

{
  "request_ref":"{{request-ref}}", 
  "request_type":"collecthold_funds",
  "auth": {
    "type": "bank.account", 
    "secure": "4if1oYEoHx5Kp+PZj6RibJlXbx8zIKkPencrypted(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 1

{
  "status": "SuccessfulWaitingForOTP",
  "message": "Transaction processed successfullyPlease enter the OTP sent to 2348022****08",
  "data": {
    "provider_response_code": "00T0",
    "provider": "Beeceptor",
    "errors": null,
    "error": null,
    "provider_response": {
      "reference": "000022200225154318222333334432",
      "payment_idmeta":{
 "136FTTP200590171",       "destinationfield_institution_codekey": "000016field_value",
        "beneficiary_account_name": "JOHN DOE JAMES",field_key":"field_value"
      }
   "beneficiary_account_number": "3056433222", }
  }
}

Request 2

{
  "beneficiaryrequest_kyc_levelref": "3"{{request_ref}}",
   
  "originator_account_name": "James Jane",request_type":"hold_funds",
	"auth": {
        "originator_account_numbersecure": "0001131256{{encrypted_otp}}",
        "originatorauth_kyc_levelprovider": "1",Beeceptor" 
    },
    "narrationtransaction": {
"My narration",       "transaction_final_amountref": 1000 //amount in kobo
  "70713093460718"
 }   }
}

Acceptable values for auth.type

...

Type

...

Description

...

card

...

...

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

Interface specification - (OnePipe → Provider)

Request

...

Response 2

{
    "request_refstatus":"{{request-ref}} "Successful",
    "request_typemessage": "collect",Transaction processed  "auth": {successfully",
    "typedata": "CARD{
| BANK.TRANSFER | AIRTIME | WALLET | BANK.ACCOUNT | CASH | VOUCHER | auth_token | provider_auth_token | custom", "provider_response_code": "00",
        "secureprovider": "4if1oYEoHx5Kp+PZj6RibJlXbx8zIKkPBeeceptor",
    "auth_provider    "errors": "Beeceptor"
  }null,
  "transaction": {     "mock_modeerror": "live"null,
        "transactionprovider_refresponse": "{{transaction-ref}}",
     "transaction_desc": "A random transaction",      "transactionprovider_ref_parenttoken": "22333055555", 
 
  "amount": 10000,     "customer":{     	"customertoken_refexpiry": "{{customer id}}",yyyy-MM-dd-hh-mm-ss",
        	"firstname": "Uju",   		"surnamehold_expiry": "Usmanuyyyy-MM-dd-hh-mm-ss",
      	"email": "ujuusmanu@gmail.com",     	"mobile_noreference": "234802343132000022200225154318222333334432",
       },     "meta":{
         	"a_key":"a_meta_value_1",     	"anotherfield_key":"afield_meta_value_2"
,
   },     "details": null,     "clientfield_infokey":"field_value"
{          "name": "TrustPay", }
       "id": null, }
    }
}

Place actual hold

Request

{
  "bankrequest_cbn_coderef": null,
  "{{request-ref}}", 
    "bankrequest_nametype": null"hold_funds",
  "auth": {
    "console_urltype": null,
  "provider_token", 
    "js_background_imagesecure": null,
        "css_url": null,
  encrypted(provider_token)",
     "logoauth_urlprovider": "https://trustpay.onepipe.io/img/trustpay_logo_console.png",
   Beeceptor",
    "footerroute_textmode": "Broughtprovider to| youoptions by <strong>SunTrust Bank</strong>",| null"
     },
  "optionstransaction": [{
    "mock_mode": "live", 
     "BANK.TRANSFER",
      "transaction_ref": "{{transaction-ref}}", 
    "CARDtransaction_desc": "A        ]random transaction", 
       "primary_color"transaction_ref_parent": "#b37038",
   
    "secondary_coloramount": "#b37038"10000,
    "customer":{
    	"primarycustomer_button_colorref": "#b37038{{customer id}}",
        "modal_background_color	"firstname": "linear-gradient(147.44deg, #d8903c 26.99%, #e69921 74.1%)Uju",
        "payment_option_colorsurname": "rgba(76, 61, 47, 0.08)Usmanu",
        "payment_option_active_color	"email": "rgba(31, 31, 31, 0.25)ujuusmanu@gmail.com",
        "app_color	"mobile_no": "#b37038234802343132"
    },
    "app_infometa": {
      "name	"a_key": "VictorMotors"a_meta_value_1",
      "id	"another_key": "5cdab3332b7d4100015f0db4","a_meta_value_2"
      "beneficiary_account_no": "0001137069",
 },
    "extrasdetails": {/*this will contain an array of provider override settings*/}
    }null
  }
}

Response

{
    "status": "Successful",
    "message": "Transaction processed successfully",
    "data": {
        "provider_response_code": "00",
        "provider": "Beeceptor",
        "errors": null,
        "error": null,
        "provider_response": {

     "reference": "000022200225154318222333334432",       "paymenthold_idexpiry": "136FTTP200590171yyyy-MM-dd-hh-mm-ss",
            "destination_institution_codereference": "000016000022200225154318222333334432",
      "beneficiary_account_name": "JOHN DOE JAMES",       "beneficiary_account_number"meta":{
"3056433222",       "beneficiary_kyc_level": "3",
      "originatorfield_account_namekey": "James Jane"field_value",
      "originator_account_number": "0001131256",       "originatorfield_kyc_levelkey": "1field_value",
      "narration": "My narration",    }
  "transaction_final_amount": 1000 //amount in kobo  }
  }   }
}

Special notes for providers

...

Acceptable values for auth.type

Possible response codes

For this service, these are the possible responses a client can receive

Breakdown of the details object

For this service, the details object will be set to null

Interface specification - (OnePipe → Provider)

Read this closely.