Metadata

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: metadata.id or metadata.name or metadata.date, and so on.

See the examples for more information.

curl https://api.mfsafrica.com/api/payments -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d phonenumber=+256778122118 \
-d currency=UGX \
-d amount=30 \
-d description="Per diem payment" \
-d callback_url="https://my.website/payments/callback" \
-d metadata.id=1234 \
-d metadata.name=Lucy \
-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);
System.out.println(response);

<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

Beyonic_Payment::create(array(
  "phonenumber" => "+256778122118",
  "amount" => "100.2",
  "currency" => "UGX",
  "description" => "Per diem payment",
  "payment_type" => "money",
  "callback_url" => "https://my.website/payments/callback",
  "metadata" => array("id"=>"1234", "name"=>"Lucy")
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

beyonic.Payment.create(phonenumber='+256778122118',
                       amount='1200',
                       currency='UGX',
                       description='Per diem',
                       callback_url='https://my.website/payments/callback',
                       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: "https://my.website/payments/callback",
    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.

The payment API
The contacts API
The collection requests API