Versions Compared

Old Version 3

changes.mady.by.user Ope Adeoye

Saved on

compared with

New Version Current

changes.mady.by.user Akin Olunloye

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Info

Before you proceed: Please read this.

...

  1. Getting consent

    1. App calls /transact with the relevant auth details

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

    3. App calls /transact/validate to supply OTP

    4. Provider responds with any of the completion codes Successful or Failed. If successful, provider also has to respond with a provider_token

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

  3. Releasing a hold

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

Gliffy
imageAttachmentIdatt262012956
macroId13a2f148-7e83-472f-949a-bcafb47284a9
baseUrlhttps://onepipe.atlassian.net/wiki
nameOnePipe 2.0 - Hold funds
diagramAttachmentIdatt262012951
containerId261193756
timestamp1585256338273

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

Code Block
languagejson
{
  "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 1

Code Block
languagejson
{
  "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",
        "beneficiaryfield_account_namekey": "field_value"JOHN
DOE JAMES",     }
 "beneficiary_account_number": "3056433222",  }
  }
}

Request 2

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

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

...

...
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)
Request
Response 2
 Code Block
languagejson
{
    "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":"a_metafield_value_2",
    },     "details": null,     "clientfield_infokey":"field_value"
 {         "name": "TrustPay", }
       "id": null, }
    }
}
Place actual hold
Request
 Code Block
languagejson
{
  "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.pngBeeceptor",

       "footerroute_textmode": "Broughtprovider to| youoptions by <strong>SunTrust Bank</strong>",| null"
    },
   "optionstransaction": [{
    "mock_mode": "live", 
     "BANK.TRANSFER",
  "transaction_ref": "{{transaction-ref}}", 
        "CARD"
        ],
  "transaction_desc": "A random transaction", 
    "primarytransaction_ref_colorparent": "#b37038", 
       "secondary_color"amount": "#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
 Code Block
languagejson
{
    "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_code    "reference": "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
...
 Info
Note that this service supports that the details object is null
Acceptable values for auth.type
Type
Description
card
Takes card details for hold.
bank.account
Takes bank account details for hold.
wallet
Takes a wallet ID for hold.
provider_token
A token representing prior consent given to hold funds
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.