ComNpay - Développeur

L'API

Introduction

Les web services exposés :
  • doivent être appelés en POST
  • retournent des réponses formatées en JSON

HTTPS/SSL

  • Les appels de web services doivent être chiffrés en utilisant les protocoles TLSv1.1 ou TLSv1.2. Les protocoles SSLv2, SSLv3 et TLSv1.0 ne sont pas autorisés.

  • Les algorithmes de chiffrement (ciphers) autorisés sont les suivants :
    • HIGH: high encryption cipher suites (Algorithmes avec clés de chiffrement d’une longueur supérieur ou égal à 128 bits)
    • MEDIUM: medium encryption cipher suites
    • RSA
  • Il faut privilégier les algorithmes de chiffrement suivants :
    • TLS_RSA_WITH_AES_256_CBC_SHA
    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

Paiement

Débit

Web service de débit.

https://secure.comnpay.com:60000/rest/payment/debit

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
transactionRef Référence client de la transaction Longueur 40 maximum
cardType Type de carte CB, VISA, MC
cardNumber Numéro de carte  
cardExpirationDate Date d'expiration de la carte Format AAMM
cvv Cryptogramme visuel  
amount Montant du débit En centimes
force3ds Permet le forçage ou l'interdiction du 3DS 1 pour forcer 3DS, 0 pour cas standard (seuil, géofiltrage)
origin Origine du paiement (URL de votre site) URL à déclarer dans "Mes URLs"
ip Adresse IP de l'acheteur Utilisée par le module de géofiltrage
customer Formulaire porteur/acheteur Exemple de formulaire porteur

Reprise débit après authentification 3DS

Etape 1 :

Le paiement 3DS en web services débute comme un paiement "classique", par l'appel du service "payment/debit". Le déclenchement du 3DS se fera selon le seuil défini sur votre portail, ou peut être forcé grâce au paramètre force3ds (1).

Si une interrogation 3D Secure est requise (seuil ou forçage), la réponse de débit portera :
  • à la racine le champ "actionCode" valorisé à "AUTH_3DS_REQUISE"
  • le champ transaction.verifyEnrollment3dsActionUrl avec l'URL vers laquelle rediriger le porteur
  • les champs transaction.verifyEnrollment3dsMd et transaction.verifyEnrollment3dsPareq permettant de pousser les infos pareq et md vers la page d'authentification

Exemple :

{
    "ok":1,
    "message":"ok",
    "transaction":{
            "transactionId":2630,
            "amount":200,
            [...]
            "verifyEnrollment3dsMd":"fUebB6kN11L8qY2v2JeU",
            "verifyEnrollment3dsPareq":"mS2i8y6R1L60yX6aH3971qN9jX64VwxBbmM9bM4iN9lV7mL5fM4e56pLBeA5xC1wV0dM0lz5pV4jkM4Y6hJ0dOFaW6xE8dU9vDGi",
            "verifyEnrollment3dsActionUrl":"https://homologation.comnpay.com/3ds.html",
            "verifyEnrollment3dsMpi":"Y"
    },
    "responseCode":"200",
    "actionCode":"AUTH_3DS_REQUISE"
}

Etape 2 :

Vous devez alors orienter votre client vers l'URL donnée par le paramètre verifyEnrollment3dsActionUrl, en passant en POST les paramètres :
  • MD
  • PaReq
  • TermUrl : URL vers laquelle sera redirigé votre client après son authentification 3DS

Exemple :

<form action="https://homologation.comnpay.com/3ds.html" id="3ds" method="post">
    <input type="hidden" name="TermUrl" value="http://www.votresite.com/retour3ds.html"/>
        <input type="hidden" name="MD" value="fUebB6kN11L8qY2v2JeU"/>
        <input type="hidden" name="PaReq" value="mS2i8y6R1L60yX6aH3971qN9jX64VwxBbmM9bM4iN9lV7mL5fM4e56pLBeA5xC1wV0dM0lz5pV4jkM4Y6hJ0dOFaW6xE8dU9vDGi"/>
