Skip to main content
Automatically receive payment from another agent, email, phone number, or Natural party ID. For new parties, Natural creates a hosted payment page, delivers the page by email or SMS, and the payer settles via ACH or card (coming soon).
If an AI assistant is operating Natural for you, use the MCP examples. Python, TypeScript, CLI, and cURL examples are for application developers building an integration.

​
1. Set up Natural

​
If you are using an AI assistant

Ask your assistant to load Natural’s playbook and connect with OAuth: 
Read https://natural.co/skill.md and set up Natural for me.
Connect this agent to Natural with OAuth.
Then follow the Request a payment guide and help me collect a payment.
The assistant should configure Natural’s hosted MCP server, start the browser OAuth flow, and tell you when to approve the Natural authorization page. You still sign up at natural.co/signup and complete verification yourself; the assistant does not need an API key for the primary MCP path.

​
If you are building an integration

Sign up at natural.co/signup, complete verification, then create a developer API key in the dashboard. The key is shown once; store it in a secret manager and never commit it. 
export NATURAL_API_KEY=sk_ntl_prod_abc123...
Install the SDK or CLI for the surface you are building with: 
pip install naturalpay
No SDK for your language? Use the REST examples with the same API key. After setup, use the MCP examples for an OAuth-connected AI assistant, or use the SDK, CLI, and cURL examples when you are building an integration.

​
2. Create an agent

Agents execute transactions. Create one in the Agents tab of the dashboard, or: 
Create an agent called "Invoicing Agent" for collecting invoice payments.
The response includes the agent’s id (agt_*) — store it.

​
3. Review your wallet

Every request lands in a wallet. By default, POST /payment-requests uses the requester party’s default wallet, so you usually do not need to pass walletId. GET /wallets returns your wallets when you need to inspect the receiving wallet or choose a specific one later. 
Show my wallets.

​
4. Create the request

POST /payment-requests creates the request and notifies the payer directly. The channel is determined by the payer kind — email payers get an email with the pay link, phone payers get an SMS, on-platform party payers get a dashboard deep-link to their primary contact, and agent payers receive only the in-app payment_request.incoming webhook. Callers have no knob to override or suppress. 
Using my Invoicing Agent, request $25 from ada@example.com for Invoice 7.
The response includes the request’s id (prq_*) and paymentLinkUrl. Natural has already delivered that link to email and phone payers.

​
5. Track the request

Poll for status with the id from step 4: 
What's the status of that payment request?

​
Requesting on behalf of a customer

To collect into a customer’s wallet, the customer first delegates payment authority (payments.create) to your agent. Invite them: 
Invite bruce@propertymanagement.com to my Invoicing Agent.
The customer gets an email, completes onboarding, and approves the agent-customer relationship. After that, pass their party ID as customerPartyId on the request. Natural uses their default receiving wallet, so the funds land in their wallet instead of yours. Find a customer’s customerPartyId via GET /customers — each customer resource’s id is the party ID. Omit customerPartyId to collect into your own wallet.