---
url: https://docs.stancer.com/en/API.md
---

# 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 {{ $frontmatter.api }} and supports **TLS 1.2**, **HTTP/1.1**
and **HTTP/2**.

Our documentation is also available in [Swagger](/api/swagger.html){target="\_self"} or
[Redoc](/api/redoc.html){target="\_self"} format.

::: info

::::tabs key:code

\== Shell

This documentation uses [httpie](https://httpie.io/) for shell examples,
and [our libraries](https://gitlab.com/wearestancer/library) for PHP, Python & Perl examples.

\== Python

For simplicity, Python code will be written using
[type hinting (PEP484)](https://www.python.org/dev/peps/pep-0484/) implemented in 3.5.

Python library currently supports Python versions 3.7 and above.

You can find our library on [PyPI](https://pypi.org/project/stancer/)
or see the source code on [GitLab](https://gitlab.com/wearestancer/library/lib-python)
or [GitHub](https://github.com/wearestancer/lib-python).

\== PHP

For simplicity, PHP code will be written using
[typed properties implemented in 7.4](https://wiki.php.net/rfc/typed_properties_v2).

PHP library currently supports PHP versions 7.4 and above.

You can find our library on [Packagist](https://packagist.org/packages/stancer/stancer)
or the source code on [GitLab](https://gitlab.com/wearestancer/library/lib-php)
or [GitHub](https://github.com/wearestancer/lib-php).

\== Perl

Perl library currently supports Perl versions 5.20 and above.

You can find our library on [CPAN](https://metacpan.org/pod/Stancer)
or see the source code on [GitLab](https://gitlab.com/wearestancer/library/lib-perl)
or [GitHub](https://github.com/wearestancer/lib-perl).

::::

## Key concepts

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](https://manage.stancer.com/en/inscription).
API keys are in the form of `sprod_xxx` for your `live` requests and `stest_xxx`
for your `test` ones.

The authentication to the API is performed
via [HTTP Basic Auth](https://www.rfc-editor.org/rfc/rfc7617).
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](https://www.rfc-editor.org/rfc/rfc7617),
you need to encode your API key in base64
before sending the corresponding authentication 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
then send an HTTP header with your encoded key.
Thus, If your encoded key is `c3Byb2RfeHh4Og==`
your header would be `Authorization: Basic c3Byb2RfeHh4Og==`.

For technical documentation, please refer to our OpenAPI documentations,
[Swagger](/api/swagger.html){target="\_self"} or [Redoc](/api/redoc.html){target="\_self"}.

If you need technical support about our API integration,
you can join our
[Slack community](https://join.slack.com/t/stancer-community/shared_invite/zt-255pdti6c-Gasrxaep0vNe4znqBeS0rQ).

## Create payments

### Through integrated payment page

To create a payment,
use the **POST /v2/payment_intents/** route.
You need to provide an amount and a currency (the default is `eur`).

If you want to associate the payment with a Payer,
you can use the `customer` field
and pass the corresponding `cust_xxx` ID.

:::tabs key:code
\== Shell

```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/payment_intents/ \
currency=eur amount=100 customer=cust_xxx description="Test payment"
{
    "id": "pi_xxx",
    "url" "https://payment.stancer.com/payment_intents/pi_xxx"
    …
}
```

\== Python

```python
customer = stancer.Customer()
customer.name = 'Foo Bar'
customer.email = 'foo.bar@example.org'
customer.send()

payment = stancer.Payment()
payment.description = 'Test payment'
payment.amount = 100  # In cents
payment.currency = 'eur'
payment.customer = customer
payment.return_url = 'https://example.com' # The landing page on your Site after the payment process
payment.send()
```

\== PHP

```php
$customer = new Stancer\Customer();
$customer->setName('Foo Bar');
$customer->setEmail('foo.bar@example.org');
$customer->send();

$payment = new Stancer\Payment()
$payment->setDescription('Test payment');
$payment->setAmount(100); // In cents
$payment->setCurrency('eur');
$payment->setCustomer($customer);
$payment->setReturnUrl('https://example.com'); // The landing page on your Site after the payment process
$payment->send();
```

\== Perl

```perl
my $customer = Stancer::Customer->new();
$customer->name('Foo Bar');
$customer->email('foo.bar@example.org');
$customer->send();

my $payment = Stancer::Payment->new();
$payment->description('Test payment');
$payment->currency('eur');
$payment->amount(100); # In cents
$payment->customer($customer);
$payment->return_url('https://example.com');
$payment->send();
```

:::

You can now send your Payer on the payment page located
at `https://payment.stancer.com/pi_xxx`,
`pi_xxx` will be replaced by the API with the according identifier.

You can find this URL in the `url` field of your `payment intent`, or ,
with the libraries:

:::tabs key:code
\== Python

```python
payment_page_url = payment.payment_page_url()
```

\== PHP

```php
$paymentPageUrl = $payment->getPaymentPageUrl();
```

\== Perl

```perl
my $payment_page_url = $payment->payment_page_url();
```

:::

***

### 3D Secure Process: Creating an Online Payment (Authorization + Capture)

**Order Setup**

The Payer places an order on the Client's website (shopping cart, address, etc.).

The Client creates a “customer” on the Stancer side by calling the **POST** API `v2/customers` and receives a cust_xxx in response.
Next, the Client creates a payment intent with the parameter `capture = false`, meaning that only authorization is requested via a **POST** HTTP request to `v2/payment_intents`.

Stancer returns the payment intent ID along with a hosted payment page (HPP) URL, which will be displayed in an iframe on the merchant’s website.

**Entering Card Information in the Iframe**

The customer’s browser loads the iframe with the Stancer HPP URL.
In this iframe, the Payer sees a credit card form fully managed by Stancer and enters their card details there.

**Initiating and Completing 3D Secure**

If the customer’s card and bank require 3D Secure authentication, Stancer opens a new window or sub-iframe within the iframe dedicated to 3D Secure.
The Payer is then redirected to their bank’s interface (SMS code, validation in the banking app, etc.) to prove they are the cardholder.

Once authentication is complete, the bank sends a 3DS result (success or failure) back to Stancer.

If authentication is successful, Stancer requests payment authorization from the banking network: the bank reserves the amount on the customer’s account without yet debiting it permanently.

**End of the iframe: notification to the Client Site**

Once authorization is successful, Stancer sets the payment intent to “authorized” status.

The HPP returns an OK response in the iframe and, via a postMessage, informs the merchant’s page that the “payment + 3DS” process was successful.

The Client Site captures this event and can then close or hide the iframe
and proceed to an internal order confirmation page or simply display a message to inform the end Payer that their purchase is being processed.

::: warning Note
**Payment funnel interruption:**
If the Payer closes the browser immediately after 3DS, the Client does not receive the notification,
but the transaction remains in “authorized” status. The funds are reserved but not captured, so the order must be considered unconfirmed.
:::

**Final confirmation and fund capture**

Outside the iframe, the merchant’s Site calls a confirmation URL when it is ready to finalize the order.

Upon this call, the merchant’s server checks the status of the payment intent with Stancer via an HTTP **GET** request `v2/payment_intent/<pi_id>` to ensure it is indeed in the “authorized” status.

If everything is correct, the Client sends the capture order to Stancer via an HTTP **POST** request `/payment_intent/<pi_id>/capture`.

Stancer then finalizes the transaction: the status changes to “to_capture” and the funds will be ready to be debited from the Payer's bank account.

***

### Set Up a SEPA Direct Debit (Available via API only)

#### Setting Up SEPA Direct Debit

You can use SEPA Direct Debit as a payment method to collect payments from your customers. First, the [prerequisites](./Concepts/Payments.html#prerequis) must be met.

Currently, payments via SEPA Direct Debit are only available through the Stancer API.
You can use them to process **one-time** or **recurring** payments by reusing the mandate ID `sepa_xxx`.

**Several possible approaches:**

* Stancer handles the creation of the mandate as well as its storage (recommended)

* You manage the signing of the mandate on your end, then you can store it on the Stancer side to tokenize it so it can be reused.

**Setup:**

**Creating the mandate via Stancer (recommended)**

For any new mandate, please carefully follow the steps below:

* Make a **POST** HTTP request to the `v2/paiement_intents` endpoint.

* Enter the amount you wish to charge the Payer in the `amount`.

* Enter `sepa` or `sepa,card` in the `methods_allowed` field (It is recommended to leave only the SEPA method if you do not want to give your Payer a choice).

* The payment page will appear with the selected payment method.

* Once this form is completed, the direct debit authorization form will be generated.

* The Payer will then receive a 4-digit code via text message to verify their identity using the phone number they previously provided on the payment page.

* Once the signature is complete, the first payment will be approved, and a link will be provided so the Payer can retrieve their direct debit authorization form.

**Importing Your Mandates into Stancer**

To import your customers' existing mandates, you must:

* Send an **POST** HTTP request to the `v2/sepa` endpoint and fill in the required fields.

* Retrieve the `sepa_id` from the request response.

* Send a new **POST** HTTP request to the `v2/mandates` endpoint.

* Enter the `sepa_id` from the previous request along with the RUM.

* Send a **POST** request to the URL specified in the `upload_url` field with your document in the request body.

Please note that our documentation is available if needed, accessible via this [link](/api/redoc.html){target="\_self"}.

## Capturing payments

You may find some payments with an **authorized** status in your User Area.

These are online payments that have not been completed for one of the following reasons:

* The transaction was created through `POST /v2/payment_intents` with the `capture=false` parameter.
* The payment flow was interrupted, even though the Payer had previously completed 3DS authentication.

These payments must therefore be captured manually. This action will debit the payment method used for the transaction.

Once a payment is **authorized**, it can be captured in two ways:

* **From the User Area**, for online payments only (Paylink, API, SDK, CMS).
* **Through the API**, for payment intents created with the `capture=false` parameter.

### From the User Area

For **online payments**, you can capture the payment directly from the User Area.

From the payment details, click **Capture**.

![manual_capture](../images/capture_manage_en.png)

### Through the API

To capture a payment, send an HTTP `POST` request to the following endpoint:

:::tabs key:code
\== Shell

```Shell
POST /v2/payment_intents/pi_xxx/capture
```

:::

Replace `pi_xxx` with the ID of the payment intent you want to capture.

Once the action has been completed, the payment goes through the following statuses:

```text
authorized → to_capture → capture_sent → captured
```

The `captured` status confirms that the payment has been successfully captured.

## Idempotency of requests

When your application sends a mutating request, a system error (network timeout, connection drop, automatic resubmission by the browser…) can occur and interrupt the request without returning a response, while our API continues to execute the request normally.
If you retry this request, the intended operation may then be performed multiple times: two payment intents created, two captures sent…

The `Idempotency-Key` header protects you from this double processing: the operation is **executed only
once**, no matter how many times you resend the request with the same key.

The header is **optional** and is available on all semantically non-idempotent requests (non-`GET`).
We recommend using it in particular on any endpoint with a financial effect (payment intent creation, capture, …).

To use it, you must generate a unique identifier before sending your request (a UUIDv4 works perfectly)
and pass it in the `Idempotency-Key` header of the request:

:::tabs key:code
\== Shell

```shell
$ http --auth stest_xxx: \
    --header 'Idempotency-Key: 7f2b6a4c-1a2b-4e8f-9c3d-4f6a2b1c0d00' \
    https://api.stancer.com/v2/payment_intents/ \
    currency=eur amount=100 customer=cust_xxx
{
    "id": "pi_xxx",
    …
}
```

:::

Two rules apply to this key:

* It must be **stable**: all retransmissions of the same operation must use the **same** key.
* It must be **unique per operation**: any new operation requires a **new** key.

Depending on when you send the request, the API responds as follows:

| Situation                        | API response                                                                                                             |
|----------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| Key never seen                   | The operation is executed normally. Its full response (status code, headers, body) is returned and kept for **24 hours** |
| Known key, operation in progress | `409 Conflict`. The operation with this key is still being processed                                                     |
| Known key, operation completed   | The stored response is returned as-is, without re-executing the operation                                                |

If your request is retransmitted while the first one is still being processed,
you receive:

:::tabs key:code
\== Shell

```shell
HTTP/1.1 409 Conflict
{
    "detail": "Duplicated request detected, previous one still in progress, retry later"
}
```

:::

You must then implement a retry mechanism (for example with an exponential backoff algorithm).
Once the previous request has completed, you will then receive its stored response in your new request:

:::tabs key:code
\== Shell

```shell
$ http --auth stest_xxx: \
    --header 'Idempotency-Key: 7f2b6a4c-1a2b-4e8f-9c3d-4f6a2b1c0d00' \
    https://api.stancer.com/v2/payment_intents/ \
    currency=eur amount=100 customer=cust_xxx
{
    "id": "pi_xxx",
    …
}
```

:::

::: danger Note

The stored response is returned regardless of its status code, **including a `4xx` error**.
If your request failed (for example `422` invalid request body), retransmitting with the same key will return the same `422`.

If you want to retry the operation (not the request), fix the request body **and** generate a new key.

:::

::: danger Note

A request's response is kept for **24 hours**: beyond that, the key is no longer recognized and a late retransmission
will be treated as a new operation.
If your recovery delays can exceed 24 hours (queue, batch processing…), implement deduplication on your side.

:::

## Webhooks

Webhooks (currently **synchronous**) allow Stancer to provide the merchant with the information required to continue processing a payment throughout the payment flow.

**Nominal case: the payment flow completes successfully**

When the flow proceeds normally, the Payer goes through all the payment steps:

* The Payer enters their card details on the payment page.
* Stancer redirects the Payer to their bank to complete 3DS authentication.
* The bank validates the 3DS authentication.
* The Payer returns to the payment page.
* Stancer requests payment authorization from the bank.
* The bank authorizes the payment.
* Stancer redirects the Payer back to the merchant's website.
* The merchant requests the payment capture.
* The merchant can finalize the order.

In this scenario, the user journey and the exchanges between Stancer and the merchant allow the payment to be completed through capture and order finalization.

![normal_case](../images/Webhooks/normal_case.png)

**Non-nominal case: the flow is interrupted**

The flow can be interrupted by the Payer at different stages. The behavior then depends on when the interruption occurs.

If the Payer interrupts the flow **before payment authorization**, for example after 3DS authentication:

* The payment has not yet been authorized.
* The merchant must not consider the payment successful.
* No capture should be performed.

Simply completing 3DS authentication does not therefore mean that the payment has been authorized.

The Payer may also interrupt the flow **after payment authorization**, for example by closing their browser before returning to the merchant's website.

In this case:

* The bank has authorized the payment.
* The funds are held on the Payer's bank account.
* The merchant may not have received the browser redirect.
* The merchant can then manually trigger the capture and continue processing the payment.

With **synchronous** webhooks, the merchant must therefore process these events directly within the payment flow rather than relying solely on the browser redirect.

![abnormal_case](../images/Webhooks/interruption.png)

To be notified in real time of changes (failed payment, unpaid subscription, etc.) and react quickly, you can configure webhooks.

**Functional flow with synchronous webhooks**

The webhook is triggered directly within the payment flow. Stancer sends the event to the merchant, which performs the required action before continuing the payment process.

After payment authorization:

1. Stancer redirects the Payer to the merchant's website.
2. Stancer sends the `payment.authorized` webhook to the merchant.
3. The merchant receives the event and requests the payment capture.
4. Stancer performs the capture.
5. Stancer sends the `payment.to_captured` webhook to the merchant.
6. The merchant receives the confirmation and finalizes the order.

![webhooks](../images/Webhooks/webhooks_case.png)

Using webhooks requires a web server on your side that can receive the various events, for example at `https://example.org/stancer/webhooks/`.

You must then create an endpoint through our API using [POST /v2/webhooks/](/api/redoc.html#tag/webhooks/operation/create_webhook_v2_webhooks__post){target="\_self"}:

:::tabs key:code

\== Shell

```shell
$ http https://api.stancer.com/v2/webhooks/ url=https://example.org/stancer/webhooks/

{
  "id": "we_xxx",
  "secret": "xxx",
  …
}
```

:::

Events are sent via a `POST <url>` request to your infrastructure. Your endpoint must provide a valid HTTPS certificate and return an HTTP `200 OK` or `204 NO CONTENT` response.

Any other status code is considered an error, and the event will be retried later using an exponential backoff mechanism. Our infrastructure attempts to deliver the message 15 times, over approximately one and a half days, before giving up:

| Attempt | Delay    | Total            |
|---------|----------|------------------|
| 1       | 0:00:15  | 0:00:15          |
| 2       | 0:00:16  | 0:00:31          |
| 3       | 0:00:31  | 0:01:02          |
| 4       | 0:01:36  | 0:02:38          |
| 5       | 0:04:31  | 0:07:09          |
| 6       | 0:10:40  | 0:17:49          |
| 7       | 0:21:51  | 0:39:40          |
| 8       | 0:40:16  | 1:19:56          |
| 9       | 1:08:31  | 2:28:27          |
| 10      | 1:49:36  | 4:18:03          |
| 11      | 2:46:55  | 7:04:58          |
| 12      | 4:04:16  | 11:09:14         |
| 13      | 5:45:51  | 16:55:05         |
| 14      | 7:56:16  | 1 day, 0:51:21   |
| 15      | 10:40:31 | 1 day, 11:31:52  |

When an event is sent, the request payload is signed using the secret key provided when the endpoint was created. This allows you to identify the sender and only process legitimate content.

The signature is an [HMAC SHA256](https://datatracker.ietf.org/doc/html/rfc2104) generated from a field containing the timestamp corresponding to the request's sending time and the request body, separated by a `.`.

This signature is transmitted in the `Stancer-Signature` HTTP request header.

:::tabs key:code

\== Python

```python
def compute(secret: str, payload: str, timestamp: int) -> [int, str]:
    secret = bytes.fromhex(secret)
    signed_payload = (str(timestamp) + ".").encode() + payload

    return hmac.digest(secret, signed_payload, hashlib.sha256).hex()


def parse(signature: str, version="v1") -> [int, str]:
    raw_values = [x.split('=') for x in signature.split(',')]
    parts = {value[0]: value[1] for value in raw_values}

    timestamp = int(parts['t'])
    crypto_signature = parts.get(version)

    return timestamp, crypto_signature


def verify(
    secret: str,
    payload: str,
    signature: str,
    now=datetime.now(tz=timezone.utc),
    delta=timedelta(minutes=1),
) -> None:
    timestamp, expected = parse(signature)
    date = datetime.fromtimestamp(timestamp, tz=timezone.utc)

    if now - date > delta:
        raise Exception("Expired signature")

    computed = compute(secret, payload, timestamp)
    ok = hmac.compare_digest(expected, computed)

    if not ok:
        raise Exception("Invalid signature")
```

\== Ruby

```ruby
def hex_to_bin(s)
  s.scan(/../).map { |x| x.hex.chr }.join
end

def compute(secret, payload, time)
  timestamp = time.to_i
  payload = "#{timestamp}.#{payload}"
  OpenSSL::HMAC.hexdigest 'sha256', secret, payload
end

def parse(signature, version = 'v1')
  signature = signature.split(',')
                       .collect { _1.split '=' }
                       .to_h

  timestamp = Time.at (signature.fetch 't').to_i
  digest = signature.fetch version

  [timestamp, digest]
end

def verify(secret, payload, signature, now = Time.now.utc, delta = 60)
  secret = hex_to_bin secret

  timestamp, expected = parse signature

  raise 'Expired signature' if (now - timestamp) > delta

  digest = compute secret, payload, now

  raise 'Invalid signature' unless digest == expected
end
```

\== PHP

```php
function checkHmac(string $secret, string $signature, string $timestamp, string $payload):void
{
    $computed = hash_hmac('sha256', $time . '.' . $body, $secret);
    $ok = hash_equals($signature, $computed);
    if (!$ok) {
        throw new \Exception();
    }
}

function parseSignature(string $stancerSignature, string $version = 'v1'): array
{
    $tmp = explode(',', $stancerSignature);
    $part = [];

    foreach ($tmp as $element) {
        [$key,$value] = explode('=', $element);
        $part[$key] = $value;
    }
    $timestamp = $part['t'];

    return [$timestamp, $part[$version]];
}

function verify(
  string $secret,
  string $payload,
  string $stancerSignature,
  \DateTimeImmutable $now,
  \DateInterval $delta)
{
    [$timestamp,$signature] = parseSignature($stancerSignature);
    // For PHP < 8.4 use:
    // $date = new \DateTimeImmutable('@' . $timestamp);
    $date = DateTimeImmutable::createFromTimestamp( $timestamp );
    if (($now->sub($delta) <=> $date) > 0) {
        throw new Exception('Expired signature');
    }
    checkHmac($secret, $signature, $timestamp, $body);
}
```

\== TS

```ts
  const checkHmac = (secret:string, data: string, hmac: string): boolean  =>{

    const generatedHmac = createHmac('sha256', Buffer.from(secret, 'hex')).update(data).digest('hex');
    return timingSafeEqual(Buffer.from(hmac), Buffer.from(generatedHmac));
  }

const checkRequest = (
  secret:string,
  payload:string,
  stancerSignature:string,
  time: { now: Temporal.Instant; delta: Temporal.Duration } = {
    now: Temporal.Now.instant(),
    delta: new Temporal.Duration(0, 0, 0, 0, 0, 1),
  },
) => {

    const parsedSignature = parseSignature(stancerSignature);
    const signatureTime = Temporal.Instant.fromEpochMilliseconds(Number(parsedSignature.timestamp) * 1000);
    const deltaNow = time.now.subtract(time.delta);
    if (Temporal.Instant.compare(deltaNow, signatureTime) > 0) {
        throw new Error('Expired signature');
    }

    const ok = checkHmac(secret,`${parsedSignature.timestamp}.${payload}`, parsedSignature.expected);
    if (!ok) {
        throw new Error('Invalid signature');
    }
}

const parseSignature = (signature: string, version = 'v1'): { timestamp: number; expected: string } => {
    const tmp = signature.split(',');
    const parts: Record<string, string> = {};
    let timestamp = undefined;
    for (const part of tmp) {
        const subPart = part.split('=');
        if (!subPart[0] || typeof subPart[0] !== 'string' || !subPart[1] || typeof subPart[1] !== 'string') {
            throw new Error('Invalid signature');
        }
        if (subPart[0] === 't') {
            timestamp = Number(subPart[1]);
        }
        parts[subPart[0]] = subPart[1];
    }
    if (!timestamp || !parts[version]) {
        throw new Error('Invalid signature');
    }
    return { timestamp: timestamp, expected: parts[version] };
}
```

:::

When verifying the signature, you should check that the transmitted timestamp is not too far from the current time, for example less than 1 minute, to protect against replay attacks.

Currently, only `v1` signatures are issued. However, this parameter is required to allow a future change of algorithm, so your code must handle:

* multiple versions in the same signature
* unsupported versions on your side

You should only validate the signature using the highest version supported by your environment.

The event received in the request body has the following format:

```json
{
  "id": "<evt_xxx>",
  "type": "<object_type>.<event>",
  "data": { … }
}
```

The data contained in `data` corresponds to the data returned by the API when retrieving an object's information (`GET /v2/<object_type>/<object_id>`).

The available event types are:

* customer
  * created
  * deleted

* card
  * created

* mandate
  * created
  * signed

* payment_intent
  * created
  * updated
  * authorized
  * captured (async mode: currently not available)

* payment
  * created
  * updated
  * authorized
  * succeeded
  * captured (async mode: currently not available)
  * refused
  * disputed (async mode: currently not available)

* product
  * created
  * updated
  * deleted

* price
  * created
  * updated
  * deleted

* refund
  * created

* subscription
  * created
  * updated
  * deleted
  * past_due
  * unpaid (async mode: currently not available)
  * canceled
  * resumed

::: danger Warning

Webhooks depend on elements outside of Stancer (network connectivity to your endpoints, availability and response of your systems, validity of your HTTPS certificates, internal rate limiting to prevent outbound DDoS attacks, queuing in case of overload, etc.) and are therefore provided on a "best effort" basis.

There is no guarantee of:

* **delivery:** a webhook may never be delivered to you
* **latency:** a webhook may arrive within seconds or several hours later
* **uniqueness:** a webhook may be delivered multiple times

Your services must therefore be designed to take these limitations into account.

:::

## API status and codes

### Payment status

The `status` field in the payment object
indicates in which state is the payment.

| Status                          | Meaning                                                                                                                              |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|    | The bank authorized the payment but the transaction will only be processed after asking for capture                                  |
|    | The bank authorized the payment, money will be processed within the day                                                              |
|  | The capture operation is being processed, the payment can not be cancelled anymore, refunds must wait the end of the capture process |
|      | The amount of the payment have been credited to your account                                                                         |
|      | The Payer declined the payment after it have been captured on your account                                                           |
|       | The authorization was not captured and expired after 7 days                                                                          |
|        | The payment has failed, refer to the response field for more details                                                                 |
|       | The payment has been refused                                                                                                         |

### Authenticated payment status

The `status` field in the auth object
indicates the authorization state for an authenticated payment.

| Status                         | Meaning                                                            |
| ------------------------------ | ------------------------------------------------------------------ |
|    | Customer strong authentication is possible                         |
|    | A strong authentication is awaiting for more information           |
|    | Customer was redirected to his bank for authentication             |
|      | Authentication succeeded, processing can continue                  |
|     | Authentication declined                                            |
|      | Authentication sessions expired after 6 hours                      |
|       | Authentication failed                                              |
|  | The strong authentication is not available for this payment method |

### Payout status

The `status` field in the payout object
indicates the state of the credit transfer between Stancer and your bank.

| Status                     | Meaning                                                                              |
| -------------------------- | ------------------------------------------------------------------------------------ |
|  | The payout has been created and is awaiting for clearing                             |
|   | The payout is ready to be transferred                                                |
|     | The payout has been sent out for processing                                          |
|     | The payout credit transfer has been processed: funds have been received by your bank |
|   | The credit transfer has failed, please refer to your User Area for more informations |

### Payment response codes

The `response` field in the payment object
show the response of the transaction authorization from the bank of the bearer (client)

⚠️ = real code & reason must not be sent to the Payer,
replace them with a generic `05 do-not-honor`.

| Code                     | Reason                                                                                                                                             |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|     | Successful approval/completion or that VIP PIN verification is valid                                                                               |
|     | Refer to card issuer                                                                                                                               |
|     | Refer to card issuer, special condition                                                                                                            |
|     | Invalid merchant or service provider                                                                                                               |
|     | Pickup                                                                                                                                             |
|     | Do not honor                                                                                                                                       |
|     | General error                                                                                                                                      |
|     | Pickup card, special condition (other than lost/stolen card)                                                                                       |
|     | Honor with identification                                                                                                                          |
|     | Request in progress                                                                                                                                |
|     | Partial approval                                                                                                                                   |
|     | VIP approval                                                                                                                                       |
|     | Invalid transaction                                                                                                                                |
|     | Invalid amount (currency conversion field overflow) or amount exceeds maximum for card program                                                     |
|     | Invalid account number (no such number)                                                                                                            |
|     | No such issuer                                                                                                                                     |
|     | Insufficient funds                                                                                                                                 |
|     | Customer cancellation                                                                                                                              |
|     | Re-enter transaction                                                                                                                               |
|     | Invalid response                                                                                                                                   |
|     | No action taken (unable to back out prior transaction)                                                                                             |
|     | Suspected Malfunction                                                                                                                              |
|     | Unable to locate record in file, or account number is missing from the inquiry                                                                     |
|     | File is temporarily unavailable                                                                                                                    |
|     | Format error                                                                                                                                       |
| ⚠️   | Suspected fraud                                                                                                                                    |
| ⚠️   | Merchant should retain card (card reported lost)                                                                                                   |
| ⚠️   | Merchant should retain card (card reported stolen)                                                                                                 |
|     | Insufficient funds                                                                                                                                 |
|     | No checking account                                                                                                                                |
|     | No savings account                                                                                                                                 |
|     | Expired card                                                                                                                                       |
|     | Incorrect PIN                                                                                                                                      |
|     | Card missing from file                                                                                                                             |
|     | Transaction not permitted to cardholder                                                                                                            |
|     | Transaction not allowed at terminal                                                                                                                |
| ⚠️   | Suspected fraud                                                                                                                                    |
|     | Activity amount limit exceeded                                                                                                                     |
| ⚠️   | Restricted card (for example, in country exclusion table)                                                                                          |
| ⚠️   | Security violation                                                                                                                                 |
| ⚠️   | Activity count limit exceeded                                                                                                                      |
|     | Response received too late                                                                                                                         |
|     | Allowable number of PIN-entry tries exceeded                                                                                                       |
|     | Unable to locate previous message (no match on retrieval reference number)                                                                         |
|     | Closed account                                                                                                                                     |
|     | ’Blocked, first used’—The transaction is from a new cardholder, and the card has not been properly unblocked.                                      |
|     | Visa transactions: credit issuer unavailable. Private label and check acceptance: Invalid date                                                     |
|     | PIN cryptographic error found (error found by VIC security module during PIN decryption)                                                           |
|     | Negative CAM, dCVV, iCVV, or CVV results                                                                                                           |
|     | Unable to verify PIN                                                                                                                               |
|     | No reason to decline a request for account number verification, address verification, CVV2 verification; or a credit voucher or merchandise return |
|     | Issuer unavailable or switch inoperative (STIP not applicable or available for this transaction)                                                   |
|     | Destination cannot be found for routing                                                                                                            |
| ⚠️   | Transaction cannot be completed, violation of law                                                                                                  |
|     | Duplicate transmission                                                                                                                             |
|     | Reconcile error                                                                                                                                    |
|     | System malfunction, System malfunction or certain field error conditions                                                                           |
|     | Server inaccessible                                                                                                                                |
|     | Authentication Required, you must do a card inserted payment with PIN code                                                                         |
|     | Authentication Required, you must do a 3-D Secure authentication                                                                                   |
|     | Pin request in Single TAP mode                                                                                                                     |
|     | Surcharge amount not permitted on Visa cards (U.S. acquirers only)                                                                                 |
|     | Force STIP                                                                                                                                         |
|     | Cash service not available                                                                                                                         |
|     | Cashback request exceeds issuer limit                                                                                                              |
|     | Decline for CVV2 failure                                                                                                                           |
|     | Invalid biller information                                                                                                                         |
|     | PIN change/unblock request declined                                                                                                                |
|     | Unsafe PIN                                                                                                                                         |
|     | Card authentication failed                                                                                                                         |
|     | Stop payment order                                                                                                                                 |
|     | Revocation of authorization order                                                                                                                  |
|     | Revocation of all authorizations order                                                                                                             |
|     | Forward to issuer                                                                                                                                  |
|     | Forward to issuer                                                                                                                                  |
|     | Offline-declined                                                                                                                                   |
|     | Unable to go online                                                                                                                                |
| ⚠️ | Refusal count exceeded for this card / SEPA                                                                                                        |
| ⚠️ | Exceeded payment volume for this card / SEPA                                                                                                       |
| ⚠️ | Card temporarily frozen by the Payer's bank                                                                                                        |
| ⚠️ | Stolen or lost card                                                                                                                                |
|   | Bank server unavailable                                                                                                                            |

### Dispute response codes (Card)

The `response` field of the dispute object
shows the reason for the Card dispute issued by the bearer's bank (client bank).

⚠️ = real code & reason must not be sent to the Payer,
replace them with a generic `45 transaction-disputed`.

| code (`response` field)  | Network    | Meaning                                                                   |
| ------------------------ | ---------- | ------------------------------------------------------------------------- |
|     | National   | Transaction not authorized                                                |
|     | National   | Duplicate processing                                                      |
|     | National   | Transaction disputed                                                      |
| ⚠️ | Visa       | Fraud; card Absent Environment                                            |
|   | Visa       | Duplicate processing                                                      |
|   | Mastercard | Requested/required authorization not obtained. Transaction not authorized |
|   | Mastercard | Duplicate processing                                                      |
| ⚠️ | Mastercard | Fraudulent transaction; no cardholder authorization                       |
|   | Mastercard | Cardholder Dispute Defective/Not as Described                             |
| ⚠️ | Mastercard | Cardholder does not recognize. Potential fraud                            |

### Dispute response codes (SEPA)

The `response` field of the dispute object
shows the reason for the SEPA dispute issued by the bearer's bank (client bank).

Those codes are defined by the [Universal financial industry message scheme](https://www.iso20022.org).

| Code (`response` field) | 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 ⚠️ Note
These test cards are intended solely for simulating specific scenarios
(examples: Disputes, Captured payments...).
Using them in a live payment flow may lead to unexpected behaviors and
compromise the integrity of your integrations.

Use only in a test environment.
:::

| Number                              | Brand      | Country | 3DS           |  Response code | Labels        |Status | Usage                  |
| ----------------------------------- | ---------- | ------- | ------------  |-----------|------------------- | -------|----------------------- |
|  | Visa       | AT 🇦🇹    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | BE 🇧🇪    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | DK 🇩🇰    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | FI 🇫🇮    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | CB         | FR 🇫🇷    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | DE 🇩🇪    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | IE 🇮🇪    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | IT 🇮🇹    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | LU 🇱🇺    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | NL 🇳🇱    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | NO 🇳🇴    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | PT 🇵🇹    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | RU 🇷🇺    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | ES 🇪🇸    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | SE 🇸🇪    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | CH 🇨🇭    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | GB 🇬🇧    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | US 🇺🇸    | Not required | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | US 🇺🇸    | Not required | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | US 🇺🇸    | Not required | 00 |OK | Accepted                                      | Payment Page                   |
|  | Mastercard | US 🇺🇸    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Mastercard | US 🇺🇸    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Mastercard | US 🇺🇸    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | US 🇺🇸    | Not enrolled | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | BR 🇧🇷    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | CA 🇨🇦    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | MX 🇲🇽    | Optional     | 00 |OK | Accepted                                      | Payment Page                   |
|  | Visa       | FR 🇫🇷    | Optional     | 00 |OK | Captured                                      | API (HPP, TTPOI, TPE, CMS etc) |
|  | Visa       | US 🇺🇸    | Required     | A1 |Must perform 3DS | Refused                         | Payment Page                   |
|  | Visa       | FR 🇫🇷    | Optional     | 05 |Do not honor | Refused                             | Payment Page                   |
|  | Visa       | FR 🇫🇷    | Optional     | 51 |Insufficient fund | Refused                        | Payment Page                   |
|  | Visa       | FR 🇫🇷    | Optional     | 41 |Lost card | Refused                                | Payment Page                   |
|  | Visa       | FR 🇫🇷    | Optional     | 00 |OK |  Disputed                                     | API (HPP, TTPOI, TPE, CMS etc) |
|  | Visa       | FR 🇫🇷    | Optional     | 00 |OK |  Disputed                                     | API (HPP, TTPOI, TPE, CMS etc) |
|  | Visa       | FR 🇫🇷    | Optional     | 00 |OK |  Disputed                                     | API (HPP, TTPOI, TPE, CMS etc) |

### Test SEPA

::: warning ⚠️ Note
These test cards are intended solely for simulating specific scenarios
(examples: Disputes, Captured payments...).
Using them in a live payment flow may lead to unexpected behaviors
and compromise the integrity of your integrations.

Use only in a test environment.
:::

| IBAN                                           | Country | Name                       | Birthdate   | Response code | Labels | Status                                    |
| ---------------------------------------------- | ------- | -------------------------- | ----------- | ---------------|----------|----------------------------------------|
|         | AT 🇦🇹    | Otto Normalverbraucher     | 1971-02-02 | 00 | OK | Accepted                                                 |
|             | BE 🇧🇪    | Jef Van Pijperzele         | 1972-03-03 | 00 | OK | Accepted                                                 |
|        | CH 🇨🇭    | Leonhard Euler             | 1973-04-04 | 00 | OK | Accepted                                                 |
|       | DE 🇩🇪    | Max Mustermann             | 1974-05-05 | 00 | OK | Accepted                                                 |
|         | EE 🇪🇪    | Friedrich Robert Faehlmann | 1975-06-06 | 00 | OK | Accepted                                                 |
|     | ES 🇪🇸    | Juan Pérez                 | 1976-07-07 | 00 | OK | Accepted                                                 |
|           | FI 🇫🇮    | Maija Meikäläinen          | 1977-08-08 | 00 | OK | Accepted                                                 |
|  | FR 🇫🇷    | Pierre Martin              | 1978-09-09 | 00 | OK | Accepted                                                 |
|       | GB 🇬🇧    | John Doe                   | 1970-01-01 | 00 | OK | Accepted                                                 |
|       | IE 🇮🇪    | John Kilkenny              | 1979-10-10 | 00 | OK | Accepted                                                 |
|         | LT 🇱🇹    | Jonas Petraitis            | 1980-11-11 | 00 | OK | Accepted                                                 |
|         | LU 🇱🇺    | Adalbert Boros             | 1981-12-12 | 00 | OK | Accepted                                                 |
|  | IT 🇮🇹    | Piero Pers                 | 1982-01-13 | 00 | OK | Accepted                                                 |
|           | NL 🇳🇱    | Jan Modaal                 | 1983-02-14 | 00 | OK | Accepted                                                 |
|              | NO 🇳🇴    | Peder Aas                  | 1984-03-15 | 00 | OK | Accepted                                                 |
|    | PT 🇵🇹    | Jan Kowalski               | 1985-04-16 | 00 | OK | Accepted                                                 |
|     | SE 🇸🇪    | Lisa Svensson              | 1986-05-17 | 00 | OK | Accepted                                                 |
|  | FR 🇫🇷    | Gilles Dupont              | 1987-06-18 | 00 | OK | Accepted                                                 |
|  | FR 🇫🇷    | Jean Banbois               | 1992-11-23 | AC01 | Incorrect Account Number |   Refused                        |
|  | FR 🇫🇷    | Marie-Jeanne Sansbanque    | 1993-12-24 | AC04 | Closed Account Number |   Refused                           |
|  | FR 🇫🇷    | Marc Barrer                | 1994-01-25 | AC06 | Blocked Account |   Refused                                 |
|  | FR 🇫🇷    | Sophie Fontek              | 1995-02-26 | AG01 | Transaction Forbidden |   Refused                           |
|  | FR 🇫🇷    | Hector Fauché              | 1996-03-27 | AM04 | Insufficient Funds |   Refused                              |
|  | FR 🇫🇷    | Lillianne Sansmandat       | 1997-04-28 | MD01 | No Mandate |  Refused                                       |
|  | FR 🇫🇷    | Vincent Refusé             | 1998-05-29 | MD06 | Refund Request By End Customer |   Refused                  |
|  | FR 🇫🇷    | Eric Indécis               | 1999-06-30 | MS02 | Not Specified Reason Customer Generated |   Refused         |
|             | BE 🇧🇪    | Camille Honnête            | 1988-07-19 | AM04 | Insufficient Funds |  Disputed                              |
|     | ES 🇪🇸    | Pepito Pérez               | 1990-09-21 | AC04 | Closed Account Number |  Disputed                           |
