Integration GuideAPI Reference
Integration Guide
  1. Payment Methods
  2. Supported Payment Methods (Host-to-host integration)

RU: TPay - Payments

📘

"paymentMethodName": "TPAY"


Payment Method Features

FeatureValue
CountryRussia
Processing CurrenciesRUB
PaymentsYes
-- Min per transaction amountVary, depends on your contract
-- Max per transaction amountVary, depends on your contract
RefundsFull & Partial
-- Full RefundYes
-- Partial RefundYes
-- Multiple Partial RefundsYes
ChargebacksNo

Workflow: Payments

Download in high resolution


List of used API Requests:

RequestEndpointDescription
Intent CreationPOST /processing/api/v1/intents• Creates a new Intent with one or more Payment transactions.
• The platform validates the request, creates internal payment records, and creates the payment link.
Refund CreationPOST /api/v1/refunds• Creates a refund request (full or partial) for a previously captured payment.
• A separate refund transaction is created and processed independently from the original payment.

Intent Creation Request/Response

📓

Request specifics

  • Endpoint: POST /processing/api/v1/intents
  • Purpose: Creates an Intent and a Payment for the selected payment method.
  • Structure: A unified request structure is used for all supported payment methods, but some fields are method-specific.
  • For this method:
    • paymentMethodName must be set to TPAY
    • incomingDetails should include: sessionTimeoutMin, redirectUrl, failureUrl, device, webView, os, browser, and account

Intent Request: Example

{
  "clientReferenceId": "123456789",
    "useCheckoutForm": false,
  "payments": [
    {
      "paymentInstrument": {
        "paymentMethodName": "TPAY",
        "incomingDetails": {
          "sessionTimeoutMin": 20,
          "redirectUrl": "https://merchant.example.com/payment/success",
          "failureUrl": "https://merchant.example.com/payment/failure",
          "device": "Desktop",
          "webView": true,
          "os": "Windows",
          "browser": "Chrome",
          "account": "R410011234567890"
        }
      },
      "submittedAmount": {
        "value": 1005.25,
        "currency": "RUB"
      },
      "authCurrencyCode": "RUB",
      "description": "Vertex - INTENT 1234",
      "webhookUrl": "webhookUrl"
    }
  ]
}

Intent Request: Fields Description

Top-Level Request Parameters
ParameterTypeRequiredDescription
clientReferenceIdStringRequiredOrder number in the merchant system.
useCheckoutFormBooleanOptionalUsed for requesting the payment via Checkout form. If not provide, then considered as false
paymentsArray of ObjectsRequiredList of payment objects to be created within the Intent.
descriptionStringOptionalIntent description.
merchantObjectOptionalMerchant information to be associated with the request.
extensionAttributesObjectOptionalAdditional key-value attributes forwarded to the payment partner as is.
Send only if agreed with our integration team — see the extensionAttributes section below.

payment
ParameterTypeRequiredDescription
payerObjectConditionalPayer details. Optional in general, but may be required for specific merchant MCC codes.
paymentInstrumentObjectRequiredPayment method and payment instrument details used to process the payment.
submittedAmountObjectRequiredAmount and currency submitted for the payment.
authCurrencyCodeStringRequiredAuthorisation currency code to be used for the payment.
It may differ from the submitted currency if FX conversion is applied.
If FX conversion is not required, it should match submittedAmount.currency.
descriptionStringOptionalPayment description.
webhookUrlStringRequiredURL to which payment status change webhooks will be sent.

payer
ParameterTypeRequiredDescription
firstnameStringOptionalPayer's first name.
lastnameStringOptionalPayer's last name.
phoneStringConditionalPayer's phone number.
Required for merchants with MCC 4814.
Must be provided in international format: +XXXXXXXXXXX.
emailStringOptionalPayer's email address.
countryIsoCodeStringOptionalPayer's country of residence in ISO 3166-1 alpha-2 format.
localeStringOptionalPayer's preferred language locale.
taxIdentificationStringOptionalConsumer tax identification number.
merchantPayerReferenceStringOptionalMerchant-provided payer reference.

paymentInstrument
ParameterTypeRequiredDescription
paymentMethodNameStringRequiredPayment method name.
For this scenario, use TPay.
incomingDetailsObjectRequiredPayment method-specific data required to initiate the payment.

incomingDetails
ParameterTypeRequiredDescription
sessionTimeoutMinIntegerOptionalSpecifies how long the payment link remains valid, in minutes. If not provided, the link expires after 20 minutes.
redirectUrlStringRequiredURL to which the payer may be redirected after a successful/unsuccessful (if failureUrl is empty) payment flow, if applicable.
failureUrlStringRequired URL to which the payer may be redirected after a failed payment flow, if applicable.
deviceStringConditional

This field is required to generate the most appropriate link for your payer.

Possible values: Mobile / Desktop

If not provided, the default value Desktop will be used, and your payer might not receive the best user experience.

webViewBooleanConditional This field is required to generate the most appropriate link for your payer.

Possible values: true / false.

If not provided, the default value true will be used, and your payer might not have the best user experience.
osStringConditional This field is required to generate the most appropriate link for your payer.

Possible values: iOS / Android /
Windows / Linux.

If not provided, the default value Windows will be used, and your payer might not have the best user experience.
browserStringConditionalThis field is required to generate the most appropriate link for your payer.

Possible values: Chrome / Firefox / JivoMobile / Microsoft Edge / Miui / Opera / Safari / Samsung / WebKit / WeChat / Yandex.

