SeQura : 3. Confirm order (legacy)

Are you using the newest flow, which features tells the shop when the order is being reviewed and when it’s fully confirmed, and ready for fulfillment? Please refer to the current documentation

Once SeQura has approved the order, the shop must confirm that the order is actually being placed. The main purpose of this action is to make sure that the customer has not changed the content of the order cart during the checkout process. In case there have been any changes in the cart, the process must start again.

Overview

For the shop to know that the order has been approved, SeQura sends an Instant Payment Notification (IPN) callback to the shop, using a URL that was provided in the first API call.

To implement IPN the shop must expose an endpoint to which SeQura can POST a notification once the order is approved. When receiving a request to that endpoint, the shop must confirm the order through SeQura’s API before responding to the IPN with a success status code.

The interaction looks like this:

IPN

Configuration

In order to use the IPN workflow you must include at least the notify_url field in the merchant section of the initial API call. We suggest including a return_url to which the shopper will be redirected once the checkout is finished.

The Notify URL: The notify_url must be included in the merchant section of the initial API call. Its value should be a URL to which SeQura can make a POST request to trigger the confirmation process.

When the shop receives a request to the notify_url it needs to find the order that needs confirming in its database. SeQura will include the shop’s order reference (if it is known) along with its own order reference in the request (see below, IPN Request Example). If these attributes are not sufficient to find the order, the shop must include identifying parameters either in the URL or in the optional notification_parameters structure.

If you are doing an integration for a shared shop platform, we recommend that you include a digital signature in the notification_parameters so that nobody can fake a real request. See Securing the IPN call for details.

The Return URL: The return_url can be included in the merchant section of the initial API call. Its value should be a URL to which SeQura can redirect the shopper (with a GET request) after the confirmation step. This is typically the URL for a page that shows an order confirmation.

If the URL contains SQ_PRODUCT_CODE, that string will be replaced with SeQura’s product code before it is sent to the shopper. For instance, if the shopper uses invoicing and return_url is http://shop.example.com/checkout/confirmed?payment_method=sq-SQ_PRODUCT_CODE, the shopper will be redirected to http://shop.example.com/checkout/confirmed?payment_method=sq-i1. This allows the shop to display slightly different messages depending on the credit product that the shopper used. (For invoicing it might be useful to tell the shopper that they will receive payment instructions after the order has been sent and that they should not pay anything now.)

The Approved Callback (optional, not recommended): As an alternative to the return_url in some cases, SeQura can trigger a call to a Javascript function on the current page. To do this, include approved_callback in the merchant section of the initial API call.

Use of approved_callback is only meaningful for payment methods that stay on the shop’s pages during the entire checkout. Hence, it cannot be used when the shopper is redirected to a credit card gateway during the approval process. For this reason, we recommend that you only use return_url.

Processing the IPN

When SeQura sends the IPN (Instant Payment Notification) to the shop, the shop should understand this as a signal from SeQura that SeQura is willing to guarantee the payment of the order for which the credit was solicited and that it is now OK to go ahead and place the order. The only remaining step is for the shop to confirm that the shopper is finalising the order in the shop using SeQura for payment.

There are several variations to this workflow. The main differentiator is if the shop is able to carry out the work implied by an IPN or not. The different cases are described in the subsections below:

The shop handles the IPN completely

To handle the IPN completely, the shop needs to

send the order data to SeQura for verification,
mark the order as completed in the shop’s database,
send the order reference to SeQura (if this has not been done already),
respond to the IPN request with a 200 OK HTTP status.

In step 1, the merchant will make a PUT request to the URL returned in the Location header field of the initial solicitation. The merchant will send again all the order data and also will include the field state="confirmed".

SeQura will usually respond with a 200 OK status in which case the shop should proceed with steps 2-4. But if the order cart, delivery address, customer data or other details have changed in an unacceptable way, SeQura will respond to the confirmation request with a 409 Conflict status and a JSON body detailing the problems. In this case, the shop must not complete the order in the shop’s database or send the order reference to SeQura, but it must still respond to the IPN request with 200 OK.

