Frequently Asked Questions

Do I need to handle currencies/countries beyond the one I sell in?

No. You only need to use the countryCode, currency, and paymentMethodCode values relevant to the market you're selling in. We'll tell you which ones apply to you.

What's the difference between "Create Payment (API)" and "Create Payment (H5)"?

• API: You receive a payment code/link/QR back and display it yourself, in your own UI.
• H5: You redirect your customer to a payment page we host — less work for you, but less control over the look and feel.

Most merchants who want a fully branded checkout use the API option. Merchants who want the fastest integration use H5.

My payment request was rejected — what should I check first?

1. Is your Authorization header formatted exactly as Bearer YOUR_API_KEY?
2. Is merchantOrderId unique? Reusing an order ID will be rejected.
3. Are all required fields present? (See the field table in the integration guide.)
4. Has your API key been suspended or regenerated recently?

How long is a payment code/link valid for?

The expiry time is returned in paymentInfo.expiredTime on the create-payment response. After this time, the customer will need a new payment request.

I didn't receive a webhook — what do I do?

Webhooks are usually near-instant but can occasionally be delayed. As a fallback, poll GET /api/payments/status?merchantOrderId=... a few minutes after creating the payment. If the status is still PENDING after an extended period, treat the order as unpaid and follow up with your customer.

Why is paidAmount sometimes different from amount?

amount is what you requested. paidAmount is what the customer actually sent — some payment methods allow the customer to send a slightly different amount, so always confirm order completion using paidAmount, not amount.

How do I know a webhook really came from Crownline Global and not someone else?

Every webhook includes an X-Payfac-Signature header — an HMAC-SHA256 signature computed using your own API key. Recompute it yourself and compare. See the "Verifying the signature" section of the integration guide for code examples.

Can I test my integration before going live?

Yes — contact us for a sandbox API key. Sandbox transactions don't move real funds.

What happens if I regenerate my API key?

The old key is invalidated immediately. Update your integration with the new key right away, or your requests will start returning 401 Unauthorized.

Is there a rate limit on API requests?

If you expect high volume, let us know in advance so we can make sure your account is configured appropriately.

Who do I contact if something isn't working?

Reach out to your Crownline Global account contact with your merchant ID, the merchantOrderId in question, and a description of what you're seeing.