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

Webhook verification and recovery

Configure the endpoint#

In your TLY Pay dashboard, open Integrations > Webhooks > Add Webhook. Enter Endpoint URL, submit, and save the credential from Save this signing Secret on your receiver. Existing signing Secrets are not shown in the Webhook list or detail. Open the Webhook detail and use Edit Webhook to change its URL or delivery status.
The API alternative is for automated integration setup: use a Key with webhook:bootstrap and call POST /v1/webhook-endpoints with Idempotency-Key and {"url":"https://merchant.example/webhooks/tly"}. This URL is illustrative. Use your real registered HTTPS domain, port 443, and no credentials, query string or fragment. The sender does not follow redirects.
You can configure one Webhook endpoint for your account. Configure it through your dashboard or the API rather than creating a second endpoint. For API setup, save the returned resource_id and one-time secret securely. A repeated setup response may omit secret. Keep the Secret you have already saved. If a retry does not return a Secret and you did not save one, rotate the Secret in your dashboard before using the endpoint. Verify saved API setup credentials with POST /v1/webhook-endpoints/{webhook_endpoint_id}/verify and {"secret":"<WEBHOOK_SECRET>"}.
secret_kind identifies an active or pending signing Secret. For rotation, open the Webhook detail under Integrations > Webhooks, choose Rotate Secret > Generate new Secret, and save the new signing Secret. Update your receiver to accept the pending signing Secret, then choose Activate rotated Secret > Activate Secret. The old signing Secret stays active until this explicit switch; afterward the sender uses only the new active signing Secret. A bounded receiver overlap can accept requests already in flight with the old signature.

Verify before parsing or processing#

TLY Pay sends an event JSON object containing schema_version, event_id, event_type, occurred_at and data. The event is payment.updated; creation, first Checkout activation and disabling Checkout access do not emit it. Updates, accepted amount changes, payment outcomes, expiration, cancellation and review can emit it.
Each delivery carries:
To verify the signature, use the timestamp's exact ASCII bytes, a period byte, and the original HTTP body bytes. Use the complete trusted Webhook signing Secret, exactly as supplied, as the HMAC-SHA256 key. Do not parse the unverified body to select a Secret, and do not reserialize JSON before verifying it.
Choose max_skew_secs in your receiver configuration and pass the current trusted Unix time as now_secs. Your HTTP framework must retrieve these case-insensitive headers correctly.
After verification, durably record or enqueue the event, deduplicate by event_id, and compare data.status_version only with the same Payment's stored version. Duplicate or stale facts must not overwrite newer facts. Return 2xx after accepting responsibility for the event. This example verifies the message only; it does not provide durable storage or fulfill an order.
The acknowledgment and business processing can happen separately after durable acceptance. HTTP 2xx acknowledges delivery, not a paid order. Use the authoritative Payment query when you need to recover missing payment facts.

Delivery and recovery#

Retries keep the event identity and envelope but use a new delivery timestamp and signature. HTTP 2xx acknowledges delivery. Network failures, 408, 425, 429 and 5xx receive finite retries; other non-2xx results are permanent failures. A redirect is not an acknowledgment.
If a notification is missing, query GET /v1/payments/{payment_id} with payment:read. Querying does not change delivery state. Open Integrations > Webhook log, select a delivery to inspect its status and attempts, and use Replay Delivery > Queue replay when you have permission to retry a delivery. Replay queues the same event again for the active Webhook, preserving its Event ID and original envelope. Delivery timestamps and signatures are generated for the new attempt. A queued replay is not proof that the receiver accepted it.
Associate an event with your integration using the verified Webhook signing Secret and the Payment ID, order reference, source amount and status version. Never derive payment success from Webhook delivery success alone.
Previous
HTTP conventions and payment status
Next
Create a Payment
Built with