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:

• PHP - https://github.com/beyonic/beyonic-php
• Ruby - https://github.com/beyonic/beyonic-ruby
• Python - https://github.com/beyonic/beyonic-python
• Zapier - Beyonic provides zapier triggers and actions in “Invite Only” mode. Please contact us if you would like to use Zapier with Beyonic’s API.
• Java - We don’t currently offer an official Java client. However, we have provided Java code examples on the ‘Java’ tab to get you started.

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:

• Use version specific URLS like: https://app.beyonic.com/api/v1
• Include the Beyonic-Version header in your request as shown in the examples to the right.

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.

Errors

401 Unauthorized error response due to using a wrong token.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: 27

{"detail":"Invalid token."}

400 Bad Request error response due to missing parameters in the request. Note that the fields are included as keys, and the error messages for each field are included as a list after each key.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 94

{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}

Beyonic uses HTTP response status codes to indicate success or failure. When a request to our API is successful, Beyonic returns an HTTP response code in the 2XX range. And when a request fails, Beyonic returns an HTTP response code in the 4XX or 5XX range.

In summary:

• Codes in the 2XX range mean that the request was processed successfully
• Codes in the 4XX range mean that something was wrong with the data that you sent. For example, you might have missed some required parameters, or you might be using a wrong API token.
• Codes in the 5XX range mean that something went wrong within Beyonic’s servers.

In all cases, the response will include an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error.

Most error responses will include a “detail” key in the body of the response, but some may include additional information, for example, they may include information about missing fields.

The examples to the right show some of the errors that might occur, including the status code and content-type in the response header, and the json-formatted details in the response body.

Common Error Codes

Error Code	Meaning
400	Bad Request – Your request is malformed or is missing some required parameters.
401	Unauthorized – You are using an invalid API token.
403	Forbidden – You are attempting to access a resource that doesn’t belong to you. Check that you are using the correct API token for the user who owns the resource.
404	Not Found – You are attempting to access a resource that doesn’t exit. Check the url for your request.
405	Method Not Allowed – You are attempting to use an invalid method. For example, you might be trying to POST to a readonly endpoint.
406	Not Acceptable – You requested a format that isn’t supported. Check the “Accept” header of your request, and try to ensure that you are using json format for your requests.
415	Unsupported Media Type – Check the content-type of the data you are sending.
429	Throttled – You are sending too many requests in a short period of time. Slow down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Note: always check the response body for details about the error.

Handling errors

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

try {
  $collection_requests = Beyonic_Collection_Request::getAll();
} catch (Beyonic_Exception $e) {
  echo $e->getMessage();
  echo json_decode($e->responseBody)->detail;
}
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6901'

try:
  collection_request = beyonic.CollectionRequest.get(23)
except beyonic.errors.ResponseError as e:
  print e
else:
  # No error, proceed with processing
  pass

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6901'

begin
  collection_request = Beyonic::CollectionRequest.get(23)
rescue RestClient::ExceptionWithResponse => e   # You probably want to use more specific RestClient codes like RestClient::Unauthorized, RestClient::ResourceNotFound, etc
  p e  # Print out the error
end

Your code should handle errors gracefully.

Beyonic’s API libraries will raise an exception when an error occurs. So you should add exception handling to your requests as shown in the examples to the right.

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:

• limit: This limits the number of records returned per page. If omitted, only 10 records are returned per page
• offset: This tells the Beyonic API where to start getting

The API response body shall include the following parameters:

• count: The total number of records available (not just on the returned page)
• next: A link to the next page of records. If there is no next page, this shall be equal to null
• previous: A link to the previous page of records. If there is no previous page, this shall be equal to null
• results: This will contain the list of records for the current page

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:

• ordering: This orders the records by one of the visible fields on the object

Ascending or Descending order:

• To use ascending order, just use the field name E.g. ordering=created
• To use descending order, add a “-” to the field name E.g. ordering=-created

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 attributes must be key-value pairs.
• Both the keys and values must be strings.
• For each record, you can have up to 10 custom attributes.

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