</form>

Etape 3 :

Lors de cette redirection, vous allez récupérer en POST les paramètres MD et PaRes, que vous devrez nous retourner par appel de web service pour finaliser le paiement :

https://secure.comnpay.com:60000/rest/payment/end3dsDebit

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
transactionId Identifiant ComNpay de la transaction Retourné en réponse du web service payment/debit
transactionRef Référence client de la transaction  
pares Valeur du champ "pares" Retourné via formulaire après authentification 3DS
md Valeur du champ "MD" Retourné via formulaire après authentification 3DS

Débit avec alias

Web service de débit sur un alias (cf porte-cartes).

https://secure.comnpay.com:60000/rest/payment/aliasDebit

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
transactionRef Référence client de la transaction Longueur 40 maximum
alias Alias de carte  
amount Montant du débit En centimes
origin Origine du paiement (URL de votre site) URL à déclarer dans "Mes URLs"
ip Adresse IP de l'acheteur Utilisée par le module de géofiltrage
customer Formulaire porteur/acheteur Exemple de formulaire porteur

Recrédit/Remboursement

Web service de recrédit d'un débit initial. Le montant du recrédit doit être inférieur ou égal au débit initial. Il est possible d'effectuer plusieurs recrédits sur une même transaction, si le montant total ne dépasse pas le débit initial.

https://secure.comnpay.com:60000/rest/payment/refund

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
transactionRef Référence client de la transaction Non nécessaire si transactionId renseigné
transactionId Id Afone de la transaction Non nécessaire si transactionRef renseigné
amount Montant du recrédit En centimes

Réponse de paiement

{
        "ok": 1,
        "message": "Paiement accepte",
        "transaction": {
                "transactionId": 6145,
                "amount": 1590,
                "ok": 1,
                "confirmed": 1,
                "cardAlias": "02EF4AFB171F94D2D560A2423BBBE306B0CBB6DE94686918BA0D0E54DB25635F",
                "cardEndDate": "1612",
                "cardTruncatedNumber": "111122XXXXXX4444",
                "cardType": "CB",
                "binCountryCode": "FR",
                "transactionDate": "20130628164913",
                "message": "Paiement accepte",
                "responseCode": "200",
                "transactionRef": "1440685092164304",
                "type": "D",
                "ask3ds": 0,
                "auth3dsCode": null,
                "auth3dsMessage": null,
                "enrollment3dsCode": null,
                "enrollment3dsMessage": null,
                "askAutor": 1,
                "autorCode": "00",
                "autorNumber": "1234",
                "verifyEnrollment3dsMd": null,
                "verifyEnrollment3dsPareq": null,
                "verifyEnrollment3dsActionUrl": null,
                "verifyEnrollment3dsMpi": null,
                "subAccount": null
        },
        "responseCode": "200"
}

Recherche de transactions

Web service de recherche de transactions

https://secure.comnpay.com:60000/rest/payment/find

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
transactionRef Référence client de la transaction Longueur 40 maximum (optionnel)
transactionType Type de transaction D pour débit, C pour crédit (optionnel)
startDate Date de début de la recherche Format yyyyMMddHHmmss (optionnel)
endDate Date de fin de la recherche Format yyyyMMddHHmmss (optionnel)
limit Nombre limite de transactions Ignoré si <=0 (optionnel)
page N° de page, à partir de 1 Ignoré si <=0 (optionnel)

Retour : liste vide si aucun résultat, NULL si accès non autorisé. Exemple :

