Common Issues

Unable to Create Order / API Request Fails

Reason	Solution
Missing or invalid API token	Ensure you are sending a valid Bearer token in the Authorization header.
Expired or revoked API token	Generate a new API token from the ForgingBlock dashboard and update your integration.
Invalid request payload	Verify required fields such as price_amount and price_currency, and ensure values match the API schema.
Unsupported fiat currency	Check that price_currency is a valid ISO-4217 code supported by ForgingBlock.
Duplicate order_id	Ensure order_id is unique per merchant, or omit it to let ForgingBlock generate one.
Rate limit exceeded	Reduce request frequency and retry after the indicated cooldown period.
Network connectivity issue	Confirm your server can reach https://api.forgingblock.io.

---

Order Status Not Updating / No Payment Callback Received

Reason	Solution
Callback URL is not publicly accessible	Ensure your callback_url is reachable from the public internet (not localhost or private IP).
Callback endpoint returns non-2xx response	Your webhook endpoint must respond with HTTP 200 OK.
Server firewall or security layer blocks requests	Allow incoming webhook requests from ForgingBlock infrastructure.
Invalid webhook signature handling	Verify webhook signatures using the ForgingBlock public key.
Order already expired	Invoices expire after 20 minutes; expired orders will not receive payment updates.

---

Debugging Tips

• Log all incoming callback payloads and headers.
• Always verify webhook signatures before processing events.
• Check order state using the Get Order API endpoint.
• Confirm expire_at has not passed before expecting payment.