Fulfill or decline a payment request

Pay a request (prq_*) addressed to you from a wallet (wal_*) or linked bank account, or turn it down. For the request lifecycle, read the Payment requests overview.

See what’s waiting on you

List the requests addressed to you with GET /payment-requests/incoming.

from naturalpay import Natural

client = Natural()
requests = client.payment_requests.list_incoming()

import Natural from "@naturalpay/sdk";

const client = new Natural();
const requests = await client.paymentRequests.listIncoming();

natural payment-requests list-incoming

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

Each item’s id (prq_*) is what you fulfill or decline below. payerCanPay: true means it’s still waiting on you.

Fulfill it

POST /payment-requests/{paymentRequestId}/fulfill pays the request and moves the money. The amount comes from the request itself. You choose only the source: set paymentSource to a wallet you own, { "type": "wallet", "walletId": "wal_..." } (omit walletId for your default), or to a verified linked bank account you own, { "type": "external_account", "externalAccountId": "eac_..." }. Bank-funded payments settle over ACH. A request accepts one attempt; retry with the same Idempotency-Key.

import uuid
from naturalpay import Natural

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

payment = agent_client.payment_requests.fulfill(
    "prq_019cd1798d7a68fe07c972bed48fb7fd",
    payment_source={"type": "wallet", "wallet_id": "wal_019cd1798d714ce765e0486a417c23dc"},
    idempotency_key=str(uuid.uuid4()),
)

// NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
const payment = await client.paymentRequests.fulfill(
  {
    paymentRequestId: "prq_019cd1798d7a68fe07c972bed48fb7fd",
    paymentSource: { type: "wallet", walletId: "wal_019cd1798d714ce765e0486a417c23dc" },
    idempotencyKey: crypto.randomUUID(),
  },
  {
    instanceId: crypto.randomUUID(),
  },
);

# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
natural payment-requests fulfill \
  --payment-request-id prq_019cd1798d7a68fe07c972bed48fb7fd \
  --json '{"paymentSource": {"type": "wallet", "walletId": "wal_019cd1798d714ce765e0486a417c23dc"}}' \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Fulfill payment request prq_019cd1798d7a68fe07c972bed48fb7fd from my main wallet.

# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
curl -X POST https://api.natural.com/payment-requests/prq_019cd1798d7a68fe07c972bed48fb7fd/fulfill \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "paymentSource": {
          "type": "wallet",
          "walletId": "wal_019cd1798d714ce765e0486a417c23dc"
        }
      }
    }
  }'

The response carries the resulting payment (pay_*), starting in PROCESSING, or IN_REVIEW when an approval policy holds it: Track it to confirm it settles.

Decline it

POST /payment-requests/{paymentRequestId}/decline turns the request down. No money moves, the requester is notified, and the request’s status becomes DECLINED. Declining is final and cannot be undone. Only an OPEN request can be declined, and declining is not available on behalf of a customer. An agent key must send X-Instance-ID here too.

import uuid

declined = client.payment_requests.decline(
    "prq_019cd1798d7a68fe07c972bed48fb7fd",
    idempotency_key=str(uuid.uuid4()),
)

const declined = await client.paymentRequests.decline({
  paymentRequestId: "prq_019cd1798d7a68fe07c972bed48fb7fd",
  idempotencyKey: crypto.randomUUID(),
});

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

Decline payment request prq_019cd1798d7a68fe07c972bed48fb7fd.

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

Overview

Common use cases

Products

Guides

Fulfill or decline a payment request

See what’s waiting on you

Fulfill it

Decline it

​See what’s waiting on you

​Fulfill it

​Decline it

See what’s waiting on you

Fulfill it

Decline it