NAV
Python Ruby PHP Go Perl

Overview

Introduction

Welcome to the Merchant Payment API reference.

This API serves as the primary gateway to:

The Merchant Payment API is organized according to REST principles and provides the following functionalities:

Environments

This API is available in 2 environments: production and pre-production, reachable via IPSec VPN or HTTPS.

Specific details relating to the endpoints will be provided upon account creation.

Versioning

Endpoints of the API are prefixed with a corresponding version number.

This is done to provide complete isolation between implementations and to ensure that subsequent changes to the API will never affect existing integrations.

Payment states

payment states

While processing a given payment, the payment undergoes various status changes as illustrated.

Conditions marked as “Upon request to customer care team” pertains to reversal and/or cancellation, which must be requested through and performed by Thunes’ customer care team.

As changes in payment status occur, updates will be sent in real-time when a callback URL is provided. In conjunction, payment status can be queried through one of two means: via the returned id or a provided external_id.

The latter serves as a unique reference in the perspective of the partner and functions to retrieve payment details when exceptions occur, such as when the supposed response was not received, as an example.

Example Flow

payment flow

As soon as a payment is confirmed, the payment order will be sent to the provider for processing.

During this time, the merchant will receive a CONFIRMED status for the payment.

Callback

POST /callback HTTP/1.1
Date: Wed, 05 Jul 2017 06:57:03 GMT
Content-Type: application/json
X-TransferTo-Apikey: 00000000-0000-0000-0000-000000000000
X-TransferTo-Nonce: 1478078334
X-TransferTo-Hmac: s4lVIrFthY9kdJ+Z2zb2N9rEEoMcDVIc895azJ+0hqY=
{
    "id": 2,
    "status": "50000",
    "status_message": "SUBMITTED",
    "status_class": "5",
    "status_class_message": "SUBMITTED",
    "external_id": "34600001",
    "external_code": null,
    "creation_date": "2017-07-05T06:56:58Z",
    "expiration_date": "2017-07-06T03:57:12Z",
    "debit_party_identifier": {
        "msisdn": "233265456000"
    },
    "details": {
        "qr_code": null,
        "qr_url": null,
        "instructions": null,
        "merchant_id": null,
        "invoice_id": null,
        "redirect_url": null,
        "amount": null,
        "currency": null
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "consumer": {
        "lastname": "Rimbaud",
        "lastname2": "",
        "middlename": "",
        "firstname": "Arthur",
        "nativename": "",
        "nationality_country_iso_code": "SGP",
        "code": null,
        "date_of_birth": "1854-08-20",
        "country_of_birth_iso_code": "FRA",
        "gender": "MALE",
        "address": null,
        "postal_code": null,
        "city": null,
        "country_iso_code": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "msisdn": "233265456000",
        "email": null,
        "id_type": null,
        "id_country_iso_code": null,
        "id_number": null,
        "id_delivery_date": null,
        "id_expiration_date": null,
        "occupation": null,
        "province_state": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "source_of_funds": "SALARY"
    },
    "callback_url": "https://callback.sample-partner.com/payments",
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "wholesale_fx_rate": 108.350585110753,
    "fee": {
        "currency": "EUR",
        "amount": 1.8
    },
    "purpose_of_remittance": null,
    "additional_information_1": null,
    "additional_information_2": null,
    "additional_information_3": null,
    "payment_method_payment_reference": null,
    "payment_method_payment_code": null
}

As the payment is being processed, changes in status will be notified in realtime if a callback URL was provided.

This endpoint must be implemented by the partner, which should expect an HTTP POST request containing a payment object represented in JSON.

The same sets of credentials used to access the Merchant Payment API will be used in authenticating to the callback endpoint, via digest auth.

Upon sucessful receipt of data, the callback endpoint should respond with an HTTP 2XX. In the event that the Merchant Payment platform did not receive this response, callback notifications will be retried several times, beyond which, the payment status will have to be queried by the partner.

Topic

Authentication

Access to all endpoints of the API requires authentication, through one of the following means:

  1. HTTP Basic Auth
  2. Digest Auth (HMAC)

Basic Auth

curl https://api-mp.thunes.com/ping \
  -u "${API_KEY}:${API_SECRET}"
URL Part Value
user-ID API key
password API secret

Your API keys and secrets represent your identity and authorization. Please keep and store them securely!

API credentials should not be shared or stored in clear text. Once in your possession, it is on you to keep those credentials safe.

Avoid storing your credentials in your source code, or in your version control system, like github for instance. Instead, you can use environment variables to pass secrets into your application, following the 12 factor app principles, use a vault mechanism (HashiCorp Vault, AWS Secret Manager, Secret in Kubernetes, …), or provide them through a configuration file excluded from your version control, provisioned automatically within your deployment process, only readable by the application.

Digest Auth

apikey = "XXX"
apisecret = "YYY"
url = "ZZZ"

nonce = int(time.time())
date = email.utils.formatdate(usegmt = True)

message = bytes(apikey + str(nonce) + date).encode('utf-8')
secret = bytes(apisecret).encode('utf-8')
hmac = base64.b64encode(hmac.new(secret, message, digestmod = hashlib.sha256).digest())

response = requests.get(url, headers = {
    'X-TransferTo-apikey': apikey,
    'X-TransferTo-nonce': nonce,
    'X-TransferTo-hmac': hmac,
    'Date': date
})
apikey = 'XXX'
apisecret = 'YYY'
url = 'ZZZ'

nonce = Time.now.strftime('%s').to_s
date = Time.now.httpdate

def sign(key, base_string)
  digest = OpenSSL::Digest::SHA256.new
  hmac = OpenSSL::HMAC.digest(digest, key, base_string)
  hmac64 = Base64.encode64(hmac).chomp.gsub(/\n/, '')
  return hmac64
end

hmac = sign(apisecret, apikey + nonce + date)

req = Net::HTTP::Get.new(url)
req['X-TransferTo-apikey'] = apikey
req['X-TransferTo-nonce'] = nonce
req['X-TransferTo-hmac'] = hmac
req['Date'] = date

http = Net::HTTP.start(url.hostname, url.port, :use_ssl => true)
response = http.request(req)
<?php
$api_key = 'XXX';
$api_secret = 'YYY';
$url = 'ZZZ';

$nonce = time();
$date = gmdate('D, d M Y H:i:s T');

$hmac = base64_encode(hash_hmac('sha256', $api_key.$nonce.$date, $api_secret, true ));

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "X-TransferTo-apikey: $api_key",
    "X-TransferTo-nonce: $nonce",
    "X-TransferTo-hmac: $hmac",
    "Date: $date"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
var apikey string = "XXX"
var secret string = "YYY"
var url string = "ZZZ"

var date string = time.Now().Format(time.RFC1123)
var nonce string = strconv.FormatInt(time.Now().Unix(), 10)

func main() {
    digest := hmac.New(sha256.New, []byte(secret))
    digest.Write([]byte(apikey + nonce + date))
    hmac := base64.StdEncoding.EncodeToString(digest.Sum(nil))

    request, err := http.NewRequest("GET", url, nil)
    request.Header.Add("X-TransferTo-apikey", apikey)
    request.Header.Add("X-TransferTo-nonce", nonce)
    request.Header.Add("X-TransferTo-hmac", hmac)
    request.Header.Add("Date", date)

    client := &http.Client{}

    response, err := client.Do(request)
}
my $api_key = 'XXX';
my $api_secret = 'YYY';
my $url = 'ZZZ';

my $nonce = time();
my $date = HTTP::Date::time2str();

my $hmac = hmac_sha256_base64($api_key, $nonce, $date, $api_secret);
$hmac .= '=' while length($hmac) % 4;

my $client = REST::Client->new;
$client->addHeader('X-TransferTo-apikey', $api_key);
$client->addHeader('X-TransferTo-nonce', $nonce);
$client->addHeader('X-TransferTo-hmac', $hmac);
$client->addHeader('Date', $date);

my $response = $client->get($url);
Header Field Description
X-TransferTo-apikey API key
X-TransferTo-nonce Unique value per request (max 64 chars)
X-TransferTo-hmac HMAC-SHA-256 (Base64 Encoded)
Date Current date in HTTP format

Errors

HTTP Response

HTTP/1.1 401 Unauthorized
{
    "errors": [
        {
            "code": "1000401",
            "message": "Unauthorized"
        }
    ]
}

Thunes uses standard HTTP response codes to indicate whether an API request is successful or not.

Status Description
200 OK
400 Bad Request:
Request was malformed
401 Unauthorized:
Credentials missing or invalid
404 Not Found:
Resource doesn’t exist
500 Server Error:
Error occurred on Thunes

Details will always be contained within the HTTP body.

API Error Codes

Code Description
1000401 Unauthorized
1000404 Resource not found
1000999 Invalid parameter
1003001 Payment method is inactive in your account
1003002 Invalid payment method
1003007 Payment method is currently unavailable
1003008 Collection amount is invalid
1003009 Parameter page is outside of the page range
1003010 Payment amount below minimum of the selected payment method
1003011 Payment amount over maximum of the selected payment method
1005001 Account is invalid
1005002 Account not found
1007001 External ID has already been used
1007002 Payment has already been confirmed
1007003 Payment can not be confirmed
1007004 Payment can no longer be confirmed, quotation has expired
1007100 Method is not supported for this payment method
1007101 Method is currently unavailable
1008002 Quotation not found
1008003 Quotation has expired
1008004 Payment not found
1009001 Unexpected error, please contact our support team

Pagination

GET /{resource}?page=1&per_page=50 HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1

API resources supporting bulk fetches via “list” API methods will be returned in a paginated fashion.

Input Parameters

Field Required Type Description
page No Integer Page number
per_page No Integer Number of results per page (default 50, max 100)

Output Headers

Field Description
X-Total Total number of records
X-Total-Pages Total number of pages
X-Per-Page Number of records per page
X-Page Current page number
X-Next-Page Next page number (if any)
X-Prev-Page Previous page number (if any)

Endpoints

Connectivity

Ping

GET /ping HTTP/1.1
200 OK
{
   "status": "up"
}

GET /ping

Query API status.

Output

Field Type Description
status String API status

Expected value of status should be “up”.

Discovery

Countries

GET /v1/merchant-payment/countries HTTP/1.1
X-Total: 2
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1
200 OK
[
    {
        "iso_code": "KEN",
        "name": "Kenya"
    },
    {
        "iso_code": "ZWE",
        "name": "Zimbabwe"
    }
]

GET /v1/merchant-payment/countries

Retrieve list of countries for all payment methods that are available for a given account.

Output

Array of country objects in a paginated fashion.

Payment Methods

GET /v1/merchant-payment/payment-methods HTTP/1.1
X-Total: 2
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1
200 OK
[
    {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    {
        "id": 2,
        "name": "Push Payment 2",
        "description": "Push payment method 2",
        "country_iso_code": "ZWE",
        "currency": "USD",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 10,
        "maximum_payment_amount": 5000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "msisdn"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "msisdn"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    }
]

GET /v1/merchant-payment/payment-methods

Retrieve information for all payment methods available for a given account, optionally filtered based on specified parameters.

Input

Field Required Type Description
page No Integer Page number
per_page No Integer Number of results per page 50, max 100)
country_iso_code No String Country code in ISO 3166-1 alpha-3 format
currency No String Currency in ISO 4217 format

Output

Array of payment method objects in a paginated fashion.

GET /v1/merchant-payment/payment-methods/2 HTTP/1.1
200 OK
{
    "id": 2,
    "name": "Push Payment 2",
    "description": "Push payment method 2",
    "country_iso_code": "ZWE",
    "currency": "USD",
    "precision": 2,
    "increment": 0.01,
    "minimum_payment_amount": 10,
    "maximum_payment_amount": 5000,
    "debit_party_identifiers_accepted": [
        [
            "msisdn"
        ]
    ],
    "debit_party_information": {
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ]
    },
    "debit_party_verification": {
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "required_consumer_fields": [
            [
                "id_type",
                "id_number"
            ]
        ]
    },
    "payment_details_fields": [
        "qr_code",
        "qr_url"
    ],
    "required_consumer_fields": [
        [
            "lastname"
        ]
    ]
}

