API de facturation par l'opérateur

Introduction

Cette API est utilisée par des tiers spécifiquement autorisés et de confiance pour débiter ou créditer des comptes de téléphonie mobile. Elle est structurée selon l'architecture REST.

Connexion

Tous les appels vers et depuis la passerelle de facturation directe Fonix s'effectuent via HTTPS POST.

Authentification

L'authentification s'effectue en indiquant la clé API dans l'en-tête de votre requête. Le nom de l'en-tête est X-API-KEY. Nous vous fournissons une clé de test et une clé de production.

Vous pouvez avoir plusieurs clés API actives simultanément pour différents services chez nous. Vos clés API donnent accès à de nombreux privilèges, veillez donc à les garder confidentielles !

Toutes les requêtes API doivent être effectuées via HTTPS. Les appels effectués via HTTP en clair échoueront. Vous devez vous authentifier pour chaque requête.

Points de terminaison de l'API FONIX

# https://sonar.fonix.io/v2/ 
# NOTE: The underlying destination IP address of these destinations changes over time.
#  Please don't use fixed destination IPs with this domain.

#Example API Keys
# Test Key: test_BYZNk5YUBMLfowSOQTUuqq3t
# Live Key: live_WrxOqXQYwEPWVJDGgdfirZrk

#Example Request including the API key
  curl -i https://sonar.fonix.io/v2/chargemobile
    -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t
    -d NUMBERS=447987654321
    -d AMOUNT=100

Gestion des versions

Cette fonctionnalité est disponible dans la version 2 de Sonar.

La version de l'API est indiquée dans l'appel « Charge Report » envoyé à votre application :
API V2 : IFVERSION=2xxxxx

Référence au message

Nous prenons en charge les références fournies par le client dans le cadre des demandes qui nous sont adressées. Cela vous permet de nous transmettre jusqu'à 80 caractères de données dans un champ (REQUESTID), que nous vous renverrons dans le rapport de facturation correspondant. Vous trouverez plus de détails dans la section « Paramètres », sous REQUESTID.

#Example including requestid
  curl -i https://sonar.fonix.io/v2/chargemobile
    -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t
    -d NUMBERS=447987654321
    -d AMOUNT=100
    -d CURRENCY=GBP
    -d REQUESTID=F21B992E9257936E3D2F7CDEB38F217C
    -d BODY=This%20message%20is%20charged%20%C2%A31.

Réussites et erreurs

Un appel d'API que vous nous envoyez est réussi si et seulement si vous recevez un 200 OK Code de réponse HTTP renvoyé.

Toute autre valeur du code de réponse HTTP indique un échec et que la requête a été rejetée. Veuillez ne pas réessayer la même requête, car elle échouerait à nouveau si elle restait inchangée.

Si les paramètres de votre requête ne passent pas la validation, vous recevez un 400 Bad Request Erreur dans la réponse. Veuillez vérifier le code de résultat dans le JSON Répondez pour obtenir plus de détails sur la panne.

Si la clé utilisée dans votre requête est incorrecte ou non autorisée, vous recevrez un 401 Unauthorized erreur dans la réponse.

Pour tous 400 BAD_REQUEST Les raisons de l'échec sont indiquées dans la réponse JSON :

RECHARGER SON TÉLÉPHONE PORTABLE

Demande

Cet appel de fonction permet de facturer le compte de téléphonie mobile d'un ou de plusieurs numéros de téléphone.

La facturation n'est tentée qu'une seule fois. En cas d'échec, nous ne tentons pas de refacturer dans le cadre de la même requête, sauf si vous spécifiez « smsfallback=yes »; dans ce cas, la facturation est tentée à nouveau par SMS surtaxé.

