Talk to an engineer
docs From npm install to first charge in minutes

Everything to build the checkout

A copy-paste quickstart, typed SDKs for the client and server, a complete API reference, a CLI for local development and a test mode that mirrors live. Start with a publishable key and have the payment element rendering in your own UI before your coffee goes cold.

Start the quickstart Open the API reference
Typed clients, generated from the spec Idempotent writes, predictable errors Local webhook replay
pi_3Q createdtest mode · 120 ms
naturpay listenforwarding to localhost
quickstart 
# add the client and server packages
npm i naturpay @naturpay/react

# pull your test keys into the CLI
npx naturpay login
✔ linked account acct_8fk · test mode
// mount the element in your UI
import { PaymentElement } from '@naturpay/react';

<PaymentElement
  secret={clientSecret}
  appearance={theme}
  onConfirm={handleDone}
/>
// confirm from your server
const result = await wv.intents.confirm(
  intentId,
  { idempotencyKey: order.id }
);
if (result.status === 'succeeded') fulfill();
Jump to
QUICKSTARTSDKsAPICLIWEBHOOKS

Quickstart

Four steps to a live charge

The whole loop fits in an afternoon: install, create an intent on the server, mount the element in your front end, then confirm and listen for the signed event. No hosted page and no redirect.

Install and authenticate

Add the client and server packages, then link the CLI to your account to pull test keys and forward events.

npm i naturpay

Create an intent

On your server, create a payment intent for the order amount and currency, with an idempotency key, and return its client secret.

POST /v1/intents

Mount the element

Render the payment element with the client secret and your appearance theme into any node you control. The fields stay isolated and PCI-safe.

<PaymentElement />

Confirm and fulfil

Confirm the intent, handle 3-D Secure inline if it triggers, then fulfil the order when the signed payment.succeeded webhook arrives.

verify webhook

SDKs and libraries

First-party clients for your stack

Client packages render the headless components; server packages talk to the API with types generated from the same spec. Pick your framework and language, or drop to the REST API if your runtime is not listed.

CLIENT · components

React

Hooks and components — the payment element, card fields and wallet buttons, with typed props and a provider for context.

npm i @naturpay/react

Vue

Composables and single-file components for Vue 3, with reactive appearance bindings and the full element catalogue.

npm i @naturpay/vue

Web Components

Framework-free custom elements you can drop into any page or framework, themed through attributes and CSS parts.

npm i @naturpay/elements

JS / vanilla

The core browser SDK that powers them all — mount elements imperatively anywhere, no build step or framework required.

npm i naturpay

SERVER · API clients

Node

Fully typed, promise-based, with auto-retries and idempotency baked into every write. ESM and CommonJS builds.

npm i naturpay

Python

Type hints throughout, sync and async clients, and dataclasses for every resource so your IDE knows the shapes.

pip install naturpay

Ruby

An idiomatic gem with first-class objects, configurable retries and structured errors you can rescue precisely.

gem install naturpay

Go

A context-aware client with typed structs, explicit error values and no reflection on the hot path.

go get go.natur-pay.com

PHP

A Composer package with PSR-friendly interfaces, typed properties and helpers for verifying webhooks.

composer require naturpay/naturpay

REST API

No SDK for your runtime? The API is plain, versioned JSON over HTTPS, with an OpenAPI spec you can generate a client from.

GET api.natur-pay.com/v1

API reference

A typed, idempotent REST API

Predictable resources, JSON bodies, idempotency keys on every write and errors with machine-readable codes. Authenticate with a secret key and create your first intent in one request.

POST /v1/intents 
curl https://api.natur-pay.com/v1/intents \
  -u sk_live_8fk…: \
  -H "Idempotency-Key: order_5821" \
  -d amount=12800 \
  -d currency=eur \
  -d capture=automatic
{
  "id": "pi_3Qk7Yc2eZf",
  "object": "payment_intent",
  "amount": 12800,
  "currency": "eur",
  "status": "requires_confirmation",
  "client_secret": "pi_3Qk7Yc_secret_…",
  "livemode": true
}
  • Resource-oriented URLs and standard HTTP verbs and status codes.
  • Idempotency keys make any retried write safe and never double-charge.
  • Cursor pagination, expandable objects and a date-based version header.
  • Errors return a type, a code and a human message you can surface.
/v1/intentscore

Intents

Create, confirm, capture and cancel a payment. The object that drives the whole flow from amount to settlement.

/v1/methodstokens

Methods

Tokenized cards and wallets you can attach to an intent or save to a customer for later, never raw card data.

/v1/refundsmoney-out

Refunds

Refund a payment in full or in part, track its status, and reconcile it against the original intent.

/v1/webhooksevents-out

Webhooks

Register signed endpoints, choose the event types you care about, and inspect recent deliveries and retries.

/v1/customersvault

Customers

Group saved methods and metadata under a customer for returning buyers and one-tap repeat purchases.

/v1/eventslog

Events

A queryable log of everything that happened on your account, the same payloads your webhooks receive.

naturpay CLI 
# forward live events to your machine
$ naturpay listen --forward localhost:3000/hooks
→ ready · whsec_test_2a9f
→ payment.succeeded  200  18ms

# replay any past event by id
$ naturpay events replay evt_1m2N
✔ re-delivered to 1 endpoint

# trigger a test scenario
$ naturpay trigger payment.failed
✔ emitted with decline_code: insufficient_funds

CLI and test mode

Develop against real shapes, locally

The CLI links to your account, scaffolds a project, tails logs and forwards live webhooks to localhost so you never deploy to test an event. Test mode returns the exact response shapes as production, and you can summon declines, disputes and authentication challenges on demand.

  • Forward and replay signed webhooks straight to your dev server.
  • Trigger declines, disputes and 3-D Secure with test methods.
  • Deterministic fixtures keep your integration tests stable.
  • Tail request logs and inspect every API call with full payloads.

Keep going

More for when you go deeper

Guides and recipes

End-to-end walkthroughs for saved cards, subscriptions, marketplaces splits, multi-currency and retries.

copy-paste ready

OpenAPI spec

The full machine-readable spec, so you can generate a typed client for any language or load it into your tooling.

versioned · downloadable

Changelog and versioning

Dated API versions pinned per request, a public changelog and deprecation windows you can plan around.

no surprise breaks

Status and uptime

A live status page for the API, dashboard and webhooks, with historical uptime and incident write-ups.

subscribe to alerts

Developer support

Reach our engineers directly at hello@natur-pay.com when you hit an edge case, with sample payloads in hand.

engineer to engineer

Example apps

Reference integrations for React, Next, Vue and a plain server, each runnable with your own test keys.

clone and run

Grab a key and start building

Create a test key, run the quickstart and watch a real payment intent move through your own UI. When you are ready to go live, talk to an engineer about volume and rollout.

Get your test keys Talk to an engineer