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.

...

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

...

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

Gliffy

imageAttachmentId	att262012956
macroId	13a2f148-7e83-472f-949a-bcafb47284a9
baseUrl	https://onepipe.atlassian.net/wiki
name	OnePipe 2.0 - Hold funds
diagramAttachmentId	att262012951
containerId	261193756
timestamp	1585256338273

...

Code Block

language	json

{
  "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
  }
}

...

Code Block

language	json

{
  "status": "WaitingForOTP",
  "message": "Please enter the OTP sent to 2348022****08",
  "data": {
    "provider_response_code": "T0",
    "provider": "Beeceptor",
    "errors": null,
    "error": null,
    "provider_response": {
      "reference": "000022200225154318222333334432",
      "meta":{}
    }   }
}

Request 2

Code Block
"field_key":"field_value", "field_key":"field_value" } } } }

Request 2

Code Block

language	json

{
  "request_ref":"{{request_ref}}", 
  "request_type":"hold_funds",
	"auth": {
        "secure": "{{encrypted_otp}}",
        "auth_provider": "Beeceptor" 
    },
    "transaction": {
        "transaction_ref": "70713093460718"
    }
}

...

Code Block

language	json

{
    "status": "Successful",
    "message": "Transaction processed successfully",
    "data": {
        "provider_response_code": "00",
        "provider": "Beeceptor",
        "errors": null,
        "error": null,
        "provider_response": {
            "provider_token": "22333055555",
            "referencetoken_expiry": "90988889999999988888"yyyy-MM-dd-hh-mm-ss",
            "tokenhold_expiry": "yyyy-MM-dd-hh-mm-ss",
            "hold_expiryreference": "yyyy-MM-dd-hh-mm-ss"000022200225154318222333334432",
        }    "meta":{
     } }

Place actual hold

Request

Code Block

language	json

{   "request_ref":"{{request-ref}}",     "requestfield_typekey":"holdfield_fundsvalue",
   "auth": {           "typefield_key": "providerfield_tokenvalue",
     "secure": "encrypted(provider_token)",     "auth_provider": "Beeceptor", }
    "route_mode":"provider | options | null"}
  },   "transaction": }
}

Place actual hold

Request

Code Block

language	json

{
    "mockrequest_moderef": "live"{{request-ref}}", 
  "request_type":"hold_funds",
  "transaction_refauth": "{{transaction-ref}}", 
    "transaction_desctype": "A random transactionprovider_token", 
    "transaction_ref_parentsecure": "encrypted(provider_token)",
     "amountauth_provider": 10000"Beeceptor",
    "customerroute_mode":{"provider | options | null"
  },
  	"customer_reftransaction": "{{customer
id}}",
    	"firstnamemock_mode": "Ujulive", 
  		"surname  "transaction_ref": "Usmanu{{transaction-ref}}", 
   	 "emailtransaction_desc": "ujuusmanu@gmail.comA random transaction", 
   	 "mobiletransaction_ref_noparent": "234802343132", 
   } "amount": 10000,
    "metacustomer":{
    	"acustomer_keyref":"a_meta_value_1 "{{customer id}}",
    	"another_keyfirstname":"a_meta_value_2" "Uju",
    },
    "detailssurname": null"Usmanu",
  } }

Response

Code Block

language	json

{
    "status 	"email": "Successfulujuusmanu@gmail.com",
    	"messagemobile_no": "234802343132"Transaction
   processed successfully"},
    "datameta": {
        "provider_response_code	"a_key": "00"a_meta_value_1",
        "provider	"another_key": "Beeceptor","a_meta_value_2"
    },
    "errorsdetails": null,
  }
}

Response

Code Block

language	json

{
    "errorstatus": null"Successful",
    "message": "Transaction processed successfully",
    "provider_responsedata": {
            "reference"provider_response_code": "9098888999999998888800",
  
         "hold_expiryprovider": "yyyy-MM-dd-hh-mm-ss"Beeceptor",
        }
"errors": null,
     }
}

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)

Request - Consent Request

Code Block

language	json

{
  "request_ref":"{{request-ref}}", 
  "request_type":"hold_funds",
  "request_mode":"transact",
  "auth": {
    "type": "{card | bank.account | wallet | provider_token}", 
    "secure": "{decrypted}",
    "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*/}
    }
  }
}

Request - Validate Consent Request

Code Block

language	json

{
  "request_mode":"validate",
  "request_ref":"{{request_ref}}", 
  "request_type":"hold_funds",
  "auth": {
    "type": null, 
    "secure": "{{otp}}",
    "auth_provider": "Beeceptor"
  },
  "transaction": {
    "mock_mode": null, 
    "transaction_ref": "{{transaction_ref}}", 
    "transaction_desc": null, 
    "transaction_ref_parent": null, 
    "amount": 0,
    "customer":null,
    "meta":null,
    "details": null
  }
}

Request - Hold

Code Block

{
  "request_ref":"{{request-ref}}", 
  "request_type":"hold_funds",
  "request_mode":"transact",
  "auth": {
    "type": "provider_token", 
    "secure": "{decrypted_token}",
    "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*/}
    }
  }
}   "error": null,
        "provider_response": {
            "hold_expiry": "yyyy-MM-dd-hh-mm-ss",
            "reference": "000022200225154318222333334432",
            "meta":{
              "field_key":"field_value",
              "field_key":"field_value"
            }
        }
    }
}

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.

Versions Compared

Old Version 5

New Version Current

Key

Overview

Request 2

Request 2

Place actual hold

Request

Place actual hold

Request

Response

Response

Acceptable values for `auth.type`

Possible response codes

Breakdown of the details object

Interface specification - (OnePipe → Provider)

Request - Consent Request

Request - Validate Consent Request

Request - Hold

Acceptable values for `auth.type`

Possible response codes

Breakdown of the details object

Interface specification - (OnePipe → Provider)

Page Comparison

Versions Compared

Old Version 5

New Version Current

Key

Overview

Request 2

Request 2

Place actual hold

Request

Place actual hold

Request

Response

Response

Acceptable values for auth.type

Possible response codes

Breakdown of the details object

Interface specification - (OnePipe → Provider)

Request - Consent Request

Request - Validate Consent Request

Request - Hold

Acceptable values for auth.type

Possible response codes

Breakdown of the details object

Interface specification - (OnePipe → Provider)

Acceptable values for `auth.type`

Acceptable values for `auth.type`