Integrating Scalapay directly
For custom checkouts, headless storefronts and in-app purchase flows. This page is a map of what the integration involves, not a substitute for the technical documentation.
Getting live on the API
The order below matters — messaging before testing, testing before live traffic.
Create the order server-side
Send the order total, currency, items and your return URLs. You receive a redirect URL for the customer.
Send the customer to approve
They review the plan and the dates, then return to the URL you supplied. Handle both the success and abandonment paths.
Wait for the webhook
The webhook is the authoritative result. Never mark an order paid on the redirect alone, because a customer can close the tab before returning.
Capture and fulfil
Once confirmed, treat the order like any other paid order in your system.
Six things specific to the API
The details that cause support tickets if you skip them.
Build for asynchronous confirmation
This is the single most common integration mistake. The redirect is a user-experience step; the webhook is the truth.
Make webhook handling idempotent
Webhooks can be delivered more than once. Processing the same event twice should not create two orders or two refunds.
Handle declines gracefully
A declined order is normal and not an error state. Return the customer to a checkout where they can pick another method.
Show messaging before checkout
The installment figure belongs on the product page. By the payment step, the decision is usually already made.
Test the full lifecycle
Order, partial refund, full refund and decline. Testing only the happy path is how problems reach production.
Order limits
Orders run from $200 to $5,000. Validate on your side before showing the option so customers are not offered something that will fail.
Test the paths that are not the happy one
Every integration works when the customer does exactly the expected thing. Problems come from the other cases.
- A customer who abandons at the approval step — they must land somewhere sensible with the basket intact.
- A declined order — this is a normal outcome, not an error. Send them back to a checkout with other options available.
- A partial refund — check the customer plan recalculates and your own reporting matches.
- An order outside the range — validate against $200 to $5,000 before showing the option, so nobody is offered something that will fail.
Testing only the successful order is the most common reason an integration causes problems in its first week.
Api integration FAQ
What developers and store owners ask before starting.
Does Scalapay have an API?+
Should I mark an order paid on the redirect?+
Are webhooks guaranteed to arrive once?+
Are partial refunds supported?+
Is there a sandbox?+
What should I validate before showing the option?+
Other integrations
Same account, different platform.
Ready to add it?
Apply for a merchant account and we will get you the credentials and the docs.