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 some information or sends some wrong information, 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
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",
"mfscode": "19637-42255",
"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: new, pending, successful, instructions_sent, processing_started, failed, expired, or reversed |
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 Ex. +80000000001 | Must be in international format |
first_name | String Ex. Luke | Subscriber first name. If omitted, the first name will be set to ‘Anonymous’ |
last_name | String Ex. Woods | Subscriber last name. If omitted, the last name will be set to ‘Contact’ |
amount* | String, Integer or Decimal Ex. 3000 | Do not include thousands separators |
currency* | String Ex. BXC Note: BXC is the Beyonic Test Currency code. See the “Testing” section for more information. See List currencies to get all available currencies. | 3 letter ISO currency code. ": { "h-0" You must have a funded wallet in this currency. If your account for this currency has zero balance, your payment will fail. |
account | Integer Ex. 1 | *Account is required to collect into a cross border account. ID of the wallet to deposit the collection into. If you have more than one account with the same currency, and you omit this parameter, then the oldest, active wallet will be used. |
reason | String Ex. Transaction Fees | 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 Ex. “{‘my_id’: ‘123ASDAsd123’}” | Custom attributes to store with this object. See the Metadata section for more information. |
success_message | String (Max 140 characters) Ex. “Thank you for your payment!” 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. If you leave this message out, a default message shall be sent by Beyonic. |
send_instructions | Boolean Ex. False | 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. "5-0": 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) Ex. “Use #1234 as the reference” | 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 Ex. 24 hours 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 Ex. 01/08/2019 13:24:12 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 Ex. 40 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 Ex. 3 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. Note: The API also does automatic retries in some cases, that are not configurable. |
subscription_settings | JSON String Ex. “{‘start_date’: ‘24/05/2019 13:24:12’,‘end_date’: ‘24/06/2019 13:24:12’,‘frequency’: ‘weekly’}” | Enables setup of recurring collection requests. See the section about Creating recurring collection request. |
Sample Request
curl https://api.mfsafrica.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",
"mfscode": "19637-42255",
"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 Ex. 01/08/2019 13:24:12 | 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 Ex. 01/08/2019 13:24:12 | 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 Ex. Monday, Tuesday | Use this for the respective days of the week you want in the recurrence. Use commas to separate multiple values. |
months | String Ex. January, February | Use this for the respective months of the year you want in the recurrence. Use commas to separate multiple values. |
frequency | String Ex. yearly | 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.mfsafrica.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 Ex. 427737 | The id of the collection you want to retrieve |
Sample Request
Sample Request:
curl https://api.mfsafrica.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.mfsafrica.com/api/collectionrequests?limit=10&offset=10",
"previous": null,
"results": [{
"id": 427737,
"organization": 4,
"amount": "3000.0000",
"currency": "BXC",
"mfscode": "19637-42455",
"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",
"mfscode": "19617-42255",
"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 e.g. 2000 | The collection request amount |
currency | String e.g. UGX | The currency code of the currency of the collection request |
collection | Integer Ex. 427737 | The ID of the collection that fulfilled or matched this collection request |
phone number | String Ex. +80000000001 | 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 Ex. ASDASDW12321312 | The transaction id or transaction reference of the collection on the mobile network operator’s side |
created_after | Date string Ex. 2017-01-01 00:00 | Only return collection requests created after this date |
created_before | Date string Ex. 2017-01-01 00:00 | Only return collection requests created before this date |
modified_after | Date string Ex 2020-01-01 00:00 | Only return collection requests modified after this date |
modified_before | Date string Ex. 2020-01-01 00:00 | Only return collection requests modified before this date |
status | String Ex. new, pending, successful, instructions_sent, processing_started, failed, expired, or reversed | Only return collection requests that have this status |
reason | String Ex. Transaction Fees | Only return collection requests that have this reason text |
contact_first_name | String Ex. Luke | Only return collection requests that have this first name in the contact. |
contact_last_name | String Ex. Woods | Only return collection requests that have this last name in the contact. |
Sample Request
Sample Request
curl "https://api.mfsafrica.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 about 1 month ago