Versions Compared

Old Version 2

changes.mady.by.user Ope Adeoye

Saved on

compared with

New Version 3

changes.mady.by.user Ope Adeoye

Saved on

Key

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

...

  • Once it's card, it should be: TripleDES.encrypt("{card.Pan};{card.Cvv};{card.Expdate};{card.Pin}",secretKey)

  • Once it's bank.account , it shd be: TripleDES.encrypt("{accountNumber};{bankCBNCode}",secretKey)

  • Once it's wallet , it shd be: TripleDES.encrypt("{walletNumber};{providerCode}",secretKey)

  • Once it's airtime , it shd be: TripleDES.encrypt("{phoneNumber};{telcoCode}",secretKey)

  • Once it's voucher , it shd be: TripleDES.encrypt("{voucherCode};{providerCode}",secretKey)

  • Once it's bvn , it shd be: TripleDES.encrypt("{bvn}",secretKey)

...

A typical /transact request

The actual API call to process a transaction

Code Block
languagejson
{
  "request_ref":"{{request_ref}}", 
  "request_type":"transfer_funds",
  "auth": {
    "type": "bank.account | card | wallet", 
    "secure": "{{encrypted(bank account details | card details | wallet)}}",
    "auth_provider": "Beeceptor",
    "route_mode": null
  },
  "transaction": {
    "mock_mode": "live", 
    "transaction_ref": "{{transaction_ref}}", 
    "transaction_desc": "A random transaction", 
    "transaction_ref_parent": null, 
    "amount": 1000,
    "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": {
    	"a_key":"a_value",
        "a_key":"a_value"
    }
  }
}

...

A typical completion response (Successful or Failed)
If all checks out.
 Code Block
languagejson
{
    "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,
            "meta":{
              "field_key":"field_value",
              "field_key":"field_value"
            }
        }
    }
}
Request Payload Description
...
Field
...
Type
...
Requirement
...
Description
...
request_ref
...
string
...
compulsory
...
Takes unique value for every request made to OnePipe
...
request_type
...
string
...
compulsory
...
This should be set to the service transfer_funds
...
auth.type
...
string
...
compulsory
...
Depending on the source of fund. This can be set to either bank.account, card, token or wallet
...
auth.secure
...
string
...
compulsory
...
This is the encrypted value of the source of fund. Depending on the auth type, this can be either bank account, card details, token or wallet details. See details on how to encrypt the secure field.
...
auth.provider
...
string
...
compulsory
...
This should be set to the name of the Provider
...
auth.route_mode
...
string
...
N/A
...
This can be set to null
...
transaction.mock_mode
...
string
...
optional
...
This can be set to either live or inspect. If left as null, value will fall back to the state of the service set on the console.
...
transaction.transaction_desc
...
string
...
optional
...
Description of your transaction
...
transaction.transaction_ref_parent
...
string
...
optional
...
Takes value of a (parent) transaction reference
...
transaction.customer.customer_ref
...
string
...
compulsory
...
Identifier for customer
...
transaction.customer.firstname
...
string
...
optional
...
First name of customer 
...
transaction.customer.surname
...
string
...
optional
...
Surname of customer
...
transaction.customer.email
...
string
...
optional
...
Email address of customer
...
transaction.customer.mobile_no
...
string
...
optional
...
Phone number of customer
...
transaction.amount
...
big int
...
compulsory
...
This is the amount (kobo) to be transferred
...
transaction.transaction_ref
...
string
...
compulsory
...
Takes unique value for every transaction call to OnePipe.
...
transaction.meta
...
object
...
optional
...
Json object of your arbitrary transaction parameters
...
transaction.details
...
object
...
compulsory
INTERFACE SPECIFICATION (ONEPIPE → PROVIDER MICRO SERVICE)
 Info
Request payload from OnePipe to the provider microservice comes encrypted, using the Triple DES Algorithm. See details.
Request (Transact)
...
languagejson
...
A typical /transact/validate request
This is when Providers respond with WaitingForOTP or PendingValidation.
 Code Block
languagejson
{
  "request_ref":"{{request_ref}}", 
  "request_type":"lookup_bvn_max",
	"auth": {
        "secure": "{{encrypted_otp}}",
        "auth_provider": "Beeceptor" 
    },
    "transaction": {
        "transaction_ref": "70713093460718"
    }
}
A /transact/validate request should typically lead to a completion response (or in some cases: another validate response if appropriate)
A typical /transact/query request
To find out the status of a former transaction
 Code Block
