ComNpay - Développeur

L'API

Introduction

Les web services exposés :
  • doivent être appelés en POST (Content-type x-www-form-urlencoded)
  • retournent des réponses formatées en JSON
Quelques règles d'accès aux API :
  • ComNpay se réserve le droit d'ajouter des champs aux retours JSON d'API
  • le droit d'utilisation de certaines API est soumis à validation (payment/aliasDebit par exemple)

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

./static/tokenisation.gif

La mise en place du paiement doit se faire via tokenisation. Un token est tout d'abord généré via un premier appel d'API.

Ce premier appel d'API doit se faire directement côté client, sans passer par votre serveur pour garantir une sécurité des données de cartes

Vous pouvez télécharger un exemple d'utilisation de cette méthode en Javascript

TÉLÉCHARGER

1-Génération d'un token

Vous devez générer un token qui résulte des informations de la carte

https://secure.comnpay.com:60000/rest/token/create

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
cardNumber Numéro de carte Cartes de test
cardExpirationDate Date d'expiration de la carte Format AAMM
cvv Cryptogramme visuel  
cardType Type de carte CB, VISA, MC
origin Origine du paiement (URL de votre site) URL à déclarer dans vos URL

Réponse

{
    "ok": 1,
    "message": "",
    "token": {
        "serialNumber": "VAD-111-111",
        "tokenRef": "TK1533224578211DEMO364",
        "cardExpirationDate": "1222",
        "cardType": "CB",
        "truncatedCardNumber": "111122XXXXXX4444"
    }
    "responseCode": "000"
}

2-Paiement via token

Côté serveur, vous devez finaliser le paiement grâce à ce token précédemment généré (ne sauvegardez pas les informations de la carte, seul le token est nécessaire).

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

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
tokenRef Token précédemment généré  
transactionRef Référence client de la transaction Longueur min 8 / Longueur max 40
amount Montant de la transaction en centime 1590 pour 15.90€
force3ds Permet le forçage ou l'interdiction du 3DS 1 pour forcer 3DS, 0 pour cas standard (seuil, géofiltrage)
redirection3DSV2Url Obligatoire pour le 3DS V2 Redirection pour effetuer le 3D Secure V2
browser Obligatoire pour le 3DS V2 Pour les applications mobiles, le champ application est obligatoire à la place
customer Fortement conseillé pour le 3DS V2  
cardholderAccount Conseillé pour le 3DS V2  
caddy Conseillé pour le 3DS V2  

3-Reprise débit après authentification 3DS V1

Etape 1 :

Si une interrogation 3D Secure est requise, la réponse de débit portera :
  • à la racine le champ actionCode valorisé à AUTH_3DS_REQUISE
  • le champ transaction.verifyEnrollment3dsV1 à true
  • 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",
        "verifyEnrollment3dsCreq":"",
        "verifyEnrollment3dsActionUrl":"https://homologation.comnpay.com/3ds.html",
        "verifyEnrollment3dsV1":true
    },
    "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="mS2i8y6R1L60yX6aH3971qN9jX64VwxBbmM9b..."/>
</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é  
transactionRef Référence client de la transaction Longueur min 8
pares Valeur du champ "PaRes" Retourné via formulaire après authentification 3DS
md Valeur du champ "MD" Retourné via formulaire après authentification 3DS

3-Reprise débit après authentification 3DS V2

Etape 1 :

Si une interrogation 3D Secure 2 est requise, la réponse de débit portera :
  • à la racine le champ actionCode valorisé à AUTH_3DS_REQUISE
  • le champ transaction.verifyEnrollment3dsV1 à false
  • le champ transaction.verifyEnrollment3dsActionUrl avec l'URL vers laquelle rediriger le porteur
  • le champs transaction.verifyEnrollment3dsCreq permettant de pousser l'info creq vers la page d'authentification

Exemple :

