Documentation API Reference

Introduction

Effectuer les requêtes

ViralPAY's apis provide a Production endpoint and a Sandbox (Test) endpoint that will allow you to test your apps with all methods

Sandbox endpoint : api-sandbox.viralpay.cm

Protocol

The only allowed protocol is HTTPS

Http verbs

As per RESTful design patterns, ViralPAY API implements the following HTTP verbs

  1. GET  - Read resources
  2. POST - Create new resources
  3. PUT - Modify existing resources
  4. DELETE - Remove resources

 

Parameters

NameTypeRequiredPossible values Default Description
grant_type string true password password The OAuth2 grant type (only the password grant type is available)
client_id string true   CLIENT_ID The client ID we have sent to you.
client_secret string true   CLIENT_SECRET The client secret we have sent to you.
username string true   USERNAME The username we have sent to you.
password string true   PASSWORD The password we have sent to you.

 

Authentification

ViralPAY API works with multiple security layers. Below we describe how to configure your credentials to access the API.

To use our application, send us an email at customer@viralpay.cm, specifying the uses you want to make of our platform.

A sales representative will contact you to verify the details of your organization, and create an account for you to test and integrate our tools.

 

Versionnage

When you make a query, you have to specify which version of the API you want to use. The version is set in the URI like this:

https://api-sandbox.viralpay.cm/v{version}/function

So if you want to call the functionality "status" for the 1 version of the API you have to call:

https://api-sandbox.viralpay.cm/v1/status

 

HTTP Code et status

Code Reponse
200 OK
400 Bad Request
401 Unauthorized
404 Not Found
405 Not Allowed
408 Request Timeout
429 Too Many Request 500
451 Unavailable for legal reason
500
Internal Server Error

 

Limitation des requêtes

We are limiting the max allowed request you can made. See below the limitation rules:
By user or IP: Maximum 86.400 queries by day
By functionality: Maximum 200 queries in 1 minute
If you reach the rate limit, you will get a 429 HTTP status code.
Note that the rate limiting is not enabled in the sandbox environment.

 

Authentification

Jeton de sécurité

POST /v1/token HTTP/1.1
Host: api-sandbox.viralpay.cm
Authorization: Basic base64_encode(client_user+':'+client_secret)

 

Headers

Name Type Required Description
Authorization string true The string 'Basic' followed by base64_encode(client_user+':'+client_secret)

 

Response

Name Type Description
request_id
 integer The current API request ID
timestamp
 number Timestamp of the query
data
 object Data of the query
 - access_token
 string The generated access token
 - expires_in
 integer The token has a validitiy of XXXX seconds
 - token_type
 string We only use the Bearer token type

 

Parameters

NameTypeRequiredPossible values Default Description
client_user string true   CLIENT_USER The client user we have sent to you.
client_secret string true   CLIENT_SECRET The client secret we have sent to you.

 

All transactions carried out on viralpay.cm require a valid security token to identify and connect the customer to our APIS.
To receive the parameters in TEST or SANDBOX mode, make a request by contacting us at: customer@viralpay.cm

Once your integrations have been successfully completed, the production data will be sent to you by email for start of operation.

The parameters necessary for the developer are:
Client User: client_user.
Client Secret: client_secret.

 

Signature

Description here

 

Infos compte

Infos compte

GET /v1/infos HTTP/1.1
Host: api-sandbox.viralpay.cm
Authorization: Bearer YOUR_BEARER_TOKEN

 

Headers

Name Type Required Description
Authorization string true The string 'Bearer ' followed by the token you got by using POST /v1/token uri.

 

Response

Name Type Description
request_id integer The current API request ID
timestamp number Timestamp of the query
data object Data of the query
- business_name string The merchant name
- business_id string The merchant id
- quater string The merchant quater
- phone_number string The current phone number

 

Solde

Connaitre le solde de vos comptes par pays.

 

GET /v1/balance HTTP/1.1
Host: api-sandbox.viralpay.cm
Authorization: Bearer YOUR_BEARER_TOKEN

 

Headers

Name Type Required Description
Authorization string true The string 'Bearer ' followed by the token you got by using POST /v1/token uri.

 

Response

NameTypeDescription
request_idintegerThe current API request ID
timestampnumberTimestamp of the query
data Array Array of Data
- country_namestring 
- numberstring 
- servicestring 
- balancenumber 
- currencystring 
- country_codestring 

 

Transactions

Historique

POST /v1/history HTTP/1.1
Host: api-sandbox.viralpay.cm
Authorization: Bearer YOUR_BEARER_TOKEN

 

Headers

Name Type Required Description
Authorization string true The string 'Bearer ' followed by the token you got by using POST /v1/token uri.

 

Parameters

NameTypeRequiredPossible values Default Description
date_begin string false

Date de début
date_end string false  
Date fin
size number true  
Taille

 

Response

Name Type Description
request_id integer The current API request ID
timestamp number Timestamp of the query
data object Data of the query

 

Statut

GET /v1/status HTTP/1.1
Host: api-sandbox.viralpay.cm
Authorization: Bearer YOUR_BEARER_TOKEN

 

Headers

Name Type Required Description
Authorization string true The string 'Bearer ' followed by the token you got by using POST /v1/token uri.

 

Parameters

Name Type Required Possible values Default Description
transaction_id string true

The transaction ID
order_id string false

The Order  ID
reference_id string false

The Reference

 

Response

NameTypeDescription
request_idintegerThe current API request ID
timestampnumberTimestamp of the query
dataobjectData of the query
- transaction_id string  
- order_idstring 
- reference_idstring 
- countrystring 
- currencystring 
- amountnumber 
- lang string  
- operator string  
- fees number  
- taxes number  
- provider_id string  
-status string Failed, Pending or Success

 

Payements

Paiement

GET /v1/pay/payin HTTP/1.1
Host: api-sandbox.viralpay.cm
Authorization: Bearer YOUR_BEARER_TOKEN

 

Headers

Name Type Required Description
Authorization string true The string 'Bearer ' followed by the token you got by using POST /v1/token uri.

 

{
"operator":"wave",
"country":"sn",
"phone_number":"0757230420",
"currency":"XOF",
"order_id":"544s5dsd5ds{{$timestamp}}",
"reference_id":"{{$timestamp}}",
"amount":200,
"lang":"en",
"return_url" : "https://api-sandbox.viralpay.cm/callbacks",
"cancel_url" : "https://api-sandbox.viralpay.cm/callbacks",
"notify_url" : "https://api-sandbox.viralpay.cm/callbacks"
}

 

Parameters

NameTypeRequiredPossible values Default Description
operator string false

Operateur téléphonique
merchant_key string false  
Code Marchand
country string true  
Code du Pays (FR/CM)
number string true

Numéro destinataire de l'opération
amount string true  
The amount of the transaction
currencystring true  
La devise utilisée dans la transaction
order_id string false

Le numero d'ordre de la transaction
reference string true  
La référence de la transaction
lang string false

La langue de la transaction
return_url string false  
Le lien ou envoyer le résultat à fin de la transaction
cancel_url string false  
Le lien ou envoyer le résultat à l'échec de la transaction
notify_url string false  
Le lien ou envoyer les notifications à fin de la transaction

 

Response

NameTypeDescription
request_idintegerThe current API request ID
timestampnumberTimestamp of the query
dataobjectData of the query
- transaction_id string  
- order_idstring 
- reference_idstring 
- countrystring 
- currencystring 
- amountnumber 
- lang string  
- operator string  
- fees number  
- taxes number  
- provider_id string  
-status string Failed, Pending or Success

 

Transferts

Transfert

GET /v1/pay/payout HTTP/1.1
Host: api-sandbox.viralpay.cm
Authorization: Bearer YOUR_BEARER_TOKEN

 

Headers

Name Type Required Description
Authorization string true The string 'Bearer ' followed by the token you got by using POST /v1/token uri.

 

{
"operator":"wave",
"country":"sn",
"phone_number":"0757230420",
"currency":"XOF",
"order_id":"544s5dsd5ds{{$timestamp}}",
"reference_id":"{{$timestamp}}",
"amount":200,
"lang":"en",
"return_url" : "https://api-sandbox.viralpay.cm/callbacks",
"cancel_url" : "https://api-sandbox.viralpay.cm/callbacks",
"notify_url" : "https://api-sandbox.viralpay.cm/callbacks"
}

 

Parameters

NameTypeRequiredPossible values Default Description
operator string false

Operateur téléphonique
merchant_key string false  
Code Marchand
country string true  
Code du Pays (FR/CM)
number string true

Numéro destinataire de l'opération
amount string true  
The amount of the transaction
currencystring true  
La devise utilisée dans la transaction
order_id string false

Le numero d'ordre de la transaction
reference string true  
La référence de la transaction
lang string false

La langue de la transaction
return_url string false  
Le lien ou envoyer le résultat à fin de la transaction
cancel_url string false  
Le lien ou envoyer le résultat à l'échec de la transaction
notify_url string false  
Le lien ou envoyer les notifications à fin de la transaction

 

Response

Name Type Description
request_id integer The current API request ID
timestamp number Timestamp of the query
data object Data of the query
- transaction_id string The current transaction id
- status string Failed, Pending or Success
- reference string Reference of transaction
- phone string The recipient phone
- amount number Amount of transaction
- fees integer The current commission

 

Virements

Transfert bancaire

POST /v1/bank/transfer HTTP/1.1
Host: api-sandbox.viralpay.cm
Authorization: Bearer YOUR_BEARER_TOKEN

 

{
"account_bank": "044",
"account_number": "0690000040",
"amount": 5500,
"narration": "Akhlm Pstmn Trnsfr xx007",
"currency": "XOF",
"operator":"wave",
"country":"sn",
"order_id": "akhlm-pstmnpyt-rfxx007_PMCKDU_1",
"reference": "akhlm-pstmnpyt-rfxx007_PMCKDU_1",
"notif_url": "http://www.moi.cm/notification",
"debit_currency": "XAF"
}

 

Headers

Name Type Required Description
Authorization string true The string 'Bearer ' followed by the token you got by using POST /v1/token uri.

 

Parameters

NameTypeRequiredPossible values Default Description
operator string false

Operateur téléphonique
country string true  
Code du Pays (FR/CM)
account_number string true

Numéro destinataire de l'opération
account_bank string true      
amount number true  
The amount of the transaction
narration string true      
currencystring true  
La devise utilisée dans la transaction
debit_currency string true      
order_id string true

Le numero d'ordre de la transaction
reference string true  
La référence de la transaction
lang string false

La langue de la transaction
return_url string false  
Le lien ou envoyer le résultat à fin de la transaction
cancel_url string false  
Le lien ou envoyer le résultat à l'échec de la transaction
notify_url string false  
Le lien ou envoyer les notifications à fin de la transaction

 

Response

Name Type Description
request_id integer The current API request ID
timestamp number Timestamp of the query
data object Data of the query
- transaction_id string The current transaction id
- status string Failed, Pending or Success
- reference string Reference of transaction
- number string The recipient phone
- amount number Amount of transaction
- bank_account_number    
- bank_account_name    
- provider_id    
- sender_number    
- order_id string  
- country    
-currency    
- operator    
- taxes    
- fees integer The current commission

 

Notifications

Notification de paiement

POST /v1/callback HTTP/1.1
Host: api-sandbox.viralpay.cm
Authorization: Bearer YOUR_BEARER_TOKEN

 

Headers

Name Type Required Description
Authorization string true The string 'Bearer ' followed by the token you got by using POST /v1/token uri.

 

Parameters

Name Type Required Possible values Default Description
transaction_id string true

The transaction ID
order_id string false

The Order  ID

 

Response

Name Type Description
request_id integer The current API request ID
timestamp number Timestamp of the query
request_ip   The current API request IP
data object Data of the query
- status number Error sent by merchant
- message string