GET /v1/merchant-payment/payment-methods/{id}

Retrieve information for a given payment method.

Output

Payment method object.

Account

Balances

GET /v1/merchant-payment/balances HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1
200 OK
[
    {
        "id": 1,
        "currency": "USD",
        "balance": 0,
        "available_balance": 0
    }
]

GET /v1/merchant-payment/balances

Retrieve information for all account balances per currency.

Input

Field Required Type Description
page No Integer Page number
per_page No Integer Number of results per page 50, max 100)

Output

Array of balance objects.

Debit Parties

Information

POST /v1/merchant-payment/payment-methods/1/debit-party-information HTTP/1.1
200 OK
{
    "debit_party_identifier": {
        "msisdn": "133265456100"
    }
}
{
    "id": 2,
    "consumer": {
        "lastname": "Doe",
        "lastname2": null,
        "middlename": null,
        "firstname": "John",
        "nativename": null,
        "nationality_country_iso_code": null,
        "code": null,
        "date_of_birth": "1980-08-21",
        "country_of_birth_iso_code": null,
        "gender": null,
        "address": null,
        "postal_code": null,
        "city": null,
        "country_iso_code": null,
        "msisdn": null,
        "email": null,
        "id_type": null,
        "id_country_iso_code": null,
        "id_number": null,
        "id_delivery_date": null,
        "id_expiration_date": null,
        "occupation": null,
        "province_state": null,
        "bank_account_holder_name": null,
        "source_of_funds": null
    }
}