{
    "ok":1,
    "message":"ok",
    "transaction":{
        "transactionId":2630,
        "amount":200,
        [...]
        "verifyEnrollment3dsMd":"",
        "verifyEnrollment3dsPareq":"",
        "verifyEnrollment3dsCreq":"4DG678VEgfs587DF878sg78sq686T86",
        "verifyEnrollment3dsActionUrl":"https://homologation.comnpay.com/3ds.html",
        "verifyEnrollment3dsV1":false
    },
    "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 le paramètre :
  • creq

La redirection se fera via l'URL définie dans la paramètre redirection3DSV2Url

Exemple :

<form action="https://homologation.comnpay.com/3ds.html"
        id="3ds" method="post">
 <input type="hidden" name="creq"
        value="4DG678VEgfs587DF878sg78sq686T86"/>
</form>

Etape 3 :

Lors de cette redirection, vous allez récupérer en POST le paramètre cres, 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é  
transactionRef Référence client de la transaction Longueur min 8
cres Valeur du champ "cres" Retourné via formulaire après authentification 3DS

Création d'alias

La création d'alias se fait également via la génération d'un token au préalable

https://secure.comnpay.com:60000/rest/alias/tokenCreate

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
tokenRef Token généré  
aliasRef Référence client de la transaction  
origin Origine du paiement (URL de votre site) URL à déclarer dans vos URL

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 min 8 / Longueur max 40
alias Alias de carte  
cvv CVV de la carte à redemander au client Vous ne devez pas le stocker sur votre application, mais bien le redemander au client
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 vos
redirection3DSV2Url Obligatoire pour le 3DS V2 Redirection pour effetuer le 3D Secure V2
browser Obligatoire pour le 3DS V2 Pour les applications mobiles, le champ application est obligatoire à la place
customer Fortement conseillé pour le 3DS V2  
cardholderAccount Conseillé pour le 3DS V2  
caddy Conseillé pour le 3DS V2  

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 Longueur min 8
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",
        "rejectDate": null,
        "responseCode": "200",
        "message": "Paiement accepte",
        "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,
        "source": "API",
        "origin": "mywebsite.com",
        "initLogin": 10000012345,
        "memo1Clic": false,
        "subAccount": null,
        "customer": {
            "road": null,
            "zipCode": null,
            "email": "tjanvier@comnpay.com",
            "lastName": null,
            "country": null,
            "firstName": null,
            "quality": null,
            "phone": null,
            "city": null,
            "meetingDate": null,
            "vatNumber": null,
            "fiscalCode": null
        },
        "payperlink": {
            "payperlinkId": "18542911b61b2701873acb9ae25790eb",
            "paymentType": "D",
            "beginDate": "20180704161544",
            "endDate": "20180704161852",
            "maxQuantity": 1,
            "language": null,
            "urlOk": null,
            "urlNok": null,
            "productReference": null,
            "productLabel": null,
            "amount": 14600,
            "customer": null,
            "creationDate": "20180704161544",
            "deferredPaymentDate": null,
            "suppressionDate": null,
            "nbPayments": 1,
            "template": null,
            "deadlinePeriod": null,
            "nextDeadlineDate": null,
            "deadlineFrequency": 0,
            "deadlineDay": 0,
            "timetableEndDate": 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 min 8 / Longueur max 40 (optionnel)
transactionType Type de transaction D pour débit, C pour crédit (optionnel)
cardAlias Alias de carte (optionnel)
startDate Date de début de la recherche Format yyyyMMddHHmmss (optionnel)
endDate Date de fin de la recherche Format yyyyMMddHHmmss (optionnel)
payperlinkId Identifiant du lien de paiement Voir section creation d'un lien de paiement
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,
            "source": "API",
            "origin": "mywebsite.com",
            "subAccount": null,
                            [...]
        }
    ]
}

Recherche d'alias

