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 3220`	Approved after simulated 3-D Secure
`4000 0000 0000 0002`	Declined

Sandbox runs 3-D Secure only when Natural’s risk check on the payment asks for it, and 4000 0000 0000 3220 always asks for it. Sandbox 3-D Secure is simulated: it passes without showing a challenge. See Card fixtures for every test card.

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.

Test subscriptions

Test card outcomes and subscription simulation controls are available to customers only in Sandbox. To test a temporary decline and recovery:

Create a subscription with no end in Sandbox and pay payment 1 with 4111 1111 1111 1111. Its saved card normally succeeds on later charges.
Open Accept → Subscriptions in the Sandbox dashboard, select the subscription, and choose Simulate. Set the next charge to decline for Insufficient funds, then advance to payment 2.
Payment 2 declines once. Retry payment 2 to make its next attempt succeed. If you advance to payment 3 instead, Natural skips the remaining retries and leaves payment 2 missed and owed. Payment 3 succeeds, and the subscription reads past_due.

A decline override applies to one actual charge attempt, then the saved test card’s normal outcome returns. Cards with predetermined later declines keep declining on later attempts. An expired-card decline stops collection for attention; a stopped-payment decline cancels the subscription. See Subscription simulations for the card outcomes and test-clock behavior.

Overview

Common use cases

Guides

1. Create an intent

2. Pay with a test card

3. Check the result

4. Settle the payment

Test subscriptions