API
Introduction
Pour offrir une expérience facile à utiliser, nous proposons des bibliothèques Python, Perl ou PHP, et nous continuerons d’étoffer ce catalogue.
Des exemples de code sont disponibles dans chaque section. Les onglets disponibles dans le menu vous permettent de basculer vers les différents languages de programmations.
L’API est disponible sur https://api.stancer.com/ et supporte TLS 1.2, HTTP/1.1 et HTTP/2.
INFO
Cette documentation utilise httpie(https://httpie.io/) pour les exemples en shell, et nos libraries pour les exemples en PHP, Python & Perl.
Par simplification des exemples, l’authenfication par votre clé d’API (--auth stest_xxx:) est omise dans les lignes de commande proposées, mais vous devez la fournir à chaque appel.
Concepts clés
L’API est disponible sur https://api.stancer.com et supporte TLS 1.2, HTTP/1.1 et HTTP/2.
La même API peut être utilisée pour accéder aux ressources live traitant les paiements réels et méthodes de paiement, mais aussi des ressources de test pour le développement de vos logiciels et le débogage. Notre service API utilise des clés d’API pour authentifier les requêtes.
Pour obtenir une clé API, vous pouvez vous inscrire sur notre site web. Les clés API sont sous la forme de sprod_xxx pour vos requêtes live et stest_xxx pour vos test.
L’authentification à l’API est effectuée via HTTP Basic Auth. Vous devez utiliser votre clé API comme nom d’utilisateur et ne fournir aucun mot de passe.
Nous vous conseillons d’utiliser le mécanisme d’authentification de base de bibliothèque HTTP, mais si vous devez le gérer manuellement, comme spécifié dans HTTP Basic Auth, vous devez encoder votre clé API en base64 avant d’envoyer l’authentification correspondante dans un en-tête HTTP Authorization. Par exemple, si votre clé API est sprod_xxx, vous devez encoder sprod_xxx: (rappelez-vous, le mot de passe doit être vide) en base64 (ce qui donne c3Byb2RfeHh4Og==) puis envoyer un Autorisation: Basic c3Byb2RfeHh4Og== en-tête HTTP.
Cette documentation se concentre sur les workflows des cas d’utilisation courants. Pour une documentation plus complète ou technique, veuillez consulter notre documentation OpenAPI Swagger ou Redoc.
Si vous avez besoin d’assistance technique sur l’intégration de notre API, vous pouvez rejoindre notre Slack communautaire.
Créer des paiements
Avec la page de paiement de Stancer
$ http https://api.stancer.com/v2/customers/ \
name="Foo Bar" email=foo.bar@example.org
{
"id": "cust_xxx",
…
}
$ http https://api.stancer.com/v2/payments/ \
currency=eur amount=100 customer=cust_xxx description="Test payment" auth=True
{
"id": "paym_xxx",
…
}Pour créer un paiement, utilisez la méthode POST /v2/payment_intents/. Vous devez au moins fournir une devise (eur par défaut) et un montant.
Si vous souhaitez associer le paiement à un client, vous pouvez utiliser le champ customer et transmettez l’ID cust_xxx correspondant.
Dans le cas des paiements basiques (objet payment et méthode POST /v2/payments/), vous devez forcer la validation 3DS avec le paramètre auth=true. Sinon, votre client ne pourra pas procéder au paiement, car sa banque refusera sûrement un paiement non authentifié. Dans le cas des intentions de paiement (objet payment_intent et méthode POST /v2/payment_intents/), la validation 3DS est directement active par défaut sans avoir besoin de paramètre supplémentaire.
Vous pouvez maintenant envoyer votre client sur la page de paiement située sur https://payment.stancer.com/payment_intents/<pi_xxx>. Remplacez l’ID de paiement en conséquence.
Une fois le paiement créé, vous pouvez le modifier jusqu’à sa capture par exemple pour refléter un changement d’achat, en utilisant la méthode PATCH /v2/payment_intents/{id}.
$ http https://api.stancer.com/v2/payments/paym_xxx amount=200Avec l’API
Vous pouvez spécifier une URL de retour avec le paramètre return_url. À la fin du processus 3DS, nous redirigerons votre client vers cette URL.
$ http https://api.stancer.com/v2/cards/ \
name="Foo Bar" number=4242424242424242 exp_month=10 exp_year=2024 cvc=424
{
"id": "card_xxx",
…
}
$ http https://api.stancer.com/v2/payments/ \
currency=eur amount=100 customer=cust_xxx description="Test payment" \
card=card_xxx auth[return_url]=http://example.org
{
"id": "paym_xxx",
"auth": {
"redirect_url": "https://3ds.iliad78.net/v2/redirect/xxx",
…
}
…
}Envoyez ensuite votre client sur le auth[redirect_url] donné pour permettre la récupération des données de carte bancaire et la validation éventuelle de 3DS si nécessaire. Après la redirection vers votre return_url, vous devez vérifier la validité de l’authentification, puis capturer le paiement si tout va bien.
$ http https://api.stancer.com/v2/payments/paym_xxx
{
…
"auth": {
"status": "success"
}
}
$ http PATCH https://api.stancer.com/v2/payments/paym_xxx \
status=captureSi vous préférez collecter vous-même le numéro de carte, vous pouvez traiter un paiement directement et obtenir un identifiant de carte (tokenisation) avec POST /v2/cards/ avant de l’utiliser ailleurs dans les appels d’API. Dans ce mode, étant donné que vous manipulez directement les numéros de carte en clair, vous avez cependant des obligations réglementaires de conformité PCI/DSS à mettre en œuvre, dépendant de votre volumétrie.
$ http https://api.stancer.com/v2/cards/ number=4242424242424242 month=8 year=2026 name="Jean Dupont"
{
"id": "card_xxx",
…
}
$ http https://api.stancer.com/v2/payments/ \
currency=eur amount=100 customer=cust_xxx card=card_xxx description="Test payment" \
card=card_xxx auth[return_url]=http://example.orgAPI status code
Payment status
Le champ status de l’objet de paiement indique dans quel état se trouve le paiement.
| Status | Meaning |
|---|---|
| authorized | The bank authorized the payment but the transaction will only be processed after asking for capture |
| to_capture | The bank authorized the payment, money will be processed within the day |
| capture_sent | The capture operation is being processed, the payment can not be cancelled anymore, refunds must wait the end of the capture process |
| captured | The amount of the payment have been credited to your account |
| disputed | The customer declined the payment after it have been captured on your account |
| expired | The authorisation was not captured and expired after 7 days |
| failed | The payment has failed, refer to the response field for more details |
| refused | The payment has been refused |
Authenticated payment status codes
The status field in the auth object returns the authorisation state for an authenticated payment.
| Status | Meaning |
|---|---|
| available | Customer strong authentication is possible |
| requested | A strong authentication is awaiting for more information |
| attempted | Customer was redirected to his bank for authentication |
| success | Authentication succeeded, processing can continue |
| declined | Authentication declined |
| expired | Authentication sessions expired after 6 hours |
| failed | Authentication failed |
| unavailable | The strong authentication is not available for this payment method |
Payout status codes
The status field in the payout explains in which state is the credit transfer which wires funds from Stancer to your bank.
| Status | Meaning |
|---|---|
| pending | The payout has been created and is awaiting for clearing |
| to_pay | The payout is ready to be transfered |
| sent | The payout has been sent out for processing |
| paid | The payout credit transfer has been processed: funds have been received by your bank |
| failed | The credit transfer has failed, please refer to you dashboard for more informations |
Card response codes
⚠️ = real code & reason must not be sent to the customer, replace them with a generic 05 do-not-honor.
| Code | Meaning |
|---|---|
| 00 | Successful approval/completion or that VIP PIN verification is valid |
| 01 | Refer to card issuer |
| 02 | Refer to card issuer, special condition |
| 03 | Invalid merchant or service provider |
| 04 | Pickup |
| 05 | Do not honor |
| 06 | General error |
| 07 | Pickup card, special condition (other than lost/stolen card) |
| 08 | Honor with identification |
| 09 | Request in progress |
| 10 | Partial approval |
| 11 | VIP approval |
| 12 | Invalid transaction |
| 13 | Invalid amount (currency conversion field overflow) or amount exceeds maximum for card program |
| 14 | Invalid account number (no such number) |
| 15 | No such issuer |
| 16 | Insufficient funds |
| 17 | Customer cancellation |
| 19 | Re-enter transaction |
| 20 | Invalid response |
| 21 | No action taken (unable to back out prior transaction) |
| 22 | Suspected Malfunction |
| 25 | Unable to locate record in file, or account number is missing from the inquiry |
| 28 | File is temporarily unavailable |
| 30 | Format error |
| 41⚠️ | Merchant should retain card (card reported lost) |
| 43⚠️ | Merchant should retain card (card reported stolen) |
| 51 | Insufficient funds |
| 52 | No checking account |
| 53 | No savings account |
| 54 | Expired card |
| 55 | Incorrect PIN |
| 56 | Card missing from file |
| 57 | Transaction not permitted to cardholder |
| 58 | Transaction not allowed at terminal |
| 59⚠️ | Suspected fraud |
| 61 | Activity amount limit exceeded |
| 62⚠️ | Restricted card (for example, in country exclusion table) |
| 63⚠️ | Security violation |
| 65⚠️ | Activity count limit exceeded |
| 68 | Response received too late |
| 75 | Allowable number of PIN-entry tries exceeded |
| 76 | Unable to locate previous message (no match on retrieval reference number) |
| 77 | Previous message located for a repeat or reversal, but repeat or reversal data are inconsistent with original message |
| 78 | ’Blocked, first used’—The transaction is from a new cardholder, and the card has not been properly unblocked. |
| 80 | Visa transactions: credit issuer unavailable. Private label and check acceptance: Invalid date |
| 81 | PIN cryptographic error found (error found by VIC security module during PIN decryption) |
| 82 | Negative CAM, dCVV, iCVV, or CVV results |
| 83 | Unable to verify PIN |
| 85 | No reason to decline a request for account number verification, address verification, CVV2 verification; or a credit voucher or merchandise return |
| 91 | Issuer unavailable or switch inoperative (STIP not applicable or available for this transaction) |
| 92 | Destination cannot be found for routing |
| 93⚠️ | Transaction cannot be completed, violation of law |
| 94 | Duplicate transmission |
| 95 | Reconcile error |
| 96 | System malfunction, System malfunction or certain field error conditions |
| 98 | Server inaccessible |
| A0 | Authentication Required, you must do a card inserted payment with PIN code |
| A1 | Authentication Required, you must do a 3-D Secure authentication |
| B1 | Surcharge amount not permitted on Visa cards (U.S. acquirers only) |
| N0 | Force STIP |
| N3 | Cash service not available |
| N4 | Cashback request exceeds issuer limit |
| N7 | Decline for CVV2 failure |
| P2 | Invalid biller information |
| P5 | PIN change/unblock request declined |
| P6 | Unsafe PIN |
| Q1 | Card authentication failed |
| R0 | Stop payment order |
| R1 | Revocation of authorization order |
| R3 | Revocation of all authorizations order |
| XA | Forward to issuer |
| XD | Forward to issuer |
| Z1 | Offline-declined |
| Z3 | Unable to go online |
| 7810⚠️ | Refusal count exceeded for this card / sepa |
| 7811⚠️ | Exceeded payment volume for this card / sepa |
| 7812⚠️ | Card temporarily frozen by the customer's bank |
| 7840⚠️ | Stolen or lost card |
| 7898 | Bank server unavailable |
Dispute response codes
⚠️ = real code & reason must not be sent to the customer, replace them with a generic 45 transaction-disputed.
| Response | Network | Meaning |
|---|---|---|
| 14 | National | Transaction not authorized |
| 42 | National | Duplicate processing |
| 45 | National | Transaction disputed |
| 1040⚠️ | Visa | Fraud; card Absent Environment |
| 1261 | Visa | Duplicate processing |
| 4808 | Mastercard | Requested/required authorization not obtained. Transaction not authorized |
| 4834 | Mastercard | Duplicate processing |
| 4837⚠️ | Mastercard | Fraudulent transaction; no cardholder authorization |
| 4853 | Mastercard | Cardholder Dispute Defective/Not as Described |
| 4863⚠️ | Mastercard | Cardholder does not recognize. Potential fraud |
SEPA Dispute response codes
| Code | ISO definition | Exhaustive list of uses-cases |
|---|---|---|
| AC01 | Incorrect Account Number | SDD B2B collection presented to a payment account whereby the Debtor account holder is a consumer or the payment account type is designed to consumers only. |
| AC04 | Closed Account Number | The account of the Debtor is closed at the Debtor PSP. Note: This code cannot be used in certain SEPA countries for reasons of data protection. MS03 could be used as an alternative. |
| AC06 | Blocked Account | Account blocked for any financial transaction. |
| AC13 | Invalid Debtor Account Type | SDD B2B collection presented to a payment account whereby the Debtor account holder is a consumer or the payment account type is designed to consumers only. |
| AG01 | Transaction Forbidden | A SDD collection cannot be booked from this type of account (account not allowed for direct debit for regulatory reasons e.g., savings account). Important note: AG01 cannot be used in the situation of an SDD B2B collection presented to a Debtor account that is a consumer account. The code AC13 needs to be used. |
| AG02 | Invalid Bank Operation Code | Recurrent after a one-off / One-off after a recurrent / Identification code of thescheme (i.e. service level or local instrument) specified in the message is incorrect |
| AM04 | Insufficient Funds | There are not enough funds on the Debtor account to debit the full amount of the collection. Note: This code cannot be used in certain SEPA countries for reasons of data protection. MS03 could be used as an alternative |
| AM05 | Duplication | CSM or Debtor PSP considers that an identical SDD collection had been sent or processed very recently |
| BE05 | Unrecognised Iniating Party | Creditor Identifier (CI) is not correct or has been changed without an amendment been reported. |
| CNOR | Creditor Bank Is Not Registered | Creditor PSP is not/ no longer registered as a SDD scheme participant under this BIC at the CSM. |
| DNOR | Debtor Bank Is Not Registered | Debtor PSP is not/ no longer registered as a SDD scheme participant under this BIC at the CSM. |
| ED05 | Settlement Failed | The Debtor PSP or the CSM must report a settlement failure. |
| FF01 | Invalid File Format | Issues with XML-file specific settings: • XML file was not duly filled out or is not correct • There is a syntax error in the file • Creditor PSP, its intermediary PSP or the CSM did not complete a XSD check before submitting the file into the scheme. |
| MD01 | No Mandate | • No mandate is existing • B2B mandate not yet confirmed by the Debtor • Refund for an unauthorised transaction (until 13 months after debit date) (For SDD Core collections only) • Mandate cancellation |
| MD02 | Missing Mandatory Mandate Information in Mandate | • Mandate data in the mandate related information is not identical to those in the mandate (amendments had not been communicated) • Mandate data not consistent with version already received for the UMR • In case of mandate amendment: the original IBAN |
| MD06 | Refund Request By End Customer | Unconditional Refund of a collection (SDD Core – until 8 weeks after debit date). |
| MD07 | End Customer Deceased | Debtor deceased. Note: This code cannot be used in certain SEPA countries for reasons of data protection. In this case MS03 can be used as alternative. |
| MS02 | Not Specified Reason Customer Generated | Refusal by Debtor at presentation. |
| MS03 | Not Specified Reason Agent Generated | Only to be used in case national legislation (e.g., data protection laws) does not allow the use of AC04, AM04, MD07, RR01, RR02, RR03 and RR04. Note: limit the use of the reason code MS03 and select the appropriate reason code in the list. |
| RC01 | Bank Identifier Incorrect | BIC of the scheme participant is not correct. |
| RR01 | Missing Debtor Account Or Identification | Missing details about the Debtor account or identification. Note: This code cannot be used in certain SEPA countries for reasons of data protection. MS03 could be used as an alternative. |
| RR02 | Missing Debtor Name Or Address | Missing Debtor name (address is optional field for EEA SDD collections); Missing address of the Debtor for non-EEA SDD collections. Note: This code cannot be used in certain SEPA countries forreasons of data protection. MS03 could be used as an alternative. |
| RR03 | Missing Creditor Name OR Address | Missing Creditor name (address is an optional field). Note: This code cannot be used in certain SEPA countries for reasons of data protection. MS03 could be used as an alternative. |
| RR04 | Regulatory Reason | Only to be used for regulatory reasons other than RR01, RR02 or RR03. Note: This code cannot be used in certain SEPA countries for reasons of data protection. MS03 could be used as an alternative. |
| SL01 | Specific Service Offered By Debtor Agent | All Debtor-invoked consumerright rejects: • Creditor blocking • Collection amount limitations • Collection frequency limitations. Other services offered by the Debtor PSP. |
Test data
Test cards
WARNING
Ces cartes de test sont destinées uniquement à la simulation de scénarios spécifiques (exemples : Contestations, Paiements capturés...). Leur utilisation dans un flux de paiement normal peut entraîner des comportements inattendus et compromettre l’intégrité de vos intégrations. À utiliser avec précaution et uniquement dans un environnement de test.
| Number | Brand | Country | 3DS | Return | Utilisation |
|---|---|---|---|---|---|
| 4000000400000008 | Visa | AT 🇦🇹 | Optional | 00 OK | Page de paiement |
| 4000000560000004 | Visa | BE 🇧🇪 | Optional | 00 OK | Page de paiement |
| 4000002080000001 | Visa | DK 🇩🇰 | Optional | 00 OK | Page de paiement |
| 4000002460000001 | Visa | FI 🇫🇮 | Optional | 00 OK | Page de paiement |
| 4000002500000003 | CB | FR 🇫🇷 | Optional | 00 OK | Page de paiement |
| 4000002760000016 | Visa | DE 🇩🇪 | Optional | 00 OK | Page de paiement |
| 4000003720000005 | Visa | IE 🇮🇪 | Optional | 00 OK | Page de paiement |
| 4000003800000008 | Visa | IT 🇮🇹 | Optional | 00 OK | Page de paiement |
| 4000004420000006 | Visa | LU 🇱🇺 | Optional | 00 OK | Page de paiement |
| 4000005280000002 | Visa | NL 🇳🇱 | Optional | 00 OK | Page de paiement |
| 4000005780000007 | Visa | NO 🇳🇴 | Optional | 00 OK | Page de paiement |
| 4000006200000007 | Visa | PT 🇵🇹 | Optional | 00 OK | Page de paiement |
| 4000006430000009 | Visa | RU 🇷🇺 | Optional | 00 OK | Page de paiement |
| 4000007240000007 | Visa | ES 🇪🇸 | Optional | 00 OK | Page de paiement |
| 4000007520000008 | Visa | SE 🇸🇪 | Optional | 00 OK | Page de paiement |
| 4000007560000009 | Visa | CH 🇨🇭 | Optional | 00 OK | Page de paiement |
| 4000008260000000 | Visa | GB 🇬🇧 | Optional | 00 OK | Page de paiement |
| 4242424242424242 | Visa | US 🇺🇸 | Not required | 00 OK | Page de paiement |
| 4444333322221111 | Visa | US 🇺🇸 | Not required | 00 OK | Page de paiement |
| 4111111111111111 | Visa | US 🇺🇸 | Not required | 00 OK | Page de paiement |
| 5555555555554444 | Mastercard | US 🇺🇸 | Optional | 00 OK | Page de paiement |
| 5200828282828210 | Mastercard | US 🇺🇸 | Optional | 00 OK | Page de paiement |
| 5105105105105100 | Mastercard | US 🇺🇸 | Optional | 00 OK | Page de paiement |
| 4000000000003055 | Visa | US 🇺🇸 | Not enrolled | 00 OK | Page de paiement |
| 4000000760000002 | Visa | BR 🇧🇷 | Optional | 00 OK | Page de paiement |
| 4000001240000000 | Visa | CA 🇨🇦 | Optional | 00 OK | Page de paiement |
| 4000004840000008 | Visa | MX 🇲🇽 | Optional | 00 OK | Page de paiement |
| 4000000000000077 | Visa | FR 🇫🇷 | Optional | 00 OK | status = 50 captured | API (HPP, TTPOI, TPE, CMS etc) |
| 4000000000003220 | Visa | US 🇺🇸 | Required | A1 must perform 3DS | status = 0 refused | Page de paiement |
| 4000000000000002 | Visa | FR 🇫🇷 | Optional | 05 do not honor | status = 0 refused | Page de paiement |
| 4000000000009995 | Visa | FR 🇫🇷 | Optional | 51 insufficient fund | status = 0 refused | Page de paiement |
| 4000000000009987 | Visa | FR 🇫🇷 | Optional | 41 lost card | status = 0 refused | Page de paiement |
| 4000000000000259 | Visa | FR 🇫🇷 | Optional | 00 OK | status = 60 disputed | API (HPP, TTPOI, TPE, CMS etc) |
| 4000000000001976 | Visa | FR 🇫🇷 | Optional | 00 OK | status = 60 disputed | API (HPP, TTPOI, TPE, CMS etc) |
| 4000000000005423 | Visa | FR 🇫🇷 | Optional | 00 OK | status = 60 disputed | API (HPP, TTPOI, TPE, CMS etc) |
Test SEPA
| IBAN | Country | Name | Birthdate | Return |
|---|---|---|---|---|
| AT611904300234573201 | AT 🇦🇹 | Otto Normalverbraucher | 1971-02-02 | 00 OK |
| BE62510007547061 | BE 🇧🇪 | Jef Van Pijperzele | 1972-03-03 | 00 OK |
| CH2089144321842946678 | CH 🇨🇭 | Leonhard Euler | 1973-04-04 | 00 OK |
| DE89370400440532013000 | DE 🇩🇪 | Max Mustermann | 1974-05-05 | 00 OK |
| EE382200221020145685 | EE 🇪🇪 | Friedrich Robert Faehlmann | 1975-06-06 | 00 OK |
| ES0700120345030000067890 | ES 🇪🇸 | Juan Pérez | 1976-07-07 | 00 OK |
| FI2112345600000785 | FI 🇫🇮 | Maija Meikäläinen | 1977-08-08 | 00 OK |
| FR1420041010050500013M02606 | FR 🇫🇷 | Pierre Martin | 1978-09-09 | 00 OK |
| GB33BUKB20201555555555 | GB 🇬🇧 | John Doe | 1970-01-01 | 00 OK |
| IE29AIBK93115212345678 | IE 🇮🇪 | John Kilkenny | 1979-10-10 | 00 OK |
| LT121000011101001000 | LT 🇱🇹 | Jonas Petraitis | 1980-11-11 | 00 OK |
| LU280019400644750000 | LU 🇱🇺 | Adalbert Boros | 1981-12-12 | 00 OK |
| IT02A0301926102000000490887 | IT 🇮🇹 | Piero Pers | 1982-01-13 | 00 OK |
| NL39RABO0300065264 | NL 🇳🇱 | Jan Modaal | 1983-02-14 | 00 OK |
| NO9386011117947 | NO 🇳🇴 | Peder Aas | 1984-03-15 | 00 OK |
| PT50000201231234567890154 | PT 🇵🇹 | Jan Kowalski | 1985-04-16 | 00 OK |
| SE3550000000054910000003 | SE 🇸🇪 | Lisa Svensson | 1986-05-17 | 00 OK |
| FR9430003000409249176322Z50 | FR 🇫🇷 | Gilles Dupont | 1987-06-18 | 00 OK |
| FR2990665286926539507769811 | FR 🇫🇷 | Jean Banbois | 1992-11-23 | AC01 Incorrect Account Number | status = 0 refused |
| FR8191676442817818484578833 | FR 🇫🇷 | Marie-Jeanne Sansbanque | 1993-12-24 | AC04 Closed Account Number | status = 0 refused |
| FR3083648641551044006702169 | FR 🇫🇷 | Marc Barrer | 1994-01-25 | AC06 Blocked Account | status = 0 refused |
| FR4200838098473368525032012 | FR 🇫🇷 | Sophie Fontek | 1995-02-26 | AG01 Transaction Forbidden | status = 0 refused |
| FR7099253427049384102178149 | FR 🇫🇷 | Hector Fauché | 1996-03-27 | AM04 Insufficient Funds | status = 0 refused |
| FR7240745948453163519978561 | FR 🇫🇷 | Lillianne Sansmandat | 1997-04-28 | MD01 No Mandate | status = 0 refused |
| FR5533686478441573584650545 | FR 🇫🇷 | Vincent Refusé | 1998-05-29 | MD06 Refund Request By End Customer | status = 0 refused |
| FR2488294045573706143240475 | FR 🇫🇷 | Eric Indécis | 1999-06-30 | MS02 Not Specified Reason Customer Generated | status = 0 refused |
| BE08510007547063 | BE 🇧🇪 | Camille Honnête | 1988-07-19 | AM04 Insufficient Funds | status = 60 disputed |
| ES5000120345030000067892 | ES 🇪🇸 | Pepito Pérez | 1990-09-21 | AC04 Closed Account Number | status = 60 disputed |