Web service de recherche d'alias

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

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
aliasRef Référence client de l'alias Longueur 40 maximum (optionnel)
transactionType Type de transaction D pour débit, C pour crédit (optionnel)
cardAlias Alias de carte (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 :

{
  "nbAliases": 1,
  "alias": [
    {
      "cardAlias": "02EF4AFB171F94D2D560A2423BBBE306B0CBB6DE94686918BA0D0E54DB25635F",
      "cardEndDate": "1901",
      "cardTruncatedNumber": "111122XXXXXX4444",
      "cardType": "MC",
      "addDate": "20160905095417",
      "lastOperationDate": "20160905095433",
      "aliasRef": "1473062054DEMOSI185",
      "ok": 1,
      "confirmed": 1,
      "message": "Paiement accepte",
      "responseCode": "200",
      "askAutor": 1,
      "autorCode": "00",
      "autorNumber": "1234"
    }
  ]
}

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 Longueur min 8

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

Comme pour le débit, l'ouverture d'une pré-autorisation se fait via token

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

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
tokenRef Token précédemment généré  
preauthorizationRef Référence client de la préauto Longueur 40 maximum
amount Montant de la transaction en centime 1590 pour 15.90€
force3ds Permet le forçage ou l'interdiction du 3DS 1 pour forcer 3DS, 0 pour cas standard (seuil, géofiltrage)
redirection3DSV2Url Obligatoire pour le 3DS V2 Redirection pour effetuer le 3D Secure V2
browser Obligatoire pour le 3DS V2 Pour les applications mobiles, le champ application est obligatoire à la place
customer Fortement conseillé pour le 3DS V2  
cardholderAccount Conseillé pour le 3DS V2  
caddy Conseillé pour le 3DS V2  

Reprise pré-autorisation 3DS

Même principe que la repise de paiement 3DS en débit, avec l'API :

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

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éauto  
pares Valeur du champ "PaRes" Retourné via formulaire après authentification 3DS
md Valeur du champ "MD" Retourné via formulaire après authentification 3DS

Ouverture d'un dossier de pré-autorisation depuis un alias

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

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
alias Alias de carte  
cvv Cryptogramme visuel Obligatoire pour déclencher un 3DS
amount Montant de la pré-autorisation En centimes
origin Origine du paiement (URL de votre site) URL à déclarer dans vos URL
redirection3DSV2Url Obligatoire pour le 3DS V2 Redirection pour effetuer le 3D Secure V2
browser Obligatoire pour le 3DS V2 Pour les applications mobiles, le champ application est obligatoire à la place
customer Fortement conseillé pour le 3DS V2  
cardholderAccount Conseillé pour le 3DS V2  
caddy Conseillé pour le 3DS V2  

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

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

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,
                "source": "API",
                "origin": "mywebsite.com",
                "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
        }
    ]
}

Paiement en 3 fois

Recherche de dossier P3F

Web service de recherche de dossier de paiement en 3 fois.

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

Paramètres POST :

Paramètre Description Commentaire
serialNumber N° de série du terminal virtuel  
key Clé de sécurité  
fileNumber Référence de dossier P3F Ex PNF2016041415997
transactionRef Référence de la transaction initiale Longueur min 8
amount Montant total du dossier  
cardNumber Numéro de carte tronqué  
status Statut du dossier REFUSED/PENDING/EXPERTISE/ERROR/CLOSED/CANCELED
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 résultats Ignoré si <=0 (optionnel)
page N° de page, à partir de 1 Ignoré si <=0 (optionnel)

Réponse