If not provided, the default value Chrome will be used, and your payer might not have the best user experience.
accountStringConditionalElectronic wallet account number.
Maximum 30 characters.
Required for merchants with MCC 6050 or 6051.

submittedAmount
ParameterTypeRequiredDescription
valueNumberRequiredSubmitted order amount.
May differ from the authorised amount if FX conversion is applied.
currencyStringRequiredSubmitted order currency.
May differ from the authorised amount if FX conversion is applied.

merchant
ParameterTypeRequiredDescription
nameStringOptionalThe name of store, that might be displayed on the checkout form if configured
websiteStringOptionalThe website of the store

extensionAttributes

A free-form set of key-value attributes that our platform forwards to the payment partner as is — the content is not validated, transformed, or mapped on our side.

  • The payment partner may require additional payment or payer attributes (for example, for anti-fraud screening) to improve the payment acceptance rate.
  • The exact set of attribute names and values is agreed individually for your account and will be provided by our integration team.
  • Send this object only if its usage has been explicitly agreed for your account. If the object is omitted, payment processing is not affected.
  • The object is not returned in API responses (Intent or Payment details) or in webhooks.
ParameterTypeRequiredDescription
{attributeName}StringOptionalAttribute name and value as advised by our integration team.

Refunds

Download in high resolution


To initiate the refund (full or partial) to the payer's original payment instrument, you must send a separate Refund request.
Use the following endpoint: Create Refund and specify the following parameters:

{
  "paymentId": 204264682781298700,
  "partial": false,
  "reason": "Customer requested a refund",
  "webhookUrl": "webhookUrl"
}
{
  "paymentId": 204264682781298700,
  "partial": true,
  // For a partial refund, specify ONLY ONE of the following:
  // - paymentSubmittedAmount (original/submitted currency)
  // - paymentAuthAmount (authorised/settlement currency)

  // This is required when FX conversion was involved in the payment
  // (e.g. USD -> RUB). The refund will be calculated using the SAME
  // exchange rate as the original payment.
  //
  // Choose the object based on the currency in which you want to
  // define the refund amount, and populate only that object.

  // Option 1: Submitted currency (inactive example)
  //  "paymentSubmittedAmount": {
  //    "value": 100.05,
  //    "currency": "USD"
  //  },

  // Option 2: Authorised currency (active example)
  "paymentAuthAmount": {
    "value": 100.05,
    "currency": "RUB"
  },
  "reason": "Customer requested a refund",
  "webhookUrl": "webhookUrl"
}
Refund amount rules
RuleDescription
Full refundSend paymentId and set partial to false, or omit partial entirely. The full refundable amount will be refunded.
Partial refundSet partial to true and provide exactly one of the following objects: paymentSubmittedAmount or paymentAuthAmount.
Mutually exclusive amount objectsDo not send paymentSubmittedAmount and paymentAuthAmount in the same request.
FX paymentsIf the original payment involved FX conversion, the refund is calculated using the same exchange rate as the original payment.
Currency choiceUse paymentSubmittedAmount if you want to define the refund in the original submitted currency.
Use paymentAuthAmount if you want to define the refund in the authorised or settlement currency.
Top-Level Refund Request Parameters
ParameterTypeRequiredDescription
paymentIdint64RequiredIdentifier of the original payment transaction to which this refund applies.
Use the paymentId returned in the original payment or Intent creation response.
partialBooleanOptionalIndicates whether the refund is partial or full.
true - partial refund.
false - full refund.
If omitted, the platform treats the request as a full refund.
paymentSubmittedAmountObjectConditionalRefund amount in the original submitted currency.
Required when partial = true and the refund amount is defined in the submitted currency.
Do not send together with paymentAuthAmount.
paymentAuthAmountObjectConditionalRefund amount in the authorised or settlement currency.
Required when partial = true and the refund amount is defined in the authorised currency.
Do not send together with paymentSubmittedAmount.
reasonStringOptionalFree-form refund reason.
Used for informational and audit purposes.
webhookUrlStringOptionalURL to which refund status change webhooks will be sent.
paymentSubmittedAmount
ParameterTypeRequiredDescription
valueNumberRequiredRefund amount value in the original submitted currency.
currencyStringRequiredRefund currency in ISO 4217 alpha-3 format.
Must match the original submitted currency.
paymentAuthAmount
ParameterTypeRequiredDescription
valueNumberRequiredRefund amount value in the authorised or settlement currency.
currencyStringRequiredRefund currency in ISO 4217 alpha-3 format.
Must match the original authorised or settlement currency.

After the creation of the refund request you must wait for the callback, that will provide you with the latest transaction status


Webhooks

🔗

More about Payment Webhooks on the dedicated page
You will receive the webhooks on each status change of any transaction you created.


Testing in Sandbox

Our system allows emulating different test cases in the sandbox environment.
To simulate specific scenarios and receive different results, use the intent.description parameter.

TPay Payment Test flow

High-resolution image is available on the link


List of Supported Cases

CaseScenario Keyword
(intent.description)		Final Payment Status
  1. Successful payment
--CAPTURED
  1. Expired Link
--CANCELLED
  1. Payment Declined
DeclinedPaymentDECLINED
  1. Failure
LinkCreationErrorERROR

Case "Successful payment"

Steps:

  1. The client creates an intent via POST /processing/api/v1/intents.
  2. A synchronous response is returned with paymentStatus = AUTHORIZATION_REQUESTED.
  3. Open the link from payments.additionalData.details.url.
  4. A callback is received with paymentStatus = CAPTURED.

Updated about 2 hours ago

Did this page help you?