{
        "nbTransactions": 1,
        "transaction": [
                {
                        "transactionId": 6145,
                        "amount": 1590,
                        "ok": 1,
                        "confirmed": 1,
                        "cardAlias": "02EF4AFB171F94D2D560A2423BBBE306B0CBB6DE94686918BA0D0E54DB25635F",
                        "cardEndDate": "1612",
                        "cardTruncatedNumber": "111122XXXXXX4444",
                        "cardType": "CB",
                        "transactionDate": "20130628164913",
                        "message": "Paiement accepte",
                        "responseCode": "200",
                        "transactionRef": "1440685092164304",
                        "type": "D",
                        "binCountryCode": null,
                        "ask3ds": 0,
                        "auth3dsCode": null,
                        "auth3dsMessage": null,
                        "enrollment3dsCode": null,
                        "enrollment3dsMessage": null,
                        "askAutor": 1,
                        "autorCode": "00",
                        "autorNumber": "1234",
                        "verifyEnrollment3dsMd": null,
                        "verifyEnrollment3dsPareq": null,
                        "verifyEnrollment3dsActionUrl": null,
                        "verifyEnrollment3dsMpi": null,
                        "subAccount": null
                }
        ]
}

Duplicatas de tickets

Web services d'édition de duplicatas de tickets, aux formats :
  • HTML (chaîne de caractères)
  • PDF (fichier encodé en base 64)

https://secure.comnpay.com:60000/rest/receipt/getHtml

https://secure.comnpay.com:60000/rest/receipt/getPdfBase64

Paramètres POST, identiques pour les deux web services :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
transactionRef Référence client de la transaction Non nécessaire si transactionId renseigné
transactionId Id Afone de la transaction Non nécessaire si transactionRef renseigné

Retour : chaîne de caractères (texte HTML ou fichier encodé en base 64 pour PDF)

Pré-autorisation

Qu'est-ce que la pré-autorisation ?

C’est la possibilité offerte au commerçant de vérifier la validité d'une carte de paiement d'une part et s'assurer de la solvabilité du client d'autre part, sans pour autant avoir débité le compte.

Le commerçant a 3 possibilités d'action dans le délai qui lui est imparti :
  • débiter réellement le montant pré-autorisé,
  • annuler la pré-autorisation,
  • n'utiliser qu'une partie de la somme.

Ouverture d'un dossier de pré-autorisation

https://secure.comnpay.com:60000/rest/preauthorization/open

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
preauthorizationRef Référence client de la pré-autorisation Longueur 40 maximum
cardType Type de carte CB, VISA, MC
cardNumber Numéro de carte  
cardExpirationDate Date d'expiration de la carte Format AAMM
cvv Cryptogramme visuel  
amount Montant de la pré-autorisation En centimes
origin Origine du paiement (URL de votre site) URL à déclarer dans "Mes URLs"
ip Adresse IP de l'acheteur Utilisée par le module de géofiltrage
customer Formulaire porteur/acheteur Exemple de formulaire porteur

Clôture d'un dossier de pré-autorisation

https://secure.comnpay.com:60000/rest/preauthorization/close

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
fileNumber N° de dossier de préauto créé Retourné en réponse du web service d'ouverture
preauthorizationRef Référence client de la pré-autorisation Longueur 40 maximum
amount Montant du débit En centimes. Si 0, annulation du dossier

Réponse d'opération pré-autorisation