languagejson
{
	"request_ref":"{{request-ref}}",
	"request_type":"{{request_type}}",
	"transaction":{
		"transaction_ref": "12978251696483"
	}
}
A /transact/validate request should typically lead to a completion response (or in some cases: another validate response if appropriate)
A typical /transact/options request
Same payload as the the /transact call, only that it’s probing the provider for options. At this point auth can be null if the provider supports it.
 Code Block
languagejson
{
  "request_ref":"{{request_ref}}", 
  "request_type":"transfer_funds",
  "auth": {
    "type": "bank.account | card | wallet", 
    "secure": "{{encrypted(bank account details | card details | wallet)}}",
    "auth_provider": "Beeceptor",
    "route_mode": null
  },
  "transaction": {
    "mock_mode": "live", 
    "securetransaction_ref": "{{bank account details | card details | wallettransaction_ref}}", 
    "authtransaction_providerdesc": "BeeceptorA random transaction", 
 },   "transaction_ref_parent": {null, 
    "mock_modeamount": 1000,
    "livecustomer",:{
     	"transactioncustomer_ref": "{{transactioncustomer_refid}}",
     "transaction_desc	"firstname": "Uju",
  		"surname": "A random transactionUsmanu",
     "transaction_ref_parent	"email": null"ujuusmanu@gmail.com",
    	"mobile_no": "amount": 1000234802343132"
    },
    "customermeta":{
    	"customera_refkey": "{{customer_id}}"a_meta_value_1",
    	"firstnameanother_key": "Uju","a_meta_value_2"
   		"surname": "Usmanu" },
    	"emaildetails": "ujuusmanu@gmail.com",{
    	"mobilea_nokey": "234802343132"
    }a_value",
    "meta":{     	"a_key":"a_meta_value_1value",
    	"another_key":"a_meta_value_2"}
    },
    "details": {
    	"a_key":"a_key",
        "a_key":"a_key"
    },
    "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": "Victor Motors",
      "id": "5cdab3332b7d4100015f0db4",
      "beneficiary_account_no": "0001137069",
      "extras": {/*this will contain an array of provider override settings*/}
    }
  }
}
Response (when otp_override = false)
Set provider_response_code to 900T0
 Code Block
