Here’s what a standard OnePipe call will look like:

{
  "request_ref":"{{request_ref}}", //a unique ref
  "request_type":"transfer_funds", //what service are you trying to execute
  "auth": {...}, //security details and what provider to forward the request to
  "transaction": {...} //details required to complete every call. Varies per service type
}

Supported operations on OnePipe

Calls to OnePipe APIs all go {{baseUrl}}/v2/transact/{{operation}}

Transact - The main call for the API service being requested: {{baseUrl}}/v2/transact/
Validate - Some services require a follow up call to finalise with an OTP or validation code. : {{baseUrl}}/v2/transact/validate
Options - Some services allow (or require) a preliminary options call to get some parameters to use in the main call: {{baseUrl}}/v2/transact/options
Query - All services support a way to query for status : {{baseUrl}}/v2/transact/query
Fulfil - Some services and providers support the ability to request for a partially completed transaction to be retried {{baseUrl}}/v2/transact/fulfil
Reverse - Some providers support the ability to rollback a transaction {{baseUrl}}/v2/transact/reverse

Interface specification (App → OnePipe)

All calls to OnePipe support for authorization details to be passed in where required in the auth.secure element.

A note on the secure element

When auth.type is ‘card’, it should be: TripleDES.encrypt("{card.Pan};{card.Cvv};{card.Expdate};{card.Pin}",secretKey)
When auth.type is ‘bank.account’ , it shd be: TripleDES.encrypt("{accountNumber};{bankCBNCode}",secretKey)
When auth.type is ‘wallet’ , it shd be: TripleDES.encrypt("{walletNumber};{providerCode}",secretKey)
When auth.type is ‘airtime’ , it shd be: TripleDES.encrypt("{phoneNumber};{telcoCode}",secretKey)
When auth.type is ‘voucher’ , it shd be: TripleDES.encrypt("{voucherCode};{providerCode}",secretKey)
When auth.type is ‘bvn’, it shd be: TripleDES.encrypt("{bvn}",secretKey)
When auth.type is ‘basic’ , it shd be: TripleDES.encrypt("{userName};{password}",secretKey)
When auth.type is 'custom' (masterpass specifically) , it shd be: TripleDES.encrypt("{user_id};{card_id};{pin}",secretKey)
When auth.type is ‘custom’ (anything else) , it shd be: TripleDES.encrypt("{ref}",secretKey)

For details on encryption using the Triple DES Algorithm, read this.

NOTE: While it’s such that some providers will need a PIN for their auth Type, others will likely not. But the interfaces are standardized not to request this value (except in the case of cards). If a provider needs it, they should respond with PendingValidation and request for the PIN.

A typical /transact request

The actual API call to process a transaction

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

{
    "status": "Successful",
    "message": "Transaction processed successfully",
    "data": {
        "provider_response_code": "00",
        "provider": "Beeceptor",
        "errors": null,
        "error": null,
        "provider_response": {
            "reference": "000022200225154318222333334432",
            "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":{
              "fee_flat": 0,
              "fee_percent": 0,
              "commission_flat": 0,
              "commission_percent": 0,
              "field_key":"field_value",
              "field_key":"field_value"
            }
        }
    }
}

NOTE: For a successfully completed transaction the response.data.provider_response.metaobject should at a minimum contain 4 fields:

fee_flat: Any flat fee that was charged to the calling client
fee_percent: Any percentage-based fee that was charged to the calling client
commission_flat: Any flat amount commission paid to the calling client
commission_percent: Any percentage-based commission paid to the calling client

A typical /transact/validate request

This is when Providers respond with WaitingForOTP or PendingValidation.

{
  "request_ref":"{{request_ref}}", 
  "request_type":"lookup_bvn_max",
	"auth": {
        "secure": "{{encrypted_otp_orPIN_orOtherInput}}",
        "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

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

{
  "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 /transact/fulfil request

To force-complete a prior transaction that is partially completed. e.g. Airtime in which the customer was debited but the airtime didn't vend.

{
    "request_ref": "{{request_ref}}",
    "request_type": "{{request type}",
    "request_mode": "fulfil",
    "transaction": {
        "amount": "18000",
        "transaction_ref": "{{transaction_ref}}",
        "transaction_desc": "{{transaction_desc}}",
        "transaction_ref_parent": "{{parent_transaction_ref}}",
        "details": {...}
    }
}

A /transact/fulfil request should typically lead to a completion response (or in some cases: another validate response if appropriate)

A typical /transact/reverse request

To rollback a prior completed transaction (when supported by a provider or service)

{
	"request_ref":"{{request-ref}}",
	"request_type":"{{request_type}}",
	"transaction":{
		"transaction_ref": "12978251696483"
	}
}

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.
data.provider_response.reference	string	optional	In the event that a provider issues its own unique reference for tracing a transaction (for reconciliation purposes), this field should be populated with that value.

Interface specification (OnePipe → Provider microservice)

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)

{
  "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",
        "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 specific settings*/}
    }
  }
}

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.

Typical Payloads