The API supports Metadata on the contact, payment, and collection request APIs.

Metadata allows you to add custom key-value attributes when creating objects. You can use metadata to track any information you want to track by attaching it to a contact, payment, or collection request object.

For example, you can include a unique ID to identify a payment or add more information about a Contact. This data will be returned when you retrieve the record later and can be used to identify the record.

Metadata has the following constraints:

  • Metadata attributes must be key-value pairs.
  • Both the keys and values must be strings.
  • For each record, you can have up to 10 custom attributes.

Metadata is added to the object a set of key-value pairs, where the key is in the format metadata.key_name, for example: or or, and so on.

See the examples for more information.

curl -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d phonenumber=+256778122118 \
-d currency=UGX \
-d amount=30 \
-d description="Per diem payment" \
-d callback_url="" \
-d \
-d \
-d payment_type=money
package com.beyonic.examples;

import com.beyonic.models.Payment;

HashMap<String, Object> paymentCreate = new HashMap<>();
paymentCreate.put("phonenumber", "+80000000001");
paymentCreate.put("first_name", "Kennedy");
paymentCreate.put("last_name", "Amani");
paymentCreate.put("currency", "BXC");
paymentCreate.put("amount", "30");
paymentCreate.put("description", "Per diem payment");
paymentCreate.put("payment_type", "money");

JSONObject metadataObj = new JSONObject();
metadataObj.put("id", 1234);
metadataObj.put("name", "Lucy");

paymentCreate.put("metadata", metadataObj.toString());

response = new Payment().create(paymentCreate, null);

  "phonenumber" => "+256778122118",
  "amount" => "100.2",
  "currency" => "UGX",
  "description" => "Per diem payment",
  "payment_type" => "money",
  "callback_url" => "",
  "metadata" => array("id"=>"1234", "name"=>"Lucy")
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

                       description='Per diem',
                       metadata={'id': '1234', 'name': 'Lucy'}
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

payment = Beyonic::Payment.create(
    phonenumber: "+256778122118",
    amount: "100.2",
    currency: "UGX",
    description: "Per diem payment",
    payment_type: "money",
    callback_url: "",
    metadata: {id: "1234", name: "Lucy"}

API methods that support metadata

Not all API methods support metadata.

Currently, the following API methods and their corresponding objects support metadata.

  1. The payment API
  2. The contacts API
  3. The collection requests API