{
        "ok": 1,
        "message": "Paiement accepte",
        "preauthorization": {
                "preauthorizationId": 247,
                "fileNumber": "PA20150827000247",
                "amount": 1590,
                "status": "CLOSURE_OK",
                "cardAlias": "02EF4AFB171F94D2D560A2423BBBE306B0CBB6DE94686918BA0D0E54DB25635F",
                "cardEndDate": "1612",
                "cardTruncatedNumber": "111122XXXXXX4444",
                "cardType": "CB",
                "openDate": "20150827162645",
                "closureDate": "20150827162726",
                "autorCode": "00",
                "autorNumber": null,
                "message": "Paiement accepte",
                "responseCode": "200",
                "preauthorizationRef": "1440685605313683",
                "transactions": [
                        {
                                "transactionId": 6146,
                                "amount": 1590,
                                "ok": 1,
                                "confirmed": 1,
                                "cardAlias": "02EF4AFB171F9...D0E54DB25635F",
                                "cardEndDate": "1612",
                                "cardTruncatedNumber": "111122XXXXXX4444",
                                "cardType": "CB",
                                "transactionDate": "20150827162726",
                                "message": "Paiement accepte",
                                "responseCode": "200",
                                "transactionRef": "1440685646812DEMOSI344",
                                "type": "PA",
                                "binCountryCode": null,
                                "ask3ds": 0,
                                "auth3dsCode": null,
                                "auth3dsMessage": null,
                                "enrollment3dsCode": null,
                                "enrollment3dsMessage": null,
                                "askAutor": 1,
                                "autorCode": "00",
                                "autorNumber": "1234",
                                "verifyEnrollment3dsMd": null,
                                "verifyEnrollment3dsPareq": null,
                                "verifyEnrollment3dsActionUrl": null,
                                "verifyEnrollment3dsMpi": null,
                                "subAccount": null
                        }
                ],
                "subAccount": null
        },
        "responseCode": "200"
}

Statuts d'une pré-autorisation

