Versions Compared

Old Version 4

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
macroId
imageAttachmentIdatt262012956
macroId13a2f148-7e83-472f-949a-bcafb47284a9
baseUrlhttps://onepipe.atlassian.net/wiki
13a2f148-7e83-472f-949a-bcafb47284a9nameOnePipe 2.0 - Hold funds
diagramAttachmentIdatt262012951
containerId261193756
timestamp1585256338273

...

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

...

Code Block
languagejson
{
  "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":{
        "field_key":"field_value",
        "field_key":"field_value"
      }
    }
  }
}

Request 2

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

...

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

Place actual hold

Request

Code Block
languagejson
{
  "request_ref":"{{request-ref}}", 
  "request_type":"hold_funds",
  "auth": {
    "type": "provider_token", 
    "secure": "encrypted(provider_token)",
    "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
languagejson
{
    "status": "Successful",
    "message": "Transaction processed successfully",
    "data": {
        "provider_response_code": "00",
        "provider": "Beeceptor",
        "errors": null,
        "error": null,
        "provider_response": {
            "hold_expiry": "yyyy-MM-dd-hh-mm-ss",
            "reference": "90988889999999988888000022200225154318222333334432",
            "meta":{
              "holdfield_expirykey":"field_value",
"yyyy-MM-dd-hh-mm-ss"              "field_key":"field_value"
            }
        }
    }
}

Info

Note that this service supports that the details object is null

...

Type

Description

card

Takes card details for debithold.

bank.account

Takes bank account details for debithold.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 debithold.

bank.transfer

Simply instructs the provider to generate bank transfer instructions.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

...

Interface specification - (OnePipe → Provider)

Request

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

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

...

Read this closely.