OpenAPI Specification
openapi: 3.1.1
info:
title: Natural Agent Keys PaymentRequests API
version: 0.2.0
description: 'Natural''s payments API for autonomous agents.
**Base URL:** `https://api.natural.com`
AI agents, including coding agents, should prefer the hosted MCP server at `https://mcp.natural.com` when an MCP-aware host runs the agent, the Natural CLI for terminal/CI workflows, and the official SDKs for application runtimes they own. Use direct HTTP only for explicit low-level integrations, unsupported SDK gaps, or infrastructure work where REST is required.
For support: support@natural.com'
servers:
- url: https://api.natural.com
description: Production
tags:
- name: PaymentRequests
description: Payment request management
paths:
/payment-requests:
post:
operationId: paymentRequests.create
summary: Create payment request
description: Create a payment request
tags:
- PaymentRequests
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
customerPartyId:
type: string
pattern: ^pty_[0-9a-f]{32}$
description: Requester party ID (pty_*). Omit to request into your own wallet; provide for delegated payment requests on behalf of a customer.
walletId:
type: string
pattern: ^wal_[0-9a-f]{32}$
description: Wallet (wal_*) that should receive the funds. Omit to use the requester party's default wallet.
amount:
type: integer
exclusiveMinimum: 0
description: Amount in cents.
currency:
enum:
- USD
type: string
default: USD
description: Currency code (currently only USD).
description:
type: string
maxLength: 80
description: Free-form description shown to the payer. Maximum 80 characters.
payerName:
type: string
maxLength: 32
description: Display name of the payer. Maximum 32 characters.
payer:
anyOf:
- type: object
properties:
type:
type: string
enum:
- email
value:
type: string
maxLength: 254
format: email
description: Email address.
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
enum:
- phone
value:
type: string
maxLength: 16
description: Phone number.
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
enum:
- party_id
value:
type: string
pattern: ^pty_[0-9a-f]{32}$
description: Natural party ID (pty_*).
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
enum:
- agent_id
value:
type: string
pattern: ^agt_[0-9a-f]{32}$
description: Natural agent ID (agt_*).
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
enum:
- handle
value:
type: string
maxLength: 62
description: Natural handle (@handle or @handle-slug).
required:
- type
- value
additionalProperties: false
title: PaymentRequestPayer
description: 'Who pays: exactly one typed email, phone, party ID, agent ID, or handle value.'
required:
- amount
- payer
additionalProperties: false
required:
- attributes
additionalProperties: false
required:
- data
additionalProperties: false
title: PaymentRequestCreateRequest
examples:
default:
summary: Default
value:
data:
attributes:
amount: 2500
currency: USD
description: Invoice 7
payerName: Ada Lovelace
payer:
type: email
value: ada@example.com
responses:
'201':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- paymentRequest
id:
type: string
pattern: ^prq_[0-9a-f]{32}$
description: Payment request ID (prq_*).
attributes:
type: object
properties:
amount:
type: integer
description: Amount in cents.
currency:
type: string
description: Currency code.
status:
enum:
- OPEN
- PROCESSING
- COMPLETED
- FAILED
- RETURNED
- CANCELED
- DECLINED
- EXPIRED
type: string
description: Payment request status.
description:
anyOf:
- type: string
- type: 'null'
description: Free-form description provided at creation. Maximum 80 characters.
requesterName:
anyOf:
- type: string
- type: 'null'
description: Display name of the party requesting payment.
requesterEmail:
anyOf:
- type: string
- type: 'null'
description: Email of the party requesting payment.
requesterAvatarUrl:
anyOf:
- type: string
format: uri
- type: 'null'
description: Public avatar URL for the party requesting payment, if one is set.
requesterHandle:
anyOf:
- type: string
- type: 'null'
description: The requesting party's composed public handle (@namespace), or null when it has none.
walletName:
anyOf:
- type: string
- type: 'null'
description: Receiving wallet name, or null when unnamed or hidden from the caller.
payerName:
anyOf:
- type: string
- type: 'null'
description: Display name of the payer.
payerEmail:
anyOf:
- type: string
- type: 'null'
description: Email of the payer, or null when none is known.
payerAvatarUrl:
anyOf:
- type: string
format: uri
- type: 'null'
description: Public avatar URL for the payer party, if one is set.
payerHandle:
anyOf:
- type: string
- type: 'null'
description: The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less.
payerPhone:
anyOf:
- type: string
- type: 'null'
description: Payer phone number when addressed by phone.
payerPartyId:
anyOf:
- type: string
- type: 'null'
description: Natural party ID (pty_*) resolved for the payer, including agent owner parties.
payerIdentifierType:
enum:
- email
- phone
- party_id
- agent_id
- handle
type: string
description: Identifier type used to address the payer.
payerIdentifier:
type: string
description: Identifier value used to address the payer.
initiatorParty:
anyOf:
- type: object
properties:
id:
type: string
pattern: ^pty_[0-9a-f]{32}$
name:
type: string
handle:
anyOf:
- type: string
- type: 'null'
description: The initiating party's composed public handle (@namespace), or null when it has none.
required:
- id
- name
- handle
additionalProperties: false
- type: 'null'
description: The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party.
initiatorAgent:
anyOf:
- type: object
properties:
id:
type: string
pattern: ^agt_[0-9a-f]{32}$
name:
type: string
handle:
anyOf:
- type: string
- type: 'null'
description: The agent's composed public handle (@namespace-slug), or null when it has none.
required:
- id
- name
- handle
additionalProperties: false
- type: 'null'
description: Agent that created this payment request, when one did. Otherwise null.
paymentLinkUrl:
type: string
format: uri
description: URL the payer visits to complete payment.
transactionId:
anyOf:
- type: string
- type: 'null'
description: ID of the transaction created by the most recent payment attempt, or null if no attempt yet.
createdAt:
type: string
description: When the payment request was created.
updatedAt:
type: string
description: When the payment request was last updated.
required:
- amount
- currency
- status
- description
- requesterName
- requesterEmail
- requesterAvatarUrl
- requesterHandle
- walletName
- payerName
- payerEmail
- payerAvatarUrl
- payerHandle
- payerPhone
- payerPartyId
- payerIdentifierType
- payerIdentifier
- initiatorParty
- initiatorAgent
- paymentLinkUrl
- transactionId
- createdAt
- updatedAt
additionalProperties: false
title: PaymentRequestAttributes
relationships:
type: object
properties:
requesterParty:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- party
id:
type: string
pattern: ^pty_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
required:
- data
additionalProperties: false
title: ToOneRelationship
description: Party requesting the payment.
payerParty:
type: object
properties:
data:
anyOf:
- type: object
properties:
type:
type: string
enum:
- party
id:
type: string
pattern: ^pty_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
- type: 'null'
required:
- data
additionalProperties: false
title: NullableToOneRelationship
description: Resolved payer party, if the payer is known to Natural.
required:
- requesterParty
- payerParty
additionalProperties: false
title: PaymentRequestCreateRelationships
required:
- type
- id
- attributes
- relationships
additionalProperties: false
title: PaymentRequestCreateResource
required:
- data
additionalProperties: false
title: PaymentRequestCreateResponse
examples:
default:
summary: Default
value:
data:
type: paymentRequest
id: prq_550e8400e29b41d4a716446655440000
attributes:
amount: 2500
currency: USD
status: OPEN
description: Invoice 7
requesterName: null
requesterEmail: null
requesterAvatarUrl: null
requesterHandle: null
walletName: Main wallet
payerName: Ada Lovelace
payerEmail: ada@example.com
payerPhone: null
payerAvatarUrl: null
payerHandle: null
payerPartyId: null
payerIdentifierType: email
payerIdentifier: ada@example.com
initiatorParty: null
initiatorAgent: null
paymentLinkUrl: https://www.natural.com/pay/token_123
transactionId: null
createdAt: '2026-04-15T00:00:00.000Z'
updatedAt: '2026-04-15T00:00:00.000Z'
relationships:
requesterParty:
data:
type: party
id: pty_019cd1798d617f65a79cb965dda9eac3
payerParty:
data: null
headers:
X-RateLimit-Limit:
description: Maximum requests allowed per window.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp when rate limit resets.
schema:
type: integer
'400':
description: Validation Error
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: invalid_value
detail: The information you entered isn't valid. Please check it and try again.
status: '400'
meta:
supportId: req_a1b2c3d4e5f6
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: unauthenticated
detail: Authentication is required.
status: '401'
meta:
supportId: req_a1b2c3d4e5f6
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
# --- truncated at 32 KB (492 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/natural-ai/refs/heads/main/openapi/natural-ai-paymentrequests-api-openapi.yml