Liste des statuts possible d'une pré-autorisation :
  • OPEN_OK : ouverture de pré-autorisation acceptée
  • OPEN_KO : ouverture de pré-autorisation refusée
  • CLOSURE_OK : clôture de pré-autorisation acceptée
  • CLOSURE_KO : clôture de pré-autorisation refusée (nouvelle tentative de clôture possible)
  • ABORT : pré-autorisation abandonnée (à l'initiative du commerçant)

Recherche de pré-autorisations

Web service de recherche de pré-autorisations

https://secure.comnpay.com:60000/rest/preauthorization/find

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
fileNumber N° de dossier de la préauto Ex : PA20130701000015 (optionnel)
preauthorizationRef Référence client de la préauto (optionnel)
startDate Date de début de la recherche Format yyyyMMddHHmmss (optionnel)
endDate Date de fin de la recherche Format yyyyMMddHHmmss (optionnel)
limit Nombre limite de pré-autorisations Ignoré si <=0 (optionnel)
page N° de page, à partir de 1 Ignoré si <=0 (optionnel)

Retour : liste vide si aucun résultat, NULL si accès non autorisé. Exemple :

{
        "nbPreauthorizations": 1,
        "preauthorization": [
                {
                        "preauthorizationId": 247,
                        "fileNumber": "PA20150827000247",
                        "amount": 1590,
                        "status": "CLOSURE_OK",
                        [...]
                        "transactions": [
                                {
                                        "transactionId": 6146,
                                        "amount": 1590,
                                        "ok": 1,
                                        [...]
                                }
                        ],
                        "subAccount": null
                }
        ]
}

Codes retours

Code Description
000 Traitement ok
001 Service indisponible
002 Configuration invalide
003 Volume de donnees depasse
004 Trop de tentatives
005 Champ obligatoire manquant
006 Fichier illisible
010 Acces interdit
011 IP interdite
012 Compte clos
013 Action interdite
040 Domaine inconnu
200 Paiement accepte
201 Service indisponible
202 Doublon transactionRef
203 Type de transaction invalide
204 Monnaie invalide
205 Montant invalide
206 Alias de carte inconnu
207 Carte refusee
208 Carte interdite
209 Carte invalide
210 carte perimee
211 La date de fin de validite de la carte est invalide
212 Le porteur n'est pas compatible 3DS
213 Type de carte invalide
214 Transaction inconnue
215 Carte en liste grise
216 Carte en liste noire
217 Montant maximum pour TPE virtuel atteint
218 Garantie refusee
2181 Garantie refusee suite expertise
219 Expertise garantie en cours
220 Aucune transaction en cours pour le porteur
221 Authentification porteur refusee
222 Porteur non inscrit au 3DS
223 3DS en cours
224 Incident 3DS, informations incompletes (md et/ou pares manquants)
225 Incident lors de l'authentification 3DS
230 Retour auto : incident technique
231 Retour auto : client interdit
232 Retour auto : refus banque
233 CVV absent
240 Preauto acceptee
241 Dossier inconnu
242 Cloture interdite
243 Dossier clos
244 Dossier annule
245 Montant de la cloture incorrect
246 Doublon reference de preauto
250 PNF interdit
251 Nombre max d'encours PNF atteint
252 Nombre max d'encours porteur PNF atteint
253 Dossier PNF inconnu
254 Avance de fonds deja versee
255 Montant d'encours PNF atteint
256 Montant d'encours PNF porteur atteint
257 Montant PNF trop eleve
260 Aucun debit initial abouti
261 Montant du recredit invalide
262 Recredit maximum mensuel atteint
263 Solde journalier insuffisant
264 Delai de recredit depasse
270 Doublon reference de token
271 Token inconnu
280 Session expiree
281 Transaction annulee
299 Transaction en cours
301 Nombre max encours porteur quotidien atteint
302 Montant max encours porteur quotidien atteint
303 Incoherence pays IP BIN
304 Blocage BIN pays
305 Blocage IP pays
306 Montant excessif
307 Nombre max encours quotidien atteint
308 Montant max encours quotidien atteint
309 Nombre max encours porteur mensuel atteint
310 Montant max encours porteur mensuel atteint
311 Nombre max encours mensuel atteint
312 Montant max encours mensuel atteint
313 Delai entre transaction porteur trop court
314 Nombre max encours minute atteint
315 Carte non francaise interdite en ETerminal
501 Verification humaine en cours
2500 Attente validation
2501 Avoir a valider par le siege
2502 Avoir refuse par le siege

Paiement récurrent

Comment effectuer un paiement récurent ?

  1. Effectuer un premier paiement via PSP (page de paiement) ou web service
  2. Appeler le web service de recherche de transactions, qui vous donnera l'alias créé pour la carte du paiement
  3. Pour les échéances suivantes, appeler le web service de paiement en utilisant en paramètre l'alias et non les coordonnées bancaires (n° carte, date de fin, CVV)

Formulaire porteur

Un formulaire porteur peut être poussé aux API de paiement. Il permet notamment :
  • de retrouver les informations du porteur sur le portail AfonePaiement (détail d'une opération, exports Excel)
  • l'envoi automatique du ticket de paiement sur l'adresse mail du porteur
{
        "firstName":"Jean",
        "lastName":"Dupont",
        "email":"jdupont@yopmail.com",
        "road":"5 Avenue de la Republique",
        "zipCode":"49100",
        "city":"Angers",
        "country":"France",
        "phone":"0606060606",
        "meetingDate":"20160630180000"
}
Champ Description Longueur maximum
firstName Prénom 100
lastName Nom 100
email Adresse mail 100
road Adresse postale 255
zipCode Code postal 10
city Ville 50
country Pays 50
phone Téléphone 20
meetingDate Date de rendez-vous 14 (format yyyyMMddHHmmss)

Connecteur / Client web service

Les connecteurs vous permettent une implémentation simple et rapide du paiement depuis votre système d'informations.

Java

Téléchargez le zip à cette adresse :

TÉLÉCHARGER
Il contient :
  • Le jar de connexion aux web services ComNpay
  • Le fichier de configuration comnpay.properties à personnaliser et ajouter à votre projet

Paramétrage comnpay.properties :

./static/comnpay-properties.png

Implémentation dans votre code java :

PaymentRequest paymentRequest = new PaymentRequest();
PaymentResponse paymentResponse = paymentRequest.debit("TESTREF000001", "CB", "1111222233334444", "2012", "123", 100);