Skip to main content
Put Natural’s payment form on your own checkout page. Your server creates a payment intent. The form takes the card and runs the payment. Before you start, connect Natural to your agent or create an API key. See Start here. Setup takes a couple of minutes; the MCP path needs no API key. Start in Sandbox. There the form loads on any site, so you can build on localhost. Set 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 customerPartyId when 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, including paymentIntent.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 with POST /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.
Use the order as the idempotency key, so a retry within 48 hours returns the same intent instead of creating a second one. The response includes 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

Create the 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

When onError 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
To change the order, update the intent on your server. The next time the payer presses Pay, the form shows the new total and asks them to press Pay again.

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, pass theme="dark":
Popups use the same theme.

Place the form

  • The form grows to fit what it shows. Don’t give PaymentForm or its parents a fixed height with overflow: hidden.
  • Size and position the form with className on PaymentForm. natural.js sets 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 on localhost in 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, enter 000000. 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 at https://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:
The path must return 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.
If you can’t add a rewrite, download Natural’s file and serve it as a static file, for example from 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:
The command prints 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 sends Cross-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 in script-src and frame-src:
That’s the whole list. 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.