See the examples for more information.

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, so feel free to try them out as you read the documentation.

Test Currency

Beyonic provides a test currency, with the following parameters:

• Phone Format: +800XXXXXXXX
• 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:

Sending Payments

• +80000000001 - When you add a contact with this number, the contact will always fail the mobile money registration checks, and therefore payments sent to this number will always fail.
• +800XXXXXXXX - All other numbers in the format +800XXXXXXXX will pass the name checks only if the contact name is “John Doe”. So, set the name to “John Doe” to test the effect of a successful name check, or set it to something else to test the effect of a failed name check.
• Subsequently, all BXC payments to numbers with format +800XXXXXXXX and name “John Doe”, (except +80000000000) will succeed, if the amount is greater than or equal to 10 and less than or equal to 5,000,000 BXC.

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

Receiving Payments

• +80000000001 - If you request a payment from this number, it will always fail with the “Cancelled By User” error. Use this to simulate a user cancelling or rejecting your payment request.
• +80000000009 - If you request a payment from this number, it will always expire. Use this to simulate a user ignoring your payment request by doing nothing and letting it expire.
• +800XXXXXXXX - All other numbers in this format will complete successfully. Use this to test successful payment request scenarios.

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. Triggering test events

To trigger a test notification, simply perform the corresponding action in your account. You can do this via the API or the web portal.

For example, to trigger a ‘contact.created’ event, simply create a contact. Or, to trigger a 'payment.status.changed’ event, use the Payments API to create a payment with the test currency and test numbers described above.

2. 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.

3. 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:

4. Viewing logged notification requests and responses

Beyonic logs notificaiton requests and responses for at least 30 days. These can be viewed by logging into the web portal, and going to “Home” > Company Settings" > “Advanced Settings” > “Notification Endpoints”

By clicking on “Recent Events”, you will be able to see events and notification attempts, including the responses that Beyonic is getting from your notification server.

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.

v3 - September 2016

• collection_request field on Collection object now contains a JSON representation of the Collection Request, not the ID

v2 - February 2016

• Accounts API to get balances of organization’s accounts.

v2 - November 2015

• Versioning improvements to provide transparent backward compatibility by automatically saving users’ version. Versions can be upgraded manually via web interface
• organization field now contains the organization ID, not name, in the Payments, Contacts and Collection Requests methods
• currency field now contains the currency code, not the currency ID, in the Collections method

Receiving Money

Introduction

Beyonic uses the term “Collection” to refer to money that you receive (or collect) from a mobile subscriber. This differentiates money you receive (Collections) from money you send to mobile subscribers (Payments).

Beyonic provides to API methods to help you with receiving money from customers.

1. Requesting collections: You can request funds from a subscriber. You do this using the Collection Requests API. See the Collection Requests documentation for more information on how to initiate a collection request. It is as simple as creating a “Collection Request” object.

2. Viewing received collections: Sometimes subscribers will send you money directly without first getting a collection request from you. The Collections API lets you access all the collections you have received, whether they are in response to a Collection Request, or if the subscriber sent the funds directly.

The difference is that collections that were received in response to a request from you will include a “collection_requests” parameter which will have a link to the collection request id.

See the Collections documentation for more information on how to view, filter or search through collections you have received.

Related Events

The “collection.received” event is triggered whenever you receive funds from a user. You can configure a web link to receive notifications whenever this event occurs. This will allow you to respond automatically whenever you receive funds. See our Webhooks API documentation for more information.

Collection Requests

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

Sample Collection Request Object (JSON):

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

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=+80000000001 \
-d currency=BXC \
-d amount=3000 \
-d metadata.my_id='123ASDAsd123'
-d send_instructions=True

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection_request = Beyonic::CollectionRequest.create(
    phonenumber: "+80000000001",
    amount: "100.2",
    currency: "BXC",
    metadata: {"my_id": "123ASDAsd123"},
    send_instructions: true
)

p collection_request  # Examine the returned object

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