{
    "nbPnfFiles": 1,
    "pnfFile": [
        {
            "fileNumber": "PNF2018071415445",
            "amount": 17980,
            "cardAlias": "02EF4AFB171F...B25635F",
            "cardEndDate": "2006",
            "cardTruncatedNumber": "111122XXXXXX4444",
            "entryDate": "20180714163358",
            "statusDate": "20180813164601",
            "status": "PENDING",
            "initLogin": null,
            "pnfTransactions": [
                {
                    "term": 1,
                    "amount": 5993,
                    "ok": 1,
                    "canceled": 0,
                    "cardAlias": "02EF4AFB171F...B25635F",
                    "cardEndDate": "2006",
                    "cardTruncatedNumber": "111122XXXXXX4444",
                    "cardType": "CB",
                    "plannedDate": "20180714163358",
                    "transactionDate": "20180714163517",
                    "message": "Paiement accepte",
                    "responseCode": "200",
                    "retries": 1
                },
                {
                    "term": 2,
                    "amount": 5993,
                    [...]
                },
                {
                    "term": 3,
                    [...]
                }
            ],
            "customer": {
                "email": "tjanvier@comnpay.com",
                [...]
            }
        }
    ]
}

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
007 Demande hors delai
008 Demande dupliquee
009 Parametre invalide
010 Acces interdit
011 IP interdite
012 Compte clos
013 Action interdite
040 Domaine inconnu
060 Campagne inconnue
061 Erreur lors de l'envoi du mail
070 Donnees porteur invalides
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
272 Alias cree
280 Session expiree
281 Transaction annulee
282 Transaction abandonnee
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
320 Porteur refuse
321 Bin bloque
322 Nombre max encours IP atteint
350 Montant transfert domestique atteint
351 Montant transfert international atteint
352 Montant transferts domestiques par jour atteint
353 Montant transferts internationaux par jour atteint
354 Nombre transferts domestiques par jour atteint
355 Nombre transferts internationaux par jour atteint
356 Montant transferts domestiques par mois atteint
357 Montant transferts inernationaux par mois atteint
358 Nombre transferts domestiques par mois atteint
359 Nombre transferts internationaux par mois atteint
360 Montant transferts domestiques par jour par iban atteint
361 Montant transferts international par jour par iban atteint
362 Nombre transferts domestiques par jour par iban atteint
363 Nombre transferts internationaux par jour par iban atteint
364 Montant transferts domestiques par mois par iban atteint
365 Montant transferts inernationaux par mois par iban atteint
366 Nombre transferts domestiques par mois par iban atteint
367 Nombre transferts internationaux par mois par iban atteint
501 Verification humaine en cours
602 Contacter l'emetteur de carte
603 Accepteur invalide
604 Conserver la carte
605 Ne pas honorer
607 Conserver la carte, conditions speciales
610 Approuvee partiellement (non autorisee)
612 Transaction invalide
613 Montant invalide
614 Numero de porteur invalide
615 Emetteur de carte inconnu
617 Annulation client
619 Repeter la transaction ulterieurement
620 Reponse erronee (erreur dans le domaine serveur)
624 Mise a jour de fichier non supportee
625 Impossible de localiser l'enregistrement dans le fichier
626 Enregistrement duplique, ancien enregistrement remplace
627 Erreur en edit sur champ de mise a jour fichier
628 Acces interdit au fichier
629 Mise a jour de fichier impossible
630 Erreur de format
631 Identifiant de l'organisme acquereur inconnu
633 Date de validite de la carte depassee
634 Suspicion de fraude
638 Nombre d'essais code confidentiel depasse
641 Carte perdue
643 Carte volee
651 Provision insuffisante ou credit depasse
654 Date de validite de la carte depassee
655 Code confidentiel errone
656 Carte absente du fichier
657 Transaction non permise a ce porteur
658 Transaction interdite au terminal
659 Suspicion de fraude
661 Montant de retrait hors limite
663 Regles de securite non respectees
668 Reponse non parvenue ou recue trop tard
675 Nombre d'essais code confidentiel depasse
676 Porteur deja en opposition, ancien enregistrement conserve
690 Arret momentane du systeme
694 Demande dupliquee
696 Mauvais fonctionnement du systeme
697 Echeance de la temporisation de surveillance globale
698 Serveur indisponible routage reseau demande a nouveau
699 Incident domaine initiateur
2001 Date signature invalide
2002 RUM invalide
2003 Signature en cours
2004 Signature annulee
2005 Echec signature
2006 Remise inconnue
2007 Statut remise invalide
2008 Remise refusee
2009 IBAN BIC invalides
2010 Rejet technique
2011 Seuil IBAN KO atteint
2012 IBAN donneur ordre invalide
2013 Prelevement inconnu
2014 ICS invalide
2015 Date reglement invalide
2016 Coord. Banc.inexploitable
2017 Compte solde cloture vire / Compte cloture
2018 Opposition sur compte / Compte bloque - Prelevement SEPA interdit par le debiteur sur ce compte
2019 Le titulaire du compte est un consommateur
2020 Operation non admise
2021 Code operation incorrect
2022 Provision insuffisante
2023 Doublon
2024 Operation d'origine deja retournee
2025 Adresse invalide
2026 Emetteur non reconnu
2027 Sur ordre du client
2028 Doublon
2029 Format invalide (Ex MD03)
2030 Type de prelevement incorrect
2031 Retour en reponse positive a un Recall
2032 Virement d'origine frauduleuse
2033 Motif reglementaire
2034 Pas d'autorisation / Absence de mandat
2035 Donnee mandat incorrecte
2036 Contestation debiteur / Contestation d'une operation autorisee
2037 Titulaire decede
2038 Sur ordre du client / Refus du debiteur
2039 Raison non communiquee
2040 Pas d'autorisation
2041 Recu a tort car operation d'origine non reeue
2042 Code banque incorrect / Identifiant bancaire incorrect
2043 Motif reglementaire
2044 Motif reglementaire
2045 Motif reglementaire
2046 Motif reglementaire
2047 Service specifique
2048 SCT non conforme du a un probleme technique
2049 Heure limite depassee
2050 Code BIC errone
2051 Format de donnee invalide
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)