Once the IPN has been handled, i.e., when SeQura has received the 200 OK, the shopper will be redirected to the return_url whether the order was successfully confirmed or not. For this reason, the action handler at the return_url must check the status of the order in the shop before deciding what to display.

Problem: Order reference missing

Until the shop informs SeQura of the order’s order_ref_1, SeQura will not be able to perform any work on the order and the merchant will not be paid for the order. SeQura will follow up at least weekly on confirmed orders that don’t have order_ref_1, but if the shop has recurring problems of this kind, SeQura will consider this a broken integration and disconnect the service.

Problem: Order reference not unique

SeQura expects the combination (merchant.id, merchant_reference.order_ref_1) to be unique for confirmed orders. The merchant must be aware that errors in the shop might mean that an order reference is reused and that SeQura will not process these orders. The error can occur in two places:

During step 1 above, when the shop requests SeQura to confirm the order. If the shop provided the order_ref_1 at the beginning of the checkout, SeQura will now check to see that the reference is unique among confirmed orders. If it isn’t, SeQura will respond with a 409 Conflict.
During step 3 above, when the shop updated the confirmed order with its order reference. Again, SeQura will respond with 409 Conflict if the order_ref_1 is not unique. This case is more complicated than the former since (a) the order is confirmed in the shop with SeQura as the payment method and (b) SeQura is not able to process the order further.

Order should not be paid with SeQura (410)

Between the start of the checkout and the IPN, the state of the shopping cart might have changed in ways that make it impossible to convert the cart to an order. For instance:

The shopper might have opened another browser tab and completed the order using another payment method.
An item in the cart might no longer be available (for the expected price, or at all).

In these cases, the shop should not confirm the order with SeQura, but instead respond to the IPN request with a 410 Gone. This will indicate to SeQura that the approved credit will not be used and that any down payment should be refunded.

Once SeQura has received the 410 Gone, the shopper will be redirected to the return_url.

Order cannot be found (404)

If the shop cannot find the order to be confirmed using the data in the notify_url or the request, it should respond with a 404 Not Found. SeQura will assume the reason is one of the following:

There has been a synchronisation delay between the storefront and the shop’s backend.
The shopper stayed too long in the checkout, and the unconfirmed order has been deleted from the shop.

SeQura will retry the IPN request a few times in case it is a synchronisation problem. If the 404 persists, SeQura will act as if it were a 410.

Order has already been confirmed with SeQura (409)

Due to communication or synchronisation errors, the shop might consider the order confirmed with SeQura while SeQura’s IPN service sees the order as needing confirmation. In this case, the shop should respond with a 409 Conflict which will serve as a signal to SeQura to investigate.

Once SeQura has received the 409 Conflict, the shopper will be redirected to an error page on SeQura’s web site.

Temporary server problem (5xx)

If the shop encounters temporary server problems during IPN processing (DB unavailable, for instance), you should send a status code in the 500 series. This tells SeQura to retry again later. SeQura will retry for up to 24 hours, during which time it will not cancel the order or return the first instalment as long as the shop responds with a 5xx.

Multi-request notification (30x)

If the shop responds with a 307 Temporary Redirect and a Location: header, SeQura will make another POST call with the same data to the URL returned in the Location: header. This can be used to work around technical shortcomings in platforms like Prestashop but is not recommended if it is not necessary. In Prestashop, the call sequence becomes:

SeQura POSTs to the notify_url.
- The shop PUTs the confirmation to SeQura, without order number.
- SeQura responds with 200.
- The shop creates an order out of the shopping cart.
The shop responds with 307 and a URL.
SeQura POSTs to the URL received in the previous step.
- The shop PUTs the confirmation to SeQura, this time with the newly assigned order number.
- SeQura responds with 200.
The shop responds with 200.

Some notes about this method:

The IPN accepts up to 2 redirects, i.e., it will make a maximum of 3 POST requests.
The URL returned in the Location: header can be the same as a previously visited URL and specifically, it can be the same as the notify_url .
Currently, a 302 Found can be used instead of the 307 Temporary Redirect. The use of 302 is deprecated and will not be allowed in new integrations. The problem is that 302 is customarily used by web servers to signal “I want you to GET this URL”, and the use of 302 sometimes creates hard-to-track bugs.
Other 30x codes are not accepted and will result in a failed IPN.

IPN Request Example

As mentioned above, SeQura includes the available order references in the IPN request. Assuming that the original API request sent by the shop contained

{
  "order": {
    "merchant": {
      "id": "...",
      "notify_url": "http://shop.example.com/ipn-me",
      "return_url": "http://shop.example.com/checkout/confirmed?payment_method=sq-SQ_PRODUCT_CODE",
    },
    "merchant_reference": {"order_ref_1": "MHPULMKOE"},
    ...

and that SeQura returned a URL ending in /9201b602-94b3-4804-8ef2-080c518378ee in the Location header, the IPN request will look like this:

POST /ipn-me HTTP/1.1
User-Agent: SeQura-IPN/1.0
Connection: close
Content-Type: application/x-www-form-urlencoded
Content-Length: 146
Host: shop.example.com

order_ref=9201b602-94b3-4804-8ef2-080c518378ee&order_ref_1=MHPULMKOE&approved_since=0&product_code=i1

Note the names order_ref for SeQura’s reference and order_ref_1 for that of the shop. order_ref_1 only appears in the IPN call if it was included in the initial API call.

The variable approved_since is equal to the number of seconds since SeQura approved the order. It is included to facilitate debugging in cases where shops return 5xx and it is recommended that the shop log this value.

The variable product_code is included for use with our platform plugins for Magento, Prestashop, etc, and should be ignored by other integrators.

The IPN request might include more data in the future without prior notification. Future data will have variable names that start with sq_ to avoid clashes with data provided in the merchant.notification_parameters key.

Securing the IPN call

Secure the IPN call by including a secure token, a short string that is hard to guess, easy to verify and only used once.

Creating a secure token: The simplest way to create a secure token is to use a cryptographic hash function and a secret salt (string which should not be known outside your application). In this example the token is the SHA1 digest of 1234:sUpErSeCrEtSaLt, i.e. the cart id, a colon and a salt.

{
  "order": {
    "merchant": {
      "notify_url": "https://my.shop.tld/checkout/sequra-ipn",
      "notification_parameters": {
        "cart": "1234",
        "token": "4207e9302d31d4fa2dbcaf9dfb45249d2581b9f8"
      },

IPs used in the IPN request

SeQura uses 3 static IPs for both sandbox and production environments, from where a request can arrive:

34.253.159.179
34.252.147.155
52.211.243.177

Notes

Please remember that when receiving the IPN you won’t have access to the session and in case you need some data from it you will need to send it in notification_parameters.

Tips for working with IPN in development environments

Using tunnels

If you want to integrate the IPN workflow in a development environment behind a firewall our servers won’t be able to lookup your notify_url unless you expose it to the net. We recommend using ngrok to expose a specific port or sub domain.

For example you could expose port 3000 with:

$ ngrok http 3000

Ngrok will generate a unique url in order to expose the desired port. For example, if ngrok assigns you http://12345678.ngrok.io your notify_url could be http://12345678.ngrok.io/checkout/sequra-ipn.

The development / staging server doesn’t have an up to date SSL certificate

The IPN expects to notify to a HTTPS url. The notify_url must be HTTPS. If the server doesn’t have an up to date SSL certificate, the IPN won’t proceed. However, there is a way to bypass this limitation in the sandbox environment. Important: This won’t work in production / live environment.

To use a non secure url in the notify_url field, you can prefix the url with the protocol “unverified-https://”. For instance: unverified-https://my.shop.tld/checkout/sequra-ipn/8765432

- API Integration Documentation

3. Confirm order (legacy)