Authorisation hold

Notice: This article covers placing an authorisation hold via Payment Page as part of processing one-time two-step purchases and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of processing one-time two-step purchases:

  • One-time two-step purchase—an article in the section Payment models and statuses that provides a general description of processing one-time two-step purchases in the ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
  • articles of the Payment methods section containing a description of processing one-time two-step purchases via Payment Page with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

General information

Two-step purchase, or one-time two-step purchase, is a payment type which uses two steps to make a one-time transfer of funds from customer to merchant. On the first step, merchant initiates an authorisation hold—in other words, the purchase amount is deducted from the credit limit of customer's card account. On the second step, the purchase amount is “captured,” or, in other words, it is transferred to the merchant account based on the merchant request or after specific time lag. Two-step purchases are currently available only for card payments.

Note: If the customer selects the payment method for which two-step purchases are not supported, a one-time one-step purchase is processed instead.

Payment Page allows you to apply authorisation hold which in fact is the first step of this purchase type; authorisation hold is also available for MO/TO (Mail Order/Telephone Order) purchases. To apply an authorisation hold, you use the Purchase operation mode.

In terms of performing the first step of the one-time two-step purchase using Payment Page, the basic steps that the customer performs may be selecting payment instrument, specifying payment details and waiting for notification about payment processing result.



To perform the second step (withdrawal or release of funds), the merchant needs to use Gate or Dashboard or configure automatic performance of this step after a specific time lag. In order to configure automatic withdrawal or release of funds, contact ecommpay technical support (support@ecommpay.com).

In terms of performing authorisation hold, payment information can be specified as follows:

  • On the payment form, by completing the fields. In this case the customer completes all the fields on the payment form.
  • On the payment form, with an option to use saved payment information. If the customer's identifier is specified in the request for opening Payment Page, the customer can either choose one of the saved payment instruments or enter new payment information; the new payment instrument can also be saved for subsequent purchases.

    In addition to selecting payment instrument, for some payment instruments entering verification code is required (such as CVC, CVV, or CID for card payments).

  • Outside the payment form, with an option to use saved payment information. In this case the customer selects specific card in the web service, the token of this card is specified in the request for opening the payment form, and, when the payment form is opened, it already contains all required payment information, except for verification code (CVC, CVV, CID) which the customer is required to enter on the payment form.


Different options of specifying payment information on Payment Page: by completing the fields on the form, by selecting the saved payment instrument on the form and by selecting saved payment instrument before opening the payment form respectively.

Time limit for authorisation hold

According to the requirements of Visa, Mastercard, and American Express, the time lag for holding funds is limited. For different types of cards the maximum allowed time lag is defined according to the following terms:

  • Visa cards:
    1. If authorisation hold is performed as a part of COF purchase processing, the maximum allowed time lag is 5 days.
    2. If authorisation hold is performed not as a part of COF purchase processing or COF purchase registration, and the merchant's Merchant Category Code (MCC) corresponds to one of the numbers: 3351–3500, 3501–3999, 4411, 7011, 7512, 7513, the maximum allowed time lag is 30 days.
    3. In other cases the maximum allowed time lag is 10 days.
  • Maestro and Cirrus cards: the maximum allowed time lag is 6 days.
  • Other Mastercard cards: the maximum allowed time lag is 28 days.
  • American Express cards:
    1. If merchant MCC is associated with hotel industry, car rental, or cruise lines the allowed time lag may extend to the entire duration of stay at a hotel, car rent duration or cruise duration, accordingly.
    2. In other cases the maximum allowed time lag is 7 days.

The maximum allowed time lag for holding funds is calculated starting from the moment the auth operation is created in the ecommpay payment platform. 30 minutes before the time lag expires, depending on the parameters specified by the ecommpay employees, one of the following operations is performed automatically: a withdrawal (capture) or a release (cancel) of the held funds, after that a callback is sent to the web service. For more information and configuration of the operation type you can refer to your ecommpay key account manager. There is an exception for American Express cards for which the maximum allowed time lag is limited by the entire duration of stay at a hotel, car rent duration or cruise duration—automatic withdrawal is not available for such cards.

