Create a payment intent and get paid by link

Create a payment intent, share its checkout link, and track the payment.

Taking card payments for a customer instead of your own business? Pass their party ID as customerPartyId on every call below. See Collecting for a customer.

Create the intent

Create the intent with POST /payment-intents. To change it while it’s open, update the intent; the pay page shows the new total before the payer pays.

import uuid
from naturalpay import Natural

# Set NATURAL_API_KEY to your agent's API key.
client = Natural(instance_id=str(uuid.uuid4()))

intent = client.payment_intents.create(
    amount=3920,
    currency="USD",
    description="Order 8842",
    idempotency_key=str(uuid.uuid4()),
)

import Natural from "@naturalpay/sdk";

// Set NATURAL_API_KEY to your agent's API key.
const client = new Natural();
const intent = await client.paymentIntents.create(
  {
    amount: 3920,
    currency: "USD",
    description: "Order 8842",
    idempotencyKey: crypto.randomUUID(),
  },
  { instanceId: crypto.randomUUID() },
);

natural payment-intents create \
  --amount 3920 \
  --currency USD \
  --description "Order 8842" \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Create a checkout link for Order 8842 for $39.20.

curl -X POST https://api.natural.com/payment-intents \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"amount":3920,"currency":"USD","description":"Order 8842"}}}'

The response includes the checkout link in data.attributes.payUrl. You can also include line items and tax.

Hand the payer the link

Send payUrl to the payer. They can enter a card, use Apple Pay where available, or use a saved card after verifying their email. Natural handles checkout, 3-D Secure, and the receipt.

Follow the payment

Read the intent with GET /payment-intents/{paymentIntentId}. Check its status to see whether it was paid.

payment = client.payment_intents.get(intent.data.id)

const payment = await client.paymentIntents.get({
  paymentIntentId: intent.data.id,
});

natural payment-intents get --payment-intent-id pmi_019d0a1b2c3d4e5f60718293a4b5c6d7

Has the payment intent for Order 8842 been paid?

curl https://api.natural.com/payment-intents/pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 \
  -H "Authorization: Bearer $NATURAL_API_KEY"

A paid intent has status completed. Its cardPayment relationship identifies the successful payment. Funds become available after settlement. Subscribe to paymentIntent.completed, cardPayment.succeeded, and cardPayment.failed webhooks for updates. See Card payments for failed attempts.

Reconcile

List payment intents to review recent activity. Filter by status or creation date. Use cursor for the next page and customerPartyId for a customer’s intents.

intents = client.payment_intents.list(status="open", limit=20)

const intents = await client.paymentIntents.list({ status: "open", limit: 20 });

natural payment-intents list --status open --limit 20

List my 20 most recent open payment intents.

curl "https://api.natural.com/payment-intents?status=open&limit=20" \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Successful payments and refunds appear in Transactions. Each payment transaction links to its card payment.

Cancel an intent

Cancel an open intent with POST /payment-intents/{paymentIntentId}/cancel. The checkout link stops working. For cURL, send data.attributes even when empty.

canceled = client.payment_intents.cancel(
    intent.data.id,
    idempotency_key=str(uuid.uuid4()),
)

const canceled = await client.paymentIntents.cancel(
  {
    paymentIntentId: intent.data.id,
    idempotencyKey: crypto.randomUUID(),
  },
  { instanceId: crypto.randomUUID() },
);

natural payment-intents cancel \
  --payment-intent-id pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Cancel the unpaid payment intent for Order 8842.

# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
curl -X POST https://api.natural.com/payment-intents/pmi_019d0a1b2c3d4e5f60718293a4b5c6d7/cancel \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "attributes": {} } }'

An intent with a payment in progress cannot be canceled, and neither can one that already completed. Refund a completed payment instead: see Refund a card payment.

Overview

Common use cases

Products

Guides

Create a payment intent and get paid by link

Create the intent

Hand the payer the link

Follow the payment

Reconcile

Cancel an intent

​Create the intent

​Hand the payer the link

​Follow the payment

​Reconcile

​Cancel an intent

Create the intent

Hand the payer the link

Follow the payment

Reconcile

Cancel an intent