Server to server

If you want the cardholder to select the payment method in your webshop instead of on the EMS Online hosted payment page to provide a better user experience, server to server is a good solution. Below you can find an overview with examples for all the different payment methods that support server to server.

Payment methods

The following fields are mandatory when creating a new order:

  • currency
  • amount
  • payment_method

When specifying the payment method in the request, payment_url will be returned to which customer needs to be redirected to.

Apple Pay

The following is an example of an Apple Pay request:

POST /v1/orders/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json
    
{
  "currency": "EUR",
  "amount": 995,
  "merchant_order_id": "EXAMPLE001",
  "description": "Example Apple Pay order",
  "return_url": "https://www.example.com/",
  "webhook_url": "https://www.example.com/webhook/",
  "transactions": [
    {
      "payment_method": "credit-card"
    }
  ]
}

Bancontact

The following is an example of a Bancontact request:

POST /v1/orders/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json
    
{
  "currency": "EUR",
  "amount": 995,
  "merchant_order_id": "EXAMPLE001",
  "description": "Example Bancontact order",
  "return_url": "https://www.example.com/",
  "webhook_url": "https://www.example.com/webhook/",
  "transactions": [
    {
      "payment_method": "bancontact"
    }
  ]
}

Credit card

The following is an example of a creditcard request:

POST /v1/orders/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json
    
{
  "currency": "EUR",
  "amount": 995,
  "merchant_order_id": "EXAMPLE001",
  "description": "Example creditcard order",
  "return_url": "https://www.example.com/",
  "webhook_url": "https://www.example.com/webhook/",
  "transactions": [
    {
      "payment_method": "credit-card"
    }
  ]
}

Currently the following brands are supported:

  • VISA
  • MasterCard
  • Maestro
  • V Pay
  • Diners/Discover

iDEAL

For an iDEAL order the following extra details are required:

  • BIC of the chosen bank (the “issuer ID”)
  • URL to redirect the customer to after payment (return_url – optional, but recommended)

The following is an example of an iDEAL request:

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

{
  "merchant_order_id": "EXAMPLE001",
  "amount": 995,
  "currency": "EUR",
  "description": "Example iDEAL order",
  "return_url": "https://www.example.com/",
  "transactions": [
    {
      "payment_method": "ideal",
      "payment_method_details": {
        "issuer_id": "INGBNL2A"
      }
    }
  ]
}

iDEAL QR

Only the Rabobank, Knab, ING and ABN AMRO banking apps can scan the QR code directly. When having another bank the customer should use their camera with built in QR scanner or a dedicated QR scanner. The customer will then be send to a payment page where they’ll be able to select their bank and complete the transaction as normal.

The following details can be specified when creating a new iDEAL QR request:

  • amount - The pre-entered amount for the specific QR code.
  • amount_changeable - This field indicates whether the Consumer can edit the amount in the app. Enter false when the amount must not be fixed and true when the amount must be editable by the user. Please note that for fixed amounts, the amount must be entered and it cannot be 0.
  • amount_max - In this field a maximum amount can be provided if the amount is not fixed. It must be larger than 0 and larger than amount. – optional
  • amount_min - In this field a mimimum amount can be provided if the amount is not fixed. It must be larger than 0 and smaller than amount. – optional
  • description - The payment description shown in the app and specified in the iDEAL messages protocol.
  • one_off - This field indicates whether the iDEAL QR code may be used only once or whether it can be used multiple times. – default true
  • expiration - The date and time at which the QR code expires and can no longer be used for iDEAL transactions. – defaults to +1 year
  • merchant_order_id - Your own order id.
  • size - In this field, the merchant indicates the size of the QR code in pixels. The value must be between 100 and 2000 px. – default 200
  • return_url - URL to redirect the customer to after payment – optional

The following is an example of an iDEAL QR request:

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

{
    "amount_changeable": false,
    "amount": 995,
    "currency": "EUR",
    "description": "Example iDEAL QR order",
    "one_off": true,
    "merchant_order_id": "TEST001",
    "size": 200,
    "return_url": "https://www.example.com/",            
    "webhook_url": "https://www.example.com/"
}

