MassPay menu

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.

This is an example of the response: 

{
    "organisation": "fab04e42-0901-4e33-839d-4a326d037497",
    "id": "cbbfa6ec-fb44-4da4-94c4-d81e92fd43e6",
    "title": "ms",
    "initials": "J",
    "first_name": "Jaimy",
    "last_name": "Uil",
    "gender": "female",
    "date_of_birth": "1971-05-12",
    "email_address": "jaimy.uil@example.com",
    "phone_number": "+31612698434",
    "fax_number": "",
    "street_address": "Korte nieuwstraat",
    "house_number": "5846",
    "house_number_suffix": "",
    "postal_code": "7244 DK",
    "city": "Naarden",
    "region": "Zuid-holland",
    "country_code": "NL",
    "social_security_number": "",
    "status": "unverified",
    "status_reason": "",
    "segment": "",
    "created_at": "2016-06-16T11:31:51.881Z",
    "last_status_update": "2016-06-16T11:31:51.881Z"
}

The id field can be used while starting a transaction (field: customer).

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 a dummy 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": "dummy",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/86.0.4240.198 Safari/537.36",
    "details": {
        "redirect_url": "https://example.com/finalize"
    },
    "webhook_transaction_update": "https://example.com"
}

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": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/86.0.4240.198 Safari/537.36",
    "payment_product": "dummy",
    "payment_product_type": "dummy",
    "processor": "dummy",
    "details": {
        "redirect_url": "https://example.com/finalize",
        "issuer": "INGBNL2A",
        "approval_url": "https://paymentapi.masspay.io/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.

  • code {String} — A 3-digit identifier.
  • 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.

Click here for more information about error codes

Redirect the customer

Once the transaction has been successfully initiated, you should redirect the customer to the approval_url.

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, such that the customer always ends up on your server.

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 status

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.

The transaction status can be checked in two ways:
GET /v1/transaction/{transaction id}/checkoutsuccess
GET /v1/transaction/{transaction id}

The normal transaction GET results in the full transaction while the "checkoutsuccess" addition results in only the necessary information to determine if the transaction was a success. For example: 

HTTP Code: 200

{
    "status": "SETTLEMENT_COMPLETED",
    "status_reason": "",
    "success": true
}

Transaction successful?

Generally speaking merchants accept both SETTLEMENT_REQUESTED and SETTLEMENT_COMPLETED as a success. This is also how the above mentioned checkoutsuccess endpoint works.

However we would like to point out that a SETTLEMENT_REQUESTED transaction still does have a very small chance of failing. For example when a customer is flagged by authorities after the capture but before settlement.

Due to the very small chance and the fact that settlement can take 1-3 days (depending on the payment method and agreements), merchants usually see SETTLEMENT_REQUESTED as a successful outcome.

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.

Transaction outcome testing

For testing the different transaction outcome statuses it's advised to use the "dummy" payment method. This will allow testing the different outcome flows.

A dummy transaction can be initiated by setting payment_product to dummy: 

{
    ...
    "payment_product": "dummy",
    ...
}