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 by using the custom_filters object in the metadata object.

Recurring Payment

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

1"metadata": {
2  "custom_filters": {
3    "recurring": true
4  }
5}

Selected Banks

You can use the banks parameter to specify an array of bank codes if you only want certain bank cards to be accepted for a transaction. You can use the List Banks^API to get the list of supported bank codes.

1"metadata": {
2  "custom_filters": {
3    "banks": ["057", "100"]
4  }
5}

Selected Card Brands

If you only want certain card brand(s) to be accepted for a transaction, specify the brands in the card_brands array:

1"metadata": {
2  "custom_filters": {
3    "card_brands": ["visa"]
4  }
5}

We currently support the following card brands:

The filters can also be combined for a comprehensive rule. In the snippet below, the filters tell us that the customer should be enrolled on recurring billing and we should only accept a visa card from Zenith (057) or Suntrust bank (100).

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}

Selected MoMo Provider

Sometimes, you want to give preference to only certain mobile money providers. For example, you might want to run a campaign to allow just a certain provider. To do this, you can specify the provider(s) in the supported_mobile_money_providers parameter:

1"metadata": {
2  "custom_filters": {
3    "supported_mobile_money_providers": ["vod"]
4  }
5}