`

Distributor API – API Developer Guide

for API

Version 1.0.3

Version: 1.0.3 Dated: 2024/08/11 Page: 1 of 13

Table of Contents
Version control........................................................................................................................................ 3
Related documents ................................................................................................................................. 3
1. Documentation location ................................................................................................................. 3
2. PayThem VVS System overview ...................................................................................................... 3
2.1. Security and encryption......................................................................................................... 3
2.3. Environments......................................................................................................................... 5
2.4. Environment endpoints ......................................................................................................... 5
2.5. Public & Private tokens.......................................................................................................... 5
2.6. Libraries and Examples .......................................................................................................... 6
3. API definition................................................................................................................................... 7
3.1. Outbound call headers .......................................................................................................... 7
3.2. Type handling ........................................................................................................................ 7
3.2.1. Dates & time ................................................................................................................. 7
3.2.2. Encoding........................................................................................................................ 7
3.3. Response handling................................................................................................................. 8
3.4. Available API functions .......................................................................................................... 9
3.5. API call definition ................................................................................................................. 10
3.5.1. Retailer top-up ................................................................................................................ 10
3.5.1.1. topup_listRetailers ...................................................................................................... 10
3.5.1.2. topup_Retailer ............................................................................................................ 12
4. UAT - User Acceptance Testing procedure ................................................................................... 13
5. Issuing of production credentials.................................................................................................. 13

Version: 1.0.3 Dated: 2024/08/11 Page: 2 of 13

Version control
Rev Changes Author Date
No:
1.0.0 Initial draft document developed and submitted for V Seabourne. 2024/06/24
review. R de Breyn
1.0.2 Wording / grammar correction. Removal of incorrect A Lamprecht 2024/06/25
elements. R de Breyn
1.0.3  Implement 24-hour load limit R de Breyn 2024/08/11
 Implement maximum limit per load

Related documents
No Document name Description
Business Process: Inbound API Describes the process for new, inbound
Integration integrations.

1. Documentation location
The API documentation is constantly updated as new requirements or features are added.

The only authorized location for this documentation is:

https://downloads.paythem.net/05_API_Libraries/

If you receive this documentation via email or other means, please immediately check the above link
to confirm you have received the latest.

Best practice is to check this location monthly.

If you are using one of our client repositories, best practice is to review the repo monthly.

2. PayThem VVS System overview

The PayThem VVS system is a JSON-based API service. It enables 3rd parties to consume web services
provided by PayThem via the VVS Platform.

3rd party clients can connect to PayThem’s Virtual Voucher System (VVS) to expand their current
offerings or build new applications via direct integration with PayThem.

2.1.Security and encryption

All communication with the VVS system has multiple layers of encryption, authentication and
verification. To secure all transactions, all communications are via a SSL secured URL and
must be used with the HTTP POST method (unless the documentation clearly specifies
otherwise).

When implementing the API:

 Clients must ensure, when communicating with the VVS system, that the PayThem SSL
certificate is valid.
 Only HTTP POST will be processed. GET / DELETE / PUT are ignored.

Version: 1.0.3 Dated: 2024/08/11 Page: 3 of 13

  VVS API supports the following encryption protocols:
o OpenSSL AES-CBC-256-OPENSSL
 PRODUCTION ONLY: For an extra layer of security, we require each API consuming client
to provide us with the public (internet) static IP address of the source server from which
API calls will be made. Any calls from any other IP addresses will be ignored and could
lead the account to be blocked and the IP address blacklisted. DDNS and DHCP IP
addresses will not be accepted.
 Each client takes full responsibility for the safeguarding of their encryption keys.
Production encryption keys will be shared in two parts, to separate client staff.
 Multiple API accounts can be created per client, each with their own encryption keys,
static IP addresses and authentication credentials. Each API account will use the
customer’s global account balance for purchases.
 HTTP compression is enabled on our servers and is preferred / recommended.

Version: 1.0.3 Dated: 2024/08/11 Page: 4 of 13

 2.2. General information
 Throughout this document, distributors are referred to as “client”.

2.3.Environments
PayThem provides two separate environments for client access.

Retailer IDs will differ between production and demo environments.

Environment Purpose
Demo  For testing connectivity between client system and VVS and testing
functionality of VVS.
 All information is like Production environment, but all transactions issued have
no monetary impact.
 Retailer IDs differ from production.
 A balance is loaded onto the accounts for testing.
 No static IP required.
Production  Production environment, all data is real-time and all transactions are real and
carry a monetary impact on the client.
 Client must provide a static, public IP address for additional security.
 Client to provide an estimated number of calls to be performed per hour.
 Client to provide a maximum number of top-ups they expect to do per day.
 Client to provide a maximum value per day that is allowed for top-up.

2.4.Environment endpoints
Environment URL Endpoint
Demo https://vvsdemo.paythem.net/API/49972/
Production https://vvs.paythem.net/API/49972/
When using one of our provided libraries, the library will receive a parameter that defines which
environment the current call will use.

2.5.Public & Private tokens

Each environment has its own, unique public key, private key, username and password
combinations.

It is crucial to note that the Demo environment’s information will not work on Production
environment and repeated posting with incorrect details will lead to the account being locked out
and the source IP blacklisted.

During an account’s API user creation process, PayThem will provide the client with:
 Public key – Passed unencrypted with each query, base64 encoded.
 Private key – used to encrypt JSON parameters before posting to API server.
 Username – encrypted into each post.

Version: 1.0.3 Dated: 2024/08/11 Page: 5 of 13

  Password – encrypted into each post.

IMPORTANT: It is the client’s responsibility to keep all public, private, username and password
details secure and hidden from end users and non-critical staff. If credentials are compromised
(knowingly or unknowingly) PayThem will not be held liable for any damages.

2.6.Libraries and Examples

PayThem provides libraries and example implementation for various languages.

Language Type git Repository

PHP 8.x Library https://bitbucket.org/paythem/inbound_distributor_api_client.git

Packagist:
https://packagist.org/packages/paythemnet/inbound_distributor_api_client

If a library or example is not available for your environment, please contact PayThem technical
support through your distributor representative.

Version: 1.0.3 Dated: 2024/08/11 Page: 6 of 13

3. API definition
Relates to the creation of a valid call to the PayThem API service.

3.1.Outbound call headers

 X-Public-Key:
PUBLIC_KEY as provided by PayThem.
 X-Hash:
HMAC Hash generated from the pre-encrypted, JSON encoded string using sha256 and the
PRIVATE_KEY as provided by PayThem.
 X-Sourceip:
Public, static IP of server or firewall

3.2.Type handling
3.2.1. Dates & time
o During VVS API posts, dates are converted from and to client’s time zone
automatically.
o IMPORTANT: be sure that your time zone is correctly set and that your server time is
not out from international atomic time by more than 29 seconds. Else, determine
and pass the time as needed to allow for proper usage.
o IMPORTANT: All dates passed from client to server and server to client will be in the
format “CCYY-MM-DD HH:MM:SS”.
o The client’s timestamp must be in “ccyy-mm-dd H:i:s” format and must be inserted
into each query to prevent replay attacks. Please ensure your time zone and time
is set correctly, preferably by a NTP service to minimize risk. A maximum of 30
second deviation from our servers will be tolerated before errors are raised.
 cc = century
 yy = year
 mm = month (zero, left padded)
 dd = day of month (zero, left padded)
o The client’s passed dates must be in “ccyy-mm-dd”.
 cc = century
 yy = year
 mm = month (zero, left padded)
 dd = day of month (zero, left padded)

3.2.2. Encoding
All content must be UTF-8.

Version: 1.0.3 Dated: 2024/08/11 Page: 7 of 13

 3.3.Response handling
If no response is returned, there could be a break in communications.

The response (once decoded / decrypted) will contain a JSON string containing the following fields:

 SERVER_TRANSACTION_ID
The log ID of the client call. This is used to error check with PayThem support in the event of
issues. All calls return a unique call ID.
 RESULT
0 = No error,
-1 = global error
else a code representing an error encountered.
 ERROR_DESCRIPTION
A human-legible error description, only populated if an error has occurred.
 CONTENT
A string (and optionally encrypted with base64 encoding, depending on call encryption
parameters) representing a JSON string, representing the result of the call made.
This field will contain the word “ERROR” (non-JSON-encoded) if an error has occurred with
the request.

A PayThem library will base64 decode, decrypt and return a JSON string which can be passed to a
JSON handler.

Version: 1.0.3 Dated: 2024/08/11 Page: 8 of 13

 3.4.Available API functions
API Function Description
topup_listRetailers List all retailers that are enabled for top-up, including
the maximum top-up amount.

Server-side configurations need to be completed by a

PayThem administrator to enable this feature. All
subsequent calls are dependent on this configuration.
topup_Retailer Top-up a selected retailer wallet with a value. The
maximum value is defined server side and returned with
listRetailers.
Unimplemented functions
topup_listTransactions Retrieve a list of top-up transactions within the date
range requested.
topup_generalStatus Returns the general status of all top-ups occurred
during the day.
topup_transactionStatusByID Returns the status of a top-up transaction for a specific
retailer, by server transaction ID.
topup_transactionStatusByReference Returns the status of a top-up transaction for a specific
retailer, by client reference.
topup_retailerStatus Returns the status (on daily transaction limits) for a
specific retailer.

Version: 1.0.3 Dated: 2024/08/11 Page: 9 of 13

 3.5.API call definition

3.5.1. Retailer top-up

3.5.1.1. topup_listRetailers
Description List all retailers that have been enabled for direct
top-up.
Parameters None
Returns Array
Response example array (
0 =>
array (
'ID' => 12449,
'NAME' => 'Retailer name in VVS (1)',
'OUTLETS_COUNT' => 2,
'PRICELIST_ID' => 102,
'SELL_MOBI' => false,
'SELL_WEB' => true,
'SELL_BULK' => false,
'SELL_API' => true,
'ADDRESS' => 'Not Defined',
'LOAD_LIMIT' => 100,
'MAX_DAILY_LOAD_LIMIT' => 1000,
'USED_DAILY_LIMIT' => 900,
'BALANCE' => 994725.17,
),
1 =>
array (
'ID' => 12459,
'NAME' => 'Retailer name in VVS (2)',
'OUTLETS_COUNT' => 2,
'PRICELIST_ID' => 320,
'SELL_MOBI' => false,
'SELL_WEB' => false,
'SELL_BULK' => false,
'SELL_API' => true,
'ADDRESS' => 'Not Defined',
'LOAD_LIMIT' => 1000,
'MAX_DAILY_LOAD_LIMIT' => 10000,
'USED_DAILY_LIMIT' => 900,
'BALANCE' => 100,
)
)
Response fields
ID VVS ID for the retailer
NAME Name of the retailer
OUTLETS_COUNT Number of outlets
PRICELIST_ID Pricelist retailer uses
SELL_MOBI Enable to sell via: Mobile
SELL_WEB Enable to sell via: Web
SELL_BULK Enable to sell via: Bulk

Version: 1.0.3 Dated: 2024/08/11 Page: 10 of 13

SELL_API Enable to sell via: API
ADDRESS Address of retailer
LOAD_LIMIT Limit for each load attempt
MAX_DAILY_LOAD_LIMIT Maximum amount that can be loaded in 24-hour
period.
USED_DAILY_LIMIT Limit used in current 24-hour period.
BALANCE Current balance of retailer

Version: 1.0.3 Dated: 2024/08/11 Page: 11 of 13

 3.5.1.2. topup_Retailer
Description Top-up a single retailer.
Parameters int retailerID
string reference
float amount
Returns Array
Response example array (
'RETAILER_BALANCE' => 153.01,
'RETAILER_REFERENCE' => 83945,
'VVS_REFERENCE' => 33278945,
'RETAILER_REMAINING_DAILY’=> 593.01
)
Response fields
RETAILER_BALANCE VVS balance for the retailer
RETAILER_REFERENCE Reference as supplied by the client
VVS_REFERENCE The VVS reference for the current transaction
RETAILER_REMAINING_DAILY Remaining amount limit available for current 24-
hour period topup.

Version: 1.0.3 Dated: 2024/08/11 Page: 12 of 13

4. UAT - User Acceptance Testing procedure
Before a client can be issued production credentials, an acceptance test by PayThem will be
conducted to assure that all required features have been integrated.

Minimum required calls to proceed to UAT phase:

 topup_listRetailers
 topup_topupRetailer

A minimum of 5 transactions must be completed for each.

For topup_topupRetailer, a sufficient number of transactions need to be completed to lead to the

daily limit error. The time period on demo is set to 10 minutes, instead of 24-hour period (for
production). This allows for shortened testing period for the topup calls.

Production credentials will only be issued once all these calls have been demonstrated successfully,
including error handling.

5. Issuing of production credentials

Once UAT is complete, only your designated Distributor administrator can request credentials.
Please contact them directly and they will submit the relevant tickets to the correct department.

Credentials will be shared in two parts:

 Public key / username – via email.

 Private key / password – any agreed, non-email communication method.

For production environment, a static IP address is required. No user will be created unless a static
IP is provided.

Version: 1.0.3 Dated: 2024/08/11 Page: 13 of 13