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: [e-mail]	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: [phone], Email: [e-mail]	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)