Purchase processing

Notice: This article covers processing one-time one-step purchases via Payment Page and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of processing one-time one-step purchases:

  • One-time one-step purchase—an article in the section Payment models and statuses that provides a general description of processing one-time one-step purchases in the ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
  • articles of the Payment methods section containing a description of processing one-time one-step purchases via Payment Page with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

General information

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 for one-time one-step purchases, you need to use Gate and/or Dashboard.

Payment Page allows you to process one-step purchases by using payment cards or alternative payment instruments including MO/TO (Mail Order/Telephone Order) purchases in which user submits card details through mail, phone, or any other means of communication. When adding a new payment card for purchase processing, its payment data is saved and a token associated with this card is generated if this option is available in the merchant project (for more details, see Tokenization). These operations are performed in the Purchase operation mode of the payment form.

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, CVV or CID 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, CID) 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—the customer is forwarded 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 authentication or in addition to it.
  • Submission of additional payment information, in terms of which a 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 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. When performing one-step purchase in a project that by default requires authorisation hold, you must additionally use the card_operation_type parameter set to sale; note that this parameter is not required in other operations.
  3. To make sure that all required parameters are specified if the capability of collecting such customer data is not implemented (details), pass at least one of the following parameters in the request: customer_email or customer_phone.
  4. 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.
  5. 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, the payment form is displayed in the language selected automatically (by the browser language, by the region, or by default—learn more).
  6. 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 and in a callback with information about the payment result.
  7. To perform an MO (Mail Order) purchase, you must use the moto_type parameter set to 1; for a TO (Telephone Order) purchase, you must add the moto_type parameter set to 2.
  8. 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 Parameters for opening payment form 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",
   "customer_phone": "44991234567",
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."

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

}
Figure 1. Example of the request for opening Payment Page
https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=en&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 431422******0056 in the project 42.

Figure 2. Example of a callback with information about successful one-step purchase
{
    "account": {
        "number": "431422******0056 ",
        "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,
    "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 3. 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": "431422******0056 ",
        "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..."
}