Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

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

  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.

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

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.

  • No labels