SDKs

pip install naturalpay
# or
uv add naturalpay

npm install @naturalpay/sdk
# or
yarn add @naturalpay/sdk

from naturalpay import Natural

# Agent key from NATURAL_API_KEY; instance_id identifies this run.
client = Natural(instance_id="invoice-run-1234")

# Create a payment on behalf of a customer
payment = client.payments.create(
    amount=10000,  # cents - $100.00
    currency="USD",
    counterparty={"type": "email", "value": "ada@example.com"},
    description="Invoice #1234",
    customer_party_id="pty_019cd1798d627ad9bc302511c4f2c115",
    idempotency_key="pay-invoice-1234",
)

print(payment.data.id)
print(payment.data.attributes.status)

import Natural from "@naturalpay/sdk";

// One client per run: instanceId names the run, and the SDK sends it
// as X-Instance-ID on every call this client makes.
const client = new Natural({ instanceId: "invoice-run-1234" }); // agent key from NATURAL_API_KEY

// Create a payment on behalf of a customer
const payment = await client.payments.create({
  amount: 10000, // cents - $100.00
  currency: "USD",
  counterparty: { type: "email", value: "ada@example.com" },
  description: "Invoice #1234",
  customerPartyId: "pty_019cd1798d627ad9bc302511c4f2c115",
  idempotencyKey: "pay-invoice-1234",
});

console.log(payment.data.id);
console.log(payment.data.attributes.status);

# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
# One client per run: instance_id names the run, and the SDK sends it
# as X-Instance-ID on every call this client makes.
client = Natural(instance_id="vendor-payouts-q1")

payment = client.payments.create(
    counterparty={"type": "email", "value": "ada@example.com"},
    amount=50000,  # cents ($500.00)
    description="Vendor payment",
    customer_party_id="pty_019cd1798d627ad9bc302511c4f2c115",
    idempotency_key="vendor_payment_001",
)

// NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
// One client per run: instanceId is required for money movement with an agent key.
const client = new Natural({ instanceId: "vendor-payouts-q1" });

const payment = await client.payments.create({
  counterparty: { type: "email", value: "ada@example.com" },
  amount: 50000, // cents ($500.00)
  description: "Vendor payment",
  customerPartyId: "pty_019cd1798d627ad9bc302511c4f2c115",
  idempotencyKey: "vendor_payment_001",
});

# NATURAL_API_KEY=sk_ntl_sandbox_...
client = Natural(base_url="https://api.sandbox.natural.com")

// NATURAL_API_KEY=sk_ntl_sandbox_...
const client = new Natural({ baseUrl: "https://api.sandbox.natural.com" });