Skip to main content

Hosted Checkout integration

Hosted Checkout is a ready-made payment page hosted by Volet.com.

To preview the page your customers will see, open the Hosted Checkout page for developers.

Your application creates a payment request and redirects the customer to Hosted Checkout. The customer completes the payment, Volet.com sends a status notification to your server, and then redirects the customer back to your website.

Hosted Checkout supports:

Before integrating, create and configure a Hosted Checkout gateway in your account. See Create payment gateway.

Payment flow​

  1. Customer places an order on your website.
  2. Your website generates a payment request and displays a payment button or link.
  3. Customer clicks Pay and is redirected to Hosted Checkout.
  4. Customer completes the payment.
  5. Volet.com sends a payment status notification to your Status URL.
  6. Your system updates the order status.
  7. Hosted Checkout displays the payment result page.
  8. The customer can then click Continue and is redirected to your Success URL or Failed URL.
Merchant website
│
▼
Hosted Checkout
│
▼
Payment
│
▼
Status URL
│
▼
Merchant backend
│
▼
Customer redirect

For successful payments, the result page includes the transaction ID and payment information. For failed or canceled payments, it displays the corresponding error or cancellation message.

Success URL and Failed URL can be configured in the Hosted Checkout settings or passed dynamically in the payment request.

note

Always rely on Status URL notifications when updating order status. Do not rely solely on browser redirects.

Success URL and Failed URL should not be used to determine the final payment status.

Hosted Checkout quick start​

VideoHow to integrate a Hosted CheckoutWatch on YouTube

Step 1: Create payment request​

Hosted Checkout endpoint​

https://account.volet.com/api/public/payment-gateway

Required parameters​

To create a payment, submit an HTML form via POST to the endpoint above. The payment request must include the following required parameters:

ParameterDescription
ac_account_emailYour Volet.com account email
ac_sci_nameHosted Checkout name
ac_amountPayment amount
ac_currencyPayment currency (e.g., USD, EUR)
ac_order_idYour unique order identifier
ac_signDigital signature

For the complete list of supported parameters, see Payment request parameters.

note

Each payment request must use a unique ac_order_id.

Do not reuse order identifiers for different payments.

Request signature​

Generate the ac_sign parameter by calculating the SHA-256 hash of the following string:

ac_account_email:ac_sci_name:ac_amount:ac_currency:secret:ac_order_id

where secret is the password you set when creating the Hosted Checkout.

Sign ac_amount exactly as you send it in the form: if you sign 100.00, send 100.00, not 100.

Example string:

[email protected]:Store:100.00:USD:password:123

SHA-256 hash:

eb9e7f491df701fe7d71c74551ae9e4226dfbed7e3a9cc4916e242d3c09f718e

Pass the resulting hash value in the ac_sign parameter.

Submit the payment request​

Submit the HTML form to the Hosted Checkout endpoint using the POST method.

Example payment request​

<form method="POST" action="https://account.volet.com/api/public/payment-gateway">
<input type="hidden" name="ac_account_email" value="[email protected]">
<input type="hidden" name="ac_sci_name" value="Store">
<input type="hidden" name="ac_amount" value="100.00">
<input type="hidden" name="ac_currency" value="USD">
<input type="hidden" name="ac_order_id" value="123">
<input type="hidden" name="ac_sign" value="eb9e7f491df701fe7d71c74551ae9e4226dfbed7e3a9cc4916e242d3c09f718e">
<button type="submit">VoletPay</button>
</form>

Step 2: Handle payment notifications​

Volet.com sends a notification to your Status URL when a transaction is created for the payment and when it is completed.

The notification is delivered using either GET or POST, depending on your Hosted Checkout configuration.

Volet.com does not guarantee that a notification is delivered again if your endpoint is unavailable or returns an error. Check orders that stay pending through GET /api/orders. The same notification can also arrive more than once: process it by ac_order_id and ac_transfer, so a repeated notification does not fulfill the order twice.

The notification contains the following parameters:

ParameterDescription
ac_transferVolet.com transaction ID
ac_transaction_statusPayment status
ac_order_idYour order identifier
ac_amountOriginal payment amount
ac_merchant_amountAmount credited to your account
ac_merchant_currencySettlement currency
ac_start_dateTransaction date and time
ac_sci_nameHosted Checkout name
ac_src_walletCustomer wallet
ac_dest_walletMerchant wallet
ac_buyer_emailCustomer email address (if available)
ac_hashNotification signature hash

For the complete list of available parameters, see Payment notification parameters.

Before updating the order status, verify the ac_hash signature to confirm that the notification originated from Volet.com.

warning

Do not mark orders as paid based on customer redirects.

Always wait for a valid Status URL notification and verify the ac_hash signature before updating the order status.

Example notification sent to your Status URL:

<form method="POST" action="https://merchant.example.com/status">
<input type="hidden" name="ac_transfer" value="235f9d0b-b48f-462c-9949-621c4930490c">
<input type="hidden" name="ac_transaction_status" value="COMPLETED">
<input type="hidden" name="ac_order_id" value="123">
<input type="hidden" name="ac_amount" value="100">
<input type="hidden" name="ac_merchant_amount" value="100">
<input type="hidden" name="ac_merchant_currency" value="USD">
<input type="hidden" name="ac_start_date" value="2026-06-23 12:30:00">
<input type="hidden" name="ac_sci_name" value="Store">
<input type="hidden" name="ac_src_wallet" value="USD123456789012">
<input type="hidden" name="ac_dest_wallet" value="USD210987654321">
<input type="hidden" name="ac_buyer_email" value="[email protected]">
<input type="hidden" name="ac_hash" value="2880965181a0345296098b3cc73b94f03ad506a63fdd5177f14996162466a526">
</form>

Verify notification signature​

To verify the notification, calculate the SHA-256 hash using the values below and compare it with the received ac_hash.

The signature string is built in this order:

ac_transfer:ac_start_date:ac_sci_name:ac_src_wallet:ac_dest_wallet:ac_order_id:ac_amount:ac_merchant_currency:password

where password is the Hosted Checkout password configured for the gateway.

Use the field values exactly as they arrive in the notification. Amounts come without trailing zeros, for example 100, not 100.00: do not reformat them before you calculate the hash.

Example string:

235f9d0b-b48f-462c-9949-621c4930490c:2026-06-23 12:30:00:Store:USD123456789012:USD210987654321:123:100:USD:password

Calculate the SHA-256 hash of this string:

2880965181a0345296098b3cc73b94f03ad506a63fdd5177f14996162466a526

Compare the calculated hash with the received ac_hash. The values must match before you update the order status.

After the signature has been successfully verified, update the corresponding order in your system using the received payment status.

Step 3: Test integration​

Before accepting live payments, verify:

  • Customer redirection to Hosted Checkout.
  • Successful payment completion.
  • Status URL notification delivery.
  • Notification signature validation.
  • Order status updates.
  • Success URL and Failed URL redirects.
  • Failed payment handling.

Notification server IP addresses​

If your infrastructure uses IP allowlists or firewall rules, allow incoming requests from the following Volet.com notification servers:

  • 13.61.247.159

Advanced configuration​

The sections below describe optional features and advanced integration scenarios.

Preselect payment method​

By default, Hosted Checkout displays a payment method selection page.

You can preselect a payment method in the payment request using the ac_ps parameter. When specified, Hosted Checkout opens the corresponding payment screen directly and skips the payment method selection step.

Add the following fields to your payment request parameters:

  1. Opens the Volet.com account login page directly:
<input type="hidden" name="ac_ps" value="VOLET">
  1. Opens the USDT on Tron payment page directly:
<input type="hidden" name="ac_ps" value="USDTETHER">
<input type="hidden" name="ac_ps_protocol" value="TRON">
  1. Opens the Bitcoin payment page directly:
<input type="hidden" name="ac_ps" value="BITCOIN">

This is useful when the customer has already selected a payment method on your website before being redirected to Hosted Checkout.

Language​

Use the ac_client_lang parameter to specify the Hosted Checkout interface language.

Example:

<input type="hidden" name="ac_client_lang" value="en">

If no language is specified, Hosted Checkout uses the default language available for the customer.

Custom fields​

You can include up to 10 custom fields in a payment request.

Volet.com does not process these fields and returns them unchanged in Status URL notifications and customer redirects.

Typical use cases:

  • Customer ID
  • Subscription ID
  • Internal invoice number
  • Comment

Example:

<input type="hidden" name="customer_id" value="12345">
<input type="hidden" name="subscription_id" value="sub_987">
<input type="hidden" name="invoice_no" value="INV-2026-001">
<input type="hidden" name="comment" value="Premium plan">

Sub-merchants​

Use the ac_submerchant_url parameter to specify the website of the merchant on whose behalf the payment is processed.

Example:

<input type="hidden" name="ac_submerchant_url" value="https://merchant.example.com">

This option is intended for payment aggregators, marketplaces, and platforms that process payments for other merchants.

note

All compliance, prohibited activity, and merchant verification requirements applicable to merchants also apply to sub-merchants.

Override URLs​

The following parameters can be specified directly in the payment request:

  • ac_success_url
  • ac_success_url_method
  • ac_fail_url
  • ac_fail_url_method
  • ac_status_url
  • ac_status_url_method

Example:

<input type="hidden" name="ac_success_url" value="https://merchant.example.com/payment-success">
<input type="hidden" name="ac_success_url_method" value="GET">
<input type="hidden" name="ac_fail_url" value="https://merchant.example.com/payment-failed">
<input type="hidden" name="ac_fail_url_method" value="GET">
<input type="hidden" name="ac_status_url" value="https://merchant.example.com/payment-status">
<input type="hidden" name="ac_status_url_method" value="POST">

Values passed in the request override the default URLs configured for the Hosted Checkout gateway.

This is useful when multiple websites, stores, applications, bots, or AI agents use the same Hosted Checkout gateway.

It also allows you to generate different success, failure, and callback URLs for different orders without creating multiple Hosted Checkout gateways.

Disable signatures​

The ac_sign parameter is optional if digital signatures are disabled in Hosted Checkout settings.

However, use signatures in production environments to verify request authenticity and prevent data tampering.

Unsigned requests should only be used for testing and development purposes.

Hosted Checkout reference​

Payment request parameters​

The payment request is an HTML form submitted by your application to Hosted Checkout.

It contains the payment details, merchant information, redirect URLs, and optional configuration parameters required to process a payment.

The table below lists all supported payment request parameters.

ParameterRequiredFormatDescriptionExamples
ac_account_emailYesStringEmail address of your Volet.com account.[email protected]
ac_sci_nameYesString (max. 50 characters)Hosted Checkout name.My Store
ac_amountYesDecimal numberAmount of the payment request. Decimal precision depends on the selected currency. Excess decimal places are truncated automatically.100.00, 49.0302, 0.12345678
ac_currencyYesCurrency codeCurrency of the payment request.USD, EUR, BTC, ETH, USDT, USDC, XRP, TRX, LTC, TON, SOL
ac_order_idYesString (max. 64 characters; "A-z", "-", "_", "0-9")Unique merchant order identifier.123456, baf419d9-6c82-4175-b870-5541b0ff3794
ac_signConditionalHex string (SHA-256)Request signature used to verify the integrity of the payment request. Required if request signature verification is enabled for the Hosted Checkout.36b4c9ad29b61d1c5996e3ef1a3af0c3194e19713613b6bf26a9b905b8019225
ac_psNoString (payment method ID)Payment method preselected when Hosted Checkout opens.VOLET, USDTETHER, USD_COIN, BITCOIN, ETHEREUM, RIPPLE, TRON, LITECOIN, TON, SOL, BNB, MATIC (for POLYGON), AVAX
ac_ps_protocolConditionalString (blockchain or protocol ID)Preselected blockchain network. Required when ac_ps is USDTETHER, USD_COIN, or BNB; otherwise optional.ETHEREUM, TRON, BINANCE_SMART_CHAIN, MATIC (for POLYGON), SOLANA, AVALANCHE, OPTIMISM, ARBITRUM, TON
ac_commentsNoString (max. 255 characters)Additional payment description displayed to the customer and cannot be modified.Payment for Order #1234
ac_success_urlNoString (max. 100 characters)Overrides the configured Success URL.https://merchant.example.com/success
ac_success_url_methodNoGET, POSTHTTP method used for the Success URL redirect. Overrides the Hosted Checkout configuration.GET
ac_fail_urlNoString (max. 100 characters)Overrides the configured Failed URL.https://merchant.example.com/failed
ac_fail_url_methodNoGET, POSTHTTP method used for the Failed URL redirect. Overrides the Hosted Checkout configuration.POST
ac_status_urlNoString (max. 100 characters)Overrides the configured Status URL.https://merchant.example.com/status
ac_status_url_methodNoGET, POSTHTTP method used for Status URL notifications. Overrides the Hosted Checkout configuration.POST
ac_client_langNoString (locale code)Language used for the Hosted Checkout page.en
ac_submerchant_urlNoString (max. 100 characters)Website URL of the sub-merchant. Used for platform integrations and required for selected merchant categories.https://seller.example.com
Custom fields (for example buyer_email, client_email)NoUp to 10 string values (max. 100 characters each)Additional merchant-defined fields returned unchanged in Status URL notifications and customer redirects. Use them to match payments with your own orders, customers, invoices, or other internal records.[email protected], #INV-12345, user_1001

