NAV Navbar
Logo
CURL PHP RUBY PYTHON JAVA

Introduction

Scroll down for examples.

Welcome to Beyonic’s API documentation.

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

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

Quick Start

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

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

Libraries

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

API Endpoint

You access Beyonic’s API at the following endpoint:

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

Versioning

Example Request:

curl -H "Beyonic-Version: v1" https://app.beyonic.com/api

require 'beyonic'
Beyonic.api_version = 'v1'

<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiVersion("v1");
?>

import beyonic
beyonic.api_version = 'v1'

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

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

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

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

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

Authentication

Example Request:

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

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

All requests must use https.

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

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

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

Duplicate Requests

Example Request:

curl https://app.beyonic.com/api -H "Duplicate-Check-Key: ab594c14986612f6167a975e1c369e71edab6900"

require 'beyonic'
Beyonic.duplicate_check_key = 'ab594c14986612f6167a975e1c369e71edab6900'

<?php
require_once('./lib/Beyonic.php');
Beyonic::setDuplicateCheckKey('ab594c14986612f6167a975e1c369e71edab6900');
?>

import beyonic
beyonic.duplicate_check_key = 'ab594c14986612f6167a975e1c369e71edab6900'

Beyonic provides a way for you to make sure that duplicate requests do not result in multiple transactions. This allows you to safely retry a request if you’re not sure that it worked the first time.

You do this by adding a “Duplicate-Check-Key” header to your request. The value of this header can be any string value of your choosing. If Beyonic finds a previous request with the same Duplicate-Check-Key, we will reject the new request with a DuplicateRequestException.

Error Handling

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:

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.
409 Conflict – You sent a duplicate request. Check your Duplicate-Check-Key
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();
  print_r(json_decode($e->responseBody));
}
?>

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:

The API response body shall include the following parameters:

Ordering Results

Ordering Example:

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

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = Beyonic::Contact.list(
  ordering: '-created'
)

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

$contacts = Beyonic_Contact::getAll(array(
  "ordering" => "-created"
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

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

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

Ascending or Descending order:

Filtering Results

Filtering Example:

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

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = Beyonic::Contact.list(
  first_name: 'tom'
)

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

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

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

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

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

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

Metadata

Example showing how to create a new payment with Metadata:

curl https://app.beyonic.com/api/payments -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d phonenumber=+256778122118 \
-d currency=UGX \
-d amount=30 \
-d description="Per diem payment" \
-d callback_url="https://my.website/payments/callback" \
-d metadata.id=1234 \
-d metadata.name=Lucy \
-d payment_type=money

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

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

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

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

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

beyonic.Payment.create(phonenumber='+256778122118',
                       amount='1200',
                       currency='UGX',
                       description='Per diem',
                       callback_url='https://my.website/payments/callback',
                       metadata={'id': '1234', 'name': 'Lucy'}
                       )

Beyonic supports Metadata, which allows you to add custom key-value attributes when creating objects. For example, you can include a unique ID to identify a payment, or add more information about a Contact. This data will be returned when you retrieve the record later, and can be used to identify the record.

Metadata has the following constraints:

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

See the examples for more information.

Custom Fields

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

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

Adding or updating custom field data

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

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

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

API methods that support custom fields.

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

  1. The payment API
  2. The contacts API

Testing

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

Test API token

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

Test Currency

Beyonic provides a test currency, with the following parameters:

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

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

Receiving Payments

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

v2 - February 2016

v2 - November 2015

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 The reason for this collection request. This is used when sending automated instructions to the customer. If you omit this field, it will be set to your company name. Please keep this field below 20 characters because some networks may truncate it. You are also advised to include your company name so that it’s clear who is requesting the funds.
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. If omitted, default network-specific instructions will be sent to the subscriber via SMS. If you want to skip sending ANY sms instructions and turn off even the default instructions, set this parameter to “skip” (instructions = “skip”)

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

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": "BXC",
    "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/131820 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = Beyonic::Collection.get(131820)

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

$collection = Beyonic_Collection::get(131820);
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

collection = beyonic.Collection.get(131820)


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 + "/131820");
            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": 131820,
    "remote_transaction_id": "12132",
    "organization": 1,
    "amount": "200.0000",
    "currency": "BXC",
    "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": "BXC",
        "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).

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:

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

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.

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.

Transactions

Introduction

Transactions are funds movements that happened to your account. This includes Mobile Payments, Airtime Payments, Collections, Service Charges, Account Balance Funds Update.The transactions API allows you to list all these transactions.

The transactions api endpoint is:

The Transaction object

Sample Transaction Object (JSON):

{
    "id": 218,
    "account": 12,
    "amount": "228.0000",
    "description": "Incoming payment from +401000000099",
    "created": "2017-03-28T12:50:59Z",
    "type": "mobile_collection"
}
Field Type Description
id long integer Unique object identifier
account long integer The ID of the account which this transaction belongs to
amount float The transaction amount
description string The payment description
created string The date that the transaction was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
type string The transaction type. This can be admin_funds_update, mobile_funds_update, funds_deposit, funds_adjustment, mobile_collection, mobile_payment, airtime_topup, service_charge, mobile_withdrawal, bank_withdrawal

Retrieving a Single Transaction

Sample Request:

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

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

transaction = Beyonic::Transaction.get(12)

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

$transaction = Beyonic_Transaction::get(12);
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

transaction = beyonic.Transaction.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 SingleTransactionExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/transactions";
    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,
   "account": 123,
   "amount": "228.0000",
   "description": "Incoming payment from +401000000099",
   "created": "2017-03-28T12:50:59Z",
   "type": "mobile_collection"
}

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

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

Listing all transactions

Sample Request:

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

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

transactions = Beyonic::Transaction.list

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

$transactions = Beyonic_Transaction::getAll();
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

transactions = beyonic.Transaction.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 ListAllTransactionsExample {

    private static final String API_ENDPOINT = "https://app.beyonic.com/api/transactions";
    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/transactions?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": 137,
      "account": 123,
      "amount": "2000.0000",
      "description": "Complementary Test Credit.",
      "created": "2016-12-09T11:16:30Z",
      "type": "admin_funds_transfer"
    },
    {
      "id": 160,
      "account": 123,
      "amount": "-600.0000",
      "description": "test msente",
      "created": "2017-02-13T12:01:38Z",
      "type": "mobile_payment"
    }
  ]
}

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

Filtering Transactions

Sample Request:

curl https://app.beyonic.com/api/transactions?type=mobile_payment -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

transactions = Beyonic::Transaction.list(
  type: 'mobile_payment'
)

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

$transactions = Beyonic_Transaction::getAll(array(
  "type" => "mobile_payment"
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

transactions = beyonic.Transaction.list(type='mobile_payment')


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

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

}

You can search or filter transactions 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.

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

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.

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:

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:

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

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.

CURL PHP RUBY PYTHON JAVA