Skip to main content
Send money to an agent, email, phone number, or Natural party ID. For new parties, Natural creates a payment link, delivers the link by email or SMS, and onboards the new party.
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 Create a payment guide and help me send 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 "Carrier Payment Agent" for paying delivery carriers.
The response includes the agent’s id (agt_*), store it to associate your agent for future requests.

​
3. Connect a bank account and fund your wallet

Fund your wallet from a linked bank account so your agent can transact autonomously.

​
Connect a bank account

Link a bank account from the Wallet tab of your dashboard — Natural connects it securely through Plaid. Once linked, list your external accounts to get the eac_* ID to deposit from: 
List my linked bank accounts.
Each linked account has an id (eac_*) — you’ll pass it to the deposit call below.

​
Fund your wallet

Pull funds from the linked account into your wallet: 
Deposit $50,000 into my wallet from my linked bank account.
Confirm the funds landed before paying. Each wallet’s balance.available is the spendable balance after pending holds: 
What's my wallet's available balance?

​
4. Send the payment

Using my Carrier Payment Agent, pay terri@contractor.com $5,000 for Q4 development work.
The response includes the payment’s id (pay_*) and an initial status.

​
5. Track the payment

Check the payment’s status with the id from step 4: 
Check the status of that payment.
Statuses move CREATED → PROCESSING → COMPLETED. A payment can also sit at PENDING_CLAIM (awaiting the recipient) or IN_REVIEW (compliance hold), or end at FAILED, CANCELED, or APPROVAL_DENIED. List and filter with GET /transactions, or subscribe to webhooks instead of polling.

​
Paying on behalf of a customer

To pay from a customer’s wallet, the customer first delegates payment authority to your agent. Invite them: 
Invite bruce@propertymanagement.com to my Carrier Payment Agent.
The customer gets an email, completes onboarding, and approves the agent-customer relationship. After that, add their party ID as customerPartyId when sending — the payment then draws from their wallet instead of yours. Find a customer’s customerPartyId via GET /customers — each customer resource’s id is the party ID.