Purchase processing

General information

Payment Page supports one-time purchases. This section covers information on processing of one-time one-step purchase by using Payment Page. General information is applicable to payments made by using payment cards and alternative payment instruments and extends the information in the Payment models and statuses section.

One-step purchase, or one-time one-step purchase, is a payment type which uses only one request to make a one-time transfer of funds from customer to merchant. To perform refunds in terms of one-time one-step purchases, you need to use Gate and/or Dashboard/Dashboard Light.

Payment Page allows processing one-step purchases by using payment cards or alternative payment instruments. When adding a new payment card for purchase processing, its payment data is saved and a token associated with this card is formed if this option is available to merchant project (for more details, see Tokenization). For this purpose the Purchase operation mode of the payment form is used.

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



When processing one-time one-step purchases by using Payment Page, 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 information, 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.

Workflow

In terms of processing one-step purchases 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 callback with the result of the request processing from the payment platform.

One-step purchase processing may involve auxiliary 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.

These procedures do not require any additional effort on the merchant's web service side, but usually require customer effort.

The following sections cover information about request and callback formats to use when processing purchases by using payment cards. For more information about request and callback formats to use when processing purchases by using alternative payment methods, see Payment methods.

Request format

The format of the request for opening Payment Page to process one-step payments using payment cards 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 body must contain the following required parameters:
    • project_id—the project ID obtained from ECommPay.
    • payment_id—the payment ID unique within the project.
    • customer_id—the customer ID unique within the project.
    • payment_amount—payment amount in minor currency units.
    • payment_currency—payment currency code in the ISO-4217 alpha-3 format.
    • signature—the signature that is 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 payment_description parameter. 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 request for processing card payment must include project, customer and payment IDs, payment currency and amount and signature. Other parameters can also be specified in the request, but they are optional.

{
   "project_id": "42",
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": "131970",
   "customer_id": "customer_12",
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."

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

}

Figure: Example of the request for opening Payment Page

https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=ru&customer_id=customer_12&project_id=42&payment_amount=131970&payment_id=456789&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB...

Callback format

The format of the callback to notify the merchant about the result of processing one-step purchase is the same as the format described in the Callbacks section.

The following is an example of callback with an information about successful 1 319,70 USD purchase made by the customer customer_12 using the payment card with the card number 424242******4243 in the project 42.

Figure: Example of a callback with information about successful one-step purchase

{
    "account": {
        "number": "424242******4243",
        "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2019-01-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 131970,
            "currency": "USD"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "legalEntity": 47,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2019-01-11T13:02:42+0000",
        "created_date": "2019-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 131970,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 131970,
            "currency": "USD"
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2019-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}

The following is the example of a callback with information about one-step purchase declined due to incorrect card data input.

Figure: Example of a callback with information about declined one-step purchase

{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "method": "card",
        "sum": {
            "amount": 131970,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "424242******4243",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 13300000004505,
        "type": "sale",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "created_date": "2019-01-11T14:11:00+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 131970,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 131970,
            "currency": "USD"
        },
        "provider": {
            "id": 12,
            "payment_id": "48219213050",
            "auth_code": "",
            "endpoint_id": 12
        },
        "code": "10102",
        "message": "Incorrect data entered",
        "eci": "05"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}