Collection Requests API
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 instructions 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 wrongs, 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:
https://api.beyonic.com/api/collectionrequests
The collection request object
Note
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,
"expiry_date": "2018-05-26 19:06:51.300273+00:00"
}
Parameters
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) |
account | long integer | The ID of the account to which a collection will be sent |
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, processing_started, instructions_sent, successful, failed, expired or reversed. New states may be added from time to time. |
error_message | string | This will contain an error description in case an error occurs |
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 |
start_date | string or null | Use this to schedule collection requests for a future date.Examples of valid values for this field include strings such as “tomorrow”, or %d/%m/%Y format e.g 09/06/2019 or %d/%m/%Y %H:%M:%S format e.g 09/06/2019 13:24:12.Please note that the start_date should be greater than the time of creating the request. |
retry_interval_minutes | integer or null | Used to retry a collection request after certain interval in minutes if a collection request isn’t yet handled or failed or expired.Note:: The retry is upto a maximum of five times and value for retry_interval_minutes cannot be less than 30. |
subscription_settings | JSON String or null | The subscriptions_settings option allows you to create recurring collection requests.A good example is when you want to bill someone monthly via mobile money. |
Creating a new Collection Request
To create a new collection request, make a POST to the endpoint above, with the attributes below.
Parameter (*required field) | Type | Description |
---|---|---|
phonenumber* | String | Must be in international format |
first_name | String | Subscriber first name. If omitted, the first name will be set to ‘Anonymous’ |
last_name | String | Subscriber last name. If omitted, the last name will be set to ‘Contact’ |
amount* | String, Integer or Decimal | Do not include thousands separators |
currency* | String | 3 letter ISO currency code. [TODO XB note] You must have a funded wallet in this currency. If your account for this currency has zero balance, your payment will fail. |
account | Integer | *Account is required to collect into a cross border account. |
reason | String | 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 | JSON String | Custom attributes to store with this object. See the Metadata section for more information. |
success_message | String (Max 140 characters) 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. | Message to be sent via SMS to the subscriber when they complete the request. ‘-Powered by Beyonic’ shall be appended to this message. |
send_instructions | Boolean | Indicates whether we should send payment instructions to the subscriber via SMS. Note, defaults to False, but we recommend setting to True for higher success rates. When True, we will send the value of "instructions" to the customer via SMS. [TODO] 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 (Max 140 characters) | 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 | Date String 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 | Defaults to “24 hours”. Specifies the date and time when this collection request will be marked as expired if no collection is received. |
start_date | Date String Examples of valid values for this field include strings such as “tomorrow”, or %d/%m/%Y format e.g 09/06/2019 or %d/%m/%Y %H:%M:%S format e.g 09/06/2019 13:24:12. | Use this to schedule collection requests for a future date. Please note that the start_date should be greater than the time of creating the request. |
retry_interval_minutes | Integer Note: The value cannot be less than 10. | Used to retry a collection request after a certain interval, in minutes, if a collection request isn’t yet successful, failed, or expired. |
max_attempts | Integer Defaults to 3. Max allowed value is 3 times. | Used to specify how many times a retry should be attempted. Set to 0 to disable these configurable retries. |
subscription_settings | JSON String | Enables setup of recurring collection requests. See the section about Creating recurring collection request. |
Sample Request
curl https://api.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
package com.beyonic.examples;
import com.beyonic.models.CollectionRequest;
Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
String response = null;
try{
HashMap<String, Object> crCreateData = new HashMap<>();
crCreateData.put("amount", "1200");
crCreateData.put("currency", "KES");
crCreateData.put("description", "Test Java Client");
crCreateData.put("phonenumber", "+254727447101");
response = new CollectionRequest().create(crCreateData, null);
System.out.println(response);
}
catch (BeyonicException e){
e.printStackTrace();
}
<?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
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
Sample Response
{
"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,
"expiry_date": "2018-05-26 19:06:51.300273+00:00"
}
Creating recurring Collection Request
To create a recurring collection request, use the options below in the subscription_settings field. The start_date and end_date are mandatory whereas weekdays, months, and frequency are optional. Recurring collection requests can only be created for local wallets/accounts.
This feature is not yet available to cross border wallets.
**Note: All timestamps are interpreted as UTC
Additional parameters for the subscription_settings field
Parameter (*required field) | Type | Description |
---|---|---|
start_date* | Date string | The start date of the subscription. The default value is the creation date of the collection request. The value must be in a future date and in the format ‘DD/MM/YYYY HH:MM:SS’. |
end_date* | Date string | The end date of the subscription. It must be greater than the start date and in the format ‘DD/MM/YYYY HH:MM:SS’. |
weekdays | String | Use this for the respective days of the week you want in the recurrence. Use commas to separate multiple values. |
months | String | Use this for the respective months of the year you want in the recurrence. Use commas to separate multiple values. |
frequency | String | Use commas to separate multiple values. Available frequency options include: yearly, monthly, weekly, daily, hourly, and minutely. |
Sample Request
The recurrence for this collection request is every week from 24th May 2019 until 24th June 2019
curl https://api.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
-d subscription_settings.start_date='24/05/2019 10:30:00'
-d subscription_settings.end_date='24/06/2019 10:30:00'
-d subscription_settings.frequency='weekly'
<?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,
"subscription_settings" => array("start_date"=>"24/05/2019 10:30:00","end_date"=>"24/06/2019 10:30:00","frequency"=>"weekly")
));
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,
subscription_settings = {
'start_date': '24/05/2019 10:30:00',
'end_date': '24/06/2019 10:30:00',
'frequency': 'weekly'}
)
print collection_request # Examine the returned object
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,
subscription_settings: {"start_date": "24/05/2019 10:30:00","end_date": "24/06/2019 10:30:00","frequency": "weekly"}
)
p collection_request # Examine the returned object
Sample Response
Retrieving a single Collection Request
To retrieve a single collection request, provide the collection request id and a collection request object will be returned.
Parameter (*required field) | Type | Description |
---|---|---|
id* | Integer | The id of the collection you want to retrieve |
Sample Request
Sample Request:
curl https://api.beyonic.com/api/collectionrequests/427737 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
{
Sample Request:
package com.beyonic.examples;
import com.beyonic.models.CollectionRequest;
Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
String response = null;
try{
response = new CollectionRequest().get(123);
System.out.println(response);
}
catch (BeyonicException e){
e.printStackTrace();
}
Sample Request:
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$collection_request = Beyonic_Collection_Request::get(427737);
print_r($collection_request); // Examine the returned object
?>
Sample Request:
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
collection_request = beyonic.CollectionRequest.get(427737)
print collection_request # Examine the returned object
Sample Request:
package com.beyonic.examples;
import com.beyonic.models.CollectionRequest;
Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
String response = null;
try{
response = new CollectionRequest().get(123);
System.out.println(response);
}
catch (BeyonicException e){
e.printStackTrace();
}
Sample Response
Returns the collection request object.
Listing all Collection Requests
To retrieve a list of all collections, make a GET request to the collections endpoint. This will return a list of collection request objects. See sample requests and responses below.
Sample Request
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");
$collection_requests = Beyonic_Collection_Request::getAll();
print_r($collection_requests); // Examine the returned objects
?>
package com.beyonic.examples;
import com.beyonic.models.CollectionRequest;
import com.beyonic.exceptions.BeyonicException;
Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
String response = null;
try{
// Pass any extra filter options and headers
response = new CollectionRequest().list(null, null);
System.out.println(response);
}
catch (BeyonicException e){
e.printStackTrace();
}
<?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
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
collection_requests = Beyonic::CollectionRequest.list
p collection_requests # Examine the returned objects
Sample Response
Returns a list of collection request objects.
{
"count": 31271,
"next": "https://api.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,
"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,
"expiry_date": "2018-05-26 14:56:55.917817+00:00"
}, ... ]
}
Filtering Collection Requests
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 phone number field is treated differently - see below).
Parameter | Type | Description |
---|---|---|
amount | decimal | The collection request amount |
currency | String | The currency code of the currency of the collection request |
collection | Integer | The ID of the collection that fulfilled or matched this collection request |
phone number | String | The phone number that the collection request was intended for. Note that the phone number will be matched in the 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 | String | The transaction id or transaction reference of the collection on the mobile network operator’s side |
created_after | Date string | Only return collection requests created after this date |
created_before | Date string | Only return collection requests created before this date |
modified_after | Date string | Only return collection requests modified after this date |
modified_before | Date string | Only return collection requests modified before this date |
status | String | Only return collection requests that have this status |
reason | String | Only return collection requests that have this reason text |
contact_first_name | String | Only return collection requests that have this first name in the contact. |
contact_last_name | String | Only return collection requests that have this last name in the contact. |
Sample Request
Sample Request
curl "https://api.beyonic.com/api/collectionrequests?phonenumber=%2B80000000001&amount=500" -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
Sample Request:
package com.beyonic.examples;
import com.beyonic.models.CollectionRequest;
import com.beyonic.exceptions.BeyonicException;
Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";
String response = null;
try{
HashMap<String, String> crFilter = new HashMap<>();
crFilter.put("amount", "155");
response = new CollectionRequest().filter(crFilter, null);
System.out.println(response);
}
catch (BeyonicException e){
e.printStackTrace();
}
Sample Request:
<?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
?>
Sample Request:
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
collection_requests = beyonic.CollectionRequest.list(phonenumber='+80000000001', amount=500)
print collection_requests # Examine the returned objects
Sample Request:
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'
collection_requests = Beyonic::CollectionRequest.list(
phonenumber: '+80000000001',
amount: 500
)
p collection_requests # Examine the returned objects
Sample Response
Returns a list of collection request objects.
Updated 10 days ago