POST /v1/merchant-payment/payment-methods/{id}/debit-party-information

Retrieve consumer information based on account details under a given payment method.

Input

Field Required Type Description
debit_party_identifier Yes Object Debit party identifier information

Output

Field Type Description
id Number Debit party information ID
consumer Object Consumer information

Verification

POST /v1/merchant-payment/payment-methods/3/debit-party-verification HTTP/1.1
200 OK
{
    "debit_party_identifier": {
        "msisdn": "123456789100"
    },
    "consumer": {
        "lastname": "Ali",
        "firstname": "Muhammad"
    }
}
{
    "id": 1,
    "account_status": "AVAILABLE"
}

POST /v1/merchant-payment/payment-methods/{id}/debit-party-verification

Validate consumer information under a given payment method.

Input

Field Required Type Description
debit_party_identifier Yes Object Debit party identifier information
consumer Yes Object Consumer information

Output

Field Type Description
id Number Debit party information ID
account_status String Account status

Payments

Quotations

POST /v1/merchant-payment/quotations HTTP/1.1
201 Created
{
    "external_id": "9481184321458",
    "payment_method_id": 2,
    "mode": "PAYMENT_AMOUNT",
    "payment": {
      "amount": 100,
      "currency": "EUR",
      "country_iso_code": "FRA"
    },
    "collection": {
      "amount": null,
      "currency": "KES"
    }
}
{
    "id": 3,
    "external_id": "9481184321458",
    "mode": "PAYMENT_AMOUNT",
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "fee": {
        "amount": 1.8,
        "currency": "EUR"
    },
    "wholesale_fx_rate": 108.350585110753,
    "creation_date": "2017-07-05T03:57:12Z",
    "expiration_date": "2017-07-06T03:57:12Z"
}

POST /v1/merchant-payment/quotations

Creates a new quotation for a given payment or collection amount.

Input

Field Required Type Description
external_id Yes String External reference ID
payment_method_id Yes Integer Payment method ID
mode Yes String Quotation mode
payment Yes† Object Payment Amount
collection Yes† Object Collection Amount

†: Requiredness will depend on the chosen mode

Output

Quotation object.

GET /v1/merchant-payment/quotations/3 HTTP/1.1
200 OK
{
    "id": 3,
    "external_id": "9481184321458",
    "mode": "PAYMENT_AMOUNT",
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "fee": {
        "amount": 1.8,
        "currency": "EUR"
    },
    "wholesale_fx_rate": 108.350585110753,
    "creation_date": "2017-07-05T03:57:12Z",
    "expiration_date": "2017-07-06T03:57:12Z"
}

GET /v1/merchant-payment/quotations/{id}

Retrieve information for a given quotation.

Output

Quotation object.

GET /v1/merchant-payment/quotations/ext-9481184321458 HTTP/1.1
200 OK
{
    "id": 3,
    "external_id": "9481184321458",
    "mode": "PAYMENT_AMOUNT",
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "fee": {
        "amount": 1.8,
        "currency": "EUR"
    },
    "wholesale_fx_rate": 108.350585110753,
    "creation_date": "2017-07-05T03:57:12Z",
    "expiration_date": "2017-07-06T03:57:12Z"
}

GET /v1/merchant-payment/quotations/ext-{external_id}

Retrieve information for a given quotation through an external reference ID.

Output

Quotation object.

Payments

