Hosted payment page

For general information on how to access the API, please see the REST API overview.

The HPP solution manages the customer redirections that are required in the checkout process and gives the option to use secure hosted payment pages by EMS Online. This significantly reduces the burden of compliance with PCI DSS for the merchant as they don’t need to store sensitive cardholder information. The following is a basic transaction where the cardholder will select a payment method on the HPP:

POST /v1/orders/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json

{
  "currency": "EUR",
  "amount": 995,
  "description": "Example description",
  "merchant_order_id": "TEST001",
  "return_url": "https://www.example.com/",
  "customer": {
    "locale": "nl"
  }
}

Please refer to the Mandatory Fields and Optional Fields below for what each one means and allowed values.

A response will be send by the server, which includes a URL (order_url) where the cardholder will need to be redirected to by the webshop.

{
  "currency": "EUR",
  "amount": 995,
  "description": "Example description",
  "merchant_order_id": "TEST001",
  "return_url": "https://www.example.com/",
  "customer": {
    "locale": "nl"
  },
  "id": "1c969951-f5f1-4290-ae41-6177961fb3cb",
  "created": "2016-07-04T11:41:57.121017+00:00",
  "modified": "2016-07-04T11:41:57.183822+00:00",
  "order_url": "api.online.emspay.eu/pay/1c969951-f5f1-4290-ae41-6177961fb3cb/",
  "status": "new"
}

All payment methods that have been approved and enabled for the webshop will be shown to the cardholder. Once the customer has completed the transaction, he will be redirected to the submitted return_url.

Select a subset of the allowed payment methods

In case you only want to offer the shopper a subset of available payment methods, you can limit the payment methods by specifying an allow list: payment_methods.

Example order request that is limited to bank transfer and iDEAL:

POST /v1/orders/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json

{
  "currency": "EUR",
  "amount": 995,
  "description": "Example description",
  "merchant_order_id": "TEST001",
  "payment_methods": ["ideal", "bank-transfer"],		
  "customer": {
    "locale": "nl"
  }
}

Change the order of payment methods

To change the order in which the payment methods are displayed on the hosted payment page, you can use the payment_methods field. Please note that Apple Pay and Google Pay are always displayed on top of the list.

Example order request that places Bancontact before the (credit) card option:

POST /v1/orders/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json

{
  "currency": "EUR",
  "amount": 995,
  "description": "Example description",
  "payment_methods: ["apple-pay", "bancontact", "credit-card"]
}

Fields

Mandatory fields

Optional fields