API
Introduction
To offer an easy-to-use experience, we offer libraries in Shell, Python, Perl or PHP and the list keeps getting longer
Code examples are displayed in each section. Tabs available in the menu allow you to switch them to various programming languages.
The API is available at https://api.stancer.com/ and supports TLS 1.2, HTTP/1.1 and HTTP/2.
INFO
This documentation uses httpie(https://httpie.io/) for shell examples, and our libraries for PHP, Python & Perl examples.
Key concepts
The API is available at https://api.stancer.com and supports TLS 1.2, HTTP/1.1 and HTTP/2 requests.
The same API can be used to access live resources processing real payments and payment methods, but also test resources for your software development and debug purpose. Our API service use API keys to authenticate requests. You can register for an API key at our website. API keys are in the form of sprod_xxx for your live requests and stest_xxx for your test ones. Corresponding public keys are pprod_xxx and ptest_xxx.
The authentication to the API is performed via HTTP Basic Auth. You must use your API key as username and provide no password.
We advise you to use the basic auth mecanism of your HTTP toolkit, but if you need to handle it manually, as specified in HTTP Basic Auth RFC, you need to encode your API key in base64 before sending the corresponding authenticationc token in an Authorization HTTP header. For example, if your API key is sprod_xxx, you need to encode sprod_xxx: (remember, empty password) in base64 (given c3Byb2RfeHh4Og==) then send a Authorization: Basic c3Byb2RfeHh4Og== HTTP header.
This documentation focus on common use case workflows. For more comprehensive or technical documentation, please refer to our OpenAPI or Redoc documentation.
Create payments
Through integrated payment page
shell
$ http --auth stest_xxx: https://api.stancer.com/v2/customers/ \
name="Foo Bar" email=foo.bar@example.org
{
"id": "cust_xxx",
…
}
$ http --auth stest_xxx: https://api.stancer.com/v2/payments/ \
currency=eur amount=100 customer=cust_xxx description="Test payment" auth=True
{
"id": "paym_xxx",
…
}To create a payment, use the POST /v2/payments route. You need to at least provide a currency and an amount.
If you want to associate the payment with a customer, you can use the customer field and pass the corresponding cust_xxx ID.
Note you currently have to force 3DS validation with the auth=true parameter. Else your customer won't be able to proceed the payment as his bank will surely refuse a not authenticated payment.
You can now send your customer on the payment page located at https://payment.stancer.com/ptest_xxx/paym_xxx. Replace public key and payment ID accordingly.
Once payment is created, you can modify it until capture for example to reflect a purchase change, using PATCH /v2/payments/{id} method.
shell
$ http --auth stest_xxx: https://api.stancer.com/v2/payments/paym_xxx amount=200Through API
shell
$ http --auth stest_xxx: https://api.stancer.com/v2/cards/ \
name="Foo Bar" number=4242424242424242 exp_month=10 exp_year=2024 cvc=424
{
"id": "card_xxx",
…
}
$ http --auth stest_xxx: 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",
…
}
…
}If you prefer to collect by yourself the card number, you can process a payment directly and tokenize the sensible information with POST /v2/cards before using it elsewhere in API calls.
You need to specify a return_url to handle 3DS authentication. At the end of the 3DS process, we will redirect your customer to this URL.
shell
$ http --auth stest_xxx: https://api.stancer.com/v2/payments/paym_xxx
{
…
"auth": {
"status": "success"
}
}
$ http --auth stest_xxx: PATCH https://api.stancer.com/v2/payments/paym_xxx \
status=captureThen send your customer on the given auth[redirect_url] to proceed with 3DS. After the redirect to your return_url, you need to check for authentication validity, then capture the payment if all is good.
API status code
Payment status
The status field in the payment object indicates in which state is the payment.
| 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
These test cards are intended solely for simulating specific scenarios (examples: Disputes, Captured payments...). Using them in a normal payment flow may lead to unexpected behaviors and compromise the integrity of your integrations. Use with caution and only in a test environment.
| Number | Brand | Country | 3DS | Return | Usage |
|---|---|---|---|---|---|
| 4000000400000008 | Visa | AT 🇦🇹 | Optional | 00 OK | Payment Page |
| 4000000560000004 | Visa | BE 🇧🇪 | Optional | 00 OK | Payment Page |
| 4000002080000001 | Visa | DK 🇩🇰 | Optional | 00 OK | Payment Page |
| 4000002460000001 | Visa | FI 🇫🇮 | Optional | 00 OK | Payment Page |
| 4000002500000003 | CB | FR 🇫🇷 | Optional | 00 OK | Payment Page |
| 4000002760000016 | Visa | DE 🇩🇪 | Optional | 00 OK | Payment Page |
| 4000003720000005 | Visa | IE 🇮🇪 | Optional | 00 OK | Payment Page |
| 4000003800000008 | Visa | IT 🇮🇹 | Optional | 00 OK | Payment Page |
| 4000004420000006 | Visa | LU 🇱🇺 | Optional | 00 OK | Payment Page |
| 4000005280000002 | Visa | NL 🇳🇱 | Optional | 00 OK | Payment Page |
| 4000005780000007 | Visa | NO 🇳🇴 | Optional | 00 OK | Payment Page |
| 4000006200000007 | Visa | PT 🇵🇹 | Optional | 00 OK | Payment Page |
| 4000006430000009 | Visa | RU 🇷🇺 | Optional | 00 OK | Payment Page |
| 4000007240000007 | Visa | ES 🇪🇸 | Optional | 00 OK | Payment Page |
| 4000007520000008 | Visa | SE 🇸🇪 | Optional | 00 OK | Payment Page |
| 4000007560000009 | Visa | CH 🇨🇭 | Optional | 00 OK | Payment Page |
| 4000008260000000 | Visa | GB 🇬🇧 | Optional | 00 OK | Payment Page |
| 4242424242424242 | Visa | US 🇺🇸 | Not required | 00 OK | Payment Page |
| 4444333322221111 | Visa | US 🇺🇸 | Not required | 00 OK | Payment Page |
| 4111111111111111 | Visa | US 🇺🇸 | Not required | 00 OK | Payment Page |
| 5555555555554444 | Mastercard | US 🇺🇸 | Optional | 00 OK | Payment Page |
| 5200828282828210 | Mastercard | US 🇺🇸 | Optional | 00 OK | Payment Page |
| 5105105105105100 | Mastercard | US 🇺🇸 | Optional | 00 OK | Payment Page |
| 4000000000003055 | Visa | US 🇺🇸 | Not enrolled | 00 OK | Payment Page |
| 4000000760000002 | Visa | BR 🇧🇷 | Optional | 00 OK | Payment Page |
| 4000001240000000 | Visa | CA 🇨🇦 | Optional | 00 OK | Payment Page |
| 4000004840000008 | Visa | MX 🇲🇽 | Optional | 00 OK | Payment Page |
| 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 | Payment Page |
| 4000000000000002 | Visa | FR 🇫🇷 | Optional | 05 do not honor | status = 0 refused | Payment Page |
| 4000000000009995 | Visa | FR 🇫🇷 | Optional | 51 insufficient fund | status = 0 refused | Payment Page |
| 4000000000009987 | Visa | FR 🇫🇷 | Optional | 41 lost card | status = 0 refused | Payment Page |
| 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 |