NAV
CURL PHP RUBY PYTHON JAVA

Introduction

Scroll down for examples.

Welcome to Beyonic’s API documentation.

The Beyonic API is REST based. We provide libraries for several languages, including PHP, Java, Ruby and Python. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

All responses shall be returned using JSON, however, if you are using the language libraries, the JSON responses will be converted into native, language specific objects.

Quick Start

Can’t wait to dive in? Follow the 6 steps below to get started.

  1. Sign Up for a Beyonic account.
  2. Login and get your API Token by clicking the user icon on the top left corner, and selecting ‘Profile’ from the dropdown menu. The API Token is shown at the bottom of the page.
  3. Download the appropriate client library from links in the “Libraries” section of this reference.
  4. Using your API token and the library, connect to the API endpoint: https://app.beyonic.com/api
  5. Identify the methods you need to use. See the “Methods” section of this reference.
  6. Profit!

Libraries

Here are links to the various client libraries & specific installation instructions:

API Endpoint

You access Beyonic’s API at the following endpoint:

This endpoint uses your saved API version (see below). If you’d like to make sure that your application always accesses the same version, you can specify a specific version as shown in the versioning section.

Versioning

Example Request:

curl -H "Beyonic-Version: v1" https://app.beyonic.com/api
require 'beyonic'
Beyonic.api_version = 'v1'
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiVersion("v1");
?>
import beyonic
beyonic.api_version = 'v1'

New API versions are released only when we make backward incompatible changes to the API. We define these as changes that will prevent our official clients from working on old versions. Some changes DO NOT result in a new version, including: Adding new API methods, adding optional parameters to existing API methods or adding new fields to responses.

You don’t need to specify a version in your request. The first time an API request is made for your organization, the version is saved, and will be used on subsequent API requests unless it is changed in the organization settings, or overridden as below. This allows your client applications to continue working even if newer API versions are released.

You can temporarily override the API version for a specific request in 2 ways:

The various API libraries provide methods for changing the version, as shown in the examples to the right.

Note that this doesn’t change your organization’s default API version, which was saved in your organizations settings the first time you interacted with the Beyonic API. To change your default API version, log into the web portal and go to “Company Settings” > Settings (Cogwheel) > Manage General Settings.

Authentication

Example Request:

curl https://app.beyonic.com/api -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey('ab594c14986612f6167a975e1c369e71edab6900');
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

All requests must use https.

The Beyonic API uses Token Based Authentication, and requires an API key for authentication. You can generate or change your API key by logging into your account. Keep your API key secret to maintain the integrity of your account.

You must supply your API key with all API requests using the “Authorization” header as shown in the examples. You should inculde your API key with all requests.

The API key in all the examples is a valid test key, so you can test the examples immediately.

Pagination

Pagination Example Request:

curl https://app.beyonic.com/api/v2/contacts?limit=10&offset=5 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_vesion = 'v2'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = Beyonic::Contact.list(
  limit: 10,
  offset: 5
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiVersion("v2");
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contacts = Beyonic_Contact::getAll(array(
  "limit" => "10",
  "offset" => "5"
));
?>
import beyonic
beyonic.api_version = 'v2'
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = beyonic.Contact.list(limit='10',
                                  offset='5')


Most Beyonic API methods support a way to retrieve a list of records. For example, you can retrieve a list of contacts.

When retrieving a list, you can control the number of records returned by adding two parameters to your request:

The API response body shall include the following parameters:

Ordering Results

Ordering Example:

curl https://app.beyonic.com/api/contacts?ordering=-created -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = Beyonic::Contact.list(
  ordering: '-created'
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contacts = Beyonic_Contact::getAll(array(
  "ordering" => "-created"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = beyonic.Contact.list(ordering='-created')


Most Beyonic API methods support a way to retrieve a list of records. For example, you can retrieve a list of contacts.

When retrieving a list, you can control the order that records are returned in by adding one parameters to your request:

Ascending or Descending order:

Filtering Results

Filtering Example:

curl https://app.beyonic.com/api/contacts?first_name=tom -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = Beyonic::Contact.list(
  first_name: 'tom'
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contacts = Beyonic_Contact::getAll(array(
  "first_name" => "tom"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = beyonic.Contact.list(first_name='tom')


Most Beyonic API methods support a way to retrieve a list of records or a single record. For example, you can retrieve a list of contacts or a single contact.

When retrieving a list or a single record, you can limit the results to records where a given field matches specific search criteria. To do this, add the keyword to your request as shown in the examples.

Not all fields are filterable. See the documentation for each method below to see which fields are filterable within that method.

Metadata

Example showing how to create a new payment with Metadata:

curl https://app.beyonic.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
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"}
)
<?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'}
                       )

Beyonic supports Metadata, which allows you to add custom key-value attributes when creating objects. 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 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.

Custom Fields

Custom Fields are similar to Metadata - they allow you to add custom data to some objects. There are a couple of differences between custom fields and other metadata:

  1. Custom fields are available through the web interface as well, while metadata fields are only available through the API
  2. Metadata keys and values can be created and edited through the API, while custom fields can only be created through the web interface (currently, you need to request addition of a custom field by contacting us). However, once custom fields have been created through the web interface, they can be updated or edited through the API as well.
  3. Metadata consists of string-based keys and string-based values. Custom field keys are strings (starting with “s_”), but the values may be of different types, including strings, numbers, boolean values or enum values (restricted to a predefined set of values)

Adding or updating custom field data

All internal custom field labels or keys start with “s_”. To see the available custom fields, and their actual key names, you can read or list the related object records, as detailed in the respective APIs.

For example, to see custom fields that have been added to your payment object, list your payments. You can identify the custom fields by their keys, which all start with “s_”.

Once you know the custom field key, you can update it’s value just like any other metadata value.

API methods that support custom fields.

Not all API methods support custom fields. Currently, the following API methods and their corresponding objects support custom fields.

  1. The payment API
  2. The contacts API

Testing

Beyonic provides a few features to ease API testing. These features are described below.

Test API token

All the examples include a test API token that actually works. They can be run directly, which enables you to try them out as you read the documentation

Test Currency

Beyonic provides a test currency, with the following parameters: * Country Code: +401 * Currency Code: BXC

The BXC currency is used throughout the examples and you can also use it in your own testing. Payments made in the BXC currency will not affect your live currency accounts. Additionally, depending on the number you are paying, you can test various success and failure scenarios. See “Test Numbers” below

Note: Currently, this test currency works only for outgoing payments.

Enabling or disabling the test currency

To enable or disable the test currency, once you’re logged into Beyonic, go to this URL:

Or go to “Home” > “Company Settings” > (Cogwheel) > Test Tools.

From that URL, you can enable the test currency, and also update the available test credit.

Test Numbers

Beyonic provides test numbers that should be used in conjunction with the test currency. The following numbers are treated in special ways when used with the BXC currency:

Note: Make sure you have enough BXC credit on your account. Use https://app.beyonic.com/testing/ to update your BXC credit.

Testing Webhooks

1. Https with invalid certificates

Beyonic only supports notification urls (also called webhooks or callback urls) that start with “https://”, even when testing. See the “Webhooks” section for more infromation. So, you should set up URL to a dedicated page on your server with a server-side https certificate.

Beyonic will usually validate the https certificate, and if validation fails, the notification will not be sent to your URL. To skip validation while testing, add ?skip-cert-verify to your URL, for example:

Note that skip-cert-verify only prevents certificate verification. It doesn’t eliminate the “https://” requirement

While you can use skip-cert-verify on your production URLs, we advise you to use valid server side certificates to maximize security on your production systems

2. Setting up a temporary callback URL and verifying the format of the notifications

If you are not able to set up a dedicated “https://” url while testing, we recommend using a service like RequestBin.

RequestBin gives you a URL that will collect requests made to it and let you inspect them in a human-friendly way. Use RequestBin to inspect and debug the webhook notifications.

Once you get a RequestBin URL, it uses http by default. Since Beyonic only supports https, remember to use “https://” and “skip-cert-verify”

For example, if your RequestBin URL is

Then use this for your callback URLs:

3. Logging all callback requests and responses

RequestBin will only show you the request format, but will not send the request to your final callback URL, and will not show you the response that Beyonic is receiving from your callback URL.

A number of third party services can be used to provide request proxying and logging. For example, Runscope provides full traffic inspection and debugging via its Gateway URLs service. This service will provide a custom URL for you, that will proxy the callbacks to your real callback URL, and log both the requests and responses. Runscope provides free plans as well as paid plans.

Once you have your gateway URL from Runscope, use that as your callback URL in Beyonic.

See this article for more information.

Changelog

This section lists new versions and the changes made in those versions. Review these changes to decide whether you need to upgrade to the new version. Note that only backward incompatible changes are shown. See the Versioning section for more information on how to upgrade to a new version.

v2 - February 2016

v2 - November 2015

Methods

These are the methods supported by Beyonic’s API. Clicking on each method in the table of contents shall reveal the actions supported by each method.

Accounts

Introduction

Accounts are buckets from which money to be sent is debited. The accounts api method allows you to list your accounts and view balances for each account.

The accounts api endpoint is https://app.beyonic.com/api/accounts

The account object

Field Type Description
id long integer Unique object identifier
organization long integer The ID of the organization that the account belongs to. (This is usually your organization ID)
balance float The current account balance
currency string The account’s currency code. i.e KES, UGX
status string The account’s status. One of: active or inactive
created string The date that the account was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
author long integer The ID of the user who created the account
modified string The date that the account was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated_by string The ID of the user who last updated the account

Listing all accounts

Sample Request:

curl https://app.beyonic.com/api/accounts -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

$accounts = Beyonic_Account::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

accounts = beyonic.Account.list()

package com.beyonic.examples.accounts;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class ListAllAccountsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/accounts";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON)

{
    "count": 2,
    "next": "https://app.beyonic.com/api/accounts?offset=10",
    "previous": null,
    "results": [
        {
            "id": 1146,
            "organization":1,
            "balance": 200.0,
            "currency": "KES",
            "status": "active",
            "created": "2015-02-13T04:22:31Z",
            "author": 7,
            "modified": "2015-02-26T13:00:35Z",
            "updated_by": 1
        },
        {
            "id": 1147,
            "organization":1,
            "balance": 100.0,
            "currency": "UGX",
            "status": "active",
            "created": "2015-02-13T04:22:31Z",
            "author": 7,
            "modified": "2015-02-26T13:00:35Z",
            "updated_by": 1
        },
    ]
}

To retrieve a list of all accounts, make a GET request to the accounts end point. This will return a list of accounts.

Filtering accounts

Sample Request:

curl https://app.beyonic.com/api/accounts?currency=KES -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

accounts = Beyonic::Account.list(
  currency: "KES"
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$accounts = Beyonic_Account::getAll(array(
  "currency" => "KES"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

accounts = beyonic.Account.list(currency='KES')

package com.beyonic.examples.accounts;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class FilterAccountsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/accounts";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "?currency=UGX");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

You can search or filter accounts on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only.

Collections (Incoming)

Introduction

Collections are payments sent to you from mobile subscribers. See how collections work for more information.

When the user sends in a payment, it will create a collection object that you can access via the Collections API using the methods shown below.

The collections api endpoint is:

The collection object

Field Type Description
id long integer Unique object identifier
remote_transaction_id string The unique transaction ID from the mobile network operator
organization long integer The ID of the organization that the collection was matched to
amount decimal The collection amount
currency string The 3 letter ISO currency code for the collection. Note:: BXC is the Beyonic Test Currency code. See the “Testing” section for more information. Supported currency codes are BXC (Testing), UGX (Uganda), KES (Kenya)
phonenumber string The phone number that the collection was initiated from, in international format, starting with a +
payment_date string The date that the collection was made, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
reference string The description or reference code that was included with the collection
status string A string showing the status of the collection. One of: successful, failed, pending or cashed_out
created string The date that the collection was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
author long integer The ID of the user who created the collection
modified string The date that the collection was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated_by string The ID of the user who last updated the collection
collection_request long integer or null The ID of the collection request that this collection was matched to, if any

Retrieving a single collection

Sample Request:

curl https://app.beyonic.com/api/collections/230 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = ab594c14986612f6167a975e1c369e71edab6900'

collection = Beyonic::Collection.get(23)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$collection = Beyonic_Collection::get(23);
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = beyonic.Collection.get(23)

package com.beyonic.examples.collections;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;


public class SingleCollectionExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/collections";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "/1");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON):

{
    "id": 230,
    "remote_transaction_id": "12132",
    "organization": 1,
    "amount": "20.0000",
    "currency": 1,
    "phonenumber": "+401000000001",
    "payment_date": "2015-12-12T00:00:00Z",
    "reference": null,
    "status": "successful",
    "created": "2015-08-01T16:49:48Z",
    "author": null,
    "modified": "2015-08-01T16:55:38Z",
    "updated_by": null
}

To retrieve a single collection object, provide the collection id and a collection object will be returned.

Parameter Required Type Example Notes
id Yes Integer 23 The id of the collection you want to retrieve

Listing all collections

Sample Request:

curl https://app.beyonic.com/api/collections -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

$collection = Beyonic_Collection::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = beyonic.Collection.list()

package com.beyonic.examples.collections;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class ListAllCollectionsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/collections";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON)

{
    "count": 3,
    "next": "https://app.beyonic.com/api/collections?offset=10",
    "previous": null,
    "results": [
        {
            "id": 82,
            "remote_transaction_id": "1485758785",
            "organization": 1,
            "amount": "2000.0000",
            "currency": 2,
            "phonenumber": "+401000000001",
            "payment_date": "2015-07-14T09:57:44Z",
            "reference": "beyonic",
            "status": "successful",
            "created": "2015-07-14T15:19:05Z",
            "author": null,
            "modified": "2015-08-20T16:48:51Z",
            "updated_by": null
        },
        {
            "id": 81,
            "remote_transaction_id": "225718814",
            "organization": 1,
            "amount": "2000.0000",
            "currency": 2,
            "phonenumber": "+401000000001",
            "payment_date": "2015-07-14T10:26:32Z",
            "reference": "Payment Ian M",
            "status": "successful",
            "created": "2015-07-14T10:27:08Z",
            "author": null,
            "modified": "2015-07-14T10:27:11Z",
            "updated_by": null
        },
        {
            "id": 77,
            "remote_transaction_id": "215569420",
            "organization": 1,
            "amount": "500.0000",
            "currency": 2,
            "phonenumber": "+401000000001",
            "payment_date": "2015-06-25T08:16:26Z",
            "reference": "payment 10",
            "status": "successful",
            "created": "2015-06-25T08:17:07Z",
            "author": null,
            "modified": "2015-06-25T08:17:18Z",
            "updated_by": null
        },
    ]
}

To retrieve a list of all collections, make a GET request to the collections endpoint. This will return a list of collection objects.

Filtering collections

Sample Request:

curl https://app.beyonic.com/api/collections?phonenumber=+401000000001&remote_transaction_id=SS12312 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = Beyonic::Collection.list(
  phonenumber: "+401000000001",
  remote_transaction_id: "SS12312"
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$collection = Beyonic_Collection::getAll(array(
  "phonenumber" => "+401000000001",
  "remote_transaction_id" => "SS12312"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = beyonic.Collection.list(phonenumber='+401000000001',
                                     remote_transaction_id='SS12312')


package com.beyonic.examples.collections;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class FilterCollectionsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/collections";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "?remote_transaction_id=SS12312");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON)

[
       {
        "id": 134,
        "phonenumber": "+256XXXXXX",
        "remote_transaction_id": "ASDCECASF",
        "payment_date": "2014-11-22T20:57:04Z",
        "reference": "Test Payment",
        "amount": 3000.000,
        "currency": "BXC",
        "status": "successful"
       }
]

You can search or filter collections on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only (the phonenumber field is treated differently - see below).

Response

Note that the response will be a list of collections, not a single collection.

Claiming an ummatched collection

Sample Request:

curl https://app.beyonic.com/api/collections?phonenumber=+401000000001&remote_transaction_id=SS12312&claim=True&amount=200 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = Beyonic::Collection.list(
  phonenumber: "+401000000001",
  remote_transaction_id: "SS12312",
  claim: true,
  amount: 200
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$collection = Beyonic_Collection::getAll(array(
  "phonenumber" => "+401000000001",
  "remote_transaction_id" => "SS12312",
  "claim" => "True",
  "amount" => "200",
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = beyonic.Collection.list(phonenumber='+401000000001',
                                     remote_transaction_id='SS12312',
                                     claim=True,
                                     amount='200')


package com.beyonic.examples.collections;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class ClaimUnmatchedCollectionExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/collections";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "?phonenumber=+401000000001&remote_transaction_id=SS12312&amount=200&claim=True");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON)

[
       {
        "id": 134,
        "phonenumber": "+256XXXXXX",
        "remote_transaction_id": "ASDCECASF",
        "payment_date": "2014-11-22T20:57:04Z",
        "reference": "Test Payment",
        "amount": 3000.000,
        "currency": "BXC",
        "status": "successful"
       }
]

By default, when you search for a collection, only collections that have been successfully assigned to your organization are searched.

You can add the “claim” parameter to instruct Beyonic to also search unmatched collections, and if any of the unmatched collections match your input, they will be assigned to your organization.

Note that when you include the claim parameter, you must also include the amount, remote_transaction_id and phonenumber parameters. Failure to do so will result in an error.

Also note that the phonenumber will be matched in international format, starting with a ’+’ sign. Partial phone number matches will fail when you try to claim a transaction. If the ’+’ sign isn’t included in your request, it will be appended before attempting to match your request.

Lastly, if your search parameters match more than one collection, the claim will fail.

Parameter Type Example Notes
claim Boolean or String True Instruct system to search unmatched transctions and claim them for your organization.

Response

Note that the response will be a list of collections, not a single collection.

Collection Requests (Billing)

Introduction

Collection Requests allow you to notify a customer to send funds to you. When you create a collection request, we send a notification to the customer, with insructions on how to fulfill the request. When they send the funds, a collection object shall be created, and matched with the collection request.

Creating a collection request prior to receiving an expected collection greatly improves the user experience for your subscribers by automatically matching transactions to your organization, even if the subscriber misses out some information or gets some of the information wrong, for example if they forget to include a reference code. Payments matching the amount, number and currency in the collection requests will be correctly assigned to you.

On some supported networks, collection requests actually “pull” the funds from the recipient’s mobile money wallet, and all they have to do is enter their PIN code to approve the transaction. This greatly improves the customer experience.

The collection requests api endpoint is:

The collection request object

Field Type Description
id long integer Unique object identifier
organization long integer The ID of the organization that owns this collection request (This is usually your organization ID)
amount decimal The collection request amount
currency string The 3 letter ISO currency code for the collection request. Note:: BXC is the Beyonic Test Currency code. See the “Testing” section for more information. Supported currency codes are BXC (Testing), UGX (Uganda), KES (Kenya)
phonenumber string The phone number that the collection request is intended for, in international format, starting with a +
reason string or null Internal description or reason for this collection request
metadata hash Any custom metadata that was added to the collection request when it was created
created string The date that the collection request was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
author long integer The ID of the user who created the collection request
modified string The date that the collection request was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated_by string The ID of the user who last updated the collection request
collection long integer or null The ID of the collection that fulfilled the collection request, if any
success_message string or null The confirmation message delivered to the customer upon successful completion of this payment request
instructions string or null Any custom instructions that were delivered to the customer
send_instructions boolean Whether or not Beyonic will attempt to send instructions to the user

Creating a new collection request

Sample Request:

curl https://app.beyonic.com/api/collectionrequests -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d phonenumber=+401000000001 \
-d currency=BXC \
-d amount=3000 \
-d metadata.my_id='123ASDAsd123'
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = Beyonic::CollectionRequest.create(
    phonenumber: "+401000000001",
    amount: "100.2",
    currency: "BXC",
    metadata: {"my_id": "123ASDAsd123"}
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

Beyonic_Collection_Request::create(array(
  "phonenumber" => "+401000000001",
  "amount" => "100.2",
  "currency" => "BXC",
  "metadata" => array("my_id"=>"123ASDAsd123")
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'


beyonic.CollectionRequest.create(phonenumber='+401000000001',
                       amount='1200',
                       currency='BXC',
                       description='Per diem',
                       callback_url='https://my.website/payments/callback',
                       metadata={'my_id': '123ASDAsd123'}
                       )
package com.beyonic.examples.collectionrequests;

import org.json.JSONException;
import org.json.JSONObject;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class CreateCollectionRequestExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/collectionrequests";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";
    private static final String PHONE_NUMBER = "+401000000001";
    private static final String CURRENCY = "BXC";
    private static final String DESCRIPTION = "Per Diem";
    private static final String AMOUNT = "1200";
    private static final String CALLBACK_URL = "https://my.website/payments/callback";;

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);
            conn.setRequestMethod("POST");
            conn.setDoOutput(true);
            conn.setDoInput(true);

            JSONObject collectionRequestObject = createCollectionRequestObject();

            BufferedWriter out = new BufferedWriter(new OutputStreamWriter(conn.getOutputStream()));
            out.write(collectionRequestObject.toString());
            out.close();

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            int beyID = 0;
            try {
                if (conn.getResponseCode() == 201) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    JSONObject obj = new JSONObject(response);
                    beyID = obj.getInt("id");
                    System.out.println("ID of created Collection Request: " + beyID);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static JSONObject createCollectionRequestObject() throws JSONException {
        JSONObject collectionRequest = new JSONObject();
        collectionRequest.put("phonenumber", PHONE_NUMBER);
        collectionRequest.put("amount", AMOUNT);
        collectionRequest.put("currency", CURRENCY);
        collectionRequest.put("description", DESCRIPTION);
        collectionRequest.put("callback_url", CALLBACK_URL);
        return collectionRequest;
    }
}

Sample Response (JSON):

{
    "id": 3620,
    "organization": 1,
    "amount": "30",
    "currency": "BXC",
    "phone_number": "+401000000001",
    "metadata": {
        "my_id": "123ASDAsd123"
    },
    "created": "2014-11-22T20:57:04.017Z",
    "author": 15,
    "modified": "2014-11-22T20:57:04.018Z",
    "updated_by": null
}

To create a new collection request, make a POST to the endpoint above, with the attributes below.

Parameter Required Type Example Notes
phonenumber Yes String +401000000001 Must be in international format
first_name No String Luke Optional subscriber first name - if omitted, the first name will be set to ‘Anonymous’
last_name No String Woods Optional subscriber last name - if omitted, the last name will be set to 'Contact’
amount Yes String, Integer or Decimal 3000 Do not include thousands separators
currency Yes String BXC 3 letter ISO currency code. No currency conversion is done, so the currency must be valid for the selected phonenumber. You must have funded Beyonic an account in this currency. If your account for this currency has zero balance, your payment will fail. Note:: BXC is the Beyonic Test Currency code. See the “Testing” section for more information. Supported currency codes are BXC (Testing), UGX (Uganda), KES (Kenya)
reason No String Transaction Fees Internal description or reason for this collection request
metadata No JSON String “{'my_id’: '123ASDAsd123’}” Custom attributes to store with this object. See the Metadata section for more information.
success_message No String (Max 140 characters) “Thank you for your payment!” New in V2. This message will be sent via SMS to the subscriber when they make a payment for this collection request. ’-Powered by Beyonic’ shall be appended to this message. If you leave this message out, a default message shall be sent by Beyonic. You can include {amount} and {customer} placeholders - these will be replaced with the amount and customer name or number details before the message is sent.
send_instructions No Boolean False New in V2. Defaults to True. Indicates whether we should send payment instructions to the subscriber via SMS. This value may be ignored on some networks that have alternative ways of notifying the subscriber of pending payment requests.
instructions No String (Max 140 characters) “Use #1234 as the reference” New in V2. Allows overriding of the default instructions sent to the subscriber. This value may be ignored on some networks that have alternative ways of notifying the subscriber of pending payment requests.

Retrieving a single collection request

Sample Request:

curl https://app.beyonic.com/api/collectionrequests/230 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = Beyonic::CollectionRequest.get(23)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$collection = Beyonic_Collection_Request::get(23);
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = beyonic.CollectionRequest.get(23)

package com.beyonic.examples.collectionrequests;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;


public class SingleCollectionRequestExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/collectionrequests";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "/1");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON):

{
    "id": 230,
    "organization": 1,
    "amount": "30",
    "currency": "BXC",
    "phone_number": "+401000000001",
    "created": "2014-11-22T20:57:04.017Z",
    "author": 15,
    "modified": "2014-11-22T20:57:04.018Z",
    "updated_by": null
}

To retrieve a single collection request, provide the collection request id and a collection request object will be returned.

Parameter Required Type Example Notes
id Yes Integer 23 The id of the collection you want to retrieve

Listing all collection requests

Sample Request:

curl https://app.beyonic.com/api/collectionrequests -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

$collection = Beyonic_Collection_Request::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = beyonic.CollectionRequest.list()

package com.beyonic.examples.collectionrequests;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class ListAllCollectionRequestsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/collectionrequests";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON)

{
    "count": 3,
    "next": "http://localhost:8000/api/collectionrequests?offset=10",
    "previous": null,
    "results": [
        {
            "id": 99,
            "organization": "Beyonic",
            "amount": "3000.0000",
            "currency": "BXC",
            "phonenumber": "+401000000001",
            "metadata": null,
            "created": "2015-08-10T16:10:01Z",
            "author": 42,
            "modified": "2015-08-10T16:10:01Z",
            "updated_by": 42
        },
        {
            "id": 100,
            "organization": "Beyonic",
            "amount": "3000.0000",
            "currency": "BXC",
            "phonenumber": "+401000000001",
            "metadata": null,
            "created": "2015-08-10T16:10:01Z",
            "author": 42,
            "modified": "2015-08-10T16:10:01Z",
            "updated_by": 42
        },
        {
            "id": 101,
            "organization": "Beyonic",
            "amount": "3000.0000",
            "currency": "BXC",
            "phonenumber": "+401000000001",
            "metadata": null,
            "created": "2015-08-10T16:10:01Z",
            "author": 42,
            "modified": "2015-08-10T16:10:01Z",
            "updated_by": 42
        }
    ]
}

To retrieve a list of all collections, make a GET request to the collections endpoint. This will return a list of collection objects.

Filtering collection requests

Sample Request:

curl https://app.beyonic.com/api/collectionrequests?remote_transaction_id=12345&amount=500 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = Beyonic::CollectionRequest.list(
  remote_transaction_id: '12345',
  amount: 500
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$collection = Beyonic_Collection_Request::getAll(array(
  "remote_transaction_id" => "12345",
  "amount" => 500
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = beyonic.CollectionRequest.list(remote_transaction_id='12345', amount=500)

package com.beyonic.examples.collectionrequests;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class FilterCollectionRequestsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/collections";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "?remote_transaction_id=SS12312&amount=500");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

You can search or filter collection requests on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only. (The phonenumber field is treated differently - see below).

Contacts

Introduction

Contacts represent people whom you can send payments to, or receive payments from. The contacts api method allows you to add, retrieve, list and update contacts in your Beyonic account. Contacts are also added automatically whenever you send a payment to a new phone number.

The contacts api endpoint is:

The contact object

Field Type Description
id long integer Unique object identifier
organization long integer The ID of the organization that the contact belongs to. (This is usually your organization ID)
first_name string The contact’s first name
last_name string The contact’s last name
email string The contact’s email address
phone_number string The contact’s phone number, in international format, starting with a +
type string The contact’s type, as set in the system. One of: employee, beneficiary, vendor, other OR a custom string
status string The contact’s status. One of: active or inactive
metadata hash Any custom metadata that was added to the contact object at creation time
created string The date that the contact was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
author long integer The ID of the user who created the contact
modified string The date that the contact was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated_by string The ID of the user who last updated the contact

Creating a new contact

Sample Request:

curl https://app.beyonic.com/api/contacts -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d first_name='John' \
-d last_name='Doe' \
-d phone_number='+401000000001' \
-d email=[email protected]' \
-d metadata.my_id='123ASDAsd123'
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = Beyonic::Contact.create(
    phone_number: "+401000000001",
    first_name: "John",
    last_name: "Doe",
    email: "[email protected]",
    metadata: {"my_id": "123ASDAsd123"}
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

Beyonic_Contact::create(array(
  "phone_number" => "+401000000001",
  "first_name" => "John",
  "last_name" => "Doe",
  "email" => "[email protected]",
  "metadata" => array("my_id"=>"123ASDAsd123")
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

beyonic.Contact.create(phone_number='+401000000001',
                       first_name='John',
                       last_name='Doe',
                       email=[email protected]',
                       metadata={'my_id': '123ASDAsd123'}
                       )
package com.beyonic.examples.contacts

import org.json.JSONException;
import org.json.JSONObject;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import static org.junit.Assert.assertTrue;

public class CreateContactExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/contacts";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";
    private static final String FIRST_NAME = "John";
    private static final String LAST_NAME = "Doe";
    private static final String PHONE_NUMBER = "+401000000001";
    private static final String EMAIL = "[email protected]";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);
            conn.setRequestMethod("POST");
            conn.setDoOutput(true);
            conn.setDoInput(true);

            JSONObject contact = createContactObject();

            BufferedWriter out = new BufferedWriter(new OutputStreamWriter(conn.getOutputStream()));
            out.write(contact.toString());
            out.close();

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            int beyID = 0;
            try {
                if (conn.getResponseCode() == 201) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    JSONObject obj = new JSONObject(response);
                    beyID = obj.getInt("id");
                    System.out.println("ID of created Contact: " + beyID);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static JSONObject createContactObject() throws JSONException {
        JSONObject contact = new JSONObject();
        contact.put("phone_number",PHONE_NUMBER);
        contact.put("first_name",FIRST_NAME);
        contact.put("last_name",LAST_NAME);
        contact.put("email",EMAIL);
        return contact;
    }
}

Sample Response (JSON):

{
    "id": 26,
    "organization": "Beyonic",
    "first_name": "Suzanne",
    "last_name": "Kwagala",
    "email": "[email protected]",
    "phone_number": "+401000000001",
    "type": "employee",
    "status": "active",
    "metadata": {
        "my_id": "123ASDAsd123"
    },
    "created": "2013-09-19T21:26:10Z",
    "author": 1,
    "modified": "2015-04-14T18:21:47Z",
    "updated_by": 42
}

To create a new contact, make a POST to the endpoint above, with the attributes below.

Parameter Required Type Example Notes
phone_number Yes String +401000000001 Must be in international format
first_name Yes String John The contact’s first name
last_name Yes String Doe The contact’s last name
email No String [email protected] The contact’s email address
metadata No JSON String “{‘my_id’: '123ASDAsd123’}” Custom attributes to store with this object. See the Metadata section for more information.

Retrieving a single contact

Sample Request:

curl https://app.beyonic.com/api/contacts/44702 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = Beyonic::Contact.get(44702)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contact = Beyonic_Contact::get(44702);
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = beyonic.Contact.get(44702)

package com.beyonic.examples.contact;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;


public class SingleContactExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/contacts";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "/44702");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON):

{
    "id":44702,
    "organization":4,
    "first_name":"John",
    "last_name":"Doe",
    "email":null,
    "phone_number":"+401000000001",
    "type":"employee",
    "status":"active",
    "metadata":{},
    "created":"2016-03-30T17:44:30Z",
    "author":134,
    "modified":"2016-03-30T17:45:22Z",
    "updated_by":134
}

To retrieve a single contact, provide the contact id and a contact object will be returned.

Parameter Required Type Example Notes
id Yes Integer 23 The id of the contact you want to retrieve

Listing all contacts

Sample Request:

curl https://app.beyonic.com/api/contacts -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

$contact = Beyonic_Contact::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = beyonic.Contact.list()

package com.beyonic.examples.contacts

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class ListAllContactsExample{

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/contacts";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON)

{
    "count": 2,
    "next": "https://app.beyonic.com/api/contacts?offset=10",
    "previous": null,
    "results": [
        {
            "id": 1146,
            "organization": "Demo Org",
            "first_name": "Eliana",
            "last_name": "Kalema",
            "email": null,
            "phone_number": "+25677XXXXXX",
            "type": "other",
            "status": "active",
            "metadata": null,
            "created": "2015-02-13T04:22:31Z",
            "author": 7,
            "modified": "2015-02-26T13:00:35Z",
            "updated_by": 1
        },
        {
            "id": 1175,
            "organization": "Demo Org",
            "first_name": "Trina",
            "last_name": "Faith",
            "email": null,
            "phone_number": "+25677XXXXXX",
            "type": "employee",
            "status": "active",
            "metadata": null,
            "created": "2015-02-18T11:52:43Z",
            "author": 137,
            "modified": "2015-02-26T13:00:35Z",
            "updated_by": 1
        },
    ]
}

To retrieve a list of all contacts, make a GET request to the contact end point. This will return a list of contacts.

Filtering contacts

Sample Request:

curl https://app.beyonic.com/api/contacts?first_name=luke -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = Beyonic::Contact.list(
  first_name: "luke"
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contact = Beyonic_Contact::getAll(array(
  "first_name" => "luke"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = beyonic.Contact.list(first_name='luke')

package com.beyonic.examples.contact;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class FilterContactsExample{

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/contacts";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "?first_name=John");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

You can search or filter contacts on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only. (The phone_number field is treated differently - see below).

Payments (Outgoing)

Introduction

To send payments to a mobile subscriber, you create a new payment object. You can also retrieve individual payments or list all payments.

The payments api endpoint is:

The payment object

Field Type Description
id long integer Unique object identifier
organization long integer The ID of the organization that the payment belongs to. (This is usually your organization ID)
amount decimal The payment amount
currency string The 3 letter ISO currency code for the payment. Note:: BXC is the Beyonic Test Currency code. See the “Testing” section for more information. Supported currency codes are BXC (Testing), UGX (Uganda), KES (Kenya)
account long integer The ID of the account from which the payment is made
description string The payment description
phone_nos list A list of phone numbers that this payment was sent to
start_date string The date that the payment is scheduled to be delivered, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
metadata hash Any custom metadata that was added to the contact object at creation time
state string The payment state. One of: new, validated, approval_needed, approval_requested, approved, rejected, scheduled, processed, processed_with_errors or cancelled
last_error string A string description of the latest error that occurred, if any
rejected_reason string Describes why the payment was rejected, if it is in the rejected state
rejected_time string The date that the payment was rejected, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
rejected_by long integer The ID of the user who rejected the payment
cancelled_reason string Describes why the payment was cancelled, if it is in the cancelled state
cancelled_time string The date that the payment was cancelled, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
cancelled_by long integer The ID of the user who cancelled the payment
created string The date that the payment was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
author long integer The ID of the user who created the payment
modified string The date that the payment was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated_by string The ID of the user who last updated the payment

Creating a new payment

Sample Request:

curl https://app.beyonic.com/api/payments -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d phonenumber=+401000000001 \
-d first_name=Kennedy\
-d last_name=Amani\
-d currency=BXC \
-d account=1 \
-d amount=30 \
-d description="Per diem payment" \
-d callback_url="https://my.website/payments/callback" \
-d payment_type=money
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

payment = Beyonic::Payment.create(
    phonenumber: "+401000000001",
    first_name: "Kennedy",
    last_name: "Amani",
    amount: "100.2",
    currency: "BXC",
    account: "1",
    description: "Per diem payment",
    payment_type: "money",
    callback_url: "https://my.website/payments/callback",
    metadata: {"id": "1234", "name": "Lucy"}
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

Beyonic_Payment::create(array(
  "phonenumber" => "+401000000001",
  "first_name" => "Kennedy",
  "last_name" => "Kennedy",
  "amount" => "100.2",
  "currency" => "BXC",
  "account" => "1",
  "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='+401000000001',
                       first_name='Kennedy',
                       last_name='Amani',
                       amount='1200',
                       currency='BXC',
                       account='1',
                       description='Per diem',
                       callback_url='https://my.website/payments/callback',
                       metadata={'id': '1234', 'name': 'Lucy'}
                       )
package com.beyonic.examples.payments;

import org.json.JSONException;
import org.json.JSONObject;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class CreatePayment {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/payments";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";
    private static final String PHONE_NUMBER = "+401000000001";
    private static final String CURRENCY = "BXC";
    private static final String DESCRIPTION = "Per Diem";
    private static final String AMOUNT = "1200";
    private static final String CALLBACK_URL = "https://my.website/payments/callback";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);
            conn.setRequestMethod("POST");
            conn.setDoOutput(true);
            conn.setDoInput(true);

            JSONObject paymentObject = createPaymentObject();

            BufferedWriter out = new BufferedWriter(new OutputStreamWriter(conn.getOutputStream()));
            out.write(paymentObject.toString());
            out.close();

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 201) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    JSONObject obj = new JSONObject(response);
                    int paymentID = obj.getInt("id");
                    System.out.println("ID of created Payment: " + paymentID);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static JSONObject createPaymentObject() throws JSONException {
        JSONObject payment = new JSONObject();
        payment.put("phonenumber", PHONE_NUMBER);
        payment.put("amount", AMOUNT);
        payment.put("currency", CURRENCY);
        payment.put("description", DESCRIPTION);
        payment.put("callback_url", CALLBACK_URL);
        return payment;
    }
}

Sample Response (JSON):

{
    "id": 3620,
    "organization": 1,
    "amount": "30",
    "currency": "BXC",
    "account": "1",
    "payment_type": "money",
    "metadata": {"id": 1234, "name": "Lucy"},
    "description": "Per diem payment",
    "phone_nos": ["+401000000001"],
    "state": "new",
    "last_error": null,
    "rejected_reason": null,
    "rejected_by": null,
    "rejected_time": null,
    "cancelled_reason": null,
    "cancelled_by": null,
    "cancelled_time": null,
    "created": "2014-11-22T20:57:04.017Z",
    "author": 15,
    "modified": "2014-11-22T20:57:04.018Z",
    "updated_by": null,
    "start_date": "2014-11-22T20:57:04.018Z"
}

To create a new payment, make a POST to the end point above, with the attributes below.

Note:

Parameter Required Type Example Notes
phonenumber Yes String +401000000001 Must be in international format
amount Yes String, Integer or Decimal 3000 Do not include thousands separators
currency No String BXC 3 letter ISO currency code. No currency conversion is done, so the currency must be valid for the selected phonenumber. You must have a funded Beyonic account in this currency. If your account for this currency has zero balance, your payment will fail. If you also provide an account parameter then the account’s currency must match the currency parameter. Note:: BXC is the Beyonic Test Currency code. See the “Testing” section for more information. Supported currency codes are BXC (Testing), UGX (Uganda), KES (Kenya)
account No Integer 1 The ID of the account from which you are making the payment. The account must be active and funded. If the account has zero balance, your payment will fail. This parameter is optional if a currency is provided. If you have more than one account with the same currency, and you leave this parameter out, the earliest created account (oldest account) that is still active will be used.
description Yes String Per diem payment This description will be sent to the recipient along with the payment, so it should be limited to about 140 characters.
payment_type No String money Options: money (default), airtime - use “airtime” to send an airtime payment instead of a mobile money payment
callback_url No String https://my.website/payments/callback Callback URLs are used to send notifications of changes in payment status. Not all payments will be completed immediately, especially if it is a payment to a new number that hasn’t been verified, or if your account has approval rules that require other users to approve payments before they are processed. Note that the URL you submit isn’t specific to a specific payment you have created. Once submitted, it will receive notifications for all future payments made via your organization, whether they are made via the API or via the web-interface. Therefore, you are encouraged to use the same URL for all payments. Since URLs are stored at a per-organization level, using different URLs may result in duplicate notifications being sent to the different URLs. See “Webhooks” below for more info.
metadata No JSON-formatted string or dictionary “{‘id’:'1234’,'name’:'Lucy’}” Metadata allows you to add custom attributes to your payments. E.g. You can include a unique ID to identify each payment. Attributes must be key-value pairs. Both the keys and values must be strings. You can add up to 10 attributes. This data will be returned when you retrieve a payment.
first_name No String John If this payment is to a new contact, you can include their first name. This name will only be used if the phone number is new.
last_name No String Doe If this payment is to a new contact, you can include their last name. This name will only be used if the phone number is new.

Responses

Retrieving a single payment

Sample Request:

curl https://app.beyonic.com/api/payments/22744 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

payment = Beyonic::Payment.get(22744)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$payment = Beyonic_Payment::get(22744);
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

payment = beyonic.Payment.get(22744)

package com.beyonic.examples.payments;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;


public class SinglePaymentExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/payments";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "/22744");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON):

{
    "id": 22744,
    "organization": 4,
    "amount": "1200.0000",
    "currency": "BXC",
    "account": "1",
    "payment_type": "money",
    "metadata": {"id": 1234, "name": "Lucy"},
    "description": "Per diem payment",
    "phone_nos": ["+401000000001"],
    "state": "new",
    "last_error": null,
    "rejected_reason": null,
    "rejected_by": null,
    "rejected_time": null,
    "cancelled_reason": null,
    "cancelled_by": null,
    "cancelled_time": null,
    "created":"2016-03-31T08:08:01Z",
    "author":134,
    "modified":"2016-03-31T08:08:45Z",
    "updated_by":134,
    "start_date":"2016-03-31T08:08:01Z"
}

To retrieve a single payment object, provide the payment id and a payment object will be returned.

Parameter Required Type Example Notes
id Yes Integer 2314 The id of the payment you want to retrieve

Listing all payments

Sample Request:

curl https://app.beyonic.com/api/payments -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

$payments = Beyonic_Payment::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

payments = beyonic.Payment.list()

package com.beyonic.examples.payments;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class ListAllPaymentsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/payments";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON)

{
    "count": 2,
    "next": "http://app.beyonic.com/api/payments?offset=10",
    "previous": null,
    "results": [
        {
            "id": 1,
            "organization": "Beyonic",
            "amount": "0.0000",
            "currency": "BXC",
            "account": "1",
            "payment_type": "money",
            "metadata": null,
            "description": "Test",
            "phone_nos": [
                "+401000000001"
            ],
            "state": "approved",
            "last_error": null,
            "rejected_reason": null,
            "rejected_by": null,
            "rejected_time": null,
            "cancelled_reason": null,
            "cancelled_by": null,
            "cancelled_time": null,
            "created": "2013-08-20T17:21:39Z",
            "author": 1,
            "modified": "2013-08-20T17:21:39Z",
            "updated_by": null,
            "start_date": "2013-08-20T00:00:00Z"
        },
        {
            "id": 2,
            "organization": "Beyonic",
            "amount": "200.0000",
            "currency": "BXC",
            "account": "2",
            "payment_type": "money",
            "metadata": null,
            "description": "Test2",
            "phone_nos": [
                "+401000000001"
            ],
            "state": "scheduled",
            "last_error": null,
            "rejected_reason": null,
            "rejected_by": null,
            "rejected_time": null,
            "cancelled_reason": null,
            "cancelled_by": null,
            "cancelled_time": null,
            "created": "2013-08-22T01:53:35Z",
            "author": 1,
            "modified": "2013-08-22T01:53:36Z",
            "updated_by": 1,
            "start_date": "2013-08-21T00:00:00Z"
        },

To return a list of all payments, make a GET request to the payments endpoint. This will return a list of payment objects.

Filtering payments

Sample Request:

curl https://app.beyonic.com/api/payments?amount=500 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

payments = Beyonic::Payment.list(
  amount: 500
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$payments = Beyonic_Payment::getAll(array(
  "amount" => 500
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

payments = beyonic.Payment.list(amount=500)

package com.beyonic.examples.payments;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class FilterPaymentsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/payments";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "?amount=500");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

You can search or filter payments on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only.

Webhooks

Introduction

Webhooks or callback URLs allow you to define URLs on your server that notifications should be sent to when specific events occur in your Beyonic account.

The webhooks api endpoint is:

Note:

Supported events

The following events are supported

Event Description Object returned in data
payment.status.changed Triggered any time a payment changes status. Payment object
collection.received Triggered any time a collection (an incoming payment) is received from a customer Collection object

Managing Webhooks

You can create and manage webhooks in two ways:

Managing Webhooks from the web browser

To manage webhooks using the web browser: 1. Log into your account. 2. Go to your organizations profile page. You can access this either from the organizations menu, or by clicking your organization name at the top left of the page. 3. Click the Settings button (Cog wheel with an arrow pointing down) 4. Click “Manage Webhooks” from the drop down menu that appears

Managing Webhooks from the API

You can use the Webhooks API described below to update or delete your callback URLs programatically.

Required permissions

To manage webhooks, either with the API or the web browser, you must have “Manage Users and Organization Settings” permissions for your organization.

The Webhook object

Field Type Description
id long integer Unique object identifier
user long integer The ID of the user who created the webhook
event string The webhook event. See the supported events section
created string The date that the webhook was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated string The date that the webhook was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
target string The URL that triggered events will be sent to

Notification body format

Sample Response (JSON):

{
    "hook": {
                "id": 53,
                "created": "2015-08-01T16:56:29Z",
                "updated": "2015-08-01T16:56:29Z",
                "event": "payment.status.changed",
                "target": "https://my.callback.url/",
                "user": 42
            },
    "data": {
                "id": 2314,
                "organization": 1,
                "amount": "30",
                "currency": "BXC",
                "payment_type": "money",
                "metadata": {"id": 1234, "name": "Lucy"},
                "description": "Per diem payment",
                "phone_nos": ["+401000000001"],
                "state": "completed",
                "last_error": null,
                "rejected_reason": null,
                "rejected_by": null,
                "rejected_time": null,
                "cancelled_reason": null,
                "cancelled_by": null,
                "cancelled_time": null,
                "created": "2014-11-22T20:57:04.017Z",
                "author": 15,
                "modified": "2014-11-22T20:57:04.018Z",
                "updated_by": null,
                "start_date": "2014-11-22T20:57:04.018Z"
            }
}

When an event is triggered, a JSON post will be sent to the URL that subscribed to the webhook. The JSON post body will include the following information:

Parameter Description
hook A JSON representation of a webhook object. See the see webhook section below.
data A JSON representation of the object that triggered the event. This is different for each event. See the ‘Supported events’ section above.

Creating a new webhook

Sample Request:

curl http://app.beyonic.com/api/webhooks -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d "payment.status.changed" \
-d target="https://my.callback.url/"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

hook = Beyonic::Webhook.create(
    event: "payment.status.changed",
    target: "https://my.callback.url/"
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

Beyonic_Webhook::create(array(
  "event" => "payment.status.changed",
  "target" => "https://my.callback.url/"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

hook = beyonic.Webhook.create(event='payment.status.changed',
                              target='https://my.callback.url/'
                              )

package com.beyonic.examples.webhooks;

import org.json.JSONException;
import org.json.JSONObject;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class CreateWebhookExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";
    private static final String EVENT = "payment.status.changed";
    private static final String TARGET = "https://my.callback.url/";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);
            conn.setRequestMethod("POST");
            conn.setDoOutput(true);
            conn.setDoInput(true);

            JSONObject contact = createWebhookObject();

            BufferedWriter out = new BufferedWriter(new OutputStreamWriter(conn.getOutputStream()));
            out.write(contact.toString());
            out.close();

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            int beyID = 0;
            try {
                if (conn.getResponseCode() == 201) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    JSONObject obj = new JSONObject(response);
                    beyID = obj.getInt("id");
                    System.out.println("ID of created Webhook: " + beyID);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static JSONObject createWebhookObject() throws JSONException {
        JSONObject webhook = new JSONObject();
        webhook.put("event",EVENT);
        webhook.put("target",TARGET);
        return webhook;
    }
}

Sample Response (JSON)

{
    "id": 53,
    "created": "2015-08-01T16:56:29Z",
    "updated": "2015-08-01T16:56:29Z",
    "event": "payment.status.changed",
    "target": "https://my.callback.url/",
    "user": 42
}

To create a new webhook, make a POST to the endpoint above, with the attributes below.

Parameter Required Type Example Notes
event Yes String 'payment.status.changed’ Must be a supported event
target Yes String 'https://my.callback.url/“’ Must be an https URL

Responses

Retrieving a single webhook

Sample Request:

curl https://app.beyonic.com/api/webhooks/23 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

hook = Beyonic::Webhook.get(23)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$hook = Beyonic_Webhook::get(23);
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

hook = beyonic.Webhook.get(23)

package com.beyonic.examples.webhooks;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;


public class SingleWebhookExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "/1");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON)

{
    "id": 23,
    "created": "2015-08-01T16:56:29Z",
    "updated": "2015-08-01T16:56:29Z",
    "event": "payment.status.changed",
    "target": "https://my.callback.url/",
    "user": 42
}

To retrieve a single webhook object, provide the webhook id and a webhook object will be returned.

Parameter Required Type Example Notes
id Yes Integer 23 The id of the webhook you want to retrieve

Listing all webhooks

Sample Request:

curl https://app.beyonic.com/api/webhooks -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

$hooks = Beyonic_Webhook::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

hooks = beyonic.Webhook.list()

package com.beyonic.examples.webhooks;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class ListAllWebhooksExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

Sample Response (JSON)

{
    "count": 4,
    "next": "http://localhost:8000/api/webhooks?offset=10",
    "previous": null,
    "results": [
        {
            "id": 50,
            "created": "2015-08-01T16:43:43Z",
            "updated": "2015-08-01T17:05:38Z",
            "event": "payment.status.changed",
            "target": "https://mysite.com/callbacks/payment/saved/1",
            "user": 42
        },
        {
            "id": 52,
            "created": "2015-08-01T16:43:43Z",
            "updated": "2015-08-01T17:05:38Z",
            "event": "payment.status.changed",
            "target": "https://mysite.com/callbacks/payment/saved",
            "user": 42
        },
        {
            "id": 53,
            "created": "2015-08-01T16:56:29Z",
            "updated": "2015-08-01T16:56:29Z",
            "event": "payment.status.changed",
            "target": "https://my.callback.url/",
            "user": 42
        },
        {
            "id": 55,
            "created": "2015-08-01T16:56:29Z",
            "updated": "2015-08-01T16:56:29Z",
            "event": "payment.status.changed",
            "target": "https://google.com",
            "user": 42
        }
    ]
}

To retrieve a list of all webhooks, make a GET request to the webhooks endpoint. This will return a list of webhooks objects.

Updating a webhook

Sample Request:

ccurl http://app.beyonic.com/api/webhooks/1 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d event="payment.status.changed" \
-d target="https://my.callback.url/" \
-X PUT
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

hook = Beyonic::Webhook.get(1)
hook.target = 'https://my.callback.url/'
hook.save()
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$hook = Beyonic_Webhook::get(1);
$hook->target = 'https://my.callback.url/';
$hook->save();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

hook = beyonic.Webhook.get(1)
hook.target = 'https://my.callback.url/'
hook.save()

package com.beyonic.examples.webhooks;

import org.json.JSONException;
import org.json.JSONObject;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;


public class UpdateWebhookExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";
    private static final String EVENT = "payment.status.changed";
    private static final String TARGET = "https://my.callback.url/";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "/503");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);
            conn.setRequestMethod("PUT");
            conn.setDoOutput(true);
            conn.setDoInput(true);

            BufferedWriter out = new BufferedWriter(new OutputStreamWriter(conn.getOutputStream()));
            out.write(webhookObject().toString());
            out.close();

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static JSONObject webhookObject() throws JSONException {
        JSONObject webhook = new JSONObject();
        webhook.put("event",EVENT);
        webhook.put("target",TARGET);
        return webhook;
    }

}

Sample Response (JSON)

{
    "id": 1,
    "created": "2015-08-01T16:56:29Z",
    "updated": "2015-08-01T16:56:29Z",
    "event": "payment.status.changed",
    "target": "https://my.callback.url/",
    "user": 42
}

To update a webhook, make a PUT request to the specific webhook’s endpoint, identified by its Id.

Deleting a webhook

Sample Request:

curl http://app.beyonic.com/api/webhooks/1 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" -X DELETE
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

Beyonic_Webhook::delete( 11 );
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

beyonic.Webhook.delete(11)

package com.beyonic.examples.webhooks;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;


public class DeleteWebhookExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "/502");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);
            conn.setRequestMethod("DELETE");

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

To delete a webhook, make a DELETE request to the specific webhook’s endpoint, identified by its Id.

Filtering webhooks

Sample Request:

curl https://app.beyonic.com/api/webhooks?user=1 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

hooks = Beyonic::Webhook.list(
  user: 1
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$hooks = Beyonic_Webhook::getAll(array(
  "user" => 1
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

hooks = beyonic.Webhook.list(user=1)

package com.beyonic.examples.webhooks;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class FilterWebhooksExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
    private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
    private static final String CHARSET = "UTF-8";

    public static void main(String[] args){
        URL url = null;
        try {
            url = new URL(API_ENDPOINT + "?user=12");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("charset", CHARSET);
            conn.setRequestProperty("Authorization", "Token " + API_KEY);

            System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());

            try {
                if (conn.getResponseCode() == 200) {
                    InputStream inputStream = conn.getInputStream();
                    BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
                    String response = reader.readLine();
                    reader.close();

                    System.out.println(response);
                }
            } finally {
                conn.disconnect();
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

You can search or filter webhooks on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only.