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:
| Required |
5 | The customer email. A copy of successful payment receipts will be sent here. Default: dropinpayments@vpay.africa | 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: support@yourorg.com | 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:
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:
| Optional (Not applicable to Mobile apps) |
Last updated