PayIn - Ecom - PaymentPage

This page describes the methods for working with Ecom PayIn orders using the PaymentPage flow: classic card payment via the gateway's internet acquiring. The client enters card data on the payment page, 3-D Secure is handled by the gateway, the merchant receives the final result via a callback or an order request.

Create Order

Creates an order and returns the payment page URL; the client enters card data on the page.

Request

URL: POST https://<host>/api/v3/merchant/orders/payin/ecom/payment-page

Headers:

• Content-Type: application/json
• Authorization: Bearer <YOUR-API-KEY>. See the "Request Authorization" page.

Request body:

Field	Type	Required	Description
methodID	integer	yes	Order method
amount	float64	yes	Order amount in fiat, rounded to 2 decimal places
trafficType	string	yes	Traffic type
successRedirectURL	string	yes	URL to redirect the client to after a successful payment
failRedirectURL	string	yes	URL to redirect the client to after a failed payment
clientID	string	no	Client identifier
merchantOrderID	string	no	Merchant order identifier; unique within the merchant
callbackURL	string	no	URL for sending callbacks
clientMetadata	object	no	Client data, see "General Information"

cURL Example

curl -X 'POST' \
  'https://<host>/api/v3/merchant/orders/payin/ecom/payment-page' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR-API-KEY>' \
  -d '{
  "methodID": 205,
  "amount": 1500.50,
  "trafficType": "ftd",
  "successRedirectURL": "https://merchant.example.com/success",
  "failRedirectURL": "https://merchant.example.com/fail",
  "clientID": "ID1234",
  "merchantOrderID": "316b6280-d6e2-4627-bacd-fcda062438bc",
  "callbackURL": "https://example.com/webhook"
}'

Response

HTTP Status Code: 200

The response body is the OrderOut order model (see "General Information") with the paymentPageURL field - the payment page URL with an access token. The order type is Ecom, the direction is PayIn:

{
  "id": "0f0e6d34-1b2a-4c5d-8e9f-0a1b2c3d4e5f",
  "createdAt": "2026-08-31T16:08:06.310479Z",
  "updatedAt": "2026-08-31T16:08:06.310479Z",
  "type": "Ecom",
  "direction": "PayIn",
  "status": "created",
  "merchantOrderID": "316b6280-d6e2-4627-bacd-fcda062438bc",
  "clientID": "ID1234",
  "methodID": 205,
  "currencyCode": "TRY",
  "amount": 1500.50,
  "trafficType": "ftd",
  "paymentPageURL": "https://<host>/payin/orders/0f0e6d34-1b2a-4c5d-8e9f-0a1b2c3d4e5f?token=<TOKEN>&lang=ru"
}

The order is created with the created status; the order lifetime is limited by the method TTL.

Possible business failures (400/409) - see the errorCode table on the "Request Authorization" page.

Payment Page

The client opens the paymentPageURL and enters card details on the service payment page. If the gateway requires confirmation, the client completes 3-D Secure on the gateway side. Based on the final status, the client is redirected to the merchant's successRedirectURL or failRedirectURL. The merchant receives the order status via a callback or an order request.

Finalization

The terminal order statuses - succeeded, failed_by_terminal, expired - are described in the status model. For each of them, a callback is sent and the client is returned to the merchant's successRedirectURL or failRedirectURL.

Callback Conditions

The webhook is sent when the order transitions to one of the trigger statuses. The full list is on the "Callbacks" page.