Authorization hold

General information

This section covers information about performing authorization hold which is the first step of the one-time two-step purchase by using Payment Page. General information is applicable to payment processing using payment cards and extends the information in the Payment models and statuses section.

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 authorization 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.

Payment Page allows performing authorization hold which is the first step of this type of payment. Authorization hold is performed using 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 (Dashboard Light) or configure automatic performance of this step after specific time lag. In order to configure automatic withdrawal or release of funds, contact ECommPay technical support (support@ecommpay.com).

In terms of performing authorization 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 or CVV 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) 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 authorization hold

According to the requirements of Visa and Mastercard, 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 Electron cards:
    1. If authorization hold is performed as a part of COF purchase processing or along with COF purchase registration, the maximum allowed time lag is 4 days.
    2. If authorization 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 35 days.
    3. In other cases the maximum allowed time lag is 11 days.
  • Other Visa cards:
    1. If authorization hold is performed as a part of COF purchase processing or along with COF purchase registration, the maximum allowed time lag is 7 days.
    2. If authorization 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 38 days.
    3. In other cases the maximum allowed time lag is 14 days.
  • Maestro and Cirrus cards: the maximum allowed time lag is 6 days.
  • Other Mastercard cards: the maximum allowed time lag is 28 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. By default, 30 minutes before the time lag expires, an automatic withdrawal of the held funds (capture) is performed, and a callback is sent to the web service. You can configure automatic release of the held funds (cancel) instead of withdrawal of funds, if needed. In order to configure automatic release of funds, contact ECommPay technical support (support@ecommpay.com).

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 authorization 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 authorization 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.

Authorization 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 1 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 authorization hold using payment cards. For information about request and notification formats when performing authorization hold using alternative payment methods, see Payment methods.

Request format

The format of the request for opening Payment Page to perform authorization 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—type of operation for payment processing using payment card. The auth value must be specified.
    • 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. 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.
  3. To display Payment Page in a required language, you need to additionally specify in the request the language_codeparameter and the language code in accordance with ISO 639-1 alpha-2 as its value. If this parameter is not specified in the request, Payment Page is displayed either in English (for all countries except for Russia) or in Russian (for Russia), according to IP address of the customer.
  4. 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 (Dashboard Light) and in a callback with information about the payment result.
  5. 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 Payment Page invocation parameters 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",
   "signature": "TSzdE5rJZaA9VyJtnfRI3620jOp2hf4RKwmKoWYjTYAK2MxF..."

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

}

Figure: Example of the request for opening Payment Page

https://https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=ru&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 authorization hold is the same as the format described in the Callbacks section.

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

Figure: Example of a callback with information about successful authorization hold

{
    "project_id": 42,
    "customer": {
        "id": "customer_12"
    },
    "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": "555555******4445",
        "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 authorization hold declined due to incorrect input of the expiration date of the payment card.

Figure: Example of a callback with information about declined authorization 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": "555555******4445",
        "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 555555******4445 of the customer customer_12 in terms of the project 42.

Figure: 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": "555555******4445",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12"
    },
    "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 authorization hold of 2 000,00 USD for the payment card with the card number555555******4445 of the customer customer_12 in terms of the project 42.

Figure: Example of the callback with information about cancelling authorization 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": "555555******4445",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12"
    },
    "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 authorization hold declined due to incorrect card data input.

Figure: Example of a callback with information about declined authorization hold

 {
    "account": {
        "number": "555555******4445",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12"
    },
    "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..."
}