NATURAL_API_KEY to your Sandbox API key and call https://api.sandbox.natural.com. Before you take real payments, add your site.
If you’re a platform that takes payments for your merchants, here is what changes:
- Pass the merchant’s party ID as
customerPartyIdwhen you create or read the intent. See Accept payments. - Register your webhook with
sources: ["own", "connected"]. With the default,["own"], you get none of your merchants’ payment events, includingpaymentIntent.completed. - The form shows the merchant’s business name, policies, and brand color, not yours. Natural registers each site with Apple Pay separately for each merchant, the first time that merchant’s form loads there.
Amounts are integer US cents:
50000 is $500.00.Create the intent
Create the intent on your server withPOST /payment-intents.
When an agent (
agt_*) creates, cancels, fulfills, or declines a payment, payment request,
transfer, payment intent, refund, or voice session, it authenticates with its own credential (an
agent key or an agent-scoped OAuth grant) and names
the run with the X-Instance-ID header. Without it the call returns 400 missingInstanceId.
Reads don’t need it.data.attributes.clientSecret. Store data.id with the order, and send the secret to the browser. Treat it like a password. Don’t log it or put it in a URL. A read of the intent returns the same clientSecret while the intent is open or processing. Once it’s completed, canceled, declined, or expired, clientSecret is null.
Add the form to your page
clientSecret Promise once, outside render. A new clientSecret or theme mounts a new form. PaymentForm removes the form when it unmounts. It works with server rendering, Strict Mode, and the Next.js app router.
Without React, install @naturalpay/js and mount the form yourself. It takes the clientSecret, theme, onComplete and onError described below.
Confirm the payment
When the payer is done,onComplete gets { paymentIntentId, status }. It fires once. If the intent was already completed or processing when the form mounted, it fires right away.
Show your confirmation on
onComplete. Don’t ship the order from there. Ship it when the paymentIntent.completed webhook arrives on your server. The webhook arrives even if the payer closes the page.
A processing payment can still fail. If it does, you get a cardPayment.failed webhook and the intent goes back to open. The form keeps showing “Payment processing”. To let the payer try again, render PaymentForm with a new key. After the intent’s fifth declined payment, the intent becomes declined instead of open, and a new form gets payment_intent_unavailable.
A setup intent’s clientSecret shows a form that saves the card without charging it. When the card is saved, onComplete gets { setupIntentId, status: "completed" }.
When a payer comes back to your checkout page, read the intent by the id you stored. If its clientSecret is null, don’t render the form. Show the payer the intent’s status instead.
Handle errors
WhenonError fires, the form is done. It can’t take a payment anymore. To try again, render PaymentForm with a new key.
An error is a plain { code, message } object. Match on code. We never rename or remove a code, but we do add new ones, so handle a code you don’t know. The message is for your logs. Its wording can change.
A problem the payer can fix, like a declined card, shows inside the form. It doesn’t call onError.
Show the order on your page
The form shows the total, your business name, and your policies. Make sure your page shows:- Each item, any tax or fee, and the total with its currency, matching the intent’s
amount - Your country, and an email address or phone number for support
- Your delivery policy, if you ship goods
Match your page
The form has no background of its own. Its Pay button uses the brand color of the intent’s merchant. On a dark page, passtheme="dark":
Place the form
- The form grows to fit what it shows. Don’t give
PaymentFormor its parents a fixed height withoverflow: hidden. - Size and position the form with
classNameonPaymentForm.natural.jssets the size of its own frames. - Popups, such as a 3-D Secure challenge or a sign-in code, open over your whole page.
- Serve your page over HTTPS. The form doesn’t load on plain
http, except onlocalhostin Sandbox.
Test in Sandbox
Your page code doesn’t change between Sandbox and live. The secret tells the form which one it’s in. Pay with the test cards. When the form asks for a code, to save a card or to sign in, enter000000.
Sandbox skips the 3-D Secure challenge popup, Google Pay, and the receipt email.
Sandbox offers Apple Pay once your site serves Apple’s file.
- Pay with your own card. It isn’t charged.
- Every Apple Pay payment succeeds. Test declines with the test cards.
- If your team can’t use real cards, use Apple’s sandbox tester accounts.
Go live
Create the intent with your production API key athttps://api.natural.com. Then list every site that shows the form. Open Developers, then API keys, and add them under Checkout domains.
A site is a scheme, host, and port, like https://shop.example.com. Browsers treat example.com and www.example.com as two sites, so list both if you use both. If you’re a platform, your sites cover the intents you create for your merchants. On a site you haven’t listed, onError gets domain_not_allowed.
Set up Apple Pay and Google Pay
Apple Pay needs one file on each of your sites. Google Pay needs one header setting.Serve Apple’s file
Apple checks the site that shows the form, not Natural’s frame inside it. Every site under Checkout domains must serve Apple’s file at this path:200 directly, with no redirect and no password. The file is the same for every Natural merchant, so rewrite the path to Natural’s file. If Natural’s file changes, your site serves the new one with no redeploy.
public/.well-known/. A copy doesn’t change when Natural’s file changes.
On Express 5, express.static hides folders whose names start with a dot. Serve the folder on its own path with app.use("/.well-known", express.static("public/.well-known")).
To check a site, run:
Ready for Apple Pay only when your site serves Natural’s file directly. Any other result prints Not ready, for example a redirect, a login page, your site’s home page, another provider’s file, or a failed download.
Natural registers each site with Apple the first time the form loads there. Apple takes up to 10 minutes to verify a site, and Apple Pay appears after that. If you add the file after the form first loads, Apple Pay appears within a day, as long as the form keeps loading on that site. Check the file before you go live to avoid the wait.
Allow the Google Pay window
Google Pay opens a Google window from the form. If your page sendsCross-Origin-Opener-Policy: same-origin, the browser cuts the form’s link to that window and the payment fails. The payer sees “Google Pay could not be completed.”
Send Cross-Origin-Opener-Policy: same-origin-allow-popups instead, or don’t send the header. Hono’s secureHeaders() and Helmet send same-origin by default. Set the option to same-origin-allow-popups:
Content Security Policy
If your page sets a Content Security Policy, allow Natural’s checkout origin inscript-src and frame-src:
natural.js makes no network requests from your page and adds no styles. PaymentForm adds the natural.js script tag without a nonce. If your policy uses nonces, keep the source above or add 'strict-dynamic'. If your page enforces Trusted Types, allow the one policy PaymentForm creates:
Browser support
The form works in webviews and in-app browsers. Apple Pay and Google Pay may not appear there.