$collection_request = Beyonic_Collection_Request::create(array(
  "phonenumber" => "+80000000001",
  "amount" => "100.2",
  "currency" => "BXC",
  "metadata" => array("my_id"=>"123ASDAsd123"),
  "send_instructions" => True
));

print_r($collection_request);  // Examine the returned object
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'


collection_request = beyonic.CollectionRequest.create(phonenumber='+80000000001',
                       amount='1200',
                       currency='BXC',
                       description='Per diem',
                       callback_url='https://my.website/payments/callback',
                       metadata={'my_id': '123ASDAsd123'},
                       send_instructions = True
                       )

print collection_request  # Examine the returned object

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 = "+80000000001";
    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";
    private static final String SEND_INSTRUCTIONS = "True";

    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);
        collectionRequest.put("send_instructions", SEND_INSTRUCTIONS);
        return collectionRequest;
    }
}

Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:

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

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	+80000000001	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 False. Indicates whether we should send payment instructions to the subscriber via SMS. Note that this field defaults to False, so if you want the collection request to actually be sent out, you must set this field to True. Omitting the field will prevent collection requests from being sent out.
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_request = Beyonic::CollectionRequest.get(23)

p collection_request  # Examine the returned object

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

$collection_request = Beyonic_Collection_Request::get(23);

print_r($collection_request);  // Examine the returned object
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection_request = beyonic.CollectionRequest.get(23)

print collection_request  # Examine the returned object

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) - if you use one of the development libraries, this is automatically converted into a native object for you:

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

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_requests = Beyonic::CollectionRequest.list

p collection_requests  # Examine the returned objects

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

$collection_requests = Beyonic_Collection_Request::getAll();

print_r($collection_requests);  // Examine the returned objects
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection_requests = beyonic.CollectionRequest.list()

print collection_requests  # Examine the returned objects

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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "count": 3,
    "next": "http://localhost:8000/api/collectionrequests?offset=10",
    "previous": null,
    "results": [
        {
            "id": 99,
            "organization": "Beyonic",
            "amount": "3000.0000",
            "currency": "BXC",
            "phonenumber": "+80000000001",
            "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": "+80000000001",
            "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": "+80000000001",
            "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_requests = Beyonic::CollectionRequest.list(
  remote_transaction_id: '12345',
  amount: 500
)

p collection_requests  # Examine the returned objects

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

$collection_requests = Beyonic_Collection_Request::getAll(array(
  "remote_transaction_id" => "12345",
  "amount" => 500
));

print_r($collection_requests);  // Examine the returned objects
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

print collection_requests  # Examine the returned objects

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).

• amount - the transaction amount
• currency - the currency code
• collection - the ID of the collection that fulfilled or matched this collection request
• phonenumber - the phonenumber that the collection request was intended for. Note that the phonenumber will be matched in international format, starting with a ’+’ sign. If the ’+’ sign isn’t included in your request, it will be appended before attempting to match your request.
• remote_transaction_id - the transaction id or transaction reference of the collection on the mobile network operator’s side

Collections

Beyonic uses the term “Collections” for payments you receive (or collect) 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:

NOTE: If you want to initiate new collections, use the Collection Requests API. The collections api only allows you to view funds that have already been sent to you.

The Collection object

Sample Collection Object (JSON):