Dictionnaire de données

Trouvez ci-dessous une liste de champs spécifiques aux API :

Champ Description Exemple/valeurs
cardType Type de carte CB/VISA/MC/AMEX
origin Site web d'origine du paiement www.mywebsite.com
source Source du paiement API/PSP/VPI(eTerminal)
subAccount Sous-compte de destination du paiement (marketplace) SA000001
type Type de transaction D/C/PA/P3F/ALS

Formulaire porteur

Avec la mise en place du 3D Secure V2, il est fortement conseillé de remplir le plus de champs possibles. Le formulaire est considéré comme l'un des plus important. Le scoring de la transaction sera donc bien meilleur, et permettra d'éviter une authentification forte, tout en garantissant le paiement par la banque du porteur.

Il permet également :
  • 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": "Thomas",
    "lastName": "Janvier",
    "email": "tjanvier@comnpay.com",
    "phone": "+33606060606",
    "personalPhone": "+33241565858",
    "professionalPhone": "+33707070707",
    "road": "tjanvier@comnpay.com",
    "road2": "Bâtiment B",
    "road3": "Appartement B315",
    "zipCode": "49100",
    "city": "Angers",
    "country": "France",
    "shipRoad": "11 boulevard Maréchal Foch",
    "shipRoad2": "",
    "shipRoad3": "",
    "shipZipCode": "49100",
    "shipCity": "ANGERS",
    "shipCountry": "FRANCE",
    "meetingDate": "20160630180000",
    "customerRef": "YOURID-ABCD1234"
}
Champ Description Longueur maximum
firstName Prénom 100
lastName Nom 100
email Adresse mail 100
phone Téléphone 20
personalPhone Téléphone personnel 20
professionalPhone Téléphone professionnel 20
road Adresse postale 255
road2 Adresse postale complémentaire 255
road3 Adresse postale complémentaire 255
zipCode Code postal 10
city Ville 50
country Pays 50
shipRoad Adresse postale livraison 255
shipRoad2 Adresse postale complémentaire livraison 255
shipRoad3 Adresse postale complémentaire livraison 255
shipZipCode Code postal livraison 10
shipCity Ville livraison 50
shipCountry Pays 50
meetingDate Date de rendez-vous Utilisée uniquement pour l'hôtellerie avec la vérification de carte à J-X avant arrivée 14 (format yyyyMMddHHmmss)
customerRef Référence unique de client 40
  • Ce formulaire doit être envoyé au format JSON
  • Nous vous conseillons de renseigner les numéros de téléphone au format international. Cela vous sera utile notamment pour le paiement par prélèvement SEPA. Le numéro de téléphone sera alors déjà pré-rempli

Application

Avec la mise en place du 3D Secure V2, il est obligatoire de remplir ce champ pour les applications.

