Request a payment - Natural Docs

Ask anyone for money and let Natural deliver the payment link. For the request lifecycle, read the Payment requests overview.

Request the payment

Create the request with POST /payment-requests. Address the payer by email, phone, party ID (pty_*), agent ID (agt_*), or handle, the same set you use for a payment counterparty. Handles, party IDs, and agent IDs must already exist on Natural. description is at most 80 characters and payerName at most 32.

import uuid
from naturalpay import Natural

# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
agent_client = Natural(
    instance_id=str(uuid.uuid4()),
)

request = agent_client.payment_requests.create(
    amount=2500,
    currency="USD",
    description="Invoice 7",
    payer_name="Ada Lovelace",
    payer={"type": "email", "value": "ada@example.com"},
    idempotency_key=str(uuid.uuid4()),
)

import Natural from "@naturalpay/sdk";

// NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
const client = new Natural();
const request = await client.paymentRequests.create(
  {
    amount: 2500,
    currency: "USD",
    description: "Invoice 7",
    payerName: "Ada Lovelace",
    payer: { type: "email", value: "ada@example.com" },
    idempotencyKey: crypto.randomUUID(),
  },
  {
    instanceId: crypto.randomUUID(),
  },
);

# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
natural payment-requests create \
  --amount 2500 \
  --currency USD \
  --description "Invoice 7" \
  --payer-name "Ada Lovelace" \
  --params '{"payer": {"type": "email", "value": "ada@example.com"}}' \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Using my Procurement Agent, request $25 from ada@example.com for Invoice 7.

# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
curl -X POST https://api.natural.com/payment-requests \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "amount": 2500,
        "currency": "USD",
        "description": "Invoice 7",
        "payerName": "Ada Lovelace",
        "payer": { "type": "email", "value": "ada@example.com" }
      }
    }
  }'

The response carries the request id (prq_*) and the paymentLinkUrl. Natural delivers the request for you: the payment link by email or text message for a payer new to Natural, a dashboard link for a payer on Natural, and the payment_request.incoming webhook for an agent.

Track it

Check status any time with GET /payment-requests/{paymentRequestId}. A request is OPEN until the payer acts. It moves to PROCESSING while their payment is in flight, then COMPLETED. It ends at DECLINED, CANCELED, EXPIRED, FAILED, or RETURNED.

request = client.payment_requests.get(request.data.id)

const status = await client.paymentRequests.get({
  paymentRequestId: request.data.id,
});

natural payment-requests get --payment-request-id prq_019cd1798d7a68fe07c972bed48fb7fd

What's the status of that payment request?

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

Cancel it

Cancel an OPEN request with POST /payment-requests/{paymentRequestId}/cancel to void its payment link and move it to CANCELED. A request that is already PROCESSING or terminal returns 409. Once the payer fulfills a request, the resulting payment settles like any other. An agent key must send X-Instance-ID here too.

import uuid

canceled = client.payment_requests.cancel(
    request.data.id,
    idempotency_key=str(uuid.uuid4()),
)

const canceled = await client.paymentRequests.cancel({
  paymentRequestId: request.data.id,
  idempotencyKey: crypto.randomUUID(),
});

natural payment-requests cancel \
  --payment-request-id prq_019cd1798d7a68fe07c972bed48fb7fd \
  --idempotency-key "$(uuidgen)"

curl -X POST https://api.natural.com/payment-requests/prq_019cd1798d7a68fe07c972bed48fb7fd/cancel \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"