{
    "id": 230,
    "remote_transaction_id": "12132",
    "organization": 1,
    "amount": "20.0000",
    "currency": 1,
    "phonenumber": "+80000000001",
    "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
}

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	JSON string	New in V3. A JSON representation of the collection request that this collection was matched to, if any. Before V3, this was simply the id of the collection request object. In V3. It’s an expanded representation of the collection request object.

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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "id": 1,
    "remote_transaction_id": "12132",
    "organization": 1,
    "amount": "200.0000",
    "currency": "KES",
    "phonenumber": "+254722000000",
    "payment_date": "2016-09-21T08:55:54Z",
    "reference": "98989",
    "status": "successful",
    "created": "2016-09-21T08:56:18Z",
    "author": 1,
    "modified": "2016-09-21T09:07:13Z",
    "updated_by": 1,
    "collection_request": {
        "id": 2,
        "organization": 1,
        "amount": "200.0000",
        "currency": "KES",
        "phonenumber": "+254722000000",
        "reason": "Test payment",
        "metadata": {},
        "created": "2016-09-21T08:52:54Z",
        "author": 1,
        "modified": "2016-09-21T09:04:14Z",
        "updated_by": 1,
        "collection": 1,
        "success_message": "",
        "instructions": "",
        "send_instructions": false,
        "status": "successful",
        "error_message": null,
        "error_details": 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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "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": "+80000000001",
            "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": "+80000000001",
            "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": "+80000000001",
            "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=+80000000001&remote_transaction_id=SS12312 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collections = Beyonic::Collection.list(
  phonenumber: "+80000000001",
  remote_transaction_id: "SS12312"
)

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