#CHARGE MOBILE request

 curl -i https://sonar.fonix.io/v2/chargemobile 
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
  -d NUMBERS=eetmo-uk.440200000017 
  -d AMOUNT=100 
  -d CURRENCY=GBP 
  -d REQUESTID=F21B992E9257936E3D2F7CDEB38F217C 
  -d CHARGEDESCRIPTION=Mobile%20Games%20Service 
  -d TIMETOLIVE=10 
  -d CHARGESILENT=no 
  -d BODY=Thanks%20for%20playing%20lucky%20roulette.%20This%20message%20is%20charged%20%C2%A31.

Réponse

Les numéros de téléphone en double dans une même requête sont éliminés, et dans la réponse, nous vous indiquons le nombre de numéros de téléphone mobile uniques que nous avons trouvés.

# CHARGE MOBILE response (success)
 {
     "success": {
         "txguid": "r-4-F21B992E9257936E3D2F7CDEB38F217C",
         "numbers": "1",
         "encoding": "gsm"
     }
 }

# CHARGE MOBILE response (failure)
 {
     "failure": {
         "parameter": "numbers",
         "failcode": "INVALID_NUMBER"
     }
 }

RAPPORT DE FACTURATION

Demande

Les rapports de facturation relatifs aux demandes Charge Mobile précédemment soumises sont envoyés à votre serveur web via une requête POST HTTPS. Ils indiquent si la facturation demandée a abouti ou a échoué. En cas d'échec, les détails concernant la raison de l'échec sont fournis dans les champs STATUSCODE et STATUSTEXT.

# CHARGE REPORT HTTPS POST example (to your application)
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=440200000017&OPERATOR=eetmo-uk
# &GUID=r-4-F21B992E9257936E3D2F7CDEB38F217C&RETRYCOUNT=0
# &STATUSCODE=DELIVERED&STATUSTEXT=charged
# &STATUSTIME=20160302145201&REQUESTID=F21B992E9257936E3D2F7CDEB38F217C
# &DURATION=0&CHARGEMETHOD=direct
#

Réponse

Le code de réponse HTTP que vous devez nous renvoyer devrait être : 200 OK

Si vous ne répondez pas par un code 200 OK, nous réessaierons d'envoyer le rapport de transaction à votre plateforme pendant une période pouvant aller jusqu'à 24 heures.

Paramètres

Les paramètres suivants sont utilisés dans l'ensemble de l'API :

• CHIFFRES: Contient les numéros de téléphone mobile des destinataires sur lesquels la facturation sera effectuée. Tous les numéros doivent inclure l'indicatif du pays, par exemple 44 pour le Royaume-Uni. Le code de l'opérateur mobile peut être précédé d'un préfixe, c'est-à-dire NUMBERS=eeora-uk.447123456789. C'est une bonne solution pour tous les cas où nous ne recevons pas au préalable de SMS MO de la part du client, par exemple lorsque nous ne pouvons que deviner l'opérateur mobile à partir du préfixe du numéro de téléphone. Pour facturer le même montant à plusieurs numéros, vous pouvez les séparer par des virgules : NUMBERS=447111122222,447333344444
  Le nombre maximal de numéros MSISDN autorisés par lot est de 100.
• NUMÉRO CHIFFRE: Peut contenir un seul et unique numéro de téléphone portable crypté. Il s'agit d'une longue valeur de hachage que nous vous transmettons via Fpay, dans le cas où le numéro de téléphone portable doit rester anonyme mais où vous devez tout de même facturer le consommateur. Remarque : Il faut utiliser la valeur de hachage dans son intégralité, y compris %2F et %3D les caractères contenus dans la chaîne.

Example ENCRYPTEDMSISDN:
  pcRBEbPss0xfscq6XLoWNA8ULssQL4UuM9eGdSkmGdcfUO%2Fu0koOav04GPDxb0yjAufzOyMuvi98JFCEMiHw3vkvIyFVmMpNciKWLLU9k1U%3D

