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.
- Sign Up for a Beyonic account.
- 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.
- Download the appropriate client library from links in the “Libraries” section of this reference.
- Using your API token and the library, connect to the API endpoint: https://app.beyonic.com/api
- Identify the methods you need to use. See the “Methods” section of this reference.
- Profit!
Client Libraries
Here are links to the various client libraries & specific installation instructions:
- PHP - https://github.com/beyonic/beyonic-php
- Ruby - https://github.com/beyonic/beyonic-ruby
- Python - https://github.com/beyonic/beyonic-python
- Zapier - Beyonic provides zapier triggers and actions in “Invite Only” mode. Please contact us if you would like to use Zapier with Beyonic’s API.
- Java - We don’t currently offer an official Java client. However, we have provided Java code examples on the ‘Java’ tab to get you started.
API Endpoint
You access Beyonic’s API at the following endpoint:
This endpoint uses your saved API version (see below). If you’d like to make sure that your application always accesses the same version, you can specify a specific version as shown in the versioning section.
Versioning
Example Request:
curl -H "Beyonic-Version: v1" https://app.beyonic.com/api
require 'beyonic'
Beyonic.api_version = 'v1'
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiVersion("v1");
?>
import beyonic
beyonic.api_version = 'v1'
New API versions are released only when we make backward incompatible changes to the API. We define these as changes that will prevent our official clients from working on old versions. Some changes DO NOT result in a new version, including: Adding new API methods, adding optional parameters to existing API methods or adding new fields to responses.
You don’t need to specify a version in your request. The first time an API request is made for your organization, the version is saved, and will be used on subsequent API requests unless it is changed in the organization settings, or overridden as below. This allows your client applications to continue working even if newer API versions are released.
You can temporarily override the API version for a specific request in 2 ways:
- Use version specific URLS like: https://app.beyonic.com/api/v1
- Include the Beyonic-Version header in your request as shown in the examples to the right.
The various API libraries provide methods for changing the version, as shown in the examples to the right.
Note that this doesn’t change your organization’s default API version, which was saved in your organizations settings the first time you interacted with the Beyonic API. To change your default API version, log into the web portal and go to “Company Settings” > Settings (Cogwheel) > Manage General Settings.
Authentication
Example Request:
curl https://app.beyonic.com/api -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey('ab594c14986612f6167a975e1c369e71edab6900');
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
All requests must use https.
The Beyonic API uses Token Based Authentication, and requires an API key for authentication. You can generate or change your API key by logging into your account. Keep your API key secret to maintain the integrity of your account.
You must supply your API key with all API requests using the “Authorization” header as shown in the examples. You should inculde your API key with all requests.
The API key in all the examples is a valid test key, so you can test the examples immediately.
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:
- Codes in the 2XX range mean that the request was processed successfully
- Codes in the 4XX range mean that something was wrong with the data that you sent. For example, you might have missed some required parameters, or you might be using a wrong API token.
- Codes in the 5XX range mean that something went wrong within Beyonic’s servers.
In all cases, the response will include an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error.
Most error responses will include a “detail” key in the body of the response, but some may include additional information, for example, they may include information about missing fields.
The examples to the right show some of the errors that might occur, including the status code and content-type in the response header, and the json-formatted details in the response body.
Common Error Codes
| Error Code | Meaning |
|---|---|
| 400 | Bad Request – Your request is malformed or is missing some required parameters. |
| 401 | Unauthorized – You are using an invalid API token. |
| 403 | Forbidden – You are attempting to access a resource that doesn’t belong to you. Check that you are using the correct API token for the user who owns the resource. |
| 404 | Not Found – You are attempting to access a resource that doesn’t exit. Check the url for your request. |
| 405 | Method Not Allowed – You are attempting to use an invalid method. For example, you might be trying to POST to a readonly endpoint. |
| 406 | Not Acceptable – You requested a format that isn’t supported. Check the “Accept” header of your request, and try to ensure that you are using json format for your requests. |
| 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.
Throttling
Requests to Beyonic are throttled. If you send too many requests too fast, you will receive a throttling error resulting in a response with the HTTP status code “429 Too Many Requests”.
API READ requests are limited to 30/minute.
API WRITE requests are limited to 3000/minute.
Pagination
Pagination Example Request:
curl https://app.beyonic.com/api/v2/contacts?limit=10&offset=5 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_vesion = 'v2'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contacts = Beyonic::Contact.list(
limit: 10,
offset: 5
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiVersion("v2");
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$contacts = Beyonic_Contact::getAll(array(
"limit" => "10",
"offset" => "5"
));
?>
import beyonic
beyonic.api_version = 'v2'
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contacts = beyonic.Contact.list(limit='10',
offset='5')
Most Beyonic API methods support a way to retrieve a list of records. For example, you can retrieve a list of contacts.
When retrieving a list, you can control the number of records returned by adding two parameters to your request:
- limit: This limits the number of records returned per page. If omitted, only 10 records are returned per page
- offset: This tells the Beyonic API where to start getting
The API response body shall include the following parameters:
- count: The total number of records available (not just on the returned page)
- next: A link to the next page of records. If there is no next page, this shall be equal to null
- previous: A link to the previous page of records. If there is no previous page, this shall be equal to null
- results: This will contain the list of records for the current page
Ordering Results
Ordering Example:
curl https://app.beyonic.com/api/contacts?ordering=-created -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contacts = Beyonic::Contact.list(
ordering: '-created'
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$contacts = Beyonic_Contact::getAll(array(
"ordering" => "-created"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contacts = beyonic.Contact.list(ordering='-created')
Most Beyonic API methods support a way to retrieve a list of records. For example, you can retrieve a list of contacts.
When retrieving a list, you can control the order that records are returned in by adding one parameters to your request:
- ordering: This orders the records by one of the visible fields on the object
Ascending or Descending order:
- To use ascending order, just use the field name E.g. ordering=created
- To use descending order, add a “-” to the field name E.g. ordering=-created
Filtering Results
Filtering Example:
curl https://app.beyonic.com/api/contacts?first_name=tom -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contacts = Beyonic::Contact.list(
first_name: 'tom'
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$contacts = Beyonic_Contact::getAll(array(
"first_name" => "tom"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contacts = beyonic.Contact.list(first_name='tom')
Most Beyonic API methods support a way to retrieve a list of records or a single record. For example, you can retrieve a list of contacts or a single contact.
When retrieving a list or a single record, you can limit the results to records where a given field matches specific search criteria. To do this, add the keyword to your request as shown in the examples.
Not all fields are filterable. See the documentation for each method below to see which fields are filterable within that method.
Metadata
Example showing how to create a new payment with Metadata:
curl https://app.beyonic.com/api/payments -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d phonenumber=+256778122118 \
-d currency=UGX \
-d amount=30 \
-d description="Per diem payment" \
-d callback_url="https://my.website/payments/callback" \
-d metadata.id=1234 \
-d metadata.name=Lucy \
-d payment_type=money
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
payment = Beyonic::Payment.create(
phonenumber: "+256778122118",
amount: "100.2",
currency: "UGX",
description: "Per diem payment",
payment_type: "money",
callback_url: "https://my.website/payments/callback",
metadata: {"id": "1234", "name": "Lucy"}
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
Beyonic_Payment::create(array(
"phonenumber" => "+256778122118",
"amount" => "100.2",
"currency" => "UGX",
"description" => "Per diem payment",
"payment_type" => "money",
"callback_url" => "https://my.website/payments/callback",
"metadata" => array("id"=>"1234", "name"=>"Lucy")
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
beyonic.Payment.create(phonenumber='+256778122118',
amount='1200',
currency='UGX',
description='Per diem',
callback_url='https://my.website/payments/callback',
metadata={'id': '1234', 'name': 'Lucy'}
)
Beyonic supports Metadata on the contact, payment and collection request APIs.
Metadata allows you to add custom key-value attributes when creating objects. You can use metadata to track any information you want to track by attaching it to a contact, payment or collection request object.
For example, you can include a unique ID to identify a payment, or add more information about a Contact. This data will be returned when you retrieve the record later, and can be used to identify the record.
Metadata has the following constraints:
- Metadata attributes must be key-value pairs.
- Both the keys and values must be strings.
- For each record, you can have up to 10 custom attributes.
Metadata is added to the object a set of key-value pairs, where the key is in the format metadata.key_name, for example: metadata.id or metadata.name or metadata.date, and so on.
See the examples for more information.
API methods that support metadata.
Not all API methods support metadata. Currently, the following API methods and their corresponding objects support metadata.
- The payment API
- The contacts API
- The collection requests API
Custom Fields
Custom Fields are similar to Metadata - they allow you to add custom data to some objects. Custom fields can be added to contacts, payments or collection requests.
There are a couple of differences between custom fields and other metadata:
- Custom fields are available through the web interface as well as the API. You can enter data in those fields, and also select them for download via excel. Metadata can be viewed through the web interface, but can only be created via the API.
- Metadata keys and values can be created and edited through the API, while custom fields ‘labels’ can only be created through the web interface by your organization administrator. However, once custom fields have been created through the web interface, they can be updated or edited through the API as well.
- 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 custom fields
Unlike metadata, you cannot just automatically use a custom field. You have to add it first. You can add custom fields by going to your organization admin page in the portal and then clicking Advanced > Custom Fields.
Once you have added the field, clicking on the field details to see the actual internal label/name of the field. It will start with an “s_”. This is how you will access the field via the API.
Entering data in fields
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.
- The payment API
- The contacts API
- The collection requests API
Testing
Beyonic provides a few features to ease API testing. These features are described below.
Test API token
All the examples include a test API token that actually works. They can be run directly, so feel free to try them out as you read the documentation.
Test Currency
Beyonic provides a test currency, with the following parameters:
- Phone Format: +800XXXXXXXX
- Currency Code: BXC
The BXC currency is used throughout the examples and you can also use it in your own testing. Payments made in the BXC currency will not affect your live currency accounts. Additionally, depending on the number you are paying, you can test various success and failure scenarios. See “Test Numbers” below
Note: Currently, this test currency works only for outgoing payments.
Enabling or disabling the test currency
To enable or disable the test currency, once you’re logged into Beyonic, go to this URL:
Or go to “Home” > “Company Settings” > (Cogwheel) > Test Tools.
From that URL, you can enable the test currency, and also update the available test credit.
Test Numbers
Beyonic provides test numbers that should be used in conjunction with the test currency. The following numbers are treated in special ways when used with the BXC currency:
Sending Payments
- +80000000001 - When you add a contact with this number, the contact will always fail the mobile money registration checks, and therefore payments sent to this number will always fail.
- +800XXXXXXXX - All other numbers in the format +800XXXXXXXX will pass the name checks only if the contact name is “John Doe”. So, set the name to “John Doe” to test the effect of a successful name check, or set it to something else to test the effect of a failed name check.
- Subsequently, all BXC payments to numbers with format +800XXXXXXXX and name “John Doe”, (except +80000000000) will succeed, if the amount is greater than or equal to 10 and less than or equal to 5,000,000 BXC.
Note: Make sure you have enough BXC credit on your account. Use https://app.beyonic.com/testing/ to update your BXC credit.
Receiving Payments
- +80000000001 - If you request a payment from this number, it will always fail with the “Cancelled By User” error. Use this to simulate a user cancelling or rejecting your payment request.
- +80000000009 - If you request a payment from this number, it will always expire. Use this to simulate a user ignoring your payment request by doing nothing and letting it expire.
- +800XXXXXXXX - All other numbers in this format will complete successfully. Use this to test successful payment request scenarios.
Note: Make sure you have enough BXC credit on your account. Use https://app.beyonic.com/testing/ to update your BXC credit.
Testing Webhooks
1. Triggering test events
To trigger a test notification, simply perform the corresponding action in your account. You can do this via the API or the web portal.
For example, to trigger a ‘contact.created’ event, simply create a contact. Or, to trigger a 'payment.status.changed’ event, use the Payments API to create a payment with the test currency and test numbers described above.
2. Https with invalid certificates
Beyonic only supports notification urls (also called webhooks or callback urls) that start with “https://”, even when testing. See the “Webhooks” section for more infromation. So, you should set up URL to a dedicated page on your server with a server-side https certificate.
Beyonic will usually validate the https certificate, and if validation fails, the notification will not be sent to your URL. To skip validation while testing, add ?skip-cert-verify to your URL, for example:
Note that skip-cert-verify only prevents certificate verification. It doesn’t eliminate the “https://” requirement
While you can use skip-cert-verify on your production URLs, we advise you to use valid server side certificates to maximize security on your production systems.
3. Setting up a temporary callback URL and verifying the format of the notifications
If you are not able to set up a dedicated “https://” url while testing, we recommend using a service like RequestBin.
RequestBin gives you a URL that will collect requests made to it and let you inspect them in a human-friendly way. Use RequestBin to inspect and debug the webhook notifications.
Once you get a RequestBin URL, it uses http by default. Since Beyonic only supports https, remember to use “https://” and “skip-cert-verify”
For example, if your RequestBin URL is
Then use this for your callback URLs:
4. Viewing logged notification requests and responses
Beyonic logs notificaiton requests and responses for at least 30 days. These can be viewed by logging into the web portal, and going to “Home” > Company Settings" > “Advanced Settings” > “Notification Endpoints”
By clicking on “Recent Events”, you will be able to see events and notification attempts, including the responses that Beyonic is getting from your notification server.
Changelog
This section lists new versions and the changes made in those versions. Review these changes to decide whether you need to upgrade to the new version. Note that only backward incompatible changes are shown. See the Versioning section for more information on how to upgrade to a new version.
v3 - September 2016
- collection_request field on Collection object now contains a JSON representation of the Collection Request, not the ID
v2 - February 2016
- Accounts API to get balances of organization’s accounts.
v2 - November 2015
- Versioning improvements to provide transparent backward compatibility by automatically saving users’ version. Versions can be upgraded manually via web interface
- organization field now contains the organization ID, not name, in the Payments, Contacts and Collection Requests methods
- currency field now contains the currency code, not the currency ID, in the Collections method
Receiving Money
Introduction
Beyonic uses the term “Collection” to refer to money that you receive (or collect) from a mobile subscriber. This differentiates money you receive (Collections) from money you send to mobile subscribers (Payments).
Beyonic provides to API methods to help you with receiving money from customers.
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.
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.
The “collectionrequest.status.changed” event is triggered whenever the status of your collection request changes, for example if a collection is received in response to your collection request, or if the collection request fails or expires. You can configure a web link to receive notifications whenever this event occurs. This will allow you to respond automatically to updates made to your collection request. 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": 427737,
"organization": 4,
"amount": "3000.0000",
"currency": "BXC",
"phonenumber": "+80000000001",
"contact": {
"id": 127694,
"organization": 4,
"first_name": "Kennedy",
"last_name": "Amani",
"email": null,
"phone_number": "+80000000001",
"type": "employee",
"status": "active",
"metadata": {},
"phone_is_supported": "yes",
"phone_is_mm_registered": "yes",
"name_on_network": "Insufficient Data Or Too Low Score",
"name_matches_network_status": "checked",
"name_matches_network_score": 0.0,
"network_name": "",
"created": "2016-12-30T21:14:27Z",
"author": 134,
"modified": "2018-04-24T08:16:27Z",
"updated_by": 134
},
"reason": "Test Org",
"metadata": {
"my_id": "123ASDAsd123"
},
"created": "2018-05-25T19:06:51Z",
"author": 134,
"modified": "2018-05-25T19:06:51Z",
"updated_by": 134,
"collection": null,
"account": null,
"success_message": "",
"instructions": null,
"send_instructions": false,
"status": "pending",
"error_message": null,
"error_details": null,
"expiry_date": "2018-05-26 19:06:51.300273+00:00"
}
| 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 + |
| contact | object | The contact that has been matched to this request. See the “Contacts” section for more information. |
| 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 |
| send_instructions | boolean | Defaults to False (but you probably want to set this to True). 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 notify the customer (with a USSD popup and an SMS), you must set this field to True. Omitting the field will prevent collection requests from being sent out to the customer. |
| instructions | string or null | 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”) |
| status | string | This is the status of the collection request. Possible values are: pending, successful, failed, expired or reversed |
| error_message | string | This will contain a short description in case of an error |
| error_details | string | This will contain an detailed description in case of an error |
| expiry_date | string or null | Defaults to “24 hours”. Specifies the date and time when this collection request will be marked as expired. Examples of valid values for this field include strings such as “tomorrow”, “24 hours”, “2 minutes”, or %d/%m/%Y format e.g 24/05/2019 or %d/%m/%Y %H:%M:%S format e.g 24/05/2019 13:24:12 |
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": 427737,
"organization": 4,
"amount": "3000.0000",
"currency": "BXC",
"phonenumber": "+80000000001",
"contact": {
"id": 127694,
"organization": 4,
"first_name": "Kennedy",
"last_name": "Amani",
"email": null,
"phone_number": "+80000000001",
"type": "employee",
"status": "active",
"metadata": {},
"phone_is_supported": "yes",
"phone_is_mm_registered": "yes",
"name_on_network": "Insufficient Data Or Too Low Score",
"name_matches_network_status": "checked",
"name_matches_network_score": 0.0,
"network_name": "",
"created": "2016-12-30T21:14:27Z",
"author": 134,
"modified": "2018-04-24T08:16:27Z",
"updated_by": 134
},
"reason": "Test Org",
"metadata": {
"my_id": "123ASDAsd123"
},
"created": "2018-05-25T19:06:51Z",
"author": 134,
"modified": "2018-05-25T19:06:51Z",
"updated_by": 134,
"collection": null,
"account": null,
"success_message": "",
"instructions": null,
"send_instructions": false,
"status": "pending",
"error_message": null,
"error_details": null,
"expiry_date": "2018-05-26 19:06:51.300273+00:00"
}
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 (but you probably want to set this to True). 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 notify the customer (with a USSD popup and an SMS), you must set this field to True. Omitting the field will prevent collection requests from being sent out to the customer. |
| 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”) |
| expiry_date | No | Date String | 24 hours | Defaults to “24 hours”. Specifies the date and time when this collection request will be marked as expired. Examples of valid values for this field include strings such as “tomorrow”, “24 hours”, “2 minutes”, or %d/%m/%Y format e.g 24/05/2019 or %d/%m/%Y %H:%M:%S format e.g 24/05/2019 13:24:12 |
Retrieving a single Collection Request
Sample Request:
curl https://app.beyonic.com/api/collectionrequests/427737 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
collection_request = Beyonic::CollectionRequest.get(427737)
p collection_request # Examine the returned object
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$collection_request = Beyonic_Collection_Request::get(427737);
print_r($collection_request); // Examine the returned object
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
collection_request = beyonic.CollectionRequest.get(427737)
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 + "/427737");
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": 427737,
"organization": 4,
"amount": "3000.0000",
"currency": "BXC",
"phonenumber": "+80000000001",
"contact": {
"id": 127694,
"organization": 4,
"first_name": "Kennedy",
"last_name": "Amani",
"email": null,
"phone_number": "+80000000001",
"type": "employee",
"status": "active",
"metadata": {},
"phone_is_supported": "yes",
"phone_is_mm_registered": "yes",
"name_on_network": "Insufficient Data Or Too Low Score",
"name_matches_network_status": "checked",
"name_matches_network_score": 0.0,
"network_name": "",
"created": "2016-12-30T21:14:27Z",
"author": 134,
"modified": "2018-04-24T08:16:27Z",
"updated_by": 134
},
"reason": "Test Org",
"metadata": {
"my_id": "123ASDAsd123"
},
"created": "2018-05-25T19:06:51Z",
"author": 134,
"modified": "2018-05-25T19:06:51Z",
"updated_by": 134,
"collection": null,
"account": null,
"success_message": "",
"instructions": null,
"send_instructions": false,
"status": "pending",
"error_message": null,
"error_details": null,
"expiry_date": "2018-05-26 19:06:51.300273+00:00"
}
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 | 427737 | 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": 31271,
"next": "https://app.beyonic.com/api/collectionrequests?limit=10&offset=10",
"previous": null,
"results": [{
"id": 427737,
"organization": 4,
"amount": "3000.0000",
"currency": "BXC",
"phonenumber": "+80000000001",
"contact": {
"id": 127694,
"organization": 4,
"first_name": "John",
"last_name": "Doe",
"email": null,
"phone_number": "+80000000001",
"type": "employee",
"status": "active",
"metadata": {},
"phone_is_supported": "yes",
"phone_is_mm_registered": "yes",
"name_on_network": "Insufficient Data Or Too Low Score",
"name_matches_network_status": "checked",
"name_matches_network_score": 0.0,
"network_name": "",
"created": "2016-12-30T21:14:27Z",
"author": 134,
"modified": "2018-04-24T08:16:27Z",
"updated_by": 134
},
"reason": "Test Org",
"metadata": {
"my_id": "123ASDAsd123"
},
"created": "2018-05-25T19:06:51Z",
"author": 134,
"modified": "2018-05-25T19:06:51Z",
"updated_by": 134,
"collection": null,
"account": null,
"success_message": "",
"instructions": null,
"send_instructions": false,
"status": "pending",
"error_message": null,
"error_details": null,
"expiry_date": "2018-05-26 19:06:51.300273+00:00"
}, {
"id": 427028,
"organization": 4,
"amount": "50000.0000",
"currency": "UGX",
"phonenumber": "+256XXXXXXXXX",
"contact": {
"id": 188525,
"organization": 4,
"first_name": "John",
"last_name": "Doe",
"email": null,
"phone_number": "+256XXXXXXXXX",
"type": "employee",
"status": "active",
"metadata": {},
"phone_is_supported": "yes",
"phone_is_mm_registered": "yes",
"name_on_network": "John Doe",
"name_matches_network_status": "checked",
"name_matches_network_score": 100.0,
"network_name": "",
"created": "2017-05-11T19:04:40Z",
"author": 134,
"modified": "2018-02-22T21:00:15Z",
"updated_by": 432
},
"reason": "Test Org",
"metadata": {
"my_id": "123ASDAsd123"
},
"created": "2018-05-25T14:56:56Z",
"author": 134,
"modified": "2018-05-25T14:58:01Z",
"updated_by": 134,
"collection": null,
"account": null,
"success_message": "",
"instructions": null,
"send_instructions": true,
"status": "pending",
"error_message": null,
"error_details": null,
"expiry_date": "2018-05-26 14:56:55.917817+00:00"
}, ... ]
}
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?phonenumber=%2B80000000001&amount=500" -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
collection_requests = Beyonic::CollectionRequest.list(
phonenumber: '+80000000001',
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(
"phonenumber" => "+80000000001",
"amount" => 500
));
print_r($collection_requests); // Examine the returned objects
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
collection_requests = beyonic.CollectionRequest.list(phonenumber='+80000000001', amount=500)
print collection_requests # Examine the returned objects
package com.beyonic.examples.collectionrequests;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class FilterCollectionRequestsExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/collections";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "?remote_transaction_id=SS12312&amount=500");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
You can search or filter collection requests on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only. (The phonenumber field is treated differently - see below).
- amount - the collection request amount
- currency - the currency code
- collection - the ID of the collection that fulfilled or matched this collection request
- phonenumber - the phonenumber that the collection request was intended for. Note that the phonenumber will be matched in international format, starting with a ’+’ sign. If the ’+’ sign isn’t included in your request, it will be appended before attempting to match your request.
- remote_transaction_id - the transaction id or transaction reference of the collection on the mobile network operator’s side
- created_after - only return collection requests created after this date (E.g. 2017-01-01 00:00)
- created_before - only return collection requests created before this date (E.g. 2017-01-01 00:00)
Collections
Beyonic uses the term “Collections” for payments you receive (or collect) from mobile subscribers. See the Beyonic collections guide 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](#collection-requests. 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. |
Accept or reject Collections
By default, collections are matched to your account and automatically accepted. However, the following networks allow you to decide whether you want to accept or reject a collection.
- Safaricom (MPESA) Kenya
- MTN Uganda
- Airtel Tanzania
- Vodacom Tanzania
- All Rwanda Networks
Enabling Collection verification
To enable this functionality, you need to add a verificaiton URL to your collection settings:
- Log into your Beyonic Account
- Click “Company Settings” on the home page
- Click “Advanced Settings”
- Click “Collection Settings”
- Enter a Collection Verification URL.
- You can also decide what action we should take if we cannot reach your verification URL for some reason. This is controlled by the “Accept Collections By Default” option. If this option is checked, we’ll accept collections when your URL is unreachable. Otherwise, they will be rejected.
Verification request parameters
{
"remote_transaction_id": "ASD12132",
"phonenumber": "+80000000001",
"reference": "Payment for A/C 13112313",
"amount": "500",
"currency_code": "BXC",
}
Once you have created a URL, we will send a JSON POST to the URL you have provided, whenever a new collection is received. The request body shall include the following parameters as a JSON object:
| Field | Description |
|---|---|
| phonenumber | The subscriber’s phone number that was used to send collection in international format, e.g. +256782123123 |
| amount | The amount that was sent, e.g. 500 |
| currency_code | The 3 letter currency code, e.g. UGX |
| reference | The reference or description that the subscriber sent along with the collection. e.g A/C 12312 |
| remote_transaction_id | The network transaction id that identifies this collection on the mobile network operator’s system e.g. ASDASDW12321312 |
ACCEPT response
ACCEPT < remote_transaction_id >
For example:
ACCEPT ASCD1234
In order to accept the collection, you must respond with a 200 response, and the following text in the body of the response:
ACCEPT < remote_transaction_id >
E.g. if the remote transaction id was ASCD1234, then you must respond with:
ACCEPT ASCD1234
REJECT response
REJECT < remote_transaction_id > < optional reason >
For example:
REJECT ASCD1234 Wrong Account Number.
In order to reject the collection, you must respond with a 200 response, and the following text in the body of the response:
REJECT < remote_transaction_id > < optional reason >
E.g. if the remote transaction id was ASCD1234, then you must respond with:
NOTE: The reject reason is optional. If included, we shall attempt to return it to the network (and the network may send it on to the subscriber)
Response timeout
You must respond within 60 seconds, otherwise the verification request will timeout and the default action shall be taken.
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=%2B80000000001&remote_transaction_id=SS12312 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
collections = Beyonic::Collection.list(
phonenumber: "+80000000001",
remote_transaction_id: "SS12312"
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$collections = Beyonic_Collection::getAll(array(
"phonenumber" => "+80000000001",
"remote_transaction_id" => "SS12312"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
collections = beyonic.Collection.list(phonenumber='+80000000001',
remote_transaction_id='SS12312')
package com.beyonic.examples.collections;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class FilterCollectionsExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/collections";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "?remote_transaction_id=SS12312");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
[
{
"id": 134,
"phonenumber": "+256XXXXXX",
"remote_transaction_id": "ASDCECASF",
"payment_date": "2014-11-22T20:57:04Z",
"reference": "Test Payment",
"amount": 3000.000,
"currency": "BXC",
"status": "successful"
}
]
You can search or filter collections on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only (the phonenumber field is treated differently - see below).
- amount - the collection amount
- currency - the currency code
- phonenumber - the phonenumber that the collection request was intended for. Note that the phonenumber will be matched in international format, starting with a ’+’ sign. If the ’+’ sign isn’t included in your request, it will be appended before attempting to match your request. This is only true for phone number searches with collections, to make claiming of transactions easier. Other
- reference - the reference code that the customer used when sending the collection
- remote_transaction_id - the transation id or transaction reference of the collection on the mobile network operator’s side
- collection_request - the ID of the collection request that this collection was matched to
- created_after - only return collections created after this date (E.g. 2017-01-01 00:00)
- created_before - only return collections created before this date (E.g. 2017-01-01 00:00)
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=%2B80000000001&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=%2B80000000001&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,
"send_sms_message": false,
"charged_fee": 0
}
| 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. |
| send_sms_message | boolean | Defaults to False. Indicates whether we should send the description as a separate sms message to the consumer. Additional SMS fees apply. See https://beyonic.com/pricing for fees information. When SMS is enabled, can use the following placeholders in the description for personalization: {firstname}, {fullname}, {phone}, {amount} |
| charged_fee | decimal | The fee that was charged. It is only available for completed payments. |
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,
"charged_fee": 0
}
To create a new payment, make a POST to the end point above, with the attributes below.
Note:
- A contact is created for each new phone number you send payments to. This gives you the benefits of the pre-verification checks that are done prior to payment processing.
- If the contact isn’t registered for mobile money, then the payment will not be sent.
- Important: One of the pre-verification checks does a name match check to make sure that the contact name is right. This check can cause your payments to fail if the names that you are sending are not the same as the names in the telecom database. If you want to by-pass this check, go into your settings in your account and uncheck the checkbox that says “Name match affects payment”.
- Important: The account and currency parameters are both optional but you must provide one of them. If you provide both them then the account’s currency must match the currency parameter.
| Parameter | Required | Type | Example | Notes |
|---|---|---|---|---|
| phonenumber | Yes | String | +80000000001 | Must be in international format |
| payment_type | No | String | money | Options: money (default), airtime - use “airtime” to send an airtime payment instead of a mobile money payment |
| amount | Yes | String, Integer or Decimal | 3000 | Do not include thousands separators |
| currency | No | String | BXC | 3 letter ISO currency code. No currency conversion is done, so the currency must be valid for the selected phonenumber. You must have a funded Beyonic account in this currency. If your account for this currency has zero balance, your payment will fail. If you also provide an account parameter then the account’s currency must match the currency parameter. Note:: BXC is the Beyonic Test Currency code. See the “Testing” section for more information. Supported currency codes are BXC (Testing), UGX (Uganda), KES (Kenya) |
| account | No | Integer | 1 | The ID of the account from which you are making the payment. The account must be active and funded. If the account has zero balance, your payment will fail. This parameter is optional if a currency is provided. If you have more than one account with the same currency, and you leave this parameter out, the earliest created account (oldest account) that is still active will be used. |
| description | Yes | String | Per diem payment | This description will be sent to the recipient along with the payment, so it should be limited to about 140 characters. |
| callback_url | No | String | https://my.website/payments/callback | Callback URLs are used to send notifications of changes in payment status. Not all payments will be completed immediately, especially if it is a payment to a new number that hasn’t been verified, or if your account has approval rules that require other users to approve payments before they are processed. Note that the URL you submit isn’t specific to a specific payment you have created. Once submitted, it will receive notifications for all future payments made via your organization, whether they are made via the API or via the web-interface. Therefore, you are encouraged to use the same URL for all payments. Since URLs are stored at a per-organization level, using different URLs may result in duplicate notifications being sent to the different URLs. See “Webhooks” below for more info. |
| metadata | No | JSON-formatted string or dictionary | “{‘id’:'1234’,'name’:'Lucy’}” | Metadata allows you to add custom attributes to your payments. E.g. You can include a unique ID to identify each payment. Attributes must be key-value pairs. Both the keys and values must be strings. You can add up to 10 attributes. This data will be returned when you retrieve a payment. |
| first_name | No | String | John | If this payment is to a new contact, you can include their first name. This name will only be used if the phone number is new. |
| last_name | No | String | Doe | If this payment is to a new contact, you can include their last name. This name will only be used if the phone number is new. |
Responses
- If successful, a JSON representation of the new payment object will be returned. The state field will be “new”
- The payment object can be identified using it’s id field, or the metadata that you supplied.
- On subsequent notification callbacks to your callback URL, the same payment object (with the same id field) will be returned. Check the state field for the latest payment status.
- The state field values can be:
- new – for new payments
- processed – for successfully completed payments
- processed_with_errors – for payments that didn’t complete successfully. The last_error field with have more information.
- rejected – for payments that were rejected during the approval process. The following fields will have more information: rejected_reason, rejected_by and rejected_time
- cancelled – for payments that were cancelled. The following fields will have more information: cancelled_reason, cancelled_by and cancelled_time
Retrieving a single Payment
Sample Request:
curl https://app.beyonic.com/api/payments/22744 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
payment = Beyonic::Payment.get(22744)
p payment # Examine the returned object
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$payment = Beyonic_Payment::get(22744);
print_r($payment); // Examine the returned object
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
payment = beyonic.Payment.get(22744)
print payment # Examine the returned object
package com.beyonic.examples.payments;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class SinglePaymentExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/payments";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "/22744");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"id": 22744,
"organization": 4,
"amount": "1200.0000",
"currency": "BXC",
"account": "1",
"payment_type": "money",
"metadata": {"id": 1234, "name": "Lucy"},
"description": "Per diem payment",
"phone_nos": ["+80000000001"],
"state": "new",
"last_error": null,
"rejected_reason": null,
"rejected_by": null,
"rejected_time": null,
"cancelled_reason": null,
"cancelled_by": null,
"cancelled_time": null,
"created":"2016-03-31T08:08:01Z",
"author":134,
"modified":"2016-03-31T08:08:45Z",
"updated_by":134,
"start_date":"2016-03-31T08:08:01Z",
"charged_fee": 0
}
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",
"charged_fee": 0
},
{
"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",
"charged_fee": 0
},
]
}
To return a list of all payments, make a GET request to the payments endpoint. This will return a list of payment objects.
Filtering Payments
Sample Request:
curl https://app.beyonic.com/api/payments?amount=500 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
payments = Beyonic::Payment.list(
amount: 500
)
p payments # Examine the returned objects
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$payments = Beyonic_Payment::getAll(array(
"amount" => 500
));
print_r($payments); // Examine the returned objects
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
payments = beyonic.Payment.list(amount=500)
print payments # Examine the returned objects
package com.beyonic.examples.payments;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class FilterPaymentsExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/payments";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "?amount=500");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
You can search or filter payments on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only.
- amount - the payment amount
- currency - the payment currency code
- payment_type - the payment type
- created_after - only return payments created after this date (E.g. 2017-01-01 00:00)
- created_before - only return payments created before this date (E.g. 2017-01-01 00:00)
Other Actions
Below are additional API endpoints supported by Beyonic’s API. Clicking on each topic in the table of contents shall reveal the actions that you can perform.
Accounts
Introduction
Accounts hold your funds. The accounts api method allows you to list your accounts and view balances for each account. When you sign up for Beyonic, at least one account in your primary currency is created for your organization. You can request additional accounts if needed.
The accounts api endpoint is:
The Account object
Sample Account Object (JSON):
{
"id": 1146,
"organization":1,
"balance": 200.0,
"currency": "KES",
"status": "active",
"created": "2015-02-13T04:22:31Z",
"author": 7,
"modified": "2015-02-26T13:00:35Z",
"updated_by": 1
}
| Field | Type | Description |
|---|---|---|
| id | long integer | Unique object identifier |
| organization | long integer | The ID of the organization that the account belongs to. (This is usually your organization ID) |
| balance | float | The current account balance |
| currency | string | The account’s currency code. i.e KES, UGX |
| status | string | The account’s status. One of: active or inactive |
| created | string | The date that the account was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ” |
| author | long integer | The ID of the user who created the account |
| modified | string | The date that the account was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ” |
| updated_by | string | The ID of the user who last updated the account |
Retrieving a Single Account
Sample Request:
curl https://app.beyonic.com/api/accounts/12 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
account = Beyonic::Account.get(12)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$account = Beyonic_Account::get(12);
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
account = beyonic.Account.get(12)
package com.beyonic.examples.account;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class SingleAccountExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/accounts";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "/12");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"id": 12,
"organization":1,
"balance": 200.0,
"currency": "KES",
"status": "active",
"created": "2015-02-13T04:22:31Z",
"author": 7,
"modified": "2015-02-26T13:00:35Z",
"updated_by": 1
}
To retrieve a single account, provide the account id and a account object will be returned.
| Parameter | Required | Type | Example | Notes |
|---|---|---|---|---|
| id | Yes | Integer | 12 | The id of the account you want to retrieve |
Listing all accounts
Sample Request:
curl https://app.beyonic.com/api/accounts -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
accounts = Beyonic::Account.list
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$accounts = Beyonic_Account::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
accounts = beyonic.Account.list()
package com.beyonic.examples.accounts;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class ListAllAccountsExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/accounts";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"count": 2,
"next": "https://app.beyonic.com/api/accounts?offset=10",
"previous": null,
"results": [
{
"id": 1146,
"organization":1,
"balance": 200.0,
"currency": "KES",
"status": "active",
"created": "2015-02-13T04:22:31Z",
"author": 7,
"modified": "2015-02-26T13:00:35Z",
"updated_by": 1
},
{
"id": 1147,
"organization":1,
"balance": 100.0,
"currency": "UGX",
"status": "active",
"created": "2015-02-13T04:22:31Z",
"author": 7,
"modified": "2015-02-26T13:00:35Z",
"updated_by": 1
},
]
}
To retrieve a list of all accounts, make a GET request to the accounts end point. This will return a list of accounts.
Filtering Accounts
Sample Request:
curl https://app.beyonic.com/api/accounts?currency=KES -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
accounts = Beyonic::Account.list(
currency: "KES"
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$accounts = Beyonic_Account::getAll(array(
"currency" => "KES"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
accounts = beyonic.Account.list(currency='KES')
package com.beyonic.examples.accounts;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class FilterAccountsExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/accounts";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "?currency=UGX");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
You can search or filter accounts on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only.
- currrency - the account currency
- status - the account status
- created_after - only return accounts created after this date (E.g. 2017-01-01 00:00)
- created_before - only return accounts created before this date (E.g. 2017-01-01 00:00)
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.
- account - the account id
- type - the type of the transaction
- created_after - only return transactions created after this date (E.g. 2017-01-01 00:00)
- created_before - only return transactions created before this date (E.g. 2017-01-01 00:00)
- start_date - the earliest date you want to include transactions from, inclusive (E.g. 2017-01-01 00:00)
- end_date - the latest date you want to include transactions, inclusive (E.g. 2017-01-01 00:00)
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 |
| 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 |
| No | String | [email protected] | The contact’s email address | |
| metadata | No | JSON String | “{‘my_id’: '123ASDAsd123’}” | Custom attributes to store with this object. See the Metadata section for more information. |
Retrieving a single contact
Sample Request:
curl https://app.beyonic.com/api/contacts/44702 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contact = Beyonic::Contact.get(44702)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$contact = Beyonic_Contact::get(44702);
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contact = beyonic.Contact.get(44702)
package com.beyonic.examples.contact;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class SingleContactExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/contacts";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "/44702");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"id":44702,
"organization":4,
"first_name":"John",
"last_name":"Doe",
"email":null,
"phone_number":"+80000000001",
"type":"employee",
"status":"active",
"metadata":{},
"created":"2016-03-30T17:44:30Z",
"author":134,
"modified":"2016-03-30T17:45:22Z",
"updated_by":134
}
To retrieve a single contact, provide the contact id and a contact object will be returned.
| Parameter | Required | Type | Example | Notes |
|---|---|---|---|---|
| id | Yes | Integer | 23 | The id of the contact you want to retrieve |
Listing all Contacts
Sample Request:
curl https://app.beyonic.com/api/contacts -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contacts = Beyonic::Contact.list
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$contacts = Beyonic_Contact::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contacts = beyonic.Contact.list()
package com.beyonic.examples.contacts
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
public class ListAllContactsExample{
private static final String API_ENDPOINT = "https://app.beyonic.com/api/contacts";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"count": 2,
"next": "https://app.beyonic.com/api/contacts?offset=10",
"previous": null,
"results": [
{
"id": 1146,
"organization": "Demo Org",
"first_name": "Eliana",
"last_name": "Kalema",
"email": null,
"phone_number": "+25677XXXXXX",
"type": "other",
"status": "active",
"metadata": null,
"created": "2015-02-13T04:22:31Z",
"author": 7,
"modified": "2015-02-26T13:00:35Z",
"updated_by": 1
},
{
"id": 1175,
"organization": "Demo Org",
"first_name": "Trina",
"last_name": "Faith",
"email": null,
"phone_number": "+25677XXXXXX",
"type": "employee",
"status": "active",
"metadata": null,
"created": "2015-02-18T11:52:43Z",
"author": 137,
"modified": "2015-02-26T13:00:35Z",
"updated_by": 1
},
]
}
To retrieve a list of all contacts, make a GET request to the contact end point. This will return a list of contacts.
Filtering Contacts
Sample Request:
curl https://app.beyonic.com/api/contacts?first_name=luke -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contacts = Beyonic::Contact.list(
first_name: "luke"
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$contacts = Beyonic_Contact::getAll(array(
"first_name" => "luke"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
contacts = beyonic.Contact.list(first_name='luke')
package com.beyonic.examples.contact;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
public class FilterContactsExample{
private static final String API_ENDPOINT = "https://app.beyonic.com/api/contacts";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "?first_name=John");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
You can search or filter contacts on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only. (The phone_number field is treated differently - see below).
- first_name - the contact’s first name
- last_name - the contact’s last name
- email - the contact’s email
- phone_number - the contact’s phone number. Note that the phonenumber will be matched in international format, starting with a ’+’ sign. If the ’+’ sign isn’t included in your request, it will be appended before attempting to match your request.
- created_after - only return contacts created after this date (E.g. 2017-01-01 00:00)
- created_before - only return contacts created before this date (E.g. 2017-01-01 00:00)
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 state. See the “Payments” section for possible state values. | 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 |
| collectionrequest.status.changed | Triggered any time a collection request status changes. See the “Collection Requests” section for possible status values. | CollectionRequest object |
The Event object
Sample Event Object (JSON)
{
"id": 1146,
"organization":1,
"type": "contact.created",
"data": {
"id": 26,
"organization": 1,
"first_name": "Suzanne",
"last_name": "Kwagala",
"email": "[email protected]",
"phone_number": "+80000000001",
"type": "employee",
"status": "active",
"metadata": null,
"created": "2013-09-19T21:26:10Z",
"author": 1,
"modified": "2015-04-14T18:21:47Z",
"updated_by": 42
},
"created": "2013-09-19T21:26:10Z",
"author": 1,
"modified": "2015-04-14T18:21:47Z",
"updated_by": 42
}
| Field | Type | Description |
|---|---|---|
| id | long integer | Unique object identifier |
| organization | long integer | The ID of the organization that the event belongs to. (This is usually your organization ID) |
| type | string | The event type. See Supported Event Types above |
| data | object | The details about the event. This is a representation of the object that triggered the event. For example, for the “contact.created” event, this will repesent a “Contact” object |
| created | string | The date that the event was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ” |
| author | long integer | The ID of the user who created the event |
| modified | string | The date that the event was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ” |
| updated_by | string | The ID of the user who last modified the event |
Retrieving a Single Account
Sample Request:
curl https://app.beyonic.com/api/events/12 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
event = Beyonic::Event.get(12)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$event = Beyonic_Event::get(12);
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
event = beyonic.Event.get(12)
package com.beyonic.examples.events;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class SingleEventExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/events";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "/12");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"id": 1146,
"organization":1,
"type": "contact.created",
"data": {
"id": 26,
"organization": 1,
"first_name": "Suzanne",
"last_name": "Kwagala",
"email": "[email protected]",
"phone_number": "+80000000001",
"type": "employee",
"status": "active",
"metadata": null,
"created": "2013-09-19T21:26:10Z",
"author": 1,
"modified": "2015-04-14T18:21:47Z",
"updated_by": 42
},
"created": "2013-09-19T21:26:10Z",
"author": 1,
"modified": "2015-04-14T18:21:47Z",
"updated_by": 42
}
To retrieve a single event, provide the event id and an event object will be returned.
| Parameter | Required | Type | Example | Notes |
|---|---|---|---|---|
| id | Yes | Integer | 12 | The id of the event you want to retrieve |
Listing all Events
Sample Request:
curl https://app.beyonic.com/api/events -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
events = Beyonic::Event.list
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$events = Beyonic_Event::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
events = beyonic.Event.list()
package com.beyonic.examples.events;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class ListAllEventsExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/events";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"count": 1,
"next": "https://app.beyonic.com/api/events?offset=10",
"previous": null,
"results": [
{
"id": 1146,
"organization":1,
"type": "contact.created",
"data": {
"id": 26,
"organization": 1,
"first_name": "Suzanne",
"last_name": "Kwagala",
"email": "[email protected]",
"phone_number": "+80000000001",
"type": "employee",
"status": "active",
"metadata": null,
"created": "2013-09-19T21:26:10Z",
"author": 1,
"modified": "2015-04-14T18:21:47Z",
"updated_by": 42
}
},
]
}
To retrieve a list of all events, make a GET request to the events end point. This will return a list of events.
Filtering Events
Sample Request:
curl https://app.beyonic.com/api/events?type=contact.created -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
events = Beyonic::Event.list(
type: "contact.created"
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$events = Beyonic_Event::getAll(array(
"type" => "contact.created"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
events = beyonic.Event.list(type='contact.created')
package com.beyonic.examples.events;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class FilterEventsExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/events";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "?type=contact.created");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
You can search or filter events on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only.
- type - the event type
Webhooks
Introduction
Webhooks or callback URLs allow you to define URLs on your server that notifications should be sent to when specific events occur in your Beyonic account.
The webhooks api endpoint is:
Note:
- Non-HTTPS URLs will be rejected. For testing with a self signed certificate, see the “Testing webhooks” section below.
- Data will be posted to the URL, and a 200 response is expected.
- A non 200 response will result in an error, and Beyonic will retry the request a total of 10 times, with an increasing wait period between each try.
- Beyonic implements a 5 second timeout on webhook requests. See 5 second timeout below for more information.
- A 410 (gone) response will lead to deletion of the webhook
- The URL you submit isn’t specific to a specific object. Once submitted, it will receive notifications for all future events of the specific type made in your organization, whether they are made via the API or via the web-interface.
- Therefore, you are encouraged to use the one URL for each event type. Since URLs are stored at a per-organization level, using different URLs may result in duplicate notifications being sent to the different URLs.
- Previously submitted urls can be deleted via the web browser, or the Webhooks API methods described elsewhere in this reference.
5 second timeout
Beyonic implements a 5 second timeout. We wait 5 seconds for a response to each request, and if there isn’t one, or there is an error, we will retry the request a total of 10 times, with an increasing wait period between each attempt.
Because of this timeout, we recommend that your webhook responds immediately with a 200 response, and then you continue processing the request. For example, you could store the event information, respond and then continue with your tasks.
Depending on the server and language you are using, there are various mechanisms for achieving this, including flushing() the output in PHP or using a message queue and background tasks in other languages.
Supported Event types
See the Events API for a list of supported event types.
Managing Webhooks
You can create and manage webhooks in two ways:
- By logging into your Beyonic account via the web browser as described below
- By using the Webhooks API described below
Managing Webhooks from the web browser
To manage webhooks using the web browser: 1. Log into your account. 2. Go “Home” > “Company Settings” > “Advanced Settings” > “Notification Endpoints”.
Managing Webhooks from the API
You can use the Webhooks API described below to update or delete your callback URLs programatically.
Required permissions
To manage webhooks, either with the API or the web browser, you must have “Manage Users and Organization Settings” permissions for your organization.
The Webhook object
Sample Webhook Object (JSON):
{
"id": 53,
"created": "2015-08-01T16:56:29Z",
"updated": "2015-08-01T16:56:29Z",
"event": "payment.status.changed",
"target": "https://my.callback.url/",
"user": 42
}
| Field | Type | Description |
|---|---|---|
| id | long integer | Unique object identifier |
| user | long integer | The ID of the user who created the webhook |
| event | string | The webhook event. See the supported events section |
| created | string | The date that the webhook was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ” |
| updated | string | The date that the webhook was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ” |
| target | string | The URL that triggered events will be sent to |
Notification body format
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"hook": {
"id": 53,
"created": "2015-08-01T16:56:29Z",
"updated": "2015-08-01T16:56:29Z",
"event": "payment.status.changed",
"target": "https://my.callback.url/",
"user": 42
},
"data": {
"id": 2314,
"organization": 1,
"amount": "30",
"currency": "BXC",
"payment_type": "money",
"metadata": {"id": 1234, "name": "Lucy"},
"description": "Per diem payment",
"phone_nos": ["+80000000001"],
"state": "completed",
"last_error": null,
"rejected_reason": null,
"rejected_by": null,
"rejected_time": null,
"cancelled_reason": null,
"cancelled_by": null,
"cancelled_time": null,
"created": "2014-11-22T20:57:04.017Z",
"author": 15,
"modified": "2014-11-22T20:57:04.018Z",
"updated_by": null,
"start_date": "2014-11-22T20:57:04.018Z"
}
}
When an event is triggered, a JSON post will be sent to the URL that subscribed to the webhook. The JSON post body will include the following information:
| Parameter | Description |
|---|---|
| hook | A JSON representation of a webhook object. See the see webhook section below. |
| data | A JSON representation of the object that triggered the event. This is different for each event. See the ‘Supported events’ section above. |
Creating a new webhook
Sample Request:
curl http://app.beyonic.com/api/webhooks -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d "payment.status.changed" \
-d target="https://my.callback.url/"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
hook = Beyonic::Webhook.create(
event: "payment.status.changed",
target: "https://my.callback.url/"
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$hook = Beyonic_Webhook::create(array(
"event" => "payment.status.changed",
"target" => "https://my.callback.url/"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
hook = beyonic.Webhook.create(event='payment.status.changed',
target='https://my.callback.url/'
)
package com.beyonic.examples.webhooks;
import org.json.JSONException;
import org.json.JSONObject;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
public class CreateWebhookExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
private static final String EVENT = "payment.status.changed";
private static final String TARGET = "https://my.callback.url/";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
conn.setRequestMethod("POST");
conn.setDoOutput(true);
conn.setDoInput(true);
JSONObject contact = createWebhookObject();
BufferedWriter out = new BufferedWriter(new OutputStreamWriter(conn.getOutputStream()));
out.write(contact.toString());
out.close();
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
int beyID = 0;
try {
if (conn.getResponseCode() == 201) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
JSONObject obj = new JSONObject(response);
beyID = obj.getInt("id");
System.out.println("ID of created Webhook: " + beyID);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
private static JSONObject createWebhookObject() throws JSONException {
JSONObject webhook = new JSONObject();
webhook.put("event",EVENT);
webhook.put("target",TARGET);
return webhook;
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"id": 53,
"created": "2015-08-01T16:56:29Z",
"updated": "2015-08-01T16:56:29Z",
"event": "payment.status.changed",
"target": "https://my.callback.url/",
"user": 42
}
To create a new webhook, make a POST to the endpoint above, with the attributes below.
| Parameter | Required | Type | Example | Notes |
|---|---|---|---|---|
| event | Yes | String | 'payment.status.changed’ | Must be a supported event |
| target | Yes | String | 'https://my.callback.url/“’ | Must be an https URL |
Responses
- If successful, a JSON representation of the new webhook object will be returned.
Retrieving a single webhook
Sample Request:
curl https://app.beyonic.com/api/webhooks/23 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
hook = Beyonic::Webhook.get(23)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$hook = Beyonic_Webhook::get(23);
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
hook = beyonic.Webhook.get(23)
package com.beyonic.examples.webhooks;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class SingleWebhookExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "/1");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"id": 23,
"created": "2015-08-01T16:56:29Z",
"updated": "2015-08-01T16:56:29Z",
"event": "payment.status.changed",
"target": "https://my.callback.url/",
"user": 42
}
To retrieve a single webhook object, provide the webhook id and a webhook object will be returned.
| Parameter | Required | Type | Example | Notes |
|---|---|---|---|---|
| id | Yes | Integer | 23 | The id of the webhook you want to retrieve |
Listing all webhooks
Sample Request:
curl https://app.beyonic.com/api/webhooks -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
hooks = Beyonic::Webhook.list
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$hooks = Beyonic_Webhook::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
hooks = beyonic.Webhook.list()
package com.beyonic.examples.webhooks;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class ListAllWebhooksExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"count": 4,
"next": "http://localhost:8000/api/webhooks?offset=10",
"previous": null,
"results": [
{
"id": 50,
"created": "2015-08-01T16:43:43Z",
"updated": "2015-08-01T17:05:38Z",
"event": "payment.status.changed",
"target": "https://mysite.com/callbacks/payment/saved/1",
"user": 42
},
{
"id": 52,
"created": "2015-08-01T16:43:43Z",
"updated": "2015-08-01T17:05:38Z",
"event": "payment.status.changed",
"target": "https://mysite.com/callbacks/payment/saved",
"user": 42
},
{
"id": 53,
"created": "2015-08-01T16:56:29Z",
"updated": "2015-08-01T16:56:29Z",
"event": "payment.status.changed",
"target": "https://my.callback.url/",
"user": 42
},
{
"id": 55,
"created": "2015-08-01T16:56:29Z",
"updated": "2015-08-01T16:56:29Z",
"event": "payment.status.changed",
"target": "https://google.com",
"user": 42
}
]
}
To retrieve a list of all webhooks, make a GET request to the webhooks endpoint. This will return a list of webhooks objects.
Updating a webhook
Sample Request:
ccurl http://app.beyonic.com/api/webhooks/1 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d event="payment.status.changed" \
-d target="https://my.callback.url/" \
-X PUT
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
hook = Beyonic::Webhook.get(1)
hook.target = 'https://my.callback.url/'
hook.save()
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$hook = Beyonic_Webhook::get(1);
$hook->target = 'https://my.callback.url/';
$hook->save();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
hook = beyonic.Webhook.get(1)
hook.target = 'https://my.callback.url/'
hook.save()
package com.beyonic.examples.webhooks;
import org.json.JSONException;
import org.json.JSONObject;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
public class UpdateWebhookExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
private static final String EVENT = "payment.status.changed";
private static final String TARGET = "https://my.callback.url/";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "/503");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
conn.setRequestMethod("PUT");
conn.setDoOutput(true);
conn.setDoInput(true);
BufferedWriter out = new BufferedWriter(new OutputStreamWriter(conn.getOutputStream()));
out.write(webhookObject().toString());
out.close();
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
private static JSONObject webhookObject() throws JSONException {
JSONObject webhook = new JSONObject();
webhook.put("event",EVENT);
webhook.put("target",TARGET);
return webhook;
}
}
Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:
{
"id": 1,
"created": "2015-08-01T16:56:29Z",
"updated": "2015-08-01T16:56:29Z",
"event": "payment.status.changed",
"target": "https://my.callback.url/",
"user": 42
}
To update a webhook, make a PUT request to the specific webhook’s endpoint, identified by its Id.
Deleting a webhook
Sample Request:
curl http://app.beyonic.com/api/webhooks/1 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" -X DELETE
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
Beyonic::Webhook.delete(1)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
Beyonic_Webhook::delete( 11 );
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
beyonic.Webhook.delete(11)
package com.beyonic.examples.webhooks;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class DeleteWebhookExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "/502");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
conn.setRequestMethod("DELETE");
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
} catch (Exception e) {
e.printStackTrace();
}
}
}
To delete a webhook, make a DELETE request to the specific webhook’s endpoint, identified by its Id.
Filtering webhooks
Sample Request:
curl https://app.beyonic.com/api/webhooks?user=1 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
hooks = Beyonic::Webhook.list(
user: 1
)
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$hooks = Beyonic_Webhook::getAll(array(
"user" => 1
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
hooks = beyonic.Webhook.list(user=1)
package com.beyonic.examples.webhooks;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class FilterWebhooksExample {
private static final String API_ENDPOINT = "https://app.beyonic.com/api/webhooks";
private static final String API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
private static final String CHARSET = "UTF-8";
public static void main(String[] args){
URL url = null;
try {
url = new URL(API_ENDPOINT + "?user=12");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Accept", "application/json");
conn.setRequestProperty("charset", CHARSET);
conn.setRequestProperty("Authorization", "Token " + API_KEY);
System.out.println(conn.getResponseCode() + " // " + conn.getResponseMessage());
try {
if (conn.getResponseCode() == 200) {
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String response = reader.readLine();
reader.close();
System.out.println(response);
}
} finally {
conn.disconnect();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
You can search or filter webhooks on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only.
- user - the ID of the user who created the webhook. Note that only users within your organization will be matched.
- event - the webhook event