API DIRECT CARRIER BILLING - (DCB) via OTP Version Date - LAfricaMobile
←
→
Transcription du contenu de la page
Si votre navigateur ne rend pas la page correctement, lisez s'il vous plaît le contenu de la page ci-dessous
REFERENCE : SUP.DEV.MAN.API.DCB.00
DATE : 22/03/2022
API DIRECT CARRIER BILLING
(DCB) via OTP
Version Date Commentaire
1 22/03/2022 par MG
SOMMAIRE
1 Présentation .............................................................................................................. 3
2 Portée ........................................................................................................................ 4
3 Paramètres du compte ............................................................................................... 4
3.1 Pré-requis............................................................................................................ 4
3.2 Variables utilisées dans la documentation.......................................................... 5
4 Envoyer SMS Code de confirmation ........................................................................ 5
4.1.1 Comment envoyer via http ........................................................................ 5
4.1.2 Comment envoyer via un code PHP ......................................................... 6
4.1.3 Comment envoyer en JSON via un code PHP .......................................... 7
5 Générer les paramètres challenges ......................................................................... 10
5.1.1 Comment envoyer via http ...................................................................... 10
5.1.2 Comment envoyer via un code PHP ....................................................... 11
5.1.3 Comment envoyer en JSON via un code PHP ........................................ 12
6 Facturer vos abonnés grâce au billing .................................................................... 14
6.1.1 Comment envoyer via un code PHP ....................................................... 14
6.1.2 Comment envoyer en JSON via un code PHP ........................................ 15
7 Coversion MSISDN en alias ISE ........................................................................... 18
7.1.1 Comment envoyer via un code PHP ....................................................... 18
7.1.2 Comment envoyer en JSON via un code PHP ........................................ 19
8 Réception de votre SMS MO.................................................................................. 20
9 Envoyer SMS MT................................................................................................... 20
9.1.1 Comment envoyer via http ...................................................................... 20
9.1.2 Comment envoyer via un code PHP ....................................................... 21
9.1.3 Comment envoyer en JSON via un code PHP ........................................ 22
10 Réception d’accusé en temps réel .......................................................................... 23
11 Liste des statuts DLR et significations .................................................................. 24
12 Code opérateur Orange ......................................................................................... 25
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 21 Présentation Le DCB est utiliser pour faire du paiement, à partir du crédit téléphonique, de contenus digitaux comme (achat musique en ligne, Crowdfunding, jeux en ligne, jeux de pari en ligne, abonnement en ligne, Ecommerce …). Il peut être combiné avec l’USSD pour faciliter l’intégration à des utilisateurs non connectés. Le DCB est disponible dans tous les pays d'afrique avec l'opérateur ORANGE. © 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 3
2 Portée Le DCB via OTP est un proxy/API pour envoyer des SMS (OTP) de confirmation et faire la facturation à des numéros Orange abonnés à votre service, en utilisant une interface API. Le DCB via OTP propose deux interfaces : - via Web: l'utilisateur se connecte via un navigateur - via API: l'application du client échange des informations automatiquement avec la plateforme de LAfricaMobile Ce document décrit la seconde manière et explique comment utiliser cette API. 3 Paramètres du compte 3.1 Pré-requis Pour utiliser cette API, vous avez besoin d'un compte valide. Lors de la création de votre compte, LAfricaMobile doit vous donner: - un login (nommé aussi accountid) - un mot de passe Cette paire identifiant / mot de passe est utilisée comme paramètre d’identification dans l'API. © 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 4
3.2 Variables utilisées dans la documentation
Dans ce document, nous utilisons des valeurs ci-dessous. Les vraies valeurs vous
seront données par notre équipe technique ou par votre propre configuration (pour les
paramètres dépendant de votre côté, ret_url par exemple). Certaines d’entre elles
peuvent ne pas être utilisées en fonction de vos besoins.
Valeurs d’essai du document:
- login=fred
- password=xpasswordx
- message = Veuillez_utiliser_le_code_suivant
- telephone = 221773758085
- sendername = LAM
- DCB via OTP base URL : https://mtpremium-prod.lafricamobile.com
Vous devez remplacer ces valeurs par vos propres paramètres pendant vos tests.
4 Envoyer SMS Code de confirmation
4.1.1 Comment envoyer via http
Au lieu d'avoir tous les paramètres encapsulés, vous pouvez directement effectué un
GET paramètres individuellement :
Les paramètres sont :
Nom Mandatory Valeur test Comment
login Y fred Value
given by
LAM
password Y xpasswordx Value
given by
LAM
message Y Veuillez_utiliser_le_code_suivant_pour_confimer_votre_achat_: Contenu à
envoyer
sendername Y SMS Mot clé
(SMS) qui
s’affiche
sur le
message
telephone Y 221773758085 Numéro
téléphone
de
l’utilisateur
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 5Donc, vous pouvez faire un appel directement dans votre navigateur :1
https://mtpremium-prod.lafricamobile.com/callotp?login=fred&password= xpasswordx
&sendername=LAM&message=Veuillez_utiliser_le_code_suivant_pour_confirmer_votre_achat_:&t
elephone=221773758085
4.1.2 Comment envoyer via un code PHP
Voici un exemple avec le script PHP
1
Veuillez mettre le signe + devant l’indicatif du numéro de téléphone
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 64.1.3 Comment envoyer en JSON via un code PHP
Voici un exemple avec le script PHP
REPONSE OK
Content-Type: application/json
{"url":"/challenge/v1/challenges/5e6773517970f8095fb99d15"}
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 7L’API générera un url /challenge/v1/challenges/5e6773517970f8095fb99d15
et un SMS avec un code de confirmation 9095 qu’on utilisera pour facturer les
abonnés
ERREUR LOGIN OU MOT DE PASSE
• Login ou Mot de passe incorrect
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 8LISTE DES CODES D’ERREUR COURANTS
response
HTTP status code reason model
400 List of error codes: • model
- SVC0001: A service error occurred
• model
- SVC0002: Invalid input value for message part
schema
- SVC0003: Invalid input value for message part
- SVC0004: No valid addresses provided for message part
- SVC0280: Message too long
403 List of error codes: • model
- POL0001: A policy error occurred
• model
- POL0003: Too many addresses specified in message part
schema
- POL0007: Nested groups specified in message part not allowed
404 List of error codes: • model
- POL0010: Requested information unavailable as the retention time
• model
interval has expired
schema
406 List of error codes: • model
- POL0011: Media type not supported
• model
schema
503 List of error codes: 1. model
- SVC1000: No resources This exception is thrown if there are no 2. model
server resources available to process the request schema
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 95 Générer les paramètres challenges
Pour facturer un abonné vous aurait besoins d’un alias appelé ise2 qu’on générera
grace à l’url et au code de vérification.
5.1.1 Comment envoyer via http
Au lieu d'avoir tous les paramètres encapsulés, vous pouvez directement effectué un
GET paramètres individuellement :
Les paramètres sont :
Nom Mandatory Valeur test Comment
login Y fred Value given by LAM
password Y xpasswordx Value given by LAM
code Y 9095 Code reçu par l’abonné
url Y /challenge/v1/challenges/5e6773517970f url reçu plus haut
8095fb99d15
telephone Y 221773758085 Numéro téléphone de
l’utilisateur
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 10Donc, vous pouvez faire un appel directement dans votre navigateur :2 https://mtpremium-prod.lafricamobile.com/callchallenge?login=fred&password= xpasswordx &code=9095&url=/challenge/v1/challenges/5e6773517970f8095fb99d15telephone=221773758085 5.1.2 Comment envoyer via un code PHP Voici un exemple avec le script PHP © 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 11
5.1.3 Comment envoyer en JSON via un code PHP
Voici un exemple avec le script PHP
REPONSE OK
Content-Type: application/json
{"challenge":{"method":"OTP-SMS-
AUTH","result":[{"type":"OrangeApiToken","value":"B640Z45OYjdYK7oZ310
"},{"type":"ise2","value":"PDKSUB-200-
Ibfbl9J+xxxxxxxxxxxxx="}],"country":"SEN","service":"LAFRICAMOBILE","p
artnerId":"PDKSUB","inputs":[{"type":"MSISDN","value":"+221773758085"},{
"type":"info","value":"OrangeApiToken,ise2"},{"type":"message","value":"test
test test OTP is %OTP% "},{"type":"confirmationCode","value":"9095"}]}}
L’API générera le ise2 PDKSUB-200-Ibfbl9J+xxxxxxxxxxxxx= qu’on utilisera pour
facturer l’abonné
ERREUR LOGIN OU MOT DE PASSE
• Login ou Mot de passe incorrect
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 12LISTE DES CODES D’ERREUR COURANTS
response
HTTP status code reason model
400 List of error codes: • model
- SVC0001: A service error occurred
• model
- SVC0002: Invalid input value for message part
schema
- SVC0003: Invalid input value for message part
- SVC0004: No valid addresses provided for message part
- SVC0280: Message too long
403 List of error codes: • model
- POL0001: A policy error occurred
• model
- POL0003: Too many addresses specified in message part
schema
- POL0007: Nested groups specified in message part not allowed
404 List of error codes: • model
- POL0010: Requested information unavailable as the retention time
• model
interval has expired
schema
406 List of error codes: • model
- POL0011: Media type not supported
• model
schema
503 List of error codes: 3. model
- SVC1000: No resources This exception is thrown if there are no 4. model
server resources available to process the request schema
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 136 Facturer vos abonnés grâce au billing
6.1.1 Comment envoyer via un code PHP
Les paramètres sont :
Nom Mandatory Valeur test Comment
login Y fred Value given by LAM
password Y xpasswordx Value given by LAM
amount Y 100.0 Valeur en CFA à prélever
clientise Y PDKSUB-200- Ise de l’abonné généré
Ibfbl9J+xxxxxxxxxxxxx=
operateur Y OSN Code opérateur
clientCorrelator Y 12345 Identifiant unique de la
requête
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 146.1.2 Comment envoyer en JSON via un code PHP Voici un exemple avec le script PHP © 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 15
REPONSE OK
Content-Type: application/json
{
"amountTransaction": {
"endUserId": "acr: X-Orange-ISE2",
"paymentAmount": {
"chargingInformation": {
"description": "AVATAR",
"currency": "XOF",
"amount": 100.0
},
"totalAmountCharged": 100.0,
"chargingMetaData": {
"onBehalfOf": "TopEleven",
"purchaseCategoryCode": "Game",
"taxAmount": 0.1,
"serviceId": "LAFRICAMOBILE"
}
},
"transactionOperationStatus": "Charged",
"referenceCode": "REF-12345",
"serverReferenceCode": "f9b72bd8-8eba-4c25-a557-2219cb8c26a2",
"clientCorrelator": "12345",
"resourceURL":"f9b72bd8-8eba-4c25-a557-2219cb8c26a2"
}
}
ERREUR LOGIN OU MOT DE PASSE
• Login ou Mot de passe incorrect
LISTE DES CODES D’ERREUR COURANTS
1. List of service exceptions for Payment
ErrorCode Exception Text Variables Response code
SVC0007 Invalid charging information None 400 Bad Request
SVC0270 Charging operation failed, the charge was None 400 d Request
not applied
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 162. List of policy exceptions for Payment
ErrorCode Exception Text Variables Response
Code
POL0253 Payment operation refused by user None 403
Forbidden
POL0254 The amount exceeds the operator limit for a None 403
single charge Forbidden
POL1000 User has insufficient credit for transaction None 403
Forbidden
POL1001 The %1 operator charging limit for this user %1 – the time period for which 403
has been exceeded the charging limit has been Forbidden
reached, e.g. hourly, daily,
weekly, monthly.
POL1002 The charge happened too soon after the None 403
previous one Forbidden
POL1004 Refund below minimum refundable amount %1 – the minimum refundable 403
supported %1 amount supported Forbidden
POL1005 A refund request requires the None 403
originalServerReferenceCode for the charge Forbidden
that is being refunded
POL1006 originalServerReferenceCode not valid None 403
Forbidden
Inconsistent transaction None 400 Bad
POL2010 Request
POL2011 Transaction expired or invalid None 400 Bad
Request
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 177 Conversion MSISDN en alias ISE 7.1.1 Comment envoyer via un code PHP © 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 18
7.1.2 Comment envoyer en JSON via un code PHP
8 Réception de votre SMS MO
Pour recevoir les sms envoyés sur le mot clé FOOT le client devra fournir à
LAFRICAMOBILE un URL du type http://[URL_PARTNER] où lui seront envoyés les
paramètres du message via GET
Paramètres transmises à URL_PARTNER sont :
Nom METHOD Mandatory Valeur test Comment
messageid GET Y 123456 Identifiant unique du client
message GET Y FOOT Mot clé du client Contenu du message
envoyé
clienttoken GET Y B64LAQZWGv Le Token
clientise GET Y PDKSUB-200-Ib L’ISE permet d’envoyer des SMS et de
facturer l’abonné
9 Envoyer SMS MT
9.1.1 Comment envoyer via http
Au lieu d'avoir tous les paramètres encapsulés, vous pouvez directement effectué un
GET paramètres individuellement :
Les paramètres sont :
Nom Mandatory Valeur test Comment
login Y Fred Value given by LAM
password Y xpasswordx Value given by LAM
message Y Hello%20World Contenu à envoyer
sendername Y FOOT Mot clé (FOOT) qui s’affiche sur le
message
clientise Y PDKSUB-200-Ib ISE de l’abonné généré ou reçu sur le
SMS MO
callbackdata Y 12345 Identifiant unique du message à
envoyé
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 20Donc, vous pouvez faire un appel directement dans votre navigateur :3 https://mtpremium-prod.lafricamobile.com/api?login=fred&password= xpasswordx &sendername=FOOT&clientise=PDKSUB-200-Ib&message=Bonjour ceci est un autre test&callbackdata=12345 9.1.2 Comment envoyer via un code PHP Voici un exemple avec le script PHP © 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 21
9.1.3 Comment envoyer en JSON via un code PHP
Voici un exemple avec le script PHP
REPONSE OK
Content-Type: application/json
{"outboundSMSMessageRequest": {
"address": "acr:X-Orange-ISE2",
"senderAddress": "tel:+26261",
"senderName": "FOOT",
"outboundSMSTextMessage": {"message": "Bonjour ceci est un autre test"},
"clientCorrelator": "12345",
"resourceURL": " fdkqk69jjs34"
}}
ERREUR LOGIN OU MOT DE PASSE
• Login ou Mot de passe incorrect
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 22LISTE DES CODES D’ERREUR COURANTS
response
HTTP status code reason model
400 List of error codes: • model
- SVC0001: A service error occurred
• model
- SVC0002: Invalid input value for message part
schema
- SVC0003: Invalid input value for message part
- SVC0004: No valid addresses provided for message part
- SVC0280: Message too long
403 List of error codes: • model
- POL0001: A policy error occurred
• model
- POL0003: Too many addresses specified in message part
schema
- POL0007: Nested groups specified in message part not allowed
404 List of error codes: • model
- POL0010: Requested information unavailable as the retention time
• model
interval has expired
schema
406 List of error codes: • model
- POL0011: Media type not supported
• model
schema
503 List of error codes: 5. model
- SVC1000: No resources This exception is thrown if there are no 6. model
server resources available to process the request schema
10 Réception d’accusé en temps réel
Il existe deux manières de suivre le routage SMS:
- votre serveur est informé par la passerelle lorsque le statut change ou bien
- vous pouvez demander à notre serveur le statut SMS.
Le premier moyen est bien meilleur, car il est en temps réel et ne charge pas la plate-
forme avec des appels inutiles.
La seconde ne doit être utilisée que exceptionnelement au risque de surcharger le
serveur.
Dans ce cas, notre serveur appelle une URL, quand il détecte que le statut a changé.
Pour recevoir le DELIVERY NOTIFICATION(DLR) le client devra founir une url où les
paramètres seront transmis.
Pour le DLR, l’url du client sera enrichi via GET en urlencoded ou POST en JSON comme
suit :
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 23GET
http://[PARTNER_URL]?telephone=221773275745&callbackdata=fdkqk69jjs34&deliverys
tatus=DeliveredToTerminal
POST http://[PARTNER_URL]
{"telephone" : "221773275745","callbackdata" :"fdkqk69jjs34","deliverystatus" :
"DeliveredToTerminal" }
NB : le callbackdata de l’accusé de réception correspond au resourceURL reçu sur la
réponse du SMS MT
11 Liste des statuts DLR et significations
- DeliveredToTerminal : SMS reçu par l’utilisateur
- DeliveredToNetwork : SMS reçu par le réseau
- DeliveryUncertain : SMS par sûre d’être reçu par l’utilisateur
- DeliveryImpossible : Impossible de transmettre le SMS à l’utilisateur
- MessageWaiting : SMS en attente reception
- DeliveryNotificationNotSupported : Impossible de notifier la reception du SMS
© 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 2412 Code opérateur Orange Country Code ISO3 Currency Botswana OBW BWA Burkina Faso OBF BFA Cameroun OCM CMR Centre Afrique OCF CAF Côté d'Ivoire OCI CIV Democratic Republic of Congo ODC COD Guinée Bissau (OGW) OGW GNB Guinée Conakry (OGN) OGC GIN Jordan OJO JOR Liberia OLR LBR Madagascar (OMG) OMG MDG Mali (OML) OML MLI Maroc (OMA) OMA MAR Niger (ONE) ONE NER Senegal (OSN) OSN SEN Sierra Leone (OSL) OSL SLE Tunisia (OTN) OTN TUN © 2020-LAFRICAMOBILE – APPLICATION PROGRAMMING INTERFACE 25
Vous pouvez aussi lire
