One-step purchase

Notice: This article covers processing one-time one-step purchases via Gate 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 Gate with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

Overview

When performing an one-time one-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.

Workflow

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

  1. Send the one-step purchase request with payment details to one of the relevant endpoints in the following group: /v2/payment/{payment method}/sale[/specifying payment details].
  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 in which the initial request did not contain the information needed by one of the payment process stakeholders. For more information on this procedure, see Submission of additional payment information.
  3. Receive a callback with the payment result from the payment platform.
  4. 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 one-step purchase processing procedure without additional requests.

Figure 1. Processing of a one-step purchase
  1. Customer initiates a purchase on the merchant web service.
  2. The web service sends the request for processing a one-step purchase by using Gate to the specified ecommpay URL.
  3. The payment platform receives the request for processing a one-step purchase 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 debiting customer account.
  9. The issuer sends the callback with a one-step purchase result to the card organisation.
  10. The card organisation sends the callback with a one-step purchase result to the ecommpay payment platform.
  11. The payment platform sends the callback to the web service.
  12. The customer receives the payment result from the web service.

The sections that follow discuss in greater detail the request format and the required parameters and the information about the format of callbacks with payment results. Information about possible statuses of this payment type can be found in the corresponding article.

Request format

In this section the presented request format is applicable to one-step purchases made with payment cards. When performing requests the following needs to be considered:

  1. The request is sent by using POST (HTTP) method to one of the following endpoints:
  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's first and last name (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. Depending on specific regional requirements and requirements of providers and payment systems, you may be required to add the following additional user information:
    • first_name—first name
    • last_name—last name
    • middle_name—middle name (or patronymic)
    • day_of_birth—birth date
    • phone—phone number
    • email—email address
    • zip—post code of residence location
    • address—address (street, house number)
    • city—city of residence (town, village, etc.)
    • district—district of residence
    • state—region of residence (state, county, canton, etc.)
    • avs_post_code—post code registered with issuer as customer's actual post code
    • avs_street_address—street and house number registered with issuer as customer's actual address

    If some parameters are missing from request submitted by your web service, the payment platform may require the web service to submit additional payment information. (For more information, see Submission of additional payment information). For detailed information what parameters are required is you specific case, refer to your account manager at ecommpay.

  6. If required, you can also add any other additional parameters Gate supports.

Thus, to perform a one-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"   
}

Customer redirection data format

In dependence on the payment system to complete the payment, you may need to redirect a customer from the web service to the payment system side. To perform the redirection, you must receive a callback from the payment platform containing the URL for redirection in the redirect_data object with the following parameters:
  • redirect_data.url—URL to redirect a customer
  • redirect_data.body—data for request sending (may be null)
  • redirect_data.method—request sending method

The following is the callback example containing customer redirection data. This callback is sent from the ecommpay payment platform to the URL specified in the merchant project settings. The payment status in this callback is awaiting redirect result until the payment is completed by the customer.

Figure 2. Callback example with redirection data
    "type": "redirect",
                "code": "0",
                "operation_id": 64897000022161,
                "request_type": "purchase",
                "redirect_data": {
                    "body": {
                    },
                    "method": "POST",
                    "url": "https://payment.asiapaygateway.com/payment/DirectInterface",
                    "encrypted": {
                        "key": 3,
                        "message": "d4d9aa52891d0a59c40069bae69b57e872d0e946b70c67860e9c3e3b182cf240033a..."
                    }

Callback format

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

The following is the example of a callback with an information about successful 4,000.00 USD purchase the customer_12 made by using the payment card № 431422******0056 in the 42 project.

Figure 3. Example of a successful one-step purchase callback
{
    "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": 400000,
            "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": 400000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 400000,
            "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 for a one-step purchase declined due to incorrect card data entered.

Figure 4. Example of a declined one-step purchase callback
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "method": "card",
        "sum": {
            "amount": 400000,
            "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": 400000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 400000,
            "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...=="
}