Checkout integration

Redirection flow

The transaction flow consists of three main steps: initialization, authorization, and validation.

The transaction is initially triggered by you server-side, by making an API call with the transaction details. If successful, a transaction object is returned to you. This is the initialization step.

The attribute details.approval_url signifies that user interaction is required, in which case you must redirect the customer's web browser to the provided URL. The customer then interacts directly with the processor, or with their financial institution. This is the authorization step.

If and when the customer has successfully authorized the payment, they are redirected to our server, where we handle the result of the authorization, and redirect them to your website. This is the validation step.

Eventually, the customer reaches the URL on your website that you provided to us during the initialization step. We append to this URL a query parameter describing the transaction, to enable you to retrieve the transaction object via our API.

redirection flow

After this final redirection, you must query our API to validate the outcome of the transaction. Successful and failed transactions both result in a redirection to the same URL, so to learn the final outcome, and to prevent spoofing of the transaction outcome by the customer, a server-side call to our API is required.

Create new customer

Before initiating the transaction you have to create a customer object and add the id to the transaction. For returning customers you don't have to create a new customer object.

You can create a customer object by making a POST request to the following url.

/v1/customer

For instance, here is a valid request body:

{
      "title": "ms",
      "gender": "female",
      "initials": "J",
      "first_name": "Jaimy",
      "last_name": "Uil",
      "date_of_birth": "1971-05-12",
      "street_address": "Korte nieuwstraat",
      "house_number": "5846",
      "city": "Naarden",
      "region": "Zuid-holland",
      "postal_code": "7244 DK",
      "country_code": "NL",
      "phone_number": "+31612698434",
      "email_address": "jaimy.uil@example.com",
      "organisation": "fab04e42-0901-4e33-839d-4a326d037497"
}

This will result in a customer json object. The id retrieved in this object can be used in the transaction request. It is also possible to create both objects at the same time but please be aware of the added complexity.

Transaction initialization

Once you have received and parsed the form submission from the customer you must initiate the transaction by making a POST request to the following url:

/v1/transaction/start

For instance, here is a valid request body that initiates an iDEAL transaction:

{
    "payment_profile": "7c23a50d-8699-431c-a82b-a78718d2b6f6",
    "amount": 14,
    "customer": "cbbfa6ec-fb44-4da4-94c4-d81e92fd43e6",
    "customer_ip": "127.0.0.1",
    "dynamic_descriptor": "orderdesc01",
    "merchant_reference": "my order id",
    "payment_product": "ideal",
    "user_agent": "Opera/12.02 (Android 4.1; Linux; Opera Mobi/ADR-1111101157; U; en-US) Presto/2.9.201 Version/12.02",
    "details": {
        "redirect_url": "https://example.com/finalize",
        "issuer": "INGBNL2A",
    },
    "webhook_transaction_update": "https://example.com"
}

The currency of the payment profile needs to be EUR, since iDEAL is only available in the Netherlands. Remember that the amount must be specified without a decimal point, meaning the value 14 refers to the amount €0.14 EUR.

The details part of the object is payment method-specific. Either see this page for the transaction details or take a look at the API documentation. It's also possible to add extra merchant data.

In response, we reply with a JSON representation of an initiated transaction. This transaction object also includes the details property, which has been augmented with an approval_url. You will need to redirect the customer to the approval_url so they may authorize the payment.

Here is an example response body of a successful transaction initiation.

{
    "id": "e0377c06-a9e0-43a8-9885-8799a8338b5a",
    "payment_profile": "7c23a50d-8699-431c-a82b-a78718d2b6f6",
    "amount": "14",
    "customer": "cbbfa6ec-fb44-4da4-94c4-d81e92fd43e6",
    "customer_ip": "127.0.0.1",
    "dynamic_descriptor": "orderdesc01",
    "user_agent": "Opera/12.02 (Android 4.1; Linux; Opera Mobi/ADR-1111101157; U; en-US) Presto/2.9.201 Version/12.02",
    "payment_product": "ideal",
    "payment_product_type": "ideal",
    "processor": "ideal",
    "details": {
        "redirect_url": "https://example.com/finalize",
        "issuer": "INGBNL2A",
        "approval_url": "https://api.magnius.com/v1/transaction/e0377c06-a9e0-43a8-9885-8799a8338b5a/authorize"
    },
    "status": "INITIATED",
    "last_status_update": "2016-06-16T11:31:51.881Z",
    "created_at": "2016-06-16T11:31:51.881Z"
}

In case of an error while initiating the transaction, the server will respond with a JSON object containing the following fields.

  • message {String} — A message describing the error.
  • details {Object} [Optional] — An object containing details about the transaction. The format of this object depends of the nature of the error.

Redirect the customer

Once the transaction has been successfully initiated, you should redirect the customer to the approval_url so they may authorize the payment by interacting directly with their bank.

At the end of the authorization process, the customer is redirected to the redirect_url you provided when you initiated the transaction. If something goes wrong during this process, we will try, whenever possible, to redirect the customer, so that the customer always ends up on your server.

The status of the transaction remains unknown until you query its status from our server. Therefore, a query parameter transaction_id is appended to the redirect_url you provided. This refers to the ID we generated for the transaction, which you must use in order to retrieve the status of the transaction.

In the event of an unexpected issue during the redirection process, an additional error query parameter is also appended to the url. This parameter is an encoded string (as defined by the encodeURIComponent presented in ECMAScript ECMA-262) which gives further information about the nature of the error.

Transaction webhooks

To receive transaction notifications we have two different options. Either you can set a general webhook url via the payment profile object (API documentation, field: webhook_transaction_update). The other option is to add the field webhook_transaction_update to the object used to initiate the transaction. This gives the opportunity to add a transaction specific URL.