One-step purchase
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
orcard_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:
- 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]
. - 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.
- Receive a callback with the payment result from the payment platform.
- 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.
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:
- 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.
- The following objects and parameters should be specified in the request:
- Object
general
—general request identification information:project_id
—the project ID obtained from ecommpaypayment_id
—payment ID unique within the projectsignature
—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 addressid
—the ID of the customer within the merchant projectscreen_res
—screen resolution of the customer's device, in pixels, with anx
character as a delimiter (for example,360x640
)email
—customer's emailphone
—customer's phone number
- Object
payment
—payment information:amount
—payment amount in minor unitscurrency
—payment currency in the ISO-4217 alpha-3 format
- Object
- 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 numberyear
—year of expiration datemonth
—month of expiration datecard_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 thecvv
parameter - when indicating the token—token in the
token
parameter and the card verification code in thecvv
parameter.
- when indicating complete card credentials—the following data in the
- 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.
- 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 namelast_name
—last namemiddle_name
—middle name (or patronymic)day_of_birth
—birth datephone
—phone numberemail
—email addresszip
—post code of residence locationaddress
—address (street, house number)city
—city of residence (town, village, etc.)district
—district of residencestate
—region of residence (state, county, canton, etc.)avs_post_code
—post code registered with issuer as customer's actual post codeavs_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.
- 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
redirect_data
object with the following parameters:redirect_data.url
—URL to redirect a customerredirect_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.
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.
The following is the example of a callback for a one-step purchase declined due to incorrect card data entered.