POST /v1/merchant-payment/quotations/3/payments HTTP/1.1
201 Created
{
    "debit_party_identifier": {
        "msisdn": "233265456000"
    },
    "consumer": {
        "lastname": "Rimbaud",
        "lastname2": "",
        "middlename": "",
        "firstname": "Arthur",
        "nativename": "",
        "nationality_country_iso_code": "SGP",
        "date_of_birth": "1854-08-20",
        "country_of_birth_iso_code": "FRA",
        "gender": "MALE",
        "msisdn": "233265456000",
        "bank_account_holder_name": "Arthur Rimbaud",
        "source_of_funds": "SALARY"
    },
    "external_id": "34600001",
    "callback_url": "https://callback.sample-partner.com/payments",
    "purpose_of_payment": "OTHER"
}
{
    "id": 2,
    "status": "10000",
    "status_message": "CREATED",
    "status_class": "1",
    "status_class_message": "CREATED",
    "external_id": "34600001",
    "external_code": null,
    "creation_date": "2017-07-05T06:56:58Z",
    "expiration_date": "2017-07-06T03:57:12Z",
    "debit_party_identifier": {
        "msisdn": "233265456000"
    },
    "details": {
        "qr_code": null,
        "qr_url": null,
        "instructions": null,
        "merchant_id": null,
        "invoice_id": null,
        "redirect_url": null,
        "amount": null,
        "currency": null
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "consumer": {
        "lastname": "Rimbaud",
        "lastname2": "",
        "middlename": "",
        "firstname": "Arthur",
        "nativename": "",
        "nationality_country_iso_code": "SGP",
        "code": null,
        "date_of_birth": "1854-08-20",
        "country_of_birth_iso_code": "FRA",
        "gender": "MALE",
        "address": null,
        "postal_code": null,
        "city": null,
        "country_iso_code": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "msisdn": "233265456000",
        "email": null,
        "id_type": null,
        "id_country_iso_code": null,
        "id_number": null,
        "id_delivery_date": null,
        "id_expiration_date": null,
        "occupation": null,
        "province_state": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "source_of_funds": "SALARY"
    },
    "callback_url": "https://callback.sample-partner.com/payments",
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "wholesale_fx_rate": 108.350585110753,
    "fee": {
        "currency": "EUR",
        "amount": 1.8
    },
    "purpose_of_remittance": null,
    "additional_information_1": null,
    "additional_information_2": null,
    "additional_information_3": null,
    "payment_method_payment_reference": null,
    "payment_method_payment_code": null
}

POST /v1/merchant-payment/quotations/{id}/payments

Create a new payment with details as specified from a given quotation.

Input

Field Required Type Description
debit_party_identifier Yes Object Debit party identifier
sender Yes Object Sender information
beneficiary Yes Object Beneficiary information
external_id Yes String External ID
external_code No String External reference code
callback_url No String Callback URL
purpose_of_remittance No String Purpose of the remittance
additional_information_1 No String Additional information
additional_information_2 No String Additional information
additional_information_3 No String Additional information

Output

Payment object.

POST /v1/merchant-payment/quotations/ext-9481184321458/payments HTTP/1.1
201 Created
{
    "debit_party_identifier": {
        "msisdn": "233265456000"
    },
    "consumer": {
        "lastname": "Rimbaud",
        "lastname2": "",
        "middlename": "",
        "firstname": "Arthur",
        "nativename": "",
        "nationality_country_iso_code": "SGP",
        "date_of_birth": "1854-08-20",
        "country_of_birth_iso_code": "FRA",
        "gender": "MALE",
        "msisdn": "233265456000",
        "bank_account_holder_name": "Arthur Rimbaud",
        "source_of_funds": "SALARY"
    },
    "external_id": "34600001",
    "callback_url": "https://callback.sample-partner.com/payments",
    "purpose_of_payment": "OTHER"
}
{
    "id": 2,
    "status": "10000",
    "status_message": "CREATED",
    "status_class": "1",
    "status_class_message": "CREATED",
    "external_id": "34600001",
    "external_code": null,
    "creation_date": "2017-07-05T06:56:58Z",
    "expiration_date": "2017-07-06T03:57:12Z",
    "debit_party_identifier": {
        "msisdn": "233265456000"
    },
    "details": {
        "qr_code": null,
        "qr_url": null,
        "instructions": null,
        "merchant_id": null,
        "invoice_id": null,
        "redirect_url": null,
        "amount": null,
        "currency": null
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "consumer": {
        "lastname": "Rimbaud",
        "lastname2": "",
        "middlename": "",
        "firstname": "Arthur",
        "nativename": "",
        "nationality_country_iso_code": "SGP",
        "code": null,
        "date_of_birth": "1854-08-20",
        "country_of_birth_iso_code": "FRA",
        "gender": "MALE",
        "address": null,
        "postal_code": null,
        "city": null,
        "country_iso_code": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "msisdn": "233265456000",
        "email": null,
        "id_type": null,
        "id_country_iso_code": null,
        "id_number": null,
        "id_delivery_date": null,
        "id_expiration_date": null,
        "occupation": null,
        "province_state": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "source_of_funds": "SALARY"
    },
    "callback_url": "https://callback.sample-partner.com/payments",
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "wholesale_fx_rate": 108.350585110753,
    "fee": {
        "currency": "EUR",
        "amount": 1.8
    },
    "purpose_of_remittance": null,
    "additional_information_1": null,
    "additional_information_2": null,
    "additional_information_3": null,
    "payment_method_payment_reference": null,
    "payment_method_payment_code": null
}

POST /v1/merchant-payment/quotations/ext-{external_id}/payments

Create a new payment with details as specified from a given quotation based on the external ID.

Input

Field Required Type Description
debit_party_identifier Yes Object Debit party identifier
sender Yes Object Sender information
beneficiary Yes Object Beneficiary information
external_id Yes String External ID
external_code No String External reference code
callback_url No String Callback URL
purpose_of_remittance No String Purpose of the remittance
additional_information_1 No String Additional information
additional_information_2 No String Additional information
additional_information_3 No String Additional information

Output

Payment object.

POST /v1/merchant-payment/payments/2/confirm HTTP/1.1
200 OK
{
    "id": 2,
    "status": "20000",
    "status_message": "CONFIRMED",
    "status_class": "2",
    "status_class_message": "CONFIRMED",
    "external_id": "34600001",
    "external_code": null,
    "creation_date": "2017-07-05T06:56:58Z",
    "expiration_date": "2017-07-06T03:57:12Z",
    "debit_party_identifier": {
        "msisdn": "233265456000"
    },
    "details": {
        "qr_code": null,
        "qr_url": null,
        "instructions": null,
        "merchant_id": null,
        "invoice_id": null,
        "redirect_url": null,
        "amount": null,
        "currency": null
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "consumer": {
        "lastname": "Rimbaud",
        "lastname2": "",
        "middlename": "",
        "firstname": "Arthur",
        "nativename": "",
        "nationality_country_iso_code": "SGP",
        "code": null,
        "date_of_birth": "1854-08-20",
        "country_of_birth_iso_code": "FRA",
        "gender": "MALE",
        "address": null,
        "postal_code": null,
        "city": null,
        "country_iso_code": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "msisdn": "233265456000",
        "email": null,
        "id_type": null,
        "id_country_iso_code": null,
        "id_number": null,
        "id_delivery_date": null,
        "id_expiration_date": null,
        "occupation": null,
        "province_state": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "source_of_funds": "SALARY"
    },
    "callback_url": "https://callback.sample-partner.com/payments",
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "wholesale_fx_rate": 108.350585110753,
    "fee": {
        "currency": "EUR",
        "amount": 1.8
    },
    "purpose_of_remittance": null,
    "additional_information_1": null,
    "additional_information_2": null,
    "additional_information_3": null,
    "payment_method_payment_reference": null,
    "payment_method_payment_code": null
}

POST /v1/merchant-payment/payments/{id}/confirm

Confirm a previously-created payment to initiate processing.

Output

Payment object.

POST /v1/merchant-payment/payments/ext-34600001/confirm HTTP/1.1
200 OK
{
    "id": 2,
    "status": "20000",
    "status_message": "CONFIRMED",
    "status_class": "2",
    "status_class_message": "CONFIRMED",
    "external_id": "34600001",
    "external_code": null,
    "creation_date": "2017-07-05T06:56:58Z",
    "expiration_date": "2017-07-06T03:57:12Z",
    "debit_party_identifier": {
        "msisdn": "233265456000"
    },
    "details": {
        "qr_code": null,
        "qr_url": null,
        "instructions": null,
        "merchant_id": null,
        "invoice_id": null,
        "redirect_url": null,
        "amount": null,
        "currency": null
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "consumer": {
        "lastname": "Rimbaud",
        "lastname2": "",
        "middlename": "",
        "firstname": "Arthur",
        "nativename": "",
        "nationality_country_iso_code": "SGP",
        "code": null,
        "date_of_birth": "1854-08-20",
        "country_of_birth_iso_code": "FRA",
        "gender": "MALE",
        "address": null,
        "postal_code": null,
        "city": null,
        "country_iso_code": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "msisdn": "233265456000",
        "email": null,
        "id_type": null,
        "id_country_iso_code": null,
        "id_number": null,
        "id_delivery_date": null,
        "id_expiration_date": null,
        "occupation": null,
        "province_state": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "source_of_funds": "SALARY"
    },
    "callback_url": "https://callback.sample-partner.com/payments",
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "wholesale_fx_rate": 108.350585110753,
    "fee": {
        "currency": "EUR",
        "amount": 1.8
    },
    "purpose_of_remittance": null,
    "additional_information_1": null,
    "additional_information_2": null,
    "additional_information_3": null,
    "payment_method_payment_reference": null,
    "payment_method_payment_code": null
}

POST /v1/merchant-payment/payments/ext-{external_id}/confirm

Confirm a previously-created payment, through an external ID, to initiate processing.

Output

Payment object.

GET /v1/merchant-payment/payments/2 HTTP/1.1
200 OK
{
    "id": 2,
    "status": "50000",
    "status_message": "SUBMITTED",
    "status_class": "5",
    "status_class_message": "SUBMITTED",
    "external_id": "34600001",
    "external_code": null,
    "creation_date": "2017-07-05T06:56:58Z",
    "expiration_date": "2017-07-06T03:57:12Z",
    "debit_party_identifier": {
        "msisdn": "233265456000"
    },
    "details": {
        "qr_code": null,
        "qr_url": null,
        "instructions": null,
        "merchant_id": null,
        "invoice_id": null,
        "redirect_url": null,
        "amount": null,
        "currency": null
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "consumer": {
        "lastname": "Rimbaud",
        "lastname2": "",
        "middlename": "",
        "firstname": "Arthur",
        "nativename": "",
        "nationality_country_iso_code": "SGP",
        "code": null,
        "date_of_birth": "1854-08-20",
        "country_of_birth_iso_code": "FRA",
        "gender": "MALE",
        "address": null,
        "postal_code": null,
        "city": null,
        "country_iso_code": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "msisdn": "233265456000",
        "email": null,
        "id_type": null,
        "id_country_iso_code": null,
        "id_number": null,
        "id_delivery_date": null,
        "id_expiration_date": null,
        "occupation": null,
        "province_state": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "source_of_funds": "SALARY"
    },
    "callback_url": "https://callback.sample-partner.com/payments",
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "wholesale_fx_rate": 108.350585110753,
    "fee": {
        "currency": "EUR",
        "amount": 1.8
    },
    "purpose_of_remittance": null,
    "additional_information_1": null,
    "additional_information_2": null,
    "additional_information_3": null,
    "payment_method_payment_reference": null,
    "payment_method_payment_code": null
}

GET /v1/merchant-payment/payments/{id}

Retrieve information for a given payment.

Output

Payment object.

GET /v1/merchant-payment/payments/ext-34600001 HTTP/1.1
200 OK
{
    "id": 2,
    "status": "50000",
    "status_message": "SUBMITTED",
    "status_class": "5",
    "status_class_message": "SUBMITTED",
    "external_id": "34600001",
    "external_code": null,
    "creation_date": "2017-07-05T06:56:58Z",
    "expiration_date": "2017-07-06T03:57:12Z",
    "debit_party_identifier": {
        "msisdn": "233265456000"
    },
    "details": {
        "qr_code": null,
        "qr_url": null,
        "instructions": null,
        "merchant_id": null,
        "invoice_id": null,
        "redirect_url": null,
        "amount": null,
        "currency": null
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "consumer": {
        "lastname": "Rimbaud",
        "lastname2": "",
        "middlename": "",
        "firstname": "Arthur",
        "nativename": "",
        "nationality_country_iso_code": "SGP",
        "code": null,
        "date_of_birth": "1854-08-20",
        "country_of_birth_iso_code": "FRA",
        "gender": "MALE",
        "address": null,
        "postal_code": null,
        "city": null,
        "country_iso_code": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "msisdn": "233265456000",
        "email": null,
        "id_type": null,
        "id_country_iso_code": null,
        "id_number": null,
        "id_delivery_date": null,
        "id_expiration_date": null,
        "occupation": null,
        "province_state": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "source_of_funds": "SALARY"
    },
    "callback_url": "https://callback.sample-partner.com/payments",
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "wholesale_fx_rate": 108.350585110753,
    "fee": {
        "currency": "EUR",
        "amount": 1.8
    },
    "purpose_of_remittance": null,
    "additional_information_1": null,
    "additional_information_2": null,
    "additional_information_3": null,
    "payment_method_payment_reference": null,
    "payment_method_payment_code": null
}

GET /v1/merchant-payment/payments/ext-{external_id}

Retrieve information for a given payment from an external ID.

Output

Payment object.

Resources

Resources

Designed around REST principles, data interchanged on various endpoints of the API are in terms of resources. These resources are expressed as objects in JSON.

Country

{
    "iso_code": "KEN",
    "name": "Kenya"
}

Represents the country information associated to a given payment method.

Field Type Description
iso_code String Country in ISO 3166-1 alpha-3 format
name String Country name

Payment Method

{
    "id": 1,
    "name": "Push Payment",
    "description": "Push payment method",
    "country_iso_code": "KEN",
    "currency": "KES",
    "precision": 2,
    "increment": 0.01,
    "minimum_payment_amount": 50,
    "maximum_payment_amount": 10000,
    "debit_party_identifiers_accepted": [
        [
            "msisdn"
        ]
    ],
    "debit_party_information": {
        "debit_party_identifiers_accepted": [
            [
                "bank_account_number"
            ]
        ]
    },
    "debit_party_verification": {
        "debit_party_identifiers_accepted": [
            [
                "bank_account_number"
            ]
        ],
        "required_consumer_fields": [
            [
                "id_type",
                "id_number"
            ]
        ]
    },
    "payment_details_fields": [
        "qr_code",
        "qr_url",
        "instructions"
    ],
    "required_consumer_fields": [
        [
            "lastname"
        ]
    ]
}

Represents the various payment methods enabled for a given account.

Field Type Description
id Integer Payment method ID
name String Payment method name
description String Payment method description
country_iso_code String Country in ISO 3166-1 alpha-3 format
currency String Currency in ISO 4217 format
precision Integer Number of digits after decimal point
increment Integer Unit of increment
minimum_payment_amount Number Minimum payment value
maximum_payment_amount Number Maximum payment value
debit_party_identifiers_accepted Array List of accepted debit party identifiers
debit_party_information Object Debit party information
debit_party_verification Object Debit party verification
payment_details_fields Array List of returned payment detail fields
required_consumer_fields Array List of required consumer fields

Payment Instruction

{
    "channel": "USSD",
    "steps": [
        "Dial *123*1#",
        "Enter Merchant ID: 123321",
        "Enter Invoice ID: 500054",
        "Enter Amount in KES: 710",
        "Confirm with your 4-digit PIN"
    ]
}

Represents instructions catered for the consumer to fulfill a payment.

Field Type Description
channel String Payment channel
steps Array Payment instruction steps

Payment Details

{
    "instructions": [
        {
            "channel": "USSD",
            "steps": [
                "Dial *123*1#",
                "Enter Merchant ID: 123321",
                "Enter Invoice ID: 500054",
                "Enter Amount in KES: 710",
                "Confirm with your 4-digit PIN"
            ]
        },
        {
            "channel": "SIM Toolkit",
            "steps": [
                "Go to your SIM Tool Kit Menu",
                "Enter Merchant ID: 123321",
                "Enter Invoice ID: 500054",
                "Enter Amount in KES: 710",
                "Confirm with your 4-digit PIN"
            ]
        }
    ],
    "qr_url": "https://qr.sample-provider.com/1234"
}

Represents the payment details for a given payment.

Field Type Description
qr_code String QR code
qr_url String QR code URL
instructions Array List of payment instruction objects
merchant_id String Merchant ID
invoice_id String Invoice ID
redirect_url String Redirect URL
amount Number Payment amount
currency String Currency in ISO 4217 format

Balance

{
    "id": 1,
    "currency": "EUR",
    "balance": 10000000,
    "available_balance": 10000000
}

Represents account balance for a given currency.

Field Type Description
id Integer Balance ID
currency String Currency in ISO 4217 format
balance Number Current balance
available_balance Number Available balance

Quotation

{
    "id": 3,
    "external_id": "9481184321458",
    "mode": "PAYMENT_AMOUNT",
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "fee": {
        "amount": 1.8,
        "currency": "EUR"
    },
    "wholesale_fx_rate": 108.350585110753,
    "creation_date": "2017-07-05T03:57:12Z",
    "expiration_date": "2017-07-06T03:57:12Z"
}

Represents quotation information used in creating a payment.

Field Type Description
id Integer Quotation ID
external_id String External reference ID
mode String Quotation mode
payment_method Object Payment method
payment Object Payment amount information
collection Object Collection amount information
collection_in_payment_currency Object Collection amount in payment currency
fee Object Fee information
wholesale_fx_rate Number Wholesale FX rate
creation_date String Creation date in HTTP format
expiration_date String Expiration date in HTTP format

Payment

{
    "id": 2,
    "status": "10000",
    "status_message": "CREATED",
    "status_class": "1",
    "status_class_message": "CREATED",
    "external_id": "34600001",
    "external_code": null,
    "creation_date": "2017-07-05T06:56:58Z",
    "expiration_date": "2017-07-06T03:57:12Z",
    "debit_party_identifier": {
        "msisdn": "233265456000"
    },
    "details": {
        "qr_code": null,
        "qr_url": null,
        "instructions": null,
        "merchant_id": null,
        "invoice_id": null,
        "redirect_url": null,
        "amount": null,
        "currency": null
    },
    "payment": {
        "country_iso_code": "FRA",
        "currency": "EUR",
        "amount": 1.5
    },
    "collection": {
        "currency": "KES",
        "amount": 162.53
    },
    "payment_method": {
        "id": 1,
        "name": "Push Payment",
        "description": "Push payment method",
        "country_iso_code": "KEN",
        "currency": "KES",
        "precision": 2,
        "increment": 0.01,
        "minimum_payment_amount": 50,
        "maximum_payment_amount": 10000,
        "debit_party_identifiers_accepted": [
            [
                "msisdn"
            ]
        ],
        "debit_party_information": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ]
        },
        "debit_party_verification": {
            "debit_party_identifiers_accepted": [
                [
                    "bank_account_number"
                ]
            ],
            "required_consumer_fields": [
                [
                    "id_type",
                    "id_number"
                ]
            ]
        },
        "payment_details_fields": [
            "qr_code",
            "qr_url",
            "instructions"
        ],
        "required_consumer_fields": [
            [
                "lastname"
            ]
        ]
    },
    "consumer": {
        "lastname": "Rimbaud",
        "lastname2": "",
        "middlename": "",
        "firstname": "Arthur",
        "nativename": "",
        "nationality_country_iso_code": "SGP",
        "code": null,
        "date_of_birth": "1854-08-20",
        "country_of_birth_iso_code": "FRA",
        "gender": "MALE",
        "address": null,
        "postal_code": null,
        "city": null,
        "country_iso_code": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "msisdn": "233265456000",
        "email": null,
        "id_type": null,
        "id_country_iso_code": null,
        "id_number": null,
        "id_delivery_date": null,
        "id_expiration_date": null,
        "occupation": null,
        "province_state": null,
        "bank_account_holder_name": "Arthur Rimbaud",
        "source_of_funds": "SALARY"
    },
    "callback_url": "https://callback.sample-partner.com/payments",
    "collection_in_payment_currency": {
        "currency": "EUR",
        "amount": 1.5
    },
    "wholesale_fx_rate": 108.350585110753,
    "fee": {
        "currency": "EUR",
        "amount": 1.8
    },
    "purpose_of_remittance": null,
    "additional_information_1": null,
    "additional_information_2": null,
    "additional_information_3": null,
    "payment_method_payment_reference": null,
    "payment_method_payment_code": null
}

Represents payment information for a payment request.

Field Type Description
id Integer Payment ID
status String Payment status code
status_message String Payment status description
status_class String Payment status class
status_class_message String Payment status class description
external_id String External ID
external_code String External reference code
creation_date String Creation date in HTTP format
expiration_date String Expiration date in HTTP format
debit_party_identifier Object Debit party identifier information
details Object Payment details
payment Object Payment amount information
collection Object Collection amount information
payment_method Object Payment method information
consumer Object Consumer information
callback_url String Callback URL
collection_in_payment_currency Object Collection amount information in payment currency
wholesale_fx_rate Number Wholesale FX rate
fee Object Fee information
purpose_of_payment String Purpose of payment
additional_information_1 String Additional information
additional_information_2 String Additional information
additional_information_3 String Additional information
payment_method_payment_reference String Payment method payment reference ID
payment_method_payment_code String Payment method payment code

Payment Amount

{
    "country_iso_code": "FRA",
    "currency": "EUR",
    "amount": 10
}

Represents payment amount details for a given payment.

Field Required Type Description
country_iso_code Yes String Country code in ISO 3166-1 alpha-3 format
currency Yes String Payment currency in ISO 4217 format
amount Yes† Number Payment amount

† : Required when chosen mode is PAYMENT_AMOUNT

Collection Amount

{
    "currency": "USD",
    "amount": 10
}

Represents collection amount details for a given payment.

Field Required Type Description
currency Yes String Collection currency in ISO 4217 format
amount Yes† Number Collection amount

†: Required when chosen mode is COLLECTION_AMOUNT

Fee

{
    "currency": "EUR",
    "amount": 1.50
}

Represents fee information for a given payment.

Field Type Description
currency String Fee amount currency in ISO 4217 format
amount Number Fee amount value

Debit Party Identifier

{
    "msisdn": "263775892100",
    "bank_account_number": "0123456789",
    "swift_bic_code": "ABCDEFGH"
}

Represents identification details for a given consumer.

Field Required Type Description
msisdn No† String MSISDN in international format
bank_account_number No† String Bank account number
iban No† String Bank account number in IBAN format
clabe No† String Bank account number in CLABE format
swift_bic_code No† String SWIFT-BIC code
bik_code No† String BIK code
ifs_code No† String IFSC code
sort_code No† String Sort code
aba_routing_number No† String ABA Routing Transfer Number
bsb_number No† String BSB number
branch_number No† String Branch number
routing_code No† String Routing code
account_type No† String Account type
account_number No† String Account number
card_number No† String Card number
email No† String Email address

†: Requiredness will depend on the payment method configuration

Consumer

{
    "lastname": "Rimbaud",
    "lastname2": "",
    "middlename": "",
    "firstname": "Arthur",
    "nativename": "",
    "nationality_country_iso_code": "SGP",
    "date_of_birth": "1854-08-20",
    "country_of_birth_iso_code": "FRA",
    "gender": "MALE",
    "msisdn": "233265456000",
    "bank_account_holder_name": "Arthur Rimbaud",
    "source_of_funds": "SALARY"
}

Represents consumer information for a given payment.

Field Required Type Description
lastname No† String Last name
lastname2 No† String Additional last name(s)
middlename No† String Middle name
firstname No† String First name
nativename No† String Full name in native characters
nationality_country_iso_code No† String Nationality in ISO 3166-1 alpha-3 format so_code
code No† String Consumer identification code
date_of_birth No† String Date of birth in ISO 8601 format
country_of_birth_iso_code No† String Country of birth in ISO 3166-1 alpha-3 format
gender No† String Gender
address No† String Address
postal_code No† String Postal code
city No† String City
country_iso_code No† String Address country in ISO 3166-1 alpha-3 format
msisdn No† String MSISDN in international format
email No† String Email address
id_type No† String Presented identification type
id_country_iso_code No† String ID country in ISO 3166-1 alpha-3 format
id_number No† String Presented identification number
id_delivery_date No† String ID delivery date in ISO 8601 format
id_expiration_date No† String ID expiration date in ISO 8601 format
occupation No† String Occupation
province_state No† String Address province/state
bank_account_holder_name No† String Bank account holder name
source_of_funds No† String Source of funds

†: Requiredness will depend on the payment method configuration

Enumerations

Enumerations

A number of resource fields will only accept a list of known values, as outlined in this section.

Quotation Mode

Mode Description
PAYMENT_AMOUNT Quotation created by specifying desired payment amount
COLLECTION_AMOUNT Quotation created by specifying desired collection amount

Account Type

Type Description
CHECKING Checking account
SAVINGS Savings account

Gender

Gender Description
MALE Male
FEMALE Female

Payment Status Class

Status Class Message
1 CREATED
2 CONFIRMED
3 REJECTED
4 CANCELLED
5 SUBMITTED
7 COMPLETED
8 REVERSED
9 DECLINED

Payment Status

Status Message
10000 CREATED
20000 CONFIRMED
30000 REJECTED
30115 REJECTED-SLS-CONSUMER
30250 REJECTED-INVALID-CONSUMER
30260 REJECTED-INVALID-CONSUMER-DETAILS
30306 REJECTED-LIMITATIONS-ON-PAYMENT-VALUE
30315 REJECTED-LIMITATIONS-ON-CONSUMER-VALUE
30330 REJECTED-LIMITATIONS-ON-ACCOUNT-VALUE
30355 REJECTED-LIMITATIONS-ON-CONSUMER-QUANTITY
30370 REJECTED-LIMITATIONS-ON-ACCOUNT-QUANTITY
30405 REJECTED-PAYMENT-METHOD-CURRENTLY-UNAVAILABLE
30500 REJECTED-INSUFFICIENT-BALANCE
40000 CANCELLED
50000 SUBMITTED
70000 COMPLETED
80000 REVERSED
90000 DECLINED
90115 DECLINED-SLS-CONSUMER
90250 DECLINED-INVALID-CONSUMER
90251 DECLINED-BARRED-CONSUMER
90260 DECLINED-INVALID-CONSUMER-DETAILS
90270 DECLINED-PAYMENT-TIME-LIMIT-REACHED
90271 DECLINED-PAYMENT-TIME-LIMIT-EXCEEDED
90272 DECLINED-COLLECTION-AMOUNT-MISMATCH
90273 DECLINED-INSUFFICIENT-BALANCE-CONSUMER-ACCOUNT
90306 DECLINED-LIMITATIONS-ON-PAYMENT-VALUE
90315 DECLINED-LIMITATIONS-ON-CONSUMER-VALUE
90330 DECLINED-LIMITATIONS-ON-ACCOUNT-VALUE
90355 DECLINED-LIMITATIONS-ON-CONSUMER-QUANTITY
90370 DECLINED-LIMITATIONS-ON-ACCOUNT-QUANTITY
90385 DECLINED-DUPLICATED-PAYMENT
90405 DECLINED-PAYMENT-METHOD-CURRENTLY-UNAVAILABLE

Account Status

Status Message
AVAILABLE Debit party account is available
UNAVAILABLE Debit party account is not available

Source of Funds

Source Description
CASH Cash
BUSINESS Business
GIFT Gift
SALARY Salary
LOTTERY Lottery
SAVINGS Savings
OTHER Others not listed

ID Type

Type Description
PASSPORT Passport
NATIONAL_ID National Identification Card
DRIVING_LICENSE Driving License
SOCIAL_SECURITY Social Security Card/Number
TAX_ID Tax Payer Identification Card/Number
SENIOR_CITIZEN_ID Senior Citizen Identification Card
BIRTH_CERTIFICATE Birth Certificate
VILLAGE_ELDER_ID Village Elder Identification Card
RESIDENT_CARD Permanent Residency Identification Card
ALIEN_REGISTRATION Alien Registration Certificate/Card
PAN_CARD PAN Card
VOTERS_ID Voter’s Identification Card
HEALTH_CARD Health Insurance Card/Number
EMPLOYER_ID Employer Identification Card
OTHER Others not listed

Purpose of Payment

Purpose Description
OTHER Other purposes