Accept in Sandbox

Create a checkout link, pay with a test card, and simulate settlement into your wallet. Set NATURAL_API_KEY to your Sandbox API key. The examples use https://api.sandbox.natural.com. For MCP, connect to https://mcp.sandbox.natural.com.

Testing for a customer? Pass their party ID as customerPartyId on each call. Your agent needs permission to act on their behalf.

1. Create an intent

Create a payment intent for $39.20. Amounts are in cents.

import uuid
from naturalpay import Natural

client = Natural(
    base_url="https://api.sandbox.natural.com",
    instance_id=str(uuid.uuid4()),
)
intent = client.payment_intents.create(
    amount=3920,
    currency="USD",
    description="Sandbox test",
    idempotency_key=str(uuid.uuid4()),
)

import Natural from "@naturalpay/sdk";

const client = new Natural({ baseUrl: "https://api.sandbox.natural.com" });
const intent = await client.paymentIntents.create(
  {
    amount: 3920,
    currency: "USD",
    description: "Sandbox test",
    idempotencyKey: crypto.randomUUID(),
  },
  { instanceId: crypto.randomUUID() },
);

export NATURAL_BASE_URL=https://api.sandbox.natural.com

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

Create a Sandbox checkout link for $39.20 with the description "Sandbox test".

curl -X POST https://api.sandbox.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": "Sandbox test"
      }
    }
  }'

Keep the intent ID and checkout link from data.attributes.payUrl.

2. Pay with a test card

Open payUrl and enter a test card. Use a future expiration date and any three-digit CVC.

Card number	Outcome
`4111 1111 1111 1111`	Approved
`4000 0000 0000 0002`	Declined

3. Check the result

Get the payment intent to check its status.

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

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

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

Has that Sandbox payment been completed?

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

4. Settle the payment

Sandbox payments require simulated settlement. Open the payment in the Sandbox dashboard and select Simulate settlement, or use the API:

settlement = client.simulations.settle_card_payment(
    result.data.relationships.card_payment.data.id,
    idempotency_key=str(uuid.uuid4()),
)

const settlement = await client.simulations.settleCardPayment(
  {
    cardPaymentId: result.data.relationships.cardPayment.data.id,
    idempotencyKey: crypto.randomUUID(),
  },
  { instanceId: crypto.randomUUID() },
);

natural simulations settle-card-payment \
  --card-payment-id cpy_019d0a1b2c3d4e5f60718293a4b5c6d8 \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Simulate settlement for that successful Sandbox card payment.

curl -X POST https://api.sandbox.natural.com/simulations/card-payments/cpy_019d0a1b2c3d4e5f60718293a4b5c6d8/settle \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "attributes": {} } }'

The response returns the card payment. If settledAt is null, get the card payment again to check settlement.

Overview

Common use cases

Products

Guides

1. Create an intent

2. Pay with a test card

3. Check the result

4. Settle the payment

​1. Create an intent

​2. Pay with a test card

​3. Check the result

​4. Settle the payment

1. Create an intent

2. Pay with a test card

3. Check the result

4. Settle the payment