Metadata

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.

1{
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  }
17}

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": "https://your-cancel-url.com"
3}

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 Banks^API.

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

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

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.