Two-step purchase

In the payment platform, two-step purchases are processed according to the payment processing model (One-time two-step purchase): the first step is initiated by request sent from merchant's web service to the payment platform, and the second step is initiated by request from merchant's web service or the payment platform may automatically perform the step after specific time elapses. Information on two-step purchases with direct use of payment cards is presented in this section, while the information on such purchases by using of alternative payment methods—in the Methods section.

Merchant web service may request change of the amount authorised on the first step. The change may be performed on a one-time basis with the following initiation of the second step or the web services may change the authorised amount multiple times with the final initiation of the second step, on request or automatically.

To configure automatic initiation of the second step (automatic withdrawal or release of the held funds), contact ecommpay technical support (support@ecommpay.com). The time lag and the type of the operation to be performed once the time lag expires are specified by the merchant.

When performing an one-time two-step purchase, you can use one of the following options to transfer payment details:

• Transfer of complete payment details. This is a basic option in which you collect all payment details from the customer, and then submit the data inside a payment request. MO/TO (Mail Order/Telephone Order) payment is a special case in which you transfer complete payment details. MO/TO is a card-not-present payment in which a customer may phone or email the merchant, place an order and pay by providing the payment card details over the phone or by email. For more information about MO/TO payments, see MO/TO payment processing.
• Transfer of payment details identifier. To enable this option, you need to perform an initial COF payment. Once you do this, the payment platform creates a payment instrument record and returns a callback with the ID of the record in the account_id or card_id parameter. You need to specify this ID each time you submit to the payment platform a request for payment using stored credentials, see Saving payment data
• Transfer of payment token. To enable this option, you need to perform an initial payment. Once you do this, the payment platform creates a payment token and returns a callback with the token in the token parameter. You need to specify this ID each time you submit to the payment platform a request for payment using stored credentials. For more information about using tokens, see Using tokens.

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 as follows:

• 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) is one of the following: 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. The format of the callback is described in the Callback format section. 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 based on the maximum allowed time lag. For instance, if the merchant configures automatic release of the held funds after 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 after 6 days.

Limits on authorised amount change

Changing the authorised amount is supported only for the purchases made with the use of the Mastercard and Visa cards with respect to the following restrictions:

• After reducing the authorised amount, the remaining amount should be at least 0.01 USD or equivalent to this amount in another currency according to the rate for this currency. If the remaining amount is less than required, the request for reducing the amount is declined with the 3117 error code.
• For the Visa cards purchases, initial amount changes of over 15 per cent are supported only for the following MCCs (Merchant Category Codes): 3351–3500, 3501–3999, 4111, 4112, 4121, 4131, 4411, 4457, 5411, 5552, 5812, 5813, 7011, 7033, 7394, 7512, 7513, 7519, 7523, 7996, 7999. For any other MCC, initial amount changes are limited to 15 per cent.

For the American Express cards purchases, this capability is not supported.

When processing a two-step purchase by using Gate, the merchant web service is required to do the following:

1. Send the request for an authorisation hold with payment details to the following endpoint: /v2/payment/card/auth.
2. If necessary, complete the additional procedures:
   • 3‑D Secure authentication. This authentication is intended to provide security to online payments by payment cards. For more information on the authentication workflow, as well as request and callback formats, see 3‑D Secure authentication.
   • Customer authentication on merchant's request. This authentication is intended to make purchases with payment cards more secure. For more information on the authentication workflow, as well as request and callback formats, see Authentication on merchant's request.
   • Additional payment information submission. This procedure is intended for cases, where the initial request did not contain the information necessary for any payment process stakeholders. For more information on this procedure, see Submission of additional payment information.
3. Receive a callback with the authorisation hold result from the payment platform.
4. If you need to change previously authorised amount without actually debiting customer account, send a request with the corresponding parameters to one of the following endpoints:
   • /v2/payment/card/incremental—to increase the authorised amount
   • /v2/payment/card/cancel—to decrease the authorised amount

   Then, you need to receive a callback with the result of your authorised amount change request.

5. Send the request for debiting customer account to the /v2/payment/card/capture endpoint or the request for cancelling an authorisation hold to the /v2/payment/card/cancel endpoint.

   If you need debit amount different from the authorised amount, simply specify the debit amount and the currency in a request to the /v2/payment/card/capture endpoint.

6. Receive a callback with the payment result from the payment platform.
7. If needed, after completing a one-time one-step purchase you can return your customers their money, if the payment method supports refunds. For more information on this procedure, see Purchase refunds.

The following diagram provides the detailed picture of an ordinary (without additional requests) two-step purchase processing procedure with cancelling an authorisation hold.

The sections that follow discuss in more details the request format and the required parameters and the information about the format of callbacks with payment results. For the general information on how to use the API, see Interaction concepts. Information about possible statuses of this payment type can be found in the corresponding article.

Request for authorisation hold

There are several things you need to consider when issuing requests:

1. The request is sent by using POST (HTTP) method to one of the following endpoints:
   • when indicating full card details—/v2/payment/card/auth,
   • when indicating an identifier instead of card details—/v2/payment/card/auth/saved,
   • when indicating a token instead of card details—/v2/payment/card/auth/token.
2. The following objects and parameters should be specified in the request:
   • Object general—general request identification information:
     • project_id—the project ID obtained from ecommpay
     • payment_id—payment ID unique within the project
     • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
   • Object customer—customer information:
     • ip_address—IP address
     • id—the ID of the customer within the merchant project
     • screen_res—screen resolution of the customer's device, in pixels, with an x character as a delimiter (for example, 360x640)
     • email—customer's email
     • phone—customer's phone number
   • Object payment—payment information:
     • amount—payment amount in minor units
     • currency—payment currency in the ISO-4217 alpha-3 format
3. The request should contain the following customer's payment card information:
   • when indicating complete card credentials—the following data in the card object:
     • pan—card number
     • year—year of expiration date
     • month—month of expiration date
     • card_holder—cardholder first and last names (as indicated on the card)
     • cvv—card verification code (as indicated on the card). This parameter is not necessary for processing of MO/TO payments. For more information, see MO/TO payment processing;
   • when indicating the identifier—the identifier which is associated with the card credentials in the payment platform in the saved_account_id parameter, and the card verification code in the cvv parameter
   • when indicating the token—token in the token parameter and the card verification code in the cvv parameter.
4. The request should contain the return_url object with the addresses for redirecting the customer to the web service:
   • success—the URL for redirecting the customer after the payment is completed;
   • decline—the URL for redirecting the customer after the payment is declined.
5. In case it is needed tot transfer funds to a merchant e-wallet, the object customer must contain the following additional parameters:
   • first_name—first name
   • last_name—last name
   • address—address (street, house number)
   • email—email
   • city—city of residence (town, village, etc.)
   • state—region of residence (state, county, canton, etc.)
6. If required, you can also add any other additional parameters Gate supports.

Thus, to perform a two-step payment by a payment card, the request must include project and payment IDs, signature, IP-address of the customer, currency and amount of payment, as well as information about the payment card, as shown in the following example:

{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "customer": {
      "ip_address": "248.121.176.220",
      "id": "customer_12",
      "screen_res": "360x640",
      "phone": "44991234567",
      "email": "john_smith@email.com"
  },
    "payment": {
      "amount": 400000,
      "currency": "USD"
  },
    "return_url": {
      "success": "https://example.com/success",
      "decline": "https://example.com/decline"
  },

//when indicating complete card credentials:
    "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JOHN SMITH",
      "cvv": "123"
  }

//when indicating the identifier of a stored payment card:
    "saved_account_id": 2345678,
    "cvv": "123"

//when indicating the token of a stored payment card:
    "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
    "cvv": "123"   
}

Request for increasing the authorised amount

The request is sent by using POST (HTTP) method to the following endpoint /v2/payment/card/incremental and must contain the following objects and parameters:

• Object general—general request identification information:
  • project_id—the project ID obtained from ecommpay
  • payment_id—payment ID unique within the project
  • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
• Object customer—customer information:
  • id—the ID of the customer within the merchant project
• Object payment—payment information:
  • amount—amount by which you request to increase the authorised amount, specified in minor units
  • currency—payment currency in the ISO-4217 alpha-3 format, must be the same as the currency submitted when requesting authorisation hold
• If required, you can also add any other additional parameters as specified on the specification.

Thus, the correct request for increasing the authorised amount must include project and payment IDs and signature, as well as the amount by which you need to increase the authorised amount and the currency code.

{
    "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "customer": {
      "id": "customer_12"
  },
    "payment": {
      "amount": 1000,
      "currency": "USD"
  }

Request for debiting of authorised amount

The request is sent by using POST (HTTP) method to the following endpoint /v2/payment/card/capture and must contain the following objects and parameters:

• Object general—general request identification information:
  • project_id—the project ID obtained from ecommpay
  • payment_id—payment ID unique within the project
  • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
• If required, you can also add any other additional parameters Gate supports.

These parameters are required to debit the entire authorised amount. To debit only a part of the authorised amount, you must additionally specify the following parameters in the payment object:

• amount—the final amount to debit in minor currency units
• currency—payment currency in the ISO-4217 alpha-3 format, must be the same as the currency submitted when requesting authorisation hold

Thus, the correct request for debiting of authorised amount must include project and payment IDs and signature and, if required, the amount and currency code.

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}

Request for partial debit or release of authorised amount

The request is sent by using POST (HTTP) method to the following endpoint /v2/payment/card/cancel and must contain the following objects and parameters:

• Object general—general request identification information:
  • project_id—the project ID obtained from ecommpay
  • payment_id—payment ID unique within the project
  • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
• If required, you can also add any other additional parameters Gate supports.

These parameters are required to release the entire authorised amount. To decrease the authorised amount, you must additionally specify the following parameters in the payment object:

• amount—the amount by which you need decrease the authorised amount, specified in minor currency units
• currency—payment currency in the ISO-4217 alpha-3 format, must be the same as the currency submitted when requesting authorisation hold

Thus, the correct request for releasing of authorised amount must include project and payment IDs and signature; if you need just to decrease the authorised amount, the correct request must contain the amount and the currency code.

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}