$collections = Beyonic_Collection::getAll(array(
  "phonenumber" => "+80000000001",
  "remote_transaction_id" => "SS12312"
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collections = beyonic.Collection.list(phonenumber='+80000000001',
                                     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) - if you use one of the development libraries, this is automatically converted into a native object for you:

[
       {
        "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).

• amount - the transaction amount
• currency - the currency code
• phonenumber - the phonenumber that the collection request was intended for. Note that the phonenumber will be matched in international format, starting with a ’+’ sign. If the ’+’ sign isn’t included in your request, it will be appended before attempting to match your request. This is only true for phone number searches with collections, to make claiming of transactions easier. Other
• reference - the reference code that the customer used when sending the collection
• remote_transaction_id - the transation id or transaction reference of the collection on the mobile network operator’s side
• collection_request - the ID of the collection request that this collection was matched to

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=+80000000001&remote_transaction_id=SS12312&claim=True&amount=200 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collections = Beyonic::Collection.list(
  phonenumber: "+80000000001",
  remote_transaction_id: "SS12312",
  claim: true,
  amount: 200
)

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

$collections = Beyonic_Collection::getAll(array(
  "phonenumber" => "+80000000001",
  "remote_transaction_id" => "SS12312",
  "claim" => "True",
  "amount" => "200",
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collections = beyonic.Collection.list(phonenumber='+80000000001',
                                     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=+80000000001&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) - if you use one of the development libraries, this is automatically converted into a native object for you:

[
       {
        "id": 134,
        "phonenumber": "+800XXXXXXXX",
        "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.

Sending Money

Introduction

Beyonic uses the term “Payments” to refer to money (or prepaid airtime) that you send to a mobile subscriber. This differentiates money you send to mobile subscribers (aka Payments) from money you receive from mobile subscribers (aka Collections).

Beyonic provides the Payments API to enable you to send a payment to a mobile subscriber, or to view payments that you have previously sent to a mobile subscriber. See the Payments documentation below for more information.

Related Events

The “payment.status.changed” event is triggered whenever something happens to a payment that you have initiated. For example, if it is successfully delivered or if it fails. You can configure a web link to receive notifications whenever this occurs. This will allow you to respond automatically whenever a payment is completed or whenever it fails. See our Webhooks API documentation for more information.

Payments

To send payments (mobile money or prepaid airtime credit) to a mobile subscriber, you create a new payment object using the payments API. You can also use the payments API to retrieve individual payments or list all payments, as shown in the sections below.

The payments api endpoint is:

The Payment object

Sample Payment Object (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": ["+80000000001"],
    "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",
    "remote_transaction_id": null
}

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)
payment_type	String	The payment type. Either “money” for mobile money or “airtime” for airtime
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
remote_transaction_id	string	The transaction id provided by the mobile network operator. This will only be available once the payment is completed.

Creating a new Payment

Sample Request:

curl https://app.beyonic.com/api/payments -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d phonenumber=+80000000001 \
-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: "+80000000001",
    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"}
)

p payment  # Examine the returned object

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

$payment = Beyonic_Payment::create(array(
  "phonenumber" => "+80000000001",
  "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")
));

print_r($payment);  // Examine the returned object
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

payment = beyonic.Payment.create(phonenumber='+80000000001',
                       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'}
                       )

print payment  # Examine the returned object

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 = "+80000000001";
    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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "id": 3620,
    "organization": 1,
    "amount": "30",
    "currency": "BXC",
    "account": "1",
    "payment_type": "money",
    "metadata": {"id": 1234, "name": "Lucy"},
    "description": "Per diem payment",
    "phone_nos": ["+80000000001"],
    "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",
    "remote_transaction_id": null
}

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

Note:

• A contact is created for each new phone number you send payments to. This gives you the benefits of the pre-verification checks that are done prior to payment processing.
• If the contact isn’t registered for mobile money, then the payment will not be sent.
• Important: One of the pre-verification checks does a name match check to make sure that the contact name is right. This check can cause your payments to fail if the names that you are sending are not the same as the names in the telecom database. If you want to by-pass this check, go into your settings in your account and uncheck the checkbox that says “Name match affects payment”.
• Important: The account and currency parameters are both optional but you must provide one of them. If you provide both them then the account’s currency must match the currency parameter.

Parameter	Required	Type	Example	Notes
phonenumber	Yes	String	+80000000001	Must be in international format
payment_type	No	String	money	Options: money (default), airtime - use “airtime” to send an airtime payment instead of a mobile money payment
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.
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

• If successful, a JSON representation of the new payment object will be returned. The state field will be “new”
• The payment object can be identified using it’s id field, or the metadata that you supplied.
• On subsequent notification callbacks to your callback URL, the same payment object (with the same id field) will be returned. Check the state field for the latest payment status.
• The state field values can be:
  • new – for new payments
  • processed – for successfully completed payments
  • processed_with_errors – for payments that didn’t complete successfully. The last_error field with have more information.
  • rejected – for payments that were rejected during the approval process. The following fields will have more information: rejected_reason, rejected_by and rejected_time
  • cancelled – for payments that were cancelled. The following fields will have more information: cancelled_reason, cancelled_by and cancelled_time

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)

p payment  # Examine the returned object

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

$payment = Beyonic_Payment::get(22744);

print_r($payment);  // Examine the returned object
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

payment = beyonic.Payment.get(22744)

print payment  # Examine the returned object

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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "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": ["+80000000001"],
    "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

p payments  # Examine the returned objects

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

$payments = Beyonic_Payment::getAll();

print_r($payments);  // Examine the returned objects
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

payments = beyonic.Payment.list()

print payments  # Examine the returned objects

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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "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": [
                "+80000000001"
            ],
            "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": [
                "+80000000001"
            ],
            "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
)

p payments  # Examine the returned objects

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

$payments = Beyonic_Payment::getAll(array(
  "amount" => 500
));

print_r($payments);  // Examine the returned objects
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

print payments  # Examine the returned objects

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.

• amount - the payment amount
• currency - the payment currency code
• payment_type - the payment type

Other Actions

Below are additional API endpoints supported by Beyonic’s API. Clicking on each topic in the table of contents shall reveal the actions that you can perform.

Accounts

Introduction

Accounts hold your funds. The accounts api method allows you to list your accounts and view balances for each account. When you sign up for Beyonic, at least one account in your primary currency is created for your organization. You can request additional accounts if needed.

The accounts api endpoint is:

The Account object

Sample Account Object (JSON):

{
    "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
}

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

Retrieving a Single Account

Sample Request:

curl https://app.beyonic.com/api/accounts/12 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

account = Beyonic::Account.get(12)

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

$account = Beyonic_Account::get(12);
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

account = beyonic.Account.get(12)

package com.beyonic.examples.account;

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


public class SingleAccountExample {

    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 + "/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();
        }
    }

}

Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "id": 12,
    "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
}

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

Parameter	Required	Type	Example	Notes
id	Yes	Integer	12	The id of the account you want to retrieve

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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "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.

• currrency - the account currency
• status - the account status

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