If the time lag specified by the merchant for automatic withdrawal or release of funds exceeds the maximum allowed time lag, withdrawal or release of funds is performed according to the maximum allowed time lag. For instance, if the merchant configures automatic release of the held funds upon the expiration of 10 days and authorisation hold is performed by using Maestro card (the maximum allowed time lag for Maestro card is 6 days), automatic release of funds is performed upon the expiration of 6 days.

Workflow

In terms of authorisation hold by using Payment Page, the merchant web service is required to do the following:

  1. Create and send a request for opening Payment Page to the payment platform.
  2. Receive a callback with information about the result of the request processing from the payment platform.

Authorisation hold performing may involve additional procedures:

  • 3‑D Secure authentication, in terms of which the customer is transferred to the service of the issuer where the customer needs to complete authentication using the code received by SMS or performing other required steps, or loading page is displayed (while issuer confirms authentication with no customer effort required).
  • Customer authentication on merchant's request, in terms of which an additional page is displayed and the customer needs to enter special verification code received by SMS or in a bank statement; this type of authentication involves a temporary hold of the agreed amount on the customer's account. This type of authentication can be used instead of 3‑D Secure authentication or in addition to it.
  • Submission of additional payment information, in terms of which notification and additional fields to be completed are displayed on the payment form. The fields should be completed on the same page of the payment form.

The following sections cover information about request and callback formats to use when performing authorisation hold using payment cards. For information about request and notification formats when performing authorisation hold using alternative payment methods, see Methods.

Request format

The format of the request for opening Payment Page to perform authorisation hold is the same as the request format described in the Payment Page API Description section. When creating request, you should consider the following:

  1. The request must contain the following required parameters:
    • card_operation_type—operation type for payment processing by using payment card. The parameter value must be set to auth, if purchases for the project are enabled by merchant request.
    • project_id—the project ID obtained from ecommpay.
    • payment_id—the payment ID unique within the project.
    • payment_amount—payment amount in minor currency units.
    • payment_currency—payment currency code according to ISO-4217 alpha-3.
    • customer_id—the customer ID unique within the project.
    • signature—the signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
  2. To make sure that all required parameters are specified if the capability of collecting such customer data is not implemented (details), pass at least one of the following parameters in the request: customer_email or customer_phone.
  3. If you need to have the payment form displayed with the payment card selected, specify the account_token parameter in the request for opening the payment form. In this parameter you need to specify token of the payment card associated with the payment information of the card on the side of the payment platform.
  4. To display Payment Page in a required language, you need to additionally specify in the request the language_code parameter and the language code in accordance with ISO 639-1 alpha-2 as its value. If this parameter is not specified, the payment form is displayed in the language selected automatically (by the browser language, by the region, or by default—learn more).
  5. To add description of the payment, you need to specify in the request the paymentDescriptionparameter. The value of this parameter is displayed to the customer on the page with information about the result and to the merchant in Dashboard and in a callback with information about the payment result.
  6. To perform an MO (Mail Order) purchase, you must use the moto_type parameter set to 1; for a TO (Telephone Order) purchase, add the moto_type parameter set to 2.
  7. If needed, you can also add any other additional parameters supported by Payment Page in the Purchase operation mode. The full list of parameters for opening Payment Page is provided in the Parameters for opening payment form section.

Thus, a correct payment request must include project, customer and payment IDs, language code, currency and the amount of a payment in the appropriate currency, the auth operation type and signature. Other parameters can also be specified in the request, but they are optional.

{
   "card_operation_type": "auth",
   "project_id": 42,
   "payment_id": "456789",
   "customer_id": "customer_12",
   "payment_currency": "USD",
   "payment_amount": "2000",
   "customer_phone": "44991234567",
   "signature": "TSzdE5rJZaA9VyJtnfRI3620jOp2hf4RKwmKoWYjTYAK2MxF...",

// when processing payment using preselected card:
    "account_token":"959c664ad64b8caa54bb7836ddc737fd1a679242a039..."

}
Figure 1. Example of the request for opening Payment Page
https://https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=en&project_id=42&payment_amount=2000&payment_id=456789&card_operation_type=auth&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhZLxEzkgcoZr...