Example​

<form method="POST" action="https://account.volet.com/api/public/payment-gateway">
<input type="hidden" name="ac_account_email" value="[email protected]">
<input type="hidden" name="ac_sci_name" value="My Store">
<input type="hidden" name="ac_amount" value="100.00">
<input type="hidden" name="ac_currency" value="USD">
<input type="hidden" name="ac_order_id" value="order_123456">
<input type="hidden" name="ac_sign" value="36b4c9ad29b61d1c5996e3ef1a3af0c3194e19713613b6bf26a9b905b8019225">

<input type="hidden" name="ac_ps" value="USDTETHER">
<input type="hidden" name="ac_ps_protocol" value="ETHEREUM">
<input type="hidden" name="ac_comments" value="Payment for Order #123456">

<input type="hidden" name="ac_success_url" value="https://merchant.example.com/payment-success">
<input type="hidden" name="ac_success_url_method" value="GET">
<input type="hidden" name="ac_fail_url" value="https://merchant.example.com/payment-failed">
<input type="hidden" name="ac_fail_url_method" value="GET">
<input type="hidden" name="ac_status_url" value="https://merchant.example.com/payment-status">
<input type="hidden" name="ac_status_url_method" value="POST">

<input type="hidden" name="ac_client_lang" value="en">
<input type="hidden" name="ac_submerchant_url" value="https://seller.example.com">

<!-- Custom fields -->
<input type="hidden" name="customer_id" value="customer_12345">
<input type="hidden" name="customer_email" value="[email protected]">
<input type="hidden" name="invoice_id" value="INV-2026-001">
<input type="hidden" name="subscription_id" value="sub_98765">
<input type="hidden" name="merchant_internal_id" value="seller_456">

<button type="submit">Pay with Volet.com</button>
</form>

Payment success parameters​

After a successful payment, Hosted Checkout redirects the customer to your Success URL and passes the payment details using the configured redirect method.

The table below describes all available parameters.

