Fulfill a payment request

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 listIncoming

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. A status of OPEN 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 only choose where it is paid from, so set paymentSource to a wallet you own.

import uuid
from naturalpay import Natural

agent_client = Natural(
    x_agent_id="agt_019cd1798d637a4da75dce386343931d",
    x_instance_id=str(uuid.uuid4()),
)

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

const payment = await client.paymentRequests.fulfill(
  {
    paymentRequestId: "prq_550e8400e29b41d4a716446655440000",
    paymentSource: { type: "wallet", walletId: "wal_550e8400e29b41d4a716446655440000" },
    idempotencyKey: crypto.randomUUID(),
  },
  {
    xAgentId: "agt_019cd1798d637a4da75dce386343931d",
    xInstanceId: crypto.randomUUID(),
  },
);

natural payment-requests fulfill \
  --payment-request-id prq_550e8400e29b41d4a716446655440000 \
  --json '{"paymentSource": {"type": "wallet", "walletId": "wal_550e8400e29b41d4a716446655440000"}}' \
  --x-agent-id agt_019cd1798d637a4da75dce386343931d \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Fulfill payment request prq_550e8400e29b41d4a716446655440000 from my main wallet.

curl -X POST https://api.natural.com/payment-requests/prq_550e8400e29b41d4a716446655440000/fulfill \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Agent-ID: agt_019cd1798d637a4da75dce386343931d" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "paymentSource": {
          "type": "wallet",
          "walletId": "wal_550e8400e29b41d4a716446655440000"
        }
      }
    }
  }'

Fulfilling returns the resulting payment (pay_*), which starts in PROCESSING. Track it to confirm it settles.

You can also fulfill from a linked bank account instead of a wallet.

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.

import uuid

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

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

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

Decline payment request prq_550e8400e29b41d4a716446655440000.

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

Overview

Common use cases

Products

Guides

Fulfill 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