Callback format

The format of the callback to notify the merchant about the result of performing authorisation hold is the same as the format described in the Callbacks section.

The following is an example of callback with an information about successful authorisation hold of 2 000,00 USD made for the customer customer_12 using the payment card with the card number 541333******0019 in terms of the project 42.

Figure 2. Example of a callback with information about successful authorisation hold
{
    "project_id": 42,
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "awaiting capture",
        "date": "2019-01-11T13:00:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "operation": {
        "id": 2777000002350,
        "type": "auth",
        "status": "success",
        "date": "2020-01-11T13:00:40+0000",
        "created_date": "2020-01-11T13:00:37+0000",
        "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "224750650",
            "date": "2020-01-11T13:00:39+0000",
            "result_code": "000",
            "result_message": "Approved",
            "auth_code": "505050",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success",
        "description": "SUCCESS",
        "eci": "00"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}

The following is the example of a callback with information about authorisation hold declined due to incorrect input of the expiration date of the payment card.

Figure 3. Example of a callback with information about declined authorisation hold
{
    "project_id": 42,
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "date": "2020-01-11T13:00:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "operation": {
        "id": 6304000002973,
        "type": "auth",
        "status": "decline",
        "date": "2020-01-11T13:00:40+0000",
        "created_date": "2019-01-11T13:00:34+0000",
        "request_id": "63821f1e49b2b289d1dee0552082ed60b4108175-5...c",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "239689120",
            "date": "2020-01-11T13:00:36+0000",
            "result_code": "101",
            "result_message": "Decline, expired card",
            "auth_code": "",
            "endpoint_id": 120
        },
        "code": "10106",
        "message": "Card expired",
        "description": "Bank cards. Operation was declined due to incorrect card expiry date entry",
        "eci": "00"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}

The following is an example of callback with an information about withdrawal of the held 2 000,00 USD from the payment card with the card number 541333******0019 of the customer customer_12 in terms of the project 42.

Figure 4. Example of the callback with information about withdrawal of the held funds
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "success",
        "date": "2020-01-11T15:54:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 7178000006597,
        "type": "capture",
        "status": "success",
        "date": "2020-01-11T15:54:40+0000",
        "created_date": "2019-01-11T15:54:39+0000",
        "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "227307324",
            "date": "2020-01-11T15:54:40+0000",
            "auth_code": "919372",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}

The following is an example of callback with an information about cancelling authorisation hold of 2 000,00 USD for the payment card with the card number 541333******0019 of the customer customer_12 in terms of the project 42.

Figure 5. Example of the callback with information about cancelling authorisation hold
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "canceled",
        "date": "2020-01-11T15:54:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 18289000007021,
        "type": "cancel",
        "status": "success",
        "date": "2020-01-11T15:54:40+0000",
        "created_date": "2020-01-11T15:54:40+0000",
        "request_id": "25cdabfad200b82bf6740d6a8d01818c6e64804e-1...c",
        "sum_initial": {
            "amount": 200000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "239672146",
            "auth_code": "",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}

The following is the example of a callback with information about authorisation hold declined due to incorrect card data input.

Figure 6. Example of a callback with information about declined authorisation hold
 {
    "account": {
        "number": "541333******0019",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2020-01-11T15:54:40+0000",
        "id": "456789",
        "method": "card",
        "status": "decline",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 18397000002376,
        "type": "cancel",
        "status": "decline",
        "date": "2020-01-11T15:54:40+0000",
        "created_date": "2020-01-11T15:54:35+0000",
        "request_id": "7482145798366de3166bedd372552b3f0094eed2-6...3",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "248013808",
            "date": "2020-01-10T22:37:10+0000",
            "auth_code": "876856",
            "endpoint_id": 120
        },
        "code": "10102",
        "message": "Incorrect data entered"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}