ParameterFormatDescriptionExamples
ac_src_walletStringCustomer wallet number used for the payment.USDT123456789012
ac_dest_walletStringMerchant wallet number or settlement wallet.USD123456789012
ac_amountDecimal number, no trailing zerosAmount of the payment request.100, 0.125
ac_merchant_amountDecimal number, no trailing zerosAmount credited to the merchant account.99.5
ac_merchant_currencyCurrency codeSettlement currency.USD, EUR, BTC, ETH, USDT, USDC, XRP, TRX, LTC, TON, SOL
ac_feeDecimal number, no trailing zerosProcessing fee charged for the payment.0.5
ac_buyer_amount_without_commissionDecimal number, no trailing zerosAmount paid by the customer before customer-paid fees, if applicable.100
ac_buyer_amount_with_commissionDecimal number, no trailing zerosTotal amount paid by the customer, including customer-paid fees.100.5
ac_buyer_currencyCurrency codeCurrency used by the customer to complete the payment.USD, EUR, BTC, ETH, USDT, USDC, XRP, TRX, LTC, TON, SOL, BNB, AVAX, POL
ac_transferUUIDUnique Volet.com transaction identifier.235f9d0b-b48f-462c-9949-621c4930490c
ac_sci_nameStringHosted Checkout name.My Store
ac_start_dateYYYY-MM-DD HH:mm:ss (UTC)Payment creation date and time.2026-06-23 12:30:00
ac_order_idStringMerchant order identifier provided in the payment request.123456, baf419d9-6c82-4175-b870-5541b0ff3794
ac_psString (payment method ID)Payment method used by the customer.VOLET, USDT, USDC, BTC, ETH, TRX, SOL
ac_transaction_statusStatusStatus of the Volet.com transaction. Fulfill the order only when it is COMPLETED; a notification sent when the transaction is created can carry an intermediate status, such as PROCESSING or PENDING.COMPLETED
ac_buyer_emailString (Email address)Customer email address. Sent only when the customer paid from a Volet.com account.[email protected]
ac_buyer_verifiedBooleanIndicates whether the customer account is verified.true, false
ac_commentsStringComment provided in the payment request.Order #123456
Custom fieldsStringMerchant-defined fields returned unchanged from the payment request.customer_id, invoice_id, subscription_id

Example​

<form method="POST" action="https://merchant.example.com/payment-success">
<input type="hidden" name="ac_src_wallet" value="USDT210987654321">
<input type="hidden" name="ac_dest_wallet" value="USD123456789012">
<input type="hidden" name="ac_amount" value="100">
<input type="hidden" name="ac_merchant_amount" value="99.5">
<input type="hidden" name="ac_merchant_currency" value="USD">
<input type="hidden" name="ac_fee" value="0.5">
<input type="hidden" name="ac_buyer_amount_without_commission" value="100">
<input type="hidden" name="ac_buyer_amount_with_commission" value="100">
<input type="hidden" name="ac_buyer_currency" value="USDT">
<input type="hidden" name="ac_transfer" value="235f9d0b-b48f-462c-9949-621c4930490c">
<input type="hidden" name="ac_sci_name" value="My Store">
<input type="hidden" name="ac_start_date" value="2026-06-23 12:30:00">
<input type="hidden" name="ac_order_id" value="order_123456">
<input type="hidden" name="ac_ps" value="VOLET">
<input type="hidden" name="ac_transaction_status" value="COMPLETED">
<input type="hidden" name="ac_buyer_email" value="[email protected]">
<input type="hidden" name="ac_buyer_verified" value="true">
<input type="hidden" name="ac_comments" value="Order #123456">
<!-- Custom fields -->
<input type="hidden" name="customer_id" value="customer_12345">
<input type="hidden" name="invoice_id" value="INV-2026-001">
<input type="hidden" name="subscription_id" value="sub_98765">
</form>

Payment failed parameters​

If a payment is canceled or fails, Hosted Checkout redirects the customer to your Failed URL and passes the payment details using the configured redirect method.

The table below describes all available parameters.

ParameterFormatDescriptionExamples
ac_dest_walletStringMerchant account or settlement wallet.USD123456789012
ac_amountDecimal numberAmount of the payment request.100.00, 49.95
ac_currencyCurrency codeCurrency of the payment request.USD, EUR, BTC, ETH, USDT, USDC, XRP, TRX, LTC, TON, SOL
ac_sci_nameStringHosted Checkout name.My Store
ac_order_idStringMerchant order identifier provided in the payment request.order_123456, baf419d9-6c82-4175-b870-5541b0ff3794
Custom fieldsStringMerchant-defined fields returned unchanged from the payment request.customer_id, invoice_id, subscription_id

Example​

<form method="POST" action="https://merchant.example.com/payment-failed">
<input type="hidden" name="ac_dest_wallet" value="USD123456789012">
<input type="hidden" name="ac_amount" value="100.00">
<input type="hidden" name="ac_currency" value="USD">
<input type="hidden" name="ac_sci_name" value="My Store">
<input type="hidden" name="ac_order_id" value="order_123456">
<!-- Custom fields -->
<input type="hidden" name="customer_id" value="customer_12345">
<input type="hidden" name="invoice_id" value="INV-2026-001">
<input type="hidden" name="subscription_id" value="sub_98765">
</form>

Payment notification parameters​

When a transaction is created for the payment and when it is completed, Hosted Checkout sends a notification to your Status URL using the configured request method (GET or POST).

The notification contains all payment success parameters plus an additional ac_hash signature.

ParameterFormatDescriptionExamples
ac_hashSHA-256 hash (hexadecimal string)SHA-256 signature used to verify that the notification was sent by Volet.com and was not modified in transit.5768f1151929639f4ebe24d600718ef1177c946f24ed3b2d1bcdeede6bd88c64

For details on how to generate and verify the signature, see Verify notification signature.

Example notification​

<form method="POST" action="https://merchant.example.com/status">
<input type="hidden" name="ac_src_wallet" value="USDT210987654321">
<input type="hidden" name="ac_dest_wallet" value="USD123456789012">
<input type="hidden" name="ac_amount" value="123.45">
<input type="hidden" name="ac_merchant_amount" value="123.35">
<input type="hidden" name="ac_merchant_currency" value="USD">
<input type="hidden" name="ac_fee" value="0.1">
<input type="hidden" name="ac_buyer_amount_without_commission" value="123.45">
<input type="hidden" name="ac_buyer_amount_with_commission" value="123.45">
<input type="hidden" name="ac_buyer_currency" value="USD">
<input type="hidden" name="ac_transfer" value="235f9d0b-b48f-462c-9949-621c4930490c">
<input type="hidden" name="ac_sci_name" value="My Shop">
<input type="hidden" name="ac_start_date" value="2026-06-23 12:30:00">
<input type="hidden" name="ac_order_id" value="123456">
<input type="hidden" name="ac_ps" value="VOLET">
<input type="hidden" name="ac_transaction_status" value="COMPLETED">
<input type="hidden" name="ac_buyer_email" value="[email protected]">
<input type="hidden" name="ac_buyer_verified" value="true">
<input type="hidden" name="ac_comments" value="Payment for order #123456">
<input type="hidden" name="ac_hash" value="5768f1151929639f4ebe24d600718ef1177c946f24ed3b2d1bcdeede6bd88c64">
<!-- Custom fields -->
<input type="hidden" name="customer_id" value="98765">
<input type="hidden" name="invoice_id" value="INV-2026-001">
</form>

If something goes wrong​

The payment page shows "Signature is not valid"​

Volet.com could not verify the ac_sign value of the payment request. Check that:

  • The signature string contains the fields in this order, separated by colons: ac_account_email:ac_sci_name:ac_amount:ac_currency:secret:ac_order_id. See Request signature.
  • Each value in the string is exactly the same as in the submitted form. For example, if the form sends ac_amount as 100.00, the string must also contain 100.00, not 100.
  • ac_sci_name matches the name of your Hosted Checkout in Payment tools.
  • secret is the current password of your Hosted Checkout. If you changed the password in Payment tools, update it in your integration too.

To test your code, calculate the hash of the example string in Request signature and compare it with the example hash.

The ac_hash of a notification does not match​

  • Build the string from the values exactly as received in the notification, in the order shown in Verify notification signature.
  • URL-decode ac_start_date before you add it to the string. The value must be in the YYYY-MM-DD HH:MM:SS format, for example 2026-06-23 12:30:00.
  • Use wallet numbers exactly as received, with the currency prefix, for example USD123456789012.
  • Use the current password of your Hosted Checkout.

Notifications do not arrive at the Status URL​

If the problem remains, contact support with the name of your Hosted Checkout, the order ID, and the time of the request. Never send your Hosted Checkout password.