Sample Contact Object (JSON)

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

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='+80000000001' \
-d email=[email protected]' \
-d metadata.my_id='123ASDAsd123'

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = Beyonic::Contact.create(
    phone_number: "+80000000001",
    first_name: "John",
    last_name: "Doe",
    email: "[email protected]",
    metadata: {"my_id": "123ASDAsd123"}
)

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

$contact = Beyonic_Contact::create(array(
  "phone_number" => "+80000000001",
  "first_name" => "John",
  "last_name" => "Doe",
  "email" => "[email protected]",
  "metadata" => array("my_id"=>"123ASDAsd123")
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = beyonic.Contact.create(phone_number='+80000000001',
                       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 = "+80000000001";
    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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "id": 26,
    "organization": "Beyonic",
    "first_name": "Suzanne",
    "last_name": "Kwagala",
    "email": "[email protected]",
    "phone_number": "+80000000001",
    "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	+80000000001	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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "id":44702,
    "organization":4,
    "first_name":"John",
    "last_name":"Doe",
    "email":null,
    "phone_number":"+80000000001",
    "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'

contacts = Beyonic::Contact.list

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

$contacts = Beyonic_Contact::getAll();
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = 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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "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'

contacts = Beyonic::Contact.list(
  first_name: "luke"
)

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

$contacts = Beyonic_Contact::getAll(array(
  "first_name" => "luke"
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = 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).

• first_name - the contact’s first name
• last_name - the contact’s last name
• email - the contact’s email
• phone_number - the contact’s phone number. Note that the phonenumber will be matched in international format, starting with a ’+’ sign. If the ’+’ sign isn’t included in your request, it will be appended before attempting to match your request.

Events

Introduction

Events track certain changes that happen to your Beyonic account. Events are created automatically when certain changes occur, and you can use them to stay informed about the changes. For example, when a new contact is created, we will create a “contact.created” event.

You can use the events API to retrieve information about recent events. Events are saved for at least 30 days. After that, they may be discarded.

The events api endpoint is:

You can also set up your account to automatically notify you as event occur. See the Webhooks API for more information about setting up automatic notification for events.

Supported Events types

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
contact.created	Triggered any time a contact is created in your account	Contact object

The Event object

Sample Event Object (JSON)

{
    "id": 1146,
    "organization":1,
    "type": "contact.created",
    "data": {
        "id": 26,
        "organization": 1,
        "first_name": "Suzanne",
        "last_name": "Kwagala",
        "email": "[email protected]",
        "phone_number": "+80000000001",
        "type": "employee",
        "status": "active",
        "metadata": null,
        "created": "2013-09-19T21:26:10Z",
        "author": 1,
        "modified": "2015-04-14T18:21:47Z",
        "updated_by": 42
    },
    "created": "2013-09-19T21:26:10Z",
    "author": 1,
    "modified": "2015-04-14T18:21:47Z",
    "updated_by": 42
}

Field	Type	Description
id	long integer	Unique object identifier
organization	long integer	The ID of the organization that the event belongs to. (This is usually your organization ID)
type	string	The event type. See Supported Event Types above
data	object	The details about the event. This is a representation of the object that triggered the event. For example, for the “contact.created” event, this will repesent a “Contact” object
created	string	The date that the event was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
author	long integer	The ID of the user who created the event
modified	string	The date that the event was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated_by	string	The ID of the user who last modified the event

Retrieving a Single Account

Sample Request:

curl https://app.beyonic.com/api/events/12 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

event = Beyonic::Event.get(12)

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

$event = Beyonic_Event::get(12);
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

event = beyonic.Event.get(12)

package com.beyonic.examples.events;

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


public class SingleEventExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/events";
    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 + "/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();
        }
    }

}

Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "id": 1146,
    "organization":1,
    "type": "contact.created",
    "data": {
        "id": 26,
        "organization": 1,
        "first_name": "Suzanne",
        "last_name": "Kwagala",
        "email": "[email protected]",
        "phone_number": "+80000000001",
        "type": "employee",
        "status": "active",
        "metadata": null,
        "created": "2013-09-19T21:26:10Z",
        "author": 1,
        "modified": "2015-04-14T18:21:47Z",
        "updated_by": 42
    },
    "created": "2013-09-19T21:26:10Z",
    "author": 1,
    "modified": "2015-04-14T18:21:47Z",
    "updated_by": 42
}

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