• MONTANT: Le montant que vous souhaitez facturer en pence. Par exemple, 1,50 £ correspondrait à AMOUNT=150. Tous les réseaux mobiles ne proposent pas la même gamme de montants de facturation ni ne prennent en charge la facturation au centime près. Si un montant de facturation ne peut être appliqué parce qu'il n'est pas pris en charge par le réseau mobile, vous recevez un rapport d'échec de facturation avec "statuscode": "INVALID_REQUEST".
• DEVISE: Champ facultatif permettant de préciser la devise de facturation. La seule valeur autorisée pour le moment est CURRENCY=GBP
• REQUESTID: champ facultatif vous permettant d'associer à votre requête une chaîne unique de 80 caractères maximum (0-9, a-z, A-Z). Si vous utilisez ce champ, vous devez vous assurer que la valeur est unique pour votre service. Si vous nous envoyez une nouvelle requête avec un REQUESTID déjà utilisé, nous ne la traiterons pas à nouveau, mais nous vous répondrons en vous renvoyant les mêmes informations que celles fournies dans notre réponse précédente.Le REQUESTID vous sera également renvoyé dans le rapport de facturation correspondant.
• DESCRIPTION DE LA FACTURATION: Le champ « Description de la facturation » est obligatoire, même s'il n'apparaît pas (encore) sur toutes les factures téléphoniques des opérateurs. La longueur maximale autorisée est de 30 caractères.
• TIMETOLIVE: Permet de définir, si vous le souhaitez, la durée de validité de la requête Charge Mobile en minutes. Si cette durée expire avant qu'une tentative de facturation n'ait été effectuée, un « rapport d'échec de facturation » vous sera renvoyé. Valeur minimale : 10 minutes, valeur maximale : 4 320 minutes, valeur par défaut : 90 minutes.
• CORPS: Le corps du message facultatif accompagnant la transaction. Si vous ne le précisez pas et que vous avez demandé CHARGESILENT=no, nous utiliserons les éléments suivants :
  • Par défaut BODY: « Le montant de nn,nn £ vous a été facturé pour le produit ou le service que vous avez choisi. »
• CHARGESILENT: Si CHARGESILENT=no si cette option est demandée, le corps du message sera visible par l'utilisateur. La valeur par défaut est CHARGESILENT=yes. REMARQUE : le message ne sera reçu par l'utilisateur final que si le prélèvement a abouti.
• SMSFALLBACK: Si SMSFALLBACK=yes si cette option est demandée, nous tenterons automatiquement de facturer l'utilisateur via un SMS surtaxé (la valeur par défaut est SMSFALLBACK=no). La solution de secours par SMS ne fonctionne que si tout si les critères suivants sont remplis :
  • La tentative de facturation directe a échoué
  • L'opérateur mobile propose une solution de secours par SMS
  • Il existe déjà un shortcode MT premium partagé avec le même montant « AMOUNT »