languagejson
{
    "status": "WaitingForOTP",
    "message": "Please enter the OTP sent to 2348022****08",
    "data": {
        "provider_response_code": "900T0",
        "provider": "Beeceptor",
        "errors": null,
        "error": null,
        "provider_response": null
    }
}
Response (when otp_override = true)
 Code Block
{
    "status": "Successful",
    "message": "Operation was successful",
    "data": {
    	"provider_responde_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,
            "meta":{
              "field_key":"field_value",
     }
}
Request Payload Description
Field
Type
Requirement
Description
request_ref
string
compulsory
Takes unique value for every request made to OnePipe
request_type
string
compulsory
This should be set to the service transfer_funds
auth.type
string
compulsory
Depending on the source of fund. This can be set to either bank.account, card, token or wallet
auth.secure
string
compulsory
This is the encrypted value of the source of fund. Depending on the auth type, this can be either bank account, card details, token or wallet details. See details on how to encrypt the secure field.
auth.provider
string
compulsory
This should be set to the name of the Provider
auth.route_mode
string
N/A
This can be set to null
transaction.mock_mode
string
optional
This can be set to either live or inspect. If left as null, value will fall back to the state of the service set on the console.
transaction.transaction_desc
string
optional
Description of your transaction
transaction.transaction_ref_parent
string
optional
Takes value of a (parent) transaction reference
transaction.customer.customer_ref
string
compulsory
Identifier for customer
transaction.customer.firstname
string
optional
First name of customer 
transaction.customer.surname
string
optional
Surname of customer
transaction.customer.email
string
optional
Email address of customer
transaction.customer.mobile_no
string
optional
Phone number of customer
transaction.amount
big int
compulsory
This is the amount (kobo) to be transferred
transaction.transaction_ref
string
compulsory
Takes unique value for every transaction call to OnePipe.
transaction.meta
object
optional
Json object of your arbitrary transaction parameters
transaction.details
object
varies per transaction type
JSON object of transaction type specific elements
Response Payload Description
Field
Type
Requirement
Description
status
string
compulsory
Gives the final status of the API call
message
string
compulsory
A message for the API caller, which may or may not be bubbled to the actual user.
data.provider_response_code
string
compulsory
A response code used internally by the provider. 
data.provider
string
compulsory
The provider that processed the transaction.
data.error
object
compulsory
The single error that caused a transaction to fail. Can be null for successful transactions.
data.errors
array
compulsory
An array of error objects from the provider, in case multiple errors occurred. Can be null.
data.error.code
string
compulsory
All error objects need to have a code.
data.error.message
string
compulsory
All error objects need to have a message.
data.provider_response
object
compulsory
An object that will encapsulate the actual response data for the provider as described by the standard specification for that service.
data.provider_response.meta
array
optional
In the event that the provider has more information to share that the specification for that transaction type is not covered, providers can put this here. It’s simply a key value pair of anything. It’s expected that apps are aware of what these values and keys might be upfront though. Works for cases where the app knows the details of the provider’s API but the OnePipe spec is inadequate.
INTERFACE SPECIFICATION (ONEPIPE → PROVIDER MICRO SERVICE)
 Info
Request payload from OnePipe to the provider microservice comes encrypted, using the Triple DES Algorithm. See details.
For calls going from OnePipe to the provider, OnePipe decrypts all secure content in the payload, inserts OnePipe related metadata (like app and client information as well as any special config for the provider) then re-encrypts the entire payload before forwarding to the provider implementation.
Request (Transact)
 Code Block
languagejson
{
  "request_mode":"{{request_ref}}", 
  "request_ref":"{{request_ref}}", 
  "request_type":"transfer_funds",
  "auth": {
    "type": "bank.account | card | wallet", 
    "secure": "decrypted({{bank account details | card details | wallet}})",
    "auth_provider": "Beeceptor"
  },
  "transaction": {
    "mock_mode": "live", 
    "transaction_ref": "{{transaction_ref}}", 
    "transaction_desc": "A random transaction", 
    "transaction_ref_parent": null, 
    "amount": 1000,
    "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": {
    	"a_key":"a_key",
        "fielda_key":"fielda_valuekey"

           },
        }
 "client_info": {
  } }
Failed Response
 Code Block
{     "statusname": "FailedTrustPay",
        "messageid": null,
"Operation was not successful",     "databank_cbn_code": null,
   {     	"providerbank_responde_code":"91",name": null,
        	"providerconsole_url": "Beeceptor"null,
        "errorsjs_background_image": [null,
          {
"css_url": null,
           "code" : "01",
   "logo_url": "https://trustpay.onepipe.io/img/trustpay_logo_console.png",
        "footer_text"message : "ReasonBrought whyto ityou failed"by <strong>SunTrust Bank</strong>",
        }
   "options": [
    ],         "error": {BANK.TRANSFER",
            "codeCARD"
 : "01",      ],
    "message : "Reason why it failed" "primary_color": "#b37038",
         }"secondary_color": "#b37038",
        "providerprimary_button_responsecolor": "#b37038",
{ 	       "responsemodal_background_codecolor": "91",
		linear-gradient(147.44deg, #d8903c 26.99%, #e69921 74.1%)",
        "responsepayment_option_messagecolor": "Failed",
			"meta":{
 rgba(76, 61, 47, 0.08)",
              "field_key":"field_value",
       "payment_option_active_color": "rgba(31, 31, 31, 0.25)",
        "fieldapp_keycolor": "field_value"
         #b37038"
    },
        }"app_info": {
     } }
Request (validate with otp)
 Code Block
languagejson
{
  "request_mode":"transfer_funds","name": "Victor Motors",
      "request_refid":"{{request_ref}} "5cdab3332b7d4100015f0db4",
      "requestbeneficiary_account_typeno": "lookup_bvn_max0001137069",
      "authextras": {/*this will contain an array of "type": null, 
provider specific settings*/}
   "secure": "{{otp}}",
    "auth_provider": "Beeceptor"
  },
  "transaction": {
    "mock_mode": null, 
    "transaction_ref": "{{transaction_ref}}", 
    "transaction_desc": null, 
    "transaction_ref_parent": null, 
    "amount": 1000,
    "customer":null,
    "meta":null,
    "details": null
  }
}
...
}
}
Explanation of the relevant fields
Field
Type
Description
request_mode
string
States the exact operation that the calling app is trying to execute. Possible values are transact, options, query, reverse, validate. 
client_info.options
array
An array of strings containing the processing options enabled for this app on the OnePipe console.
app_info.id
string
Unique identifier for the app on this OnePipe instance
app_info.name
string
The name of the app
app_info.beneficiary_account_no
string
The account number for the app on the console
app_info.extras[]
array
An array of key value pairs representing the settings required by the provider as configured on the console for the app. The provider needs to be aware of them and treat accordingly.