{
    "browserIP": "192.168.14.10",
    "browserLanguage": "fr",
}
Champ Description Code
browserIP IP du navigateur  
browserLanguage Langage utilisé par l'application  

Ce formulaire doit être envoyé au format JSON

Information compte porteur

Avec la mise en place du 3D Secure V2, il est conseillé de remplir le plus de champs possibles.

{
   "chAccDate": "20200130",
   "chAccChange": "20200215",
   "chAccPwChange": "20201001",
   "shipAddressUsage": "20200216",
   "txnActivityDay": 0,
   "txnActivityYear": 12,
   "provisionAttemptsDay": 1,
   "nbPurchaseAccount": 4,
   "suspiciousAccActivity": "01",
   "shipNameIndicator": "01"
}
  • Ce formulaire doit être envoyé au format JSON
  • chAccDate : Date d'ouverture de compte
  • chAccChange : Date de dernière modification du compte
  • chAccPwChange : Date de dernier changement de mot de passe
  • shipAddressUsage : Date de première utilisation de l'adresse de livraison
  • txnActivityDay : Nombre de transactions (réussies et abandonnées) pour ce compte du titulaire de la carte au cours des 24 heures précédentes
  • txnActivityYear : Nombre de transactions (réussies et abandonnées) pour ce compte du titulaire de la carte au cours de l'année passée
  • provisionAttemptsDay : Tentatives d'ajout de cartes sur ce compte du titulaire
  • nbPurchaseAccount : Nombre d'achat au court (transactions réussies) des 6 derniers mois
  • suspiciousAccActivity :
    • "01" : Pas d'activité suspicieuse
    • "02" : Une activité suspicieuse a été observée
  • shipNameIndicator :
    • "01" : Le nom du compte est similaire au nom de livraison
    • "02" : Le nom du compte est différent du nom de livraison

Panier

Avec la mise en place du 3D Secure V2, il est conseillé de remplir le plus de champs possibles.

{
    "shipIndicator": "01",
    "deliveryTimeframe": "01",
    "deliveryEmailAddress": "tjanvier@comnpay.com",
    "reorderItemsInd": "01",
    "preOrderPurchaseInd": "01",
    "preOrderDate": "20220520",
    "giftCardAmount": 12,
    "nbCarteCadeau": 1
}
  • Ce formulaire doit être envoyé au format JSON
  • shipIndicator : Mode d'expédition choisi pour la transaction
    • "01" : Envoi à l'adresse de facturation du titulaire de la carte
    • "02" : Envoi à une autre adresse vérifiée par le commerçant
    • "03" : Envoi à une adresse différente de l'adresse de facturation du titulaire de la carte
    • "04" : "Clic and collect" : Enlèvement dans un magasin local
    • "05" : Biens numériques (comprend les services en ligne, les cartes cadeaux électroniques, ...)
    • "06" : Billets de voyage et d'événements, non expédiés
    • "07" : Autres (par exemple, jeux, services numériques non livrés, abonnements à des médias électroniques, etc.)
  • deliveryTimeframe : Délai de livraison
    • "01" : Livraison électronique
    • "02" : Expédition le jour même
    • "03" : Expédition de nuit
    • "04" : Expédition en deux jours ou plus
  • reorderItemsInd :
    • "01" : Première commande
    • "02" : Recommande d'un même panier
  • preOrderPurchaseInd :
    • "01" : Marchandise disponible
    • "02" : Bientôt disponible
  • giftCardAmount : Pour un achat de carte prépayée ou de carte cadeau, le montant total de l'achat de la ou des cartes prépayées ou de la ou des cartes cadeaux sans les centimes (par exemple, 12,45 € est 12)
  • giftCardCount : Pour l'achat de cartes prépayées ou de cartes-cadeaux, le nombre total des cartes prépayées ou des cartes-cadeaux/codes achetés. Le champ est limité à 2 caractères

Exemple rapide : requête cURL en PHP