• NORETRY: Si NORETRY=yes est demandé en association avec SMSFALLBACK=yes, nous tenterons alors uniquement de facturer l'utilisateur par le biais d'un SMS surtaxé UNE FOIS. Cette option est utile lorsque vous avez besoin d'un traitement rapide de vos demandes de facturation, mais que vous souhaitez tout de même utiliser le SMS comme solution de secours. La valeur par défaut est NORETRY=no, ce qui signifie que nous essayons à nouveau de facturer le client par SMS pendant un certain temps.
• NETWORKRETRY: La valeur par défaut est NETWORKRETRY=yes. Si la valeur est définie sur NO, veuillez vous assurer que l'opérateur est bien indiqué dans la requête, c'est-à-dire NUMBERS=eeora-uk.447123456789.
  Lorsque vous nous envoyez une demande, nous vérifions d'abord si nous avons déjà enregistré une transaction premium réussie pour le numéro MSISDN que vous souhaitez facturer. Si tel est le cas, nous essayons d'abord de facturer ce numéro MSISDN via l'opérateur avec lequel la transaction a été effectuée, puis, si cet opérateur ne reconnaît pas le numéro MSISDN, via les autres opérateurs.
  Si vous savez avec certitude à quel opérateur appartient le numéro Msisdn (c'est-à-dire si vous obtenez le nom de l'opérateur grâce à l'enrichissement de l'en-tête ou à partir d'un message MO envoyé à un numéro court), vous devez envoyer NETWORKRETRY=NO pour obtenir une réponse plus rapide.

Paramètres d'entrée

Les paramètres d'information suivants apparaissent dans CHARGE RESPONSE:

• IFVERSION: la version de l'API actuellement utilisée.
• MONUMBER: Le numéro de téléphone portable de l'utilisateur qui a été facturé. Le format est MONUMBER=447111122222.
• OPÉRATEUR: Code de l'opérateur mobile de l'utilisateur facturé.
• MODE DE PAIEMENT: Le mode de facturation utilisé. Valeurs possibles : direct ou psms.
• GUID: l'identifiant unique que nous avons attribué à cette transaction.
• DURÉE: Le temps, en secondes, qu'il a fallu pour appliquer la charge ou pour constater que celle-ci avait échoué.
• RETRYCOUNT: ce paramètre s'affiche lorsqu'une requête vous est renvoyée. Il augmente à chaque nouvelle tentative.
• CODE D'ÉTAT: Code indiquant si votre demande Charge Mobile a abouti ou a échoué.
• STATUSTEXT: Une description fournissant des informations complémentaires sur le code d'état.

• STATUSTIME: horodatage de la création du rapport de facturation
• REQUESTID: Si vous avez envoyé votre demande Charge Mobile avec un identifiant de demande unique, ce champ le contiendra afin de vous aider à identifier la transaction.
• Condition particulière pour les clients O2 : Si operator=o2-uk et statuscode si l'une des valeurs du tableau ci-dessous est présente, le message d'erreur correspondant doit s'afficher via l'interface de paiement.

• Condition particulière pour les clients EE : Si operator=eeora-uk ou operator=eetmo-uk et statuscode si l'une des valeurs du tableau ci-dessous est présente, le message d'erreur correspondant doit s'afficher via l'interface de paiement.

Codes des opérateurs mobiles

La liste suivante des codes d'opérateurs mobiles est utilisée dans cette version de l'API (V2) ainsi que dans toutes les versions futures :

Types de personnages

Les types de données suivants sont utilisés dans l'ensemble de l'API :

• Chiffres : caractères 0 à 9
• Alphanumérique : tout caractère UTF-8
• Numéro de portable : chiffres de 0 à 9, le premier caractère peut être « + »
• Heure : horodatage au format AAAAMMJJHHMMSS
• Version : Version MNNBBB
• GUID : caractères 0 à 9, a à f, A à F et « - »

# Examples
# 
# 
# 
#  ORIGINATOR=84588
# 
#  BODY=Test+message
# 
#  NUMBERS=447111222333
# 
#  RECEIVETIME=20130202102030
# 
#  IFVERSION=201001
# 
#  GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

Exemple de demande

Les requêtes envoyées avec une clé API TEST (c'est-à-dire une clé API commençant par test_) ou avec le paramètre DUMMY=YES sont des requêtes FICTIVES et ne sont pas transmises aux opérateurs de réseau.

Notre système génère en interne un RAPPORT DE FACTURATION en fonction du MSISDN fourni dans la requête CHARGE MOBILE.

OPERATOR sera défini en fonction des 4 premiers chiffres du MSISDN, conformément au tableau suivant:

Pour tout autre préfixe msisdn, celui-ci sera défini en fonction d'une recherche dans les plages de numéros.

STATUSCODE, STATUSTEXT et CHARGEMETHOD sont déterminés en fonction des 8 derniers chiffres du MSISDN, conformément au tableau suivant :

Exemple de Charge Mobile

#Your charge mobile request made to an O2 number 440000000017:

curl -i https://sonar.fonix.io/v2/chargemobile 
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
  -d NUMBERS=440000000017 
  -d AMOUNT=100 
  -d CURRENCY=GBP 
  -d REQUESTID=F21B992E9257936E3D2F7CDEB38F217C 
  -d CHARGEDESCRIPTION=Mobile%20Games%20Service 
  -d TIMETOLIVE=10 
  -d CHARGESILENT=no 
  -d BODY=Thanks%20for%20playing%20lucky%20roulette.%20This%20message%20is%20charged%20%C2%A31.

# Our ack for your request:
#
# {
#  "success": {
#     "txguid":"r-4-F21B992E9257936E3D2F7CDEB38F217C",
#     "numbers":"1",
#     "encoding":"gsm"
#   }
# }

# Our charge report request made to you:
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=440000000017&OPERATOR=o2-uk
# &GUID=r-4-F21B992E9257936E3D2F7CDEB38F217C&RETRYCOUNT=0
# &STATUSCODE=DELIVERED&STATUSTEXT=charged&STATUSTIME=20160302123716
# &REQUESTID=F21B992E9257936E3D2F7CDEB38F217C&DURATION=0&CHARGEMETHOD=direct
#
# Your ack for our request:
#
# HTTP 200 OK

Exemple de Charge Mobile avec solution de secours par SMS

# Your charge mobile request made to 440100000001:

curl -i https://sonar.fonix.io/v2/chargemobile 
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
  -d NUMBERS=voda-uk.440100000001 
  -d AMOUNT=100
  -d CURRENCY=GBP
  -d REQUESTID=C1E82726F1423AC298971B37265F8ED2
  -d CHARGEDESCRIPTION=Top%20Up%20Service
  -d TIMETOLIVE=10
  -d SMSFALLBACK=yes
  -d NORETRY=yes
  -d BODY=Thanks%20for%20playing%20topping%20up.%20This%20message%20is%20charged%20%C2%A31.

# Our ack for your request:
#
# {
#  "success": {
#     "txguid":"r-4-C1E82726F1423AC298971B37265F8ED2",
#     "numbers":"1",
#     "encoding":"gsm"
#   }
# }

# Our charge report request made to you:
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=440100000001&OPERATOR=voda-uk
# &GUID=r-4-C1E82726F1423AC298971B37265F8ED2&RETRYCOUNT=0
# &STATUSCODE=DELIVERED&STATUSTEXT=charged&STATUSTIME=20160302124250
# &REQUESTID=C1E82726F1423AC298971B37265F8ED2&DURATION=0&CHARGEMETHOD=psms

# Your ack for our request:
#
# HTTP 200 OK

API de remboursement

Introduction

L'API Fonix REFUND permet aux commerçants d'annuler les prélèvements effectués via CHARGE MOBILE au cours des 90 derniers jours.

# REQUEST:
curl -i https://refund.fonix.io/v2/refund 
-H X-API-KEY:SERVICE_API_KEY  
-d REQUESTID=requestid1 
-d NUMBERS=o2-uk.447400000000 
-d CHARGE_GUID=chargeguid1 
-d DUMMY=YES

# RESPONSE 
{
   "success":{
       "ifversion":"201001",
       "statuscode":"OK",
       "statustext":"Successfully Refunded",
       "guid":"r-1-requestid1",
       "requestid":"requestid1",
       "charge_guid":"chargeguid1",
       "refund_time":"20210803153118",
       "refunded_amount_in_pence":150
   }
 }

Détails de l'appel

Paramètres de requête

Tous les paramètres, à l'exception de DUMMY, sont obligatoires.

• REQUESTID: chaîne de caractères ne dépassant pas 80 caractères (0-9, a-z, A-Z) utilisée pour identifier une requête ; elle doit être unique au sein de votre service.
• CHIFFRES: Contient un seul et unique numéro de téléphone mobile pour lequel les informations sont demandées. Le code de l'opérateur mobile doit être indiqué en préfixe, c'est-à-dire NUMBERS=eeora-uk.447123456789
• AUTEUR DE LA TRANSACTION: Facultatif. Permet de préciser l'émetteur utilisé dans la demande de prélèvement PSMS.
  Valeurs possibles :
  direct si le prélèvement initial a été effectué par facturation directe (c'est la valeur par défaut) ;
  ORIGINATOR utilisé dans la requête PSMS ;
  psms si le prélèvement a été effectué via PSMS mais que l'émetteur PSMS n'est pas connu.
• CHARGE_GUID: la valeur renvoyée dans le paramètre GUID du rapport CHARGE REPORT à rembourser.

• DUMMY: Facultatif, valeurs YES/NO, valeur par défaut NO.

Réponse

La réponse REFUND est au format JSON.
Si l'un des paramètres ne passe pas la validation, une réponse d'échec indiquant le paramètre concerné et un code d'erreur est renvoyée.
c'est-à-dire {"failure":{"parameter":"NUMBERS","failcode":"INVALID_NUMBER"}}

Si la requête adressée au réseau mobile échoue, une réponse d'échec contenant le code d'état et le texte d'état correspondant à l'échec est renvoyée.
c'est-à-dire {"failure":{"ifversion":"201001","statuscode":"MNO_TX_NOT_FOUND","statustext":"Charge Transaction Not Found","guid":"r-1-requestid1","requestid":"requestid1","charge_guid":"chargeguid1","refund_time":"20210714155121"}}

Si le nombre de requêtes envoyées simultanément dépasse la valeur MAX CONCURRENT REQUESTS, une réponse d'échec avec le code d'état WINDOW_EXCEEDED est renvoyée.
c'est-à-dire {"failure":{"ifversion":"201001","statuscode":"WINDOW_EXCEEDED","statustext":"Too many requests made to the server in parallel"}}

Si le traitement de la requête prend plus de 120 secondes, une réponse en attente est renvoyée.
c'est-à-dire {"pending":{"ifversion":"201001","statuscode":"PENDING","statustext":"The request is still processing","guid":"r-1-requestid1","requestid":"requestid1"}}

Si la transaction identifiée par CHARGE_GUID et MOBILE NUMBER fait l'objet d'un remboursement, une réponse indiquant que l'opération a réussi est renvoyée.
c'est-à-dire {"success":{"ifversion":"201001","statuscode":"OK","statustext":"Successfully Refunded","guid":"r-1-requestid1","requestid":"requestid1","charge_guid":"chargeguid1","refund_time":"20210714155511","refunded_amount_in_pence":299}}

Paramètres de réponse

Les réponses peuvent être de type « échec », « en attente » ou « réussite ». Vous trouverez des exemples de ces types de réponses dans le paragraphe précédent.

• ifversion: version de l'API Fonix.
• paramètre: paramètre pour lequel la validation a échoué.
• code d'erreur: motif de l'échec de la validation.
• code d'état: code utilisé pour indiquer l'état de la requête.
• statustext: Une brève description associée au code d'état.
• guid: identifiant unique attribué par Fonix à partir du REQUESTID
• requestid: L'identifiant REQUESTID envoyé dans la requête
• charge_guid: le CHARGE_GUID envoyé dans la requête
• refund_time: Date et heure auxquelles la demande a atteint son statut définitif (AAAAMMJJHHMMSS).
• montant_remboursé_en_pence: montant remboursé.

Erreurs de validation des paramètres

Lorsqu'un ou plusieurs paramètres ne passent pas la validation, l'API Fonix REFUND renvoie une réponse d'échec au format {"failure":{"parameter":"NUMBERS","failcode":"INVALID_NUMBER"}}.
Le parameter Ce champ indiquera le nom du paramètre transmis qui n'a pas passé la validation.
Le failcode Ce champ sera renseigné avec l'un des codes suivants :

Codes d'état

Version du document

v1.3