5. Config Options

This page contains a breakdown of the configuration options that can be passed to control the behaviour of the VPay Javascript Payment Dropin
The dropin JS library options are a set of parameters passed into the create() function as a JSON payload (as seen from samples in previous pages). Below, each available option is described in detail.
S/N
Name
Description
Relevance
1
amount
This is the order amount (as it would be represented in note denomination, not coin denomination). E.g. 110.50, 21500, 7999.99. Amount must be greater than 0 and less than 10000000. NOTE: The amount you provide will always be rounded up to the nearest whole integer.
Required
2
currency
This is the currency in which order value is to be processed. Default: NGN. Use other currency codes e.g. USD if international payments are enabled for your account.
Optional
3
domain
Either sandbox or live. This determines whether the payment UI presents options for testing or options to accept live payments.
Required
4
key
Your merchant public key as copied from your VPay merchant account Settings -> API page. Use your merchant private key to authenticate server-side, web hook payloads. The private key is passed as a JWT token in the request header to your web hook as follows: headers: {
'Content-Type': 'application/json',
'x-payload-auth': JWT_TOKEN
} The deconstructed JWT token will contain a secret property with the private key as value.
Required
5
email
The customer email. A copy of successful payment receipts will be sent here. Default: [email protected]
Optional
6
transactionref
A unique, alphanumeric transaction reference, to be generated by you each time you initiate a fresh transaction. Use your preferred scheme for generation.
Required
7
customer_service_channel
The customer service & support channels of your business e.g. Tel: +2348030070000, Email: [email protected]
Required
8
txn_charge
Amount to be charged to paying customer in addition to the order amount above. This amount must be greater than 0 and will share currency with order amount.
Optional
9
txn_charge_type
Either flat or percentage. This indicates how the payment total should be computed using the order amount and txn_charge above. E.g. order amount = 1000, txn_charge = 5, txn_charge_type = “percentage” then total = 1000 + (1000 * 5%) = 1000 + 50 = 1050. NOTE: To balance a VPay transaction fee of say, 1.3%, compute the txn_charge as follows. 1) grand_total = amount / (1 - 1.3%) i.e. amount / (1 - 0.013) 2) txn_charge = grand_total - amount E.g. to cover charges for 1,000, txn_charge should be (1000 / (1 - 0.013)) - 1000 i.e. 13.2 or 14 rounded up to next whole integer. Ensure to set txn_charge_type to flat.
Optional (if txn_charge is not specified)
10
onSuccess(response)
Use this to provide a Javascript callback function that will be called on your checkout webpage once the transaction is confirmed as successful. A status payload will be sent through the response argument in this format: {message: "Status Description", code: "XX"}. Valid Responses Include:
{
message: "Transaction successful.
amount: 1200",
code: "00"
}
Recommended Practice
When client-side onSuccess is called, ALWAYS confirm transaction status from your server side before processing customer order. This confirmation is made possible because your server side web hook is also notified of success.
Optional (Not applicable to Mobile apps)
11
onExit(response)
Use this to provide a Javascript callback function that will be called once a user exits the dropin popup. A status payload will be sent through the response argument in this format: {
message: "Status Descripton",
code: "XX"
} Valid Responses Include:
{
message: "Timeout occurred
before transaction
confirmation",
code: "01"
}
{
message: "Timeout occurred
without user taking payment
action",
code: "02"
}
{
message: "User cancelled the
transaction",
code: "03"
}
{
message: "User exited the flow",
code: "04"
} {
message: "Failed transaction",
code: "09"
}
Optional (Not applicable to Mobile apps)