cURL (abréviation de client URL request library : « bibliothèque de requêtes aux URL pour les clients ») est une
interface en ligne de commande, destinée à récupérer le contenu d'une ressource accessible par un réseau informatique.

L'exemple suivant permet d'initialiser le paiement pour un montant de 10.00€ sur la carte 1111222233334444

N'oubliez pas de remplacer le champ 'serialNumber' et 'key' par vos identifiants de paiements

<?php
$webService = 'https://secure.comnpay.com:60000/rest/payment/tokenDebit';
$postFields = array(
    'serialNumber'       => 'VAD-111-111',
    'key'                => '6RLl4FlO2o4ZvAdflK2p',
    'transactionRef'     => 'test',
    'tokenRef'           => 'DHS73993HEHUD8HJZ'
    'amount'             => 1000,
    'force3ds'           => 0,
    'ip'                 => $_SERVER['REMOTE_ADDR'],
    'customer' => json_encode(array(
        "firstName"=>"Thomas",
        "lastName"=>"Janvier",
        "email"=>"tjanvier@comnpay.com",
        "phone"=>"+33606060606",
        "personalPhone"=>"+33241565858",
        "professionalPhone"=>"+33707070707",
        "road"=>"tjanvier@comnpay.com",
        "road2"=>"Bâtiment B",
        "road3"=>"Appartement B315",
        "zipCode"=>"49100",
        "city"=>"Angers",
        "country"=>"France",
        "shipRoad"=>"11 boulevard Maréchal Foch",
        "shipRoad2"=>"",
        "shipRoad3"=>"",
        "shipZipCode"=>"49100",
        "shipCity"=> "ANGERS",
        "shipCountry"=> "FRANCE",
        "meetingDate"=>"20160630180000",
        "customerRef"=>"YOURID-ABCD1234"
    )),
    'browser' => json_encode(array(
       "browserAcceptHeader":"Accept: ...
                               Accept-Charset: ...
                               ...",
        "browserIP"=>"192.168.14.10",
        "browserJavaEnabled"=>true,
        "browserLanguage"=>"fr",
        "browserColorDepth"=>24,
        "browserScreenHeight"=>1080,
        "browserScreenWidth"=>1920,
        "browserTZ"=>"-120",
        "browserUserAgent"=>"Mozilla/5.0 (Wi...",
        "challengeWindowSize"=>"05",
        "browserJavascriptEnabled"=>true,
    )),
    'cardholderAccount' => json_encode(array(
       "chAccDate"=>"20200130",
       "chAccChange"=>"20200215",
       "chAccPwChange"=>"20201001",
       "shipAddressUsage"=>"20200216",
       "txnActivityDay"=>0,
       "txnActivityYear"=>12,
       "provisionAttemptsDay"=>1,
       "nbPurchaseAccount"=>4,
       "suspiciousAccActivity"=>"01",
       "shipNameIndicator"=>"01",
    )),
    'caddy' => json_encode(array(
       "shipIndicator"=>"01",
        "deliveryTimeframe"=>"01",
        "deliveryEmailAddress"=>"tjanvier@comnpay.com",
        "reorderItemsInd"=>"01",
        "preOrderPurchaseInd"=>"01",
        "preOrderDate"=>"20220520",
        "giftCardAmount"=>12,
        "nbCarteCadeau"=>1
    ))
);
$datasString = http_build_query($postFields);
$ch = curl_init();
curl_setopt($ch,CURLOPT_URL, $webService);
curl_setopt($ch,CURLOPT_POSTFIELDS, $datasString);
$result = curl_exec($ch);
curl_close($ch);
echo $result;
?>

Cartes de test

Voici les cartes qui peuvent être utilisées pour simuler les différents encaissements en homologation :

Sans 3D Secure : Tout paiement strictement inférieur à 30€

Pour tout paiement supérieur ou égal à 30€ :

  • 3D Secure V1 : 2221001892683407
  • 3D Secure V2 avec authentification : 5306889942833340 > Le code à saisir dans la page d'authentification est 1234
  • 3D Secure V2 sans authentification ("frictionless") : 5512459816707530