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’s 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"
  }
}

Fields

Mandatory fields

Field name	Description, possible values and format
`currency`	Only EUR is supported at the moment.
`amount`	All amounts are in cents. For example the amount of 12.95 needs to be sent as 1295.

Optional fields

Field name	Description, possible values and format
`merchant_order_id`	The order ID that will be stored.
`return_url`	URL where cardholder will be redirected to once the transaction has been completed. If not provided, the customer will be redirected to page at EMS Online and unless you make use of the webhook, your webshop won’t be able to know if there are any updates on the transaction status.
`locale`	This locale will be used to determine the language of the hosted payment page. Possible values are: `nl` `de` `nl-BE` `fr-BE` `en-GB`
`description`	A description of the order that will be stored.
`payment_methods`	If you let the customer select the payment method (e. g. iDEAL or credit card) in your shop environment or want to define the payment type yourself, transmit the parameter `payment_methods`. If you do not submit this parameter, the payment gateway will display a drop-down menu to the customer to choose from the payment methods available for your shop. Valid values are: `amex` `apple-pay` `bancontact` `credit-card` `ideal` `klarna-pay-later` `klarna-pay-now` `payconiq` `paypal` `bank-transfer`
`webhook_url`	The URL that will be used for the webhook.
`expiration_period`	It is optional to set an `expiration_period`, which will expire the payment page after a fixed duration.