Parameter	Required	Type	Example	Notes
id	Yes	Integer	12	The id of the event you want to retrieve

Listing all Events

Sample Request:

curl https://app.beyonic.com/api/events -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

events = Beyonic::Event.list

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

$events = Beyonic_Event::getAll();
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

events = beyonic.Event.list()

package com.beyonic.examples.events;

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

public class ListAllEventsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/events";
    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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "count": 1,
    "next": "https://app.beyonic.com/api/events?offset=10",
    "previous": null,
    "results": [
        {
            "id": 1146,
            "organization":1,
            "type": "contact.created",
            "data": {
                    "id": 26,
                    "organization": 1,
                    "first_name": "Suzanne",
                    "last_name": "Kwagala",
                    "email": "[email protected]",
                    "phone_number": "+80000000001",
                    "type": "employee",
                    "status": "active",
                    "metadata": null,
                    "created": "2013-09-19T21:26:10Z",
                    "author": 1,
                    "modified": "2015-04-14T18:21:47Z",
                    "updated_by": 42
                }
        },
    ]
}

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

Filtering Events

Sample Request:

curl https://app.beyonic.com/api/events?type=contact.created -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

events = Beyonic::Event.list(
  type: "contact.created"
)

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

$events = Beyonic_Event::getAll(array(
  "type" => "contact.created"
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

events = beyonic.Event.list(type='contact.created')

package com.beyonic.examples.events;

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

public class FilterEventsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/events";
    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 + "?type=contact.created");
            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 events 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.

• type - the event type

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:

• Non-HTTPS URLs will be rejected. For testing with a self signed certificate, see the “Testing webhooks” section below.
• Data will be posted to the URL, and a 200 response is expected.
• A non 200 response will result in an error, and Beyonic will retry the request a total of 10 times, with an increasing wait period between each try.
• Beyonic implements a 5 second timeout on webhook requests. See 5 second timeout below for more information.
• A 410 (gone) response will lead to deletion of the webhook
• The URL you submit isn’t specific to a specific object. Once submitted, it will receive notifications for all future events of the specific type made in your organization, whether they are made via the API or via the web-interface.
• Therefore, you are encouraged to use the one URL for each event type. Since URLs are stored at a per-organization level, using different URLs may result in duplicate notifications being sent to the different URLs.
• Previously submitted urls can be deleted via the web browser, or the Webhooks API methods described elsewhere in this reference.

5 second timeout

Beyonic implements a 5 second timeout. We wait 5 seconds for a response to each request, and if there isn’t one, or there is an error, we will retry the request a total of 10 times, with an increasing wait period between each attempt.

Because of this timeout, we recommend that your webhook responds immediately with a 200 response, and then you continue processing the request. For example, you could store the event information, respond and then continue with your tasks.

Depending on the server and language you are using, there are various mechanisms for achieving this, including flushing() the output in PHP or using a message queue and background tasks in other languages.

Supported Event types

See the Events API for a list of supported event types.

Managing Webhooks

You can create and manage webhooks in two ways:

• By logging into your Beyonic account via the web browser as described below
• By using the Webhooks API described below

Managing Webhooks from the web browser

To manage webhooks using the web browser: 1. Log into your account. 2. Go “Home” > “Company Settings” > “Advanced Settings” > “Notification Endpoints”.

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

Sample Webhook Object (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
}

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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "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": ["+80000000001"],
                "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");

$hook = 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) - if you use one of the development libraries, this is automatically converted into a native object for you:

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

• If successful, a JSON representation of the new webhook object will be returned.

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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "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) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "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.

• user - the ID of the user who created the webhook. Note that only users within your organization will be matched.
• event - the webhook event