The API response will contain, in the qr_url field, the URL to the QR code:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "amount": "9.95",
    "amount_changeable": false,
    "beneficiary": "Example Merchant",
    "description": "Example order #1",
    "expiration": "2020-09-23 11:28",
    "id": "1a4a46d1-e839-49e5-9f10-a3895a3d59e3",
    "merchant_id": "298939b0-cb8b-4e1d-b388-3efae9205fff",
    "merchant_order_id": "TEST001",
    "merchant_sub_id": 0,
    "one_off": true,
    "project_id": "9db1fc26-eab3-4b68-82e0-6c5dad856c89",
    "qr_url": "https://qr2.ideal.nl/ideal-qr/qr/get/1a4a56a1-e839-49e5-9f10-a3805a3d49e4",
    "return_url": "https://www.example.com/",
    "size": 200,
    "webhook_url": "https://www.example.com/"
}

To be able to recognize an iDEAL QR order we store the flag from-idealqr and we store the qr_id in the extra > idealqr_id field. The following is an example of an iDEAL QR request order status:

{
    "amount": 995,
    "created": "2019-09-23T11:33:12.237535+00:00",
    "currency": "EUR",
    "description": "Example order #1",
    "extra": {
        "idealqr_id": "1a4a46d1-e839-49e5-9f10-a3895a3d59e3"
    },
    "flags": [
        "from-idealqr"
    ],
    "id": "b06ebdcb-972f-4e03-bdb4-8099bfb34861",
    "last_transaction_added": "2019-09-23T11:33:12.523240+00:00",
    "merchant_id": "298939b0-cb8b-4e1d-b388-3efae9205fff",
    "merchant_order_id": "TEST001",
    "modified": "2019-09-23T11:33:14.106042+00:00",
    "project_id": "9db1fc26-eab3-4b68-82e0-6c5dad856c89",
    "return_url": "http:\/\/www.example.com\/",
    "status": "processing",
    "transactions": [
        {
            "amount": 995,
            "balance": "internal",
            "created": "2019-09-23T11:33:12.523240+00:00",
            "credit_debit": "credit",
            "currency": "EUR",
            "description": "Example order #1",
            "events": [
                {
                    "event": "new",
                    "id": "38ff72e6-681d-4cf5-995c-8a443dfa1c64",
                    "noticed": "2019-09-23T11:33:12.682978+00:00",
                    "occurred": "2019-09-23T11:33:12.523240+00:00",
                    "source": "set_status"
                },
                {
                    "event": "processing",
                    "id": "5c0f10e8-0ef6-4f27-94db-f174b05a633e",
                    "noticed": "2019-09-23T11:33:12.785172+00:00",
                    "occurred": "2019-09-23T11:33:12.785172+00:00",
                    "source": "set_status"
                }
            ],
            "expiration_period": "PT30M",
            "id": "0aab2e41-98b3-4637-9c24-6d9f2bc81a72",
            "merchant_id": "298939b0-cb8b-4e1d-b388-3efae9205fff",
            "modified": "2019-09-23T11:33:14.133730+00:00",
            "order_id": "b06ebdcb-972f-4e03-bdb4-8099bfb34861",
            "payment_method": "ideal",
            "payment_method_brand": "ideal",
            "payment_method_details": {
                "consumer_bic": null,
                "consumer_city": null,
                "consumer_iban": null,
                "consumer_name": null,
                "issuer_authentication_url": "https:\/\/betalen.rabobank.nl\/ideal-betaling\/landingpage?random=e4179943e12b0ca52ed4035dd63180f39c9f393ed482bbcca13dd32ade970265&trxid=0030004422693169",
                "issuer_id": "RABONL2U",
                "status": "Open",
                "transaction_id": "0030004422693169"
            },
            "payment_url": "http:\/\/www.example.com\/",
            "project_id": "9db1fc26-eab3-4b68-82e0-6c5dad856c89",
            "status": "processing"
        }
    ],
    "webhook_url": "http:\/\/www.example.com\/"
}

Payconiq

The following is an example of a Payconiq request:

POST /v1/orders/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json
    
{
  "currency": "EUR",
  "amount": 995,
  "merchant_order_id": "EXAMPLE001",
  "description": "Example Payconiq order",
  "return_url": "https://www.example.com/",
  "webhook_url": "https://www.example.com/webhook/",
  "transactions": [
    {
      "payment_method": "payconiq"
    }
  ]
}

PayPal

The following is an example of a PayPal request:

POST /v1/orders/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json
    
{
  "currency": "EUR",
  "amount": 995,
  "merchant_order_id": "EXAMPLE001",
  "description": "Example PayPal order",
  "return_url": "https://www.example.com/",
  "webhook_url": "https://www.example.com/webhook/",
  "transactions": [
    {
      "payment_method": "paypal"
    }
  ]
}

Bank Transfer

The following is an example of a bank transfer request:

POST /v1/orders/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json
    
{
  "currency": "EUR",
  "amount": 995,
  "merchant_order_id": "EXAMPLE001",
  "description": "Example Bank Transfer order",
  "return_url": "https://www.example.com/",
  "webhook_url": "https://www.example.com/webhook/",
  "transactions": [
    {
      "payment_method": "bank-transfer"
    }
  ]
}

The field reference will be returned in the response, which the customer will need to mention in the description of the bank transfer for identification on our side.

{
  "amount": 995,
  "client": {
    "user_agent": "Testing API"
  },
  "created": "2016-07-04T11:41:53.734183+00:00",
  "currency": "EUR",
  "id": "e4d22966-fbba-4753-ab89-b1ec9997171e",
  "last_transaction_added": "2016-07-04T11:41:54.028067+00:00",
  "merchant_id": "7131b462-1b7d-489f-aba9-de2f0eadc9dc",
  "modified": "2016-07-04T11:41:54.609881+00:00",
  "project_id": "1ef558ed-d77d-470d-b43b-c0f4a131bcef",
  "return_url": "https://www.example.com/",
  "status": "processing",
  "transactions": [
    {
      "amount": 995,
      "balance": "internal",
      "created": "2016-07-04T11:41:54.028067+00:00",
      "credit_debit": "credit",
      "currency": "EUR",
      "events": [
        {
          "event": "new",
          "id": "8c7f2802-9eee-44d1-b691-95bea6a2dc32",
          "noticed": "2016-07-04T11:41:54.154965+00:00",
          "occurred": "2016-07-04T11:41:54.028067+00:00",
          "source": "set_status"
        },
        {
          "event": "pending",
          "id": "80e845b6-c9e2-403d-a8d4-e193ab246767",
          "noticed": "2016-07-04T11:41:54.568740+00:00",
          "occurred": "2016-07-04T11:41:54.568740+00:00",
          "source": "set_status"
        }
      ],
      "expiration_period": "P30D",
      "id": "c511a0ec-a023-49a6-a5bf-00bdcaef2f21",
      "merchant_id": "7131b462-1b7d-489f-aba9-de2f0eadc9dc",
      "modified": "2016-07-04T11:41:54.837387+00:00",
      "order_id": "e4d22966-fbba-4753-ab89-b1ec9997171e",
      "payment_method": "bank-transfer",
      "payment_method_brand": "sepa",
      "payment_method_details": {
        "consumer_bic": "",
        "consumer_iban": "",
        "consumer_name": "",
        "reference": "9210201636861572",
        "creditor_account_holder_city": "Amsterdam",
        "creditor_account_holder_country": "Netherlands",
        "creditor_account_holder_name": "EMS",
        "creditor_bic": "NL08ABNA0000000XXX",
        "creditor_iban": "ABNXXXXX",
      },
      "project_id": "1ef558ed-d77d-470d-b43b-c0f4a131bcef",
      "status": "pending"
    }
  ]
}

Because the status of a bank transfer is always decoupled and delayed, the only way to be notified when the status has changed is to make use of the webhook.