1. TLY Pay API
English
  • English
  • 简体中文
  • TLY Pay API
    • Getting started
    • HTTP conventions and payment status
    • Webhook verification and recovery
    • Payment integration
      • Create a Payment
      • Get Payment status
      • Cancel a Payment
      • Disable Checkout access
      • Check pricing configuration
      • Configure a Webhook endpoint
      • Verify a Webhook signing Secret
  • Schemas
    • CreatePayment
    • CreatedPayment
    • ErrorResponse
    • BootstrapWebhook
    • MerchantPaymentView
    • MerchantStoreSourceView
    • MerchantStoreView
    • OneTimeSecretResponse
    • SourceAmount
    • MerchantSourceAmountView
    • VerifyWebhookBinding
    • WebhookBindingView
  1. TLY Pay API

Getting started

This reference is for developers integrating TLY Pay payments into their applications. Use the TLY Pay API from your server to create a Payment, open Hosted or Embedded Checkout, and reconcile the result through a signed Webhook or an authoritative query.
The API and app use Payment for the payment record, shown under Payments. The app's Create Payment Link action creates a Payment Link for opening Hosted Checkout. Your customers pay through Hosted or Embedded Checkout. Both use the same Payment.

Set up your TLY Pay account#

The following action names match the English app interface:
1.
Sign in and complete account registration.
2.
Open Settings > Payment settings. If you have no verified receiving wallet, choose Connect a Wallet, name your Wallet, and approve the connection once in TLY Wallet. Verification completes automatically. A wallet already connected and verified can be reused. Display currency changes only how estimated Wallet values are displayed; it does not change Payment pricing or accepted payment assets.
3.
Open Checkout. In Enabled networks and currencies, confirm which currencies are enabled for the verified wallet. These are the currencies customers can pay with.
4.
For Embedded Checkout, configure Website (optional) on the same Checkout page with your HTTPS website origin. Hosted Checkout does not require this setting.
5.
Open Integrations > API keys and choose Issue API Key. This action issues the standard scopes below. Save the credential from Save this API Key; existing credentials cannot be revealed again.
6.
If using payment notifications, prepare your receiver, then open Integrations > Webhooks > Add Webhook, enter the receiver's public HTTPS URL, and save the signing Secret. Use the separate Webhook guide for verification and rotation.
Wallet connection requires TLY Wallet for approval and proof of control. Your integration server and customers do not use your wallet credentials. Reading wallet balances and addresses does not require the extension.
The standard API Key scopes are:
payment:write: create or cancel Payments and disable Checkout access.
payment:read: query payment status and verify pricing configuration.
webhook:bootstrap: configure a Webhook endpoint and verify its signing Secret.
Keep API Keys and Webhook signing Secrets on your server. Use Authorization: Bearer <API_KEY>; never put an API Key in browser code, a URL, screenshots or logs. To replace a Key, issue a new one, deploy and verify it, and revoke the old one in your TLY Pay dashboard.
Use the TLY Pay API and Checkout origin supplied for your integration. Examples use your server-side TLY_API_ORIGIN and TLY_API_KEY configuration. Set HOSTED_CHECKOUT_ORIGIN to the supplied Checkout origin.

API origin#

Send API requests to https://api.tlypay.com. Keep your API Key in server-side configuration.

Check pricing and create a Payment#

Read GET /v1/store with your API Key to verify the configured pricing source and website domain before building the request. Use the returned primary_source kind, ref and decimals to construct source_amount. Do not infer Payment pricing from Display currency or from the asset your customer will pay with.
curl --request POST "${TLY_API_ORIGIN}/v1/payments" \
  --header "Authorization: Bearer ${TLY_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-example-1048" \
  --data '{"order_ref":"ORDER-EXAMPLE-1048","source_amount":{"kind":"fiat","currency":"USD","amount_raw":"12800"}}'
All values are illustrative. source_amount must match your configured primary pricing source. USD 12800 means USD 128.00. Use positive integer strings without leading zeros, not floating-point numbers. The service determines decimals. For crypto pricing, provide kind: "crypto", your configured pricing_ref, and amount_raw; do not substitute a token contract address or a network ID for a pricing ref.
order_ref is optional and is not a unique key. Keep one Idempotency-Key for each creation intent and reuse both that Key and the same request body after a timeout. A successful create or identical replay returns HTTP 200, not 201. Creating a Payment does not mark the order paid.
Save the returned payment_id with your order. Use it to open Checkout, query payment status and identify the Payment when contacting support. You and your customers use the same ID, which can be displayed and copied. Checkout remains subject to website authorization, risk checks, expiry and access restrictions. Queries and changes from your server require your API Key.

Open Checkout and reconcile the order#

Open Hosted Checkout at HOSTED_CHECKOUT_ORIGIN with /#payment_id=<payment_id>. For Embedded Checkout, load the supplied Embedded Checkout script at /widget/crypto-pay.js once on your website and call window.CryptoPay.open({ paymentId }) with the returned Payment ID. The Hosted Checkout URL carries the same ID in its fragment. Your customer opens Checkout to start paying; creating a link alone does not prove payment.
The Embedded Checkout script handles checkout requests at the supplied Checkout origin. Your server continues to call /v1/* at TLY_API_ORIGIN; never expose your API Key to browser code.
For Embedded Checkout, include checkout_origin in the create request with the HTTPS origin permitted by Website (optional). Omitting it uses the configured Hosted Checkout origin. Saving a website in your TLY Pay dashboard alone does not change the origin of an API-created Payment.
Configure a signed payment.updated Webhook, or query GET /v1/payments/{payment_id} from your server with payment:read. Query responses describe authoritative payment facts. A browser redirect or Webhook delivery result is not a payment receipt.
Only fulfill an order according to the authoritative status and your exception policy. Handle partial payments, overpayments and review-required payments explicitly. Webhooks can be duplicated or arrive out of order; use the event identity and the Payment's status_version as described in the Webhook guide.
The Webhook exchange is optional when your integration uses authoritative queries instead. A state event can describe an incomplete or exceptional payment; receiving it is not by itself a reason to fulfill an order. Hosted Checkout and Embedded Checkout use the same payment facts.

Optional operations#

Cancel an open, unexpired Payment with no accepted or confirming funds using POST /v1/payments/{payment_id}/cancel. Repeating a successful cancellation reads the current state.
Disable Checkout access using DELETE /v1/payments/{payment_id}/consumer-access. Customers will no longer be able to access this Payment through Checkout. Its payment status is unchanged; you can still query the Payment from your server.
Use GET /v1/store to verify the API Key's configured pricing source and website domain.
API Key management is under Integrations > API keys. Wallet connection and Display currency are under Settings > Payment settings; Enabled networks and currencies and Website (optional) are under Checkout. Webhook management is under Integrations > Webhooks.
Next
HTTP conventions and payment status
Built with