Recurring credit-card payments

Recurring credit card payments can be used for subscription-based payments and other situations where costs with a periodical character have to be paid. In a series of recurring transactions, each transaction must have the same amount. The maximum time span that can be covered by a series of recurring transactions is one year; after this period the original first authorization is no longer valid and a new cycle has to be started. A merchant can apply for recurring payments feature, only if he/she has already been approved for Credit Cards.

First Recurring Transaction

In order to setup recurring payments, the merchant has to perform a first recurring transaction. The first recurring transaction is created with the recurring_type set to first. It is like a regular credit Card transaction in which the customer(card holder) needs to visit the URL supplied in the returned payment_url field and authenticate themselves on the 3D secure page.

Example first recurring order request:

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

{
  "merchant_order_id": "1",
  "amount": 4000,
  "currency": "EUR",
  "description": "Credit card order - First recurring",
  "transactions": [
    {
      "payment_method": "credit-card",
      "payment_method_details": {
        "recurring_type":"first"
      }
    }
  ]
}

Returns response

{
  "amount": 4000,
  "client": {
    "user_agent": "Testing API"
  },
  "created": "2017-11-24T14:43:15.522321+00:00",
  "currency": "EUR",
  "description": "Credit card order - First recurring",
  "id": "3da62f95-c934-470c-a8a1-a4123e362501",
  "last_transaction_added": "2017-11-24T14:43:15.941760+00:00",
  "merchant_id": "69c489e0-570d-43d6-a362-4b3e92131e15",
  "merchant_order_id": "1",
  "modified": "2017-11-24T14:43:17.235885+00:00",
  "project_id": "3b279187-0454-455c-8f5f-85a37f77de8b",
  "status": "new",
  "transactions": [
    {
      "amount": 4000,
      "balance": "internal",
      "created": "2017-11-24T14:43:15.941760+00:00",
      "credit_debit": "credit",
      "currency": "EUR",
      "description": "Credit card order - First recurring",
      "expiration_period": "PT30M",
      "id": "bb6ffac8-09c3-4143-bad0-e4bfd56c8f15",
      "merchant_id": "69c489e0-570d-43d6-a362-4b3e92131e15",
      "modified": "2017-11-24T14:43:17.162586+00:00",
      "order_id": "3da62f95-c934-470c-a8a1-a4123e362501",
      "payment_method": "credit-card",
      "payment_method_details": {
        "recurring_type": "first"
      },
      "payment_url": "api.online.emspay.eu/pay/3da62f95-c934-470c-a8a1-a4123e362501/?payment_method=credit-card",
      "project_id": "3b279187-0454-455c-8f5f-85a37f77de8b",
      "status": "new"
    }
  ]
}

Once the customer completes the first recurring payment, the merchant can obtain the vault_token to be used for the actual recurring transactions by sending a HTTP GET request to /orders/<order_id>/. This is thevault_token to be used for all the subsequent actual recurring transactions for this customer.

Example - Getting details of a first recurring order:

GET /v1/orders/3da62f95-c934-470c-a8a1-a4123e362501/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=

Response contains vault_token within transaction’s payment_method_details:

{
  "amount": 4000,
  "client": {
    "user_agent": "Testing API"
  },
  "created": "2017-11-24T14:43:15.522321+00:00",
  "currency": "EUR",
  "customer": {
    "country": "NL",
    "ip_address": "127.0.0.1"
  },
  "description": "Credit card order - First recurring",
  "id": "3da62f95-c934-470c-a8a1-a4123e362501",
  "last_transaction_added": "2017-11-24T14:43:15.941760+00:00",
  "merchant_id": "69c489e0-570d-43d6-a362-4b3e92131e15",
  "merchant_order_id": "1",
  "modified": "2017-11-24T14:47:43.712462+00:00",
  "project_id": "3b279187-0454-455c-8f5f-85a37f77de8b",
  "status": "completed",
  "transactions": [
    {
      "amount": 4000,
      "balance": "internal",
      "created": "2017-11-24T14:43:15.941760+00:00",
      "credit_debit": "credit",
      "currency": "EUR",
      "description": "Credit card order - First recurring",
      "expiration_period": "PT30M",
      "id": "bb6ffac8-09c3-4143-bad0-e4bfd56c8f15",
      "merchant_id": "69c489e0-570d-43d6-a362-4b3e92131e15",
      "modified": "2017-11-24T14:47:43.315040+00:00",
      "order_id": "3da62f95-c934-470c-a8a1-a4123e362501",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "payment_method_details": {
        "card_expiry": "012020",
        "cardholder_name": "Cardholder name",
        "liability_shift": true,
        "recurring_type": "first",
        "truncated_pan": "************0002",
        "vault_token": "0c8fd8ab-25ec-4109-ac8f-495804aa5026"
      },
      "product_type": "corpnl",
      "project_id": "3b279187-0454-455c-8f5f-85a37f77de8b",
      "status": "completed"
    }
  ]
}

Actual Recurring Transaction

After the first recurring credit card transaction, it is possible for the merchant to perform the actual recurring credit card transactions on-demand. The actual recurring transaction is created with the recurring_type set to recurring along with the vault_token set to the value obtained after the first recurring transaction creation.

The actual recurring transaction will be initiated instantly and completed without shopper intervention. It will not contain payment_url in the response.

Example recurring order request:

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

{
  "merchant_order_id": "2",
  "amount": 4000,
  "currency": "EUR",
  "description": "Credit card order - Actual recurring",
  "transactions": [
    {
      "payment_method": "credit-card",
      "payment_method_details": {
        "recurring_type": "recurring",
        "vault_token":"0c8fd8ab-25ec-4109-ac8f-495804aa5026"
      }
    }
  ]
}

Returns response

{
  "amount": 4000,
  "client": {
    "user_agent": "Testing API"
  },
  "created": "2017-11-27T11:01:31.773782+00:00",
  "currency": "EUR",
  "description": "Credit card order - Actual recurring",
  "id": "0a73c8e3-7a2f-40ee-8f6c-fa41a37c140a",
  "last_transaction_added": "2017-11-27T11:01:32.838300+00:00",
  "merchant_id": "69c489e0-570d-43d6-a362-4b3e92131e15",
  "merchant_order_id": "2",
  "modified": "2017-11-27T11:01:38.611714+00:00",
  "project_id": "3b279187-0454-455c-8f5f-85a37f77de8b",
  "status": "processing",
  "transactions": [
    {
      "amount": 4000,
      "balance": "internal",
      "created": "2017-11-27T11:01:32.838300+00:00",
      "credit_debit": "credit",
      "currency": "EUR",
      "description": "Credit card order - Actual recurring",
      "expiration_period": "PT30M",
      "id": "9a4a7cea-5f7c-46ae-80d0-b63a15ec56b5",
      "merchant_id": "69c489e0-570d-43d6-a362-4b3e92131e15",
      "modified": "2017-11-27T11:01:38.655435+00:00",
      "order_id": "0a73c8e3-7a2f-40ee-8f6c-fa41a37c140a",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "payment_method_details": {
        "card_expiry": "012020",
        "cardholder_name": "Cardholder name",
        "first_authorised_transaction_id": "bb6ffac8-09c3-4143-bad0-e4bfd56c8f15",
        "liability_shift": false,
        "recurring_type": "recurring",
        "truncated_pan": "************0002",
        "vault_token": "0c8fd8ab-25ec-4109-ac8f-495804aa5026"
      },
      "product_type": "corpnl",
      "project_id": "3b279187-0454-455c-8f5f-85a37f77de8b",
      "status": "processing"
    }
  ]
}