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

INTERFACE SPECIFICATION (APP → ONEPIPE)

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

A note on the secure element

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

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

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 MICRO SERVICE)

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.

  • No labels