One-step purchase

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.

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.

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.

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:
   • when indicating complete card credentials—/v2/payment/card/sale,
   • when indicating the identifier instead of card credentials—/v2/payment/card/sale/saved,
   • when indicating the token instead of card credentials—/v2/payment/card/sale/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'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"   
}