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. This information extends the information in the Payment types, operations and payments 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.

Payment Page allows you to apply authorization hold which in fact is the first step of this purchase type. To apply an authorization 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 either to use Gate or Dashboard or to configure automatic performance of this step after specific time out. In order to configure automatic withdrawal or release of funds, contact Rocketpay technical support (support@rocketpay.kz).

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

Time limit for authorization hold

According to the requirements of Visa, 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 cards: the maximum allowed time lag is 6 days.

The maximum allowed time lag for holding funds is calculated starting from the moment the auth operation is created in the Rocketpay payment platform. 30 minutes before the time lag expires, depending on the parameters specified by the Rocketpay 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 Rocketpay key account manager.

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.

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—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 Rocketpay.
    • 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_code parameter 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 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.rocketpay.kz/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 authorization hold is the same as the format described in the Callbacks in Payment Page 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..."
}