Collection Requests API

Suggest Edits

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:

https://api.mfsafrica.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

FieldTypeDescription
idlong integerUnique object identifier
organizationlong integerThe ID of the organization that owns this collection request (This is usually your organization ID)
amountdecimalThe collection request amount
currencystringThe 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)
accountlong integerThe ID of the account to which a collection will be sent
phonenumberstringThe phone number that the collection request is intended for, in international format, starting with a +
contactobjectThe contact that has been matched to this request. See the “Contacts” section for more information.
reasonstring or nullInternal description or reason for this collection request
metadatahashAny custom metadata that was added to the collection request when it was created
createdstringThe date that the collection request was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
authorlong integerThe ID of the user who created the collection request
modifiedstringThe date that the collection request was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated_bystringThe ID of the user who last updated the collection request
collectionlong integer or nullThe ID of the collection that fulfilled the collection request, if any
success_messagestring or nullThe confirmation message delivered to the customer upon successful completion of this payment request
send_instructionsbooleanDefaults 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.
instructionsstring or nullAllows 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”)
statusstringThis is the status of the collection request. Possible values are: new, pending, successful, failed, expired, or reversed
error_messagestringThis will contain an error description in case an error occurs
expiry_datestring or nullDefaults 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_datestring or nullUse 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_minutesinteger or nullUsed 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_settingsJSON String or nullThe 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)TypeDescription
phonenumber*String
Ex. +80000000001		Must be in international format
first_nameString
Ex. Luke		Subscriber first name. If omitted, the first name will be set to ‘Anonymous’
last_nameString
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. [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.
accountInteger
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.
reasonString
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.
metadataJSON String
Ex. “{‘my_id’: ‘123ASDAsd123’}”		Custom attributes to store with this object. See the Metadata section for more information.
success_messageString (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_instructionsBoolean
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. [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.
instructionsString (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_dateDate 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_dateDate 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_minutesInteger
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_attemptsInteger
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_settingsJSON 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",
    "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)TypeDescription
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’.
weekdaysString
Ex. Monday, Tuesday		Use this for the respective days of the week you want in the recurrence. Use commas to separate multiple values.
monthsString
Ex. January, February		Use this for the respective months of the year you want in the recurrence. Use commas to separate multiple values.
frequencyString
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)TypeDescription
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",
        "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).

ParameterTypeDescription
amountdecimal
e.g. 2000		The collection request amount
currencyString
e.g. UGX		The currency code of the currency of the collection request
collectionInteger
Ex. 427737		The ID of the collection that fulfilled or matched this collection request
phone numberString
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_idString
Ex. ASDASDW12321312		The transaction id or transaction reference of the collection on the mobile network operator’s side
created_afterDate string
Ex. 2017-01-01 00:00		Only return collection requests created after this date
created_beforeDate string
Ex. 2017-01-01 00:00		Only return collection requests created before this date
modified_afterDate string
Ex 2020-01-01 00:00		Only return collection requests modified after this date
modified_beforeDate string
Ex. 2020-01-01 00:00		Only return collection requests modified before this date
statusString
Ex. new, pending, instructions_sent, successful, failed, expired, reversed)		Only return collection requests that have this status
reasonString
Ex. Transaction Fees		Only return collection requests that have this reason text
contact_first_nameString
Ex. Luke		Only return collection requests that have this first name in the contact.
contact_last_nameString
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 4 months ago