@naturalpay/react

Natural's embedded payment form as a React component. PaymentForm is a client component, so it works in the Next.js App Router.

The guide, Embed the payment form, has the server code, webhook setup, and every error code. Agents can read it as Markdown at https://docs.natural.com/guides/accept/embedded-checkout.md.

How a payment works

1. Your server creates a payment intent with POST /payment-intents, through @naturalpay/sdk or any HTTP client. The response has the secret at data.attributes.clientSecret. Send it to the browser, and treat it like a password.
2. Your page renders PaymentForm with the clientSecret. The payer pays inside the form.
3. The form calls onComplete. Show your confirmation there.
4. Your server gets the paymentIntent.completed webhook. Fulfill the order from the webhook, not from onComplete.

Add the form

npm install @naturalpay/react

import { PaymentForm } from "@naturalpay/react";

<PaymentForm clientSecret={clientSecret} onComplete={showConfirmation} onError={showError} />;

Props

• clientSecret is the payment intent's clientSecret, or a Promise of it. It's required. A new value mounts a new form, so create a Promise once, not on every render.
• theme is "light" (the default) or "dark", for a page with a dark background. A new value mounts a new form.
• onComplete gets { paymentIntentId, status }, once, when the payer is done. A completed status means the payer paid. A processing status means the result arrives by webhook, and the payment can still fail.
• onError gets a failed mount and every later error. Without it, errors go to the console.
• className is set on the <div> that holds the form.

Set up your site

• Serve your page over HTTPS. Plain http works only on localhost and 127.0.0.1, and only in Sandbox.
• Start in Sandbox. There the form loads on any site.
• Before you take live payments, add each site that shows the form, like https://shop.example.com, in the Natural dashboard under Developers → API keys → Checkout domains. In live mode, a site that isn't listed gets domain_not_allowed.
• If your page sets a Content Security Policy, allow https://checkout.natural.com in script-src and frame-src.
• If your page sends Cross-Origin-Opener-Policy: same-origin, send same-origin-allow-popups instead. Otherwise Google Pay fails.

Handle errors

An error is a plain { code, message } object, not an Error.

• Match on code. A code is never renamed or removed, but new ones are added, so handle a code you don't know.
• Log message. Its wording can change, so don't match on it or show it to payers.
• After onError fires, the form can't take a payment. Render PaymentForm with a new key to let the payer try again.
• A declined card shows inside the form. It doesn't call onError.

The guide lists every code. Changes are in CHANGELOG.md.

What your page must show

The form shows the merchant name, card fields, the authorization sentence, and your policies. Your page shows the rest:

1. What the payer is buying.
2. Each item, any tax or fee, and the total with its currency.
3. Your country and a support email or phone, on the page or in your footer.
4. Your delivery policy, if you ship goods.

Natural emails the payer a receipt.