Add custom data to your request payload

Crafting Metadata

With metadata, you can add additional parameters that an endpoint doesn't accept naturally. Crafting metadata will depend on your language's handling of JSON. Common metadata are:

  • Invoice ID
  • Cart ID
  • Cart Items
  • Payment medium (site/app)

There are two ways to add parameters to the metadata object:

  1. Key/value pair: You pass the parameter as a key and value pair like this: cart_id: IU929. Parameters passed this way don't show up on the dashboard, however, they are returned with the API response.
  2. Custom Fields: The custom_fields key is reserved for an array of custom fields that should show on the dashboard when you click the transaction.

Custom fields have 3 keys: display_name, variable_name, and value. The display name will be the label for the value when displaying.

2 "metadata": {
3 "cart_id": 398,
4 "custom_fields": [
5 {
6 "display_name": "Invoice ID",
7 "variable_name": "Invoice ID",
8 "value": 209
9 },
10 {
11 "display_name": "Cart Items",
12 "variable_name": "cart_items",
13 "value": "3 bananas, 12 mangoes"
14 }
15 ]
16 }

Cancel Action

You can redirect your users to a chosen URL when they cancel a payment. This is done by setting a cancel_action in your metadata:

1"metadata": {
2 "cancel_action": ""

Custom Filters

Custom filters allow you control how a transaction is completed.

Recurring (boolean)

If you need to directly debit the customer in future, specify recurring=true under this object to ensure we accept only verve cards that support recurring billing. And force a bank authentication for MasterCard and VISA.

Banks (array)

If you only want some particular bank(s) cards to be accepted for a transaction, specify the bank codes in the object thus: banks: ["057","100"] . To get the list of bank codes supported, please check this API endpoint: List BanksAPI.

Card Brands (array)

If you only want some particular card brand(s) to be accepted for a transaction, specify the brands in the object thus: brands: ["visa","verve"]

2 "metadata": {
3 "custom_filters": {
4 "recurring": true,
5 "banks": [
6 "057",
7 "100"
8 ],
9 "card_brands": [
10 "visa"
11 ]
12 }
13 }

This would mean the transaction is intended to be for enrolling on a recurring billing platform. And we should only accept a visa card from Zenith (057) or Suntrust bank (100).

All keys are optional.