Troubleshooting payments

When an order status isn't what you expect, first identify where the problem occurred: creating the payment order, the buyer's checkout, webhook delivery, or your system's order update.

Gather this information first

• Your order ID (orderId)
• The Taria Pay paymentId
• The buyer's email
• The transaction hash (txHash)
• The webhook delivery id
• A screenshot of what the buyer saw
• When the issue occurred

Payment order creation fails

Common causes:

• API key missing, invalid, or revoked
• orderId already exists
• amount, currency, or URL fields are malformed
• The server has the wrong API base URL configured (TARIAPAY_API_BASE must be the origin only; the SDK appends /v1)

How to resolve:

1. Confirm the API key is only used server-side.
2. Check the request fields against the API reference.
3. If the error response includes a requestId, record it and contact support.

The buyer can't complete payment

Common causes:

• Wallet not connected, or on the wrong network
• Insufficient balance
• The buyer rejected the wallet confirmation
• The buyer's chosen network or currency is currently unavailable

How to resolve:

1. Have the buyer check their wallet balance and network.
2. Check the payment options shown on the checkout page.
3. If the payment is already on-chain, record the transaction hash.

The buyer paid, but your site's order didn't update

Check the webhook first:

1. Is the webhook endpoint a publicly reachable HTTPS URL?
2. Does the signing secret match the one in the Dashboard?
3. Does your server read the raw request body before verifying the signature? (constructWebhookEvent from @tariapay/sdk does this if you pass req.text() / the raw body.)
4. Does the handler return 2xx?
5. Is the order-update logic idempotent?

Never use whether the buyer reached the successUrl to determine the final payment result.

Webhook deliveries are failing

Check Delivery Logs under Developers:

• Response status code
• Most recent error
• Retry count
• Delivery id
• Event type

Common fixes:

• Correct the webhook URL.
• Update the signing secret.
• Open up the firewall or security policy.
• Have the handler return 2xx quickly and move slow work to the background.

Contacting support

If you can't pin down the issue, email support@tariapay.com with the diagnostic information listed at the top of this page.