Two-step purchase

Overview

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.

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

Limits

Time limit for authorization hold

Visa and Mastercard require that the time lag for holding funds is limited. For different types of cards the maximum allowed time lag is defined as follows:

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

Limits on authorised amount change

For Visa cards, changes of the authorised amount that exceed 15 percent of the initial amount are allowed only for the following MCCs (Merchant Category Code): 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, changes to the initial amount must not exceed 15 percent.

In contrast, Mastercard does not impose any limits on changes to the initially authorised amount.

Workflow

When ordinary 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 Customer authentication by using the 3‑D Secure 1.
    • 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 Additional payment information submission.
  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 mount 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 refund.

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

Figure: Processing of a two-step purchase with debiting customer account

  1. Customer initiates a purchase on the merchant web service.
  2. The web service sends the request for an authorisation hold by using Gate to the specified ECommPay URL.
  3. The payment platform receives the request for an authorisation hold by using Gate.
  4. The payment platform performs the request acceptance that includes validation of the required parameters and signature.
  5. The payment platform sends to the web service response with request receipt confirmation and correctness check result.
  6. The payment platform performs the internal request processing and sends it to the card organisation.
  7. The card organisation performs the internal request processing and sends it to the issuer.
  8. The issuer performs the internal request processing and an authorisation hold.
  9. The issuer sends the callback with the authorisation hold result to the card organisation.
  10. The card organisation sends the callback with the authorisation hold result to the ECommPay payment platform.
  11. The payment platform sends the callback with the authorisation hold result to the web service.
  12. The customer receives the authorisation hold result from the web service.
  13. The web service sends the request for debiting customer account (or cancelling an authorisation hold) by using Gate to the specified ECommPay URL.
  14. The payment platform receives the request for debiting customer account (or cancelling an authorisation hold) by using Gate.
  15. The payment platform performs the request acceptance that includes validation of the required parameters and signature.
  16. The payment platform sends to the web service response with request receipt confirmation and correctness check result.
  17. The payment platform performs the internal request processing and sends it to the card organisation.
  18. The card organisation performs the internal request processing and sends it to the issuer.
  19. The issuer performs the internal request processing and debiting customer account.
  20. The issuer sends the callback with result of debiting customer account to the card organisation.
  21. The card organisation sends the callback with result of debiting customer account to the ECommPay payment platform.
  22. The payment platform sends the callback with result of debiting customer account to the web service.
  23. If an authorisation hold cancelled, the customer receives the payment result from the web service.

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.

Request format

This section describes the request format applied in two-step purchases by payment cards. Note that processing of two-step purchases includes issuing requests for authorisation hold, as well increase, decrease, release, and debit of authorised amount.

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:
  2. The following objects and parameters must 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
    • Object payment—payment information:
      • amount—payment amount in minor units
      • currency—payment currency in the ISO-4217 alpha-3 format
  3. The request must 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. 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.)
  5. 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"
  }
    "payment": {
      "amount": 400000,
      "currency": "USD",
  },
//when indicating complete card credentials:
    "card": {
      "pan": "4242424242424243",
      "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 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...=="
  },
    "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...=="
    },
}

Callback format

A two-step purchase uses the standard format for callbacks to submit purchase results. For more information, see Callbacks.

The following is an example of a callback with the information about the successful 2,000.00 USD authorisation hold the customer_12 made by using the payment card 555555******4445 in the 42 project.

Figure: Callback example of a successful authorisation 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": "2019-01-11T13:00:40+0000",
        "created_date": "2019-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": "2019-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 for a declined authorisation hold because of an incorrect card expiration date.

Figure: Callback example of a declined authorisation hold

{
    "project_id": 42,
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "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": 6304000002973,
        "type": "auth",
        "status": "decline",
        "date": "2019-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": "2019-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 the example of a callback with the information about the successful increase of the authorisation hold by 10,00 USD made on the payment card 555555******4445 in the 42 project of for the customer_12 customer.

Figure: Callback example for an increased authorisation hold

{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "awaiting capture",
        "date": "2019-01-11T15:54:40+0000",
        "method": "card",
        "description": ""
    },
    "account": {
        "number": "555555******4445",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12"
    },
    "operation": {
        "id": 7178000006589,
        "type": "incremental",
        "status": "success",
        "date": "2019-01-11T15:54:40+0000",
        "created_date": "2019-01-11T15:54:39+0000",
        "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
        "sum_initial": {
            "amount": 1000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 1000,
            "currency": "USD"
        },
        "provider": {
            "id": 120,
            "payment_id": "227307324",
            "date": "2019-01-11T15:54:40+0000",
            "auth_code": "919372",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}

The following is the example of a callback with the information about the successful 2,000.00 USD debiting customer account the customer_12 initiated the payment card 555555******4445 in the 42 project.

Figure: Callback example of a successful debiting of customer funds

{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "success",
        "date": "2019-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": "2019-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": "2019-01-11T15:54:40+0000",
            "auth_code": "919372",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}

The following is the example of a callback with the information about the successful cancelling of the 2,000.00 USD authorisation hold for the payment card 555555******4445 in the 42 project.

Figure: Callback example of a successful cancelling of an authorisation hold

{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "canceled",
        "date": "2019-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": "2019-01-11T15:54:40+0000",
        "created_date": "2019-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 for cancelling an authorisation hold declined due to incorrect card data entered.

Figure: Callback example of a declined cancelling an authorisation hold

 {
    "account": {
        "number": "555555******4445",
        "type": "mastercard",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12"
    },
    "payment": {
        "date": "2019-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": "2019-01-11T15:54:40+0000",
        "created_date": "2019-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": "2019-01-10T22:37:10+0000",
            "auth_code": "876856",
            "endpoint_id": 120
        },
        "code": "10102",
        "message": "Incorrect data entered"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}