Manuel d'intégration de l'API viewPAY
- Accueil
- Intégration viewPAY
Documentation de l'API viewPAY
(Plateforme de paiements multi opérateur en ligne)
| Version | Date | Auteur | Description |
|---|---|---|---|
1.0 |
17-Juillet-2019 |
Lab2View S.A.R.L. |
Initial Draft |
Getting Started
Introduction
a) C’est quoi viewPAY ?viewPAY est une Fintech africaine créée en 2019. Nous accompagnons les entreprises dans leur croissance en les dotant de solutions de paiement et de transfert de monnaie électronique. Grâce à notre activité, nous ouvrons de nouvelles opportunités aux entrepreneurs d'Afrique francophone, permettons à des millions de personnes exclues des services bancaires de payer en ligne et contribuons ainsi à l'émergence d'une économie numérique à la fois forte et inclusive
b) Les ressources de viewPAY
Dites à vos clients que vous acceptez viewPAY.
Renforcez la confiance de vos acheteurs en téléchargeant les visuels et logos viewPAY. Tout ce
dont vous avez besoin est à votre disposition : logos viewPAY, moyens de paiement acceptés,
bannières ou encore logos viewPAY mobile. N'hésitez pas à les placer sur votre page d'accueil et
sur votre page de paiement.
| Code | Description |
|---|---|
| ORANGE_CMR | Orange Cameroun, pour les paiements /OM/ au Cameroun |
| MTN_CMR | MTN Cameroun, pour les paiements /MOMO/ au Cameroun |
| ORANGE_CIV | Orange Côte d’Ivoire, pour les paiements /OM/ en CIV |
| MTN_CIV | MTN Côte d’Ivoire, pour les paiements /MOMO/ en CIV |
| MOOV_CIV | MOOV Côte d’Ivoire, pour les paiements /MOOV Money/ en Côte d’Ivoire |
Paiement API viewPAY
L’intégration se fait en 03 étapes
Vous avez besoin d'un compte (disponible à l’adresse https://www.view-pay.com/register) et
d'un service actif sur viewPAY sinon, ouvrez un compte marchand et créez un nouveau service.
Une fois ce résultat obtenu, connectez-vous à votre backoffice pour générer votre Clé d’API et
votre nom de domaine afin de procéder à l'intégration.
Dans la mesure où les opérations monétaires peuvent se faire à intervalle de temps non synchrone, il faut des moyens de communications donnant la possibilité de changer l’état des opérations à votre niveau, élément que nous appelons callback.
| Callback | Informations |
|---|---|
| callback_success | URL de notification ou changement du statut des opérations valides. |
| callback_error | URL de notification ou changement du statut des opérations non valides. |
ATTENTION : Assurez-vous que le solde de votre portefeuille Mobile Money est positif, car vous devrez l'utiliser pendant l'intégration.
Méthodes
1. Cash In
Opération consistant à effectuer un dépôt dans les comptes ViewPay ce qui équivaut à un retrait dans le compte client.
Request| Method | URL |
|---|---|
| POST | https://www.view-pay.com/api/repo/cash/in |
| Type | Params | Values |
|---|---|---|
| HEAD | Accept |
application/json |
| HEAD | Content - type |
application/json |
| POST | operator_code |
string |
| POST | amount |
int |
| POST | token |
string |
| POST | number |
string |
| POST | client_reference |
string |
| POST | have_prefix |
boolean |
| POST | callback |
string |
Token : C’est la clé d’API qui a été générée dans votre interface utilisateur permet d’identifier de manière unique.
Amount : c’est le montant qui devra être dépose par le client dans le compte viewpay.
Operator_code : c’est le code de l’opérateur utilisé pour effectuer la transaction.
Number : C’est le numéro que le client doit fournir.
Client_reference : Référence de l’opération chez le marchand, afin qu’on puisse identifier une opération de façon unique pour ce marchand.
Have_prefix : Valeur booléenne obligatoire qui indique si le numéro de téléphone comme par le préfix du pays (237NUMERO) dans ce cadre mettre la valeur true sinon mettre la valeur false.
callback : Elément incontournable et obligatoire afin que le marchand puisse être notifier en cas de changement de statut de l’opération à son niveau. Lorsqu’une opération est initiée au niveau de l’API, elle prend un temps de traitement puis elle retourne un résultat au marchand via ce callback, qui est une adresse qu’on appelle par POST pour communiquer sur les changements.
Dans le tableau ci-après nous pouvons noter quelques exemples de réponse en cas de fonctionnement ou de disfonctionnement de l’API lors d’un appel.
| Status | Responses |
|---|---|
| 200 |
{
"message": "L'opération est en cours de traitement par un terminal.",
"code": "T200",
"data": {
"client_reference": "RTXL1V16X0PGJF87",
"reference": "RTXL1V16X0PGJF87",
"prefix": "237",
"number": "651830353",
"amount": "500",
"fees": "5",
"net_amount": "495",
"currency": "XAF",
"status": "PENDING",
"type_operation": "cashin",
"operator": "MTN Cameroun",
"created_at": "2019-07-18 07:16:42"
}
}
|
| 403 |
{"message":"API key is missing."}
|
| 400 | {
"message" : "Please provide username.",
"code" : "T600"
}
|
| 400 | {"error":"Please provide password."} |
| 401 | {"error":"Invalid API key."} |
| 401 | {"error":"Incorrect username or password."} |
| 422 |
{
"message": "The given data was invalid.",
"errors": {
"number": [
"The number field is required."
],
"amount": [
"The amount field is required."
]
}
}
|
| 500 | {"error":"Something went wrong. Please try again later."} |
2. Cash Out
Opération consistant à effectuer un retrait dans les comptes ViewPay, ce qui équivaut à un dépôt dans le compte client.
Request| Method | URL |
|---|---|
| POST | https://www.view-pay.com/api/repo/cash/out |
| Type | Params | Values |
|---|---|---|
| HEAD | Accept |
application/json |
| HEAD | Content - type |
application/json |
| POST | operator_code |
string |
| POST | amount |
int |
| POST | token |
string |
| POST | number |
string |
NB : Les différents paramètres de la requête de cette opération sont identiques aux paramètres de la requête de type CASH IN.
Dans le tableau ci-après nous pouvons noter quelques exemples de réponse en cas de fonctionnement ou de disfonctionnement de l’API lors d’un appel.
| Status | Responses |
|---|---|
| 200 |
{
"message": "L'opération est en cours de traitement par un terminal.",
"code": "T200",
"data": {
"client_reference": "RTXL1V16X0PGJF87",
"reference": "RTXL1V16X0PGJF87",
"prefix": "237",
"number": "651830353",
"amount": "500",
"fees": "5",
"net_amount": "495",
"currency": "XAF",
"status": "PENDING",
"type_operation": "cashout",
"operator": "MTN Cameroun",
"created_at": "2019-07-18 07:16:42"
}
}
|
| 403 |
{"message":"API key is missing."}
|
| 400 | {
"message" : "Please provide username.",
"code" : "T600"
}
|
| 400 | {"error":"Please provide password."} |
| 401 | {"error":"Invalid API key."} |
| 401 | {"error":"Incorrect username or password."} |
| 422 |
{
"message": "The given data was invalid.",
"errors": {
"number": [
"The number field is required."
],
"amount": [
"The amount field is required."
]
}
}
|
| 500 | {"error":"Something went wrong. Please try again later."} |
3. Vérification des Statuts
Opération consistant à vérifier quel est le statut de votre opération sur ViewPay.
Request| Method | URL |
|---|---|
| POST | https://www.view-pay.com/api/repo/cashout/verify/{REFERENCE} |
| Type | Params | Values |
|---|---|---|
| HEAD | Accept |
application/json |
| HEAD | Content - type |
application/json |
| URL |
{{REFERENCE}} |
string |
NB : Les différents paramètres de la requête de cette opération sont identiques aux paramètres de la requête de type CASH IN.
Dans le tableau ci-après nous pouvons noter quelques exemples de réponse en cas de fonctionnement ou de disfonctionnement de l’API lors d’un appel.
| Status | Responses |
|---|---|
| 200 |
{
"message": "L'opération est en cours de traitement par un terminal.",
"code": "T200",
"data": {
"client_reference": "RTXL1V16X0PGJF87",
"reference": "RTXL1V16X0PGJF87",
"prefix": "237",
"number": "651830353",
"amount": "500",
"fees": "5",
"net_amount": "495",
"currency": "XAF",
"status": "PENDING",
"type_operation": "cashout",
"operator": "MTN Cameroun",
"created_at": "2019-07-18 07:16:42"
}
}
|
| 403 |
{"message":"API key is missing."}
|
| 400 | {
"message" : "Please provide username.",
"code" : "T600"
}
|
| 400 | {"error":"Please provide password."} |
| 401 | {"error":"Invalid API key."} |
| 401 | {"error":"Incorrect username or password."} |
| 422 |
{
"message": "The given data was invalid.",
"errors": {
"number": [
"The number field is required."
],
"amount": [
"The amount field is required."
]
}
}
|
| 500 | {"error":"Something went wrong. Please try again later."} |
Token : C’est la clé d’API qui a été générée dans votre interface utilisateur permet d’identifier de manière unique.
REFERENCE : Référence unique fournie par viewPAY lors de la construction d’une opération, qui vous permettra d’identifier l’opération et de retourner le statut à un moment donné.
| Status | Responses |
|---|---|
| 200 |
{
"message" : "le statut de l’opération est disponible",
"code" : "T200",
"data" : {
"reference" : "RTXL1V16X0PGJF87",
"status" : "PENDING"
}
}
|
| 403 |
{"message":"API key is missing."}
|
| 400 | {
"message" : "Please provide username.",
"code" : "T600"
}
|
| 400 | {"error":"Please provide reference."} |
| 401 | {"error":"Invalid API key."} |
| 401 | {"error":"no object."} |
| 422 |
{
"message": "The given data was invalid.",
"errors": {
"number": [
"The number field is required."
],
}
}
|
| 500 | {"error":"Something went wrong. Please try again later."} |
Glossaire
Conventions
- Client - Application client.
- Statut - Code de statut HTTP de la réponse.
- Toutes les réponses possibles sont répertoriées sous ‘Réponses’ pour chaque méthode. Un seul d'entre eux est émis par serveur de requêtes.
- Toutes les réponses sont au format JSON.
- Tous les paramètres de requête sont obligatoires sauf s'ils sont explicitement marqués [optionnel]
Statuts Codes (HTTPS STATUS)
Tous les codes de statut sont des codes de statut HTTP standard. Ceux ci-dessous sont utilisés dans cette API.
- 2XX - Success of some kind
- 4XX - Error occurred in client’s part
- 5XX - Error occurred in server’s part
| Status Code | Description |
|---|---|
| 200 |
OK
|
| 201 |
Created
|
| 202 |
Accepted (Request accepted, and queued for execution)
|
| 400 |
Bad Request
|
| 401 |
Authentication failure
|
| 403 |
Forbidden
|
| 405 |
Method Not Allowed
|
| 409 |
Conflict
|
| 412 |
Precondition Failed
|
| 413 |
Request Entity Too Large
|
| 500 |
Internal Server Error
|
| 501 |
Not Implemented
|
| 503 |
Service Unavailable
|
Code des réponses du serveur viewPay lors des opérations
Tous les codes qui sont retournés dans les réponses de l’API sont des codesliés au support technique permettant de comprendre rapidement s’il y a un problème ou pas. Ceux ci-dessous sont utilisés dans cette API.
| Status Code | Description |
|---|---|
| TP200 |
OK
|
| T001 |
Aucun terminal allumé et utilisable pour le moment
|
| T401 |
Impossible d'effectuer l'opération
|
| T405 |
Impossible d'établir la connexion avec le terminal, un problème d'adresse avec le serveur
|
| T505 |
Le montant maximum que nous prenons en compte est 450000 CFA pour une opération
|
| T555 |
Montant minimal de la transaction est de 100 CFA
|
| T600 |
Le solde de votre compte de retrait (CASH OUT) est insuffisant.
|
| T705 |
La référence du paiement n’existe pas
|