openapi: 3.2.0 info: title: Natural Payment Requests 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: Payment Requests description: Payment request management paths: /payment-requests: post: operationId: paymentRequests.create summary: Create payment request description: Create a payment request tags: - Payment Requests 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: 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: forbidden detail: You do not have permission to perform this action. status: '403' meta: supportId: req_a1b2c3d4e5f6 '404': description: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. 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: not_found detail: The requested resource was not found. status: '404' meta: supportId: req_a1b2c3d4e5f6 '409': description: Conflict 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: conflict detail: The request conflicts with the current resource state. status: '409' meta: supportId: req_a1b2c3d4e5f6 '422': 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: '422' source: pointer: /data/attributes/email meta: supportId: req_a1b2c3d4e5f6 '428': description: Precondition Required 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: mfa_required detail: MFA verification required status: '428' meta: supportId: req_a1b2c3d4e5f6 '429': description: Too Many Requests 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: rate_limited detail: Too many requests. Please try again later. status: '429' meta: supportId: req_a1b2c3d4e5f6 headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer 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 '500': description: Internal Server 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: server_error detail: Something went wrong. status: '500' meta: supportId: req_a1b2c3d4e5f6 '501': description: Not Implemented 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: not_implemented detail: This operation is not available. status: '501' meta: supportId: req_a1b2c3d4e5f6 '502': description: Bad Gateway 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: bad_gateway detail: We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. status: '502' meta: supportId: req_a1b2c3d4e5f6 '503': description: Service Unavailable 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: service_unavailable detail: The service is temporarily unavailable. status: '503' meta: supportId: req_a1b2c3d4e5f6 security: - HTTPBearer: [] parameters: - name: Idempotency-Key in: header required: true schema: type: string maxLength: 255 description: Unique key for safely retrying a request without creating duplicates. - name: X-Agent-ID in: header required: false schema: anyOf: - type: string maxLength: 36 pattern: ^agt_[0-9a-f]{32}$ - type: 'null' description: Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity. - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money. get: operationId: paymentRequests.list summary: List payment requests description: List outgoing payment requests tags: - Payment Requests parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Maximum results per page. allowEmptyValue: true allowReserved: true - name: cursor in: query schema: type: string maxLength: 1024 description: Cursor from the previous page. allowEmptyValue: true allowReserved: true - name: partyId in: query schema: type: string pattern: ^pty_[0-9a-f]{32}$ description: Effective party ID (pty_*) for delegated payment request access. allowEmptyValue: true allowReserved: true - name: includeCompleted in: query schema: anyOf: - type: boolean - type: string default: true description: Whether to include completed payment requests. allowEmptyValue: true allowReserved: true - name: includeCanceled in: query schema: anyOf: - type: boolean - type: string default: false description: Whether to include canceled payment requests. allowEmptyValue: true allowReserved: true - name: X-Agent-ID in: header required: false schema: anyOf: - type: string maxLength: 36 pattern: ^agt_[0-9a-f]{32}$ - type: 'null' description: Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity. - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money. responses: '200': description: Successful Response content: application/json: schema: type: object properties: data: type: array items: 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. wallet: type: object properties: data: type: object properties: type: type: string enum: - wallet id: type: string pattern: ^wal_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: Wallet that receives the funds. 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. payerAgent: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - agent id: type: string pattern: ^agt_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payer agent, or null unless addressed by agent ID or agent handle. payment: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - payment id: type: string pattern: ^pay_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payment submitted for this payment request, if one exists. required: - requesterParty - wallet - payerParty - payerAgent - payment additionalProperties: false title: PaymentRequestRelationships required: - type - id - attributes - relationships additionalProperties: false title: PaymentRequestResource meta: type: object properties: pagination: type: object properties: hasMore: type: boolean description: Whether more results are available. nextCursor: anyOf: - type: string - type: 'null' description: Cursor for the next page, or null when there are no more results. required: - hasMore - nextCursor additionalProperties: false title: PaginationMeta required: - pagination additionalProperties: false required: - data - meta additionalProperties: false title: PaymentRequestListResponse examples: default: summary: Default value: data: - type: paymentRequest id: prq_550e8400e29b41d4a716446655440000 attributes: amount: 2500 currency: USD status: OPEN description: Invoice 7 requesterName: Acme Payments requesterEmail: billing@acmepayments.com requesterAvatarUrl: https://static.natural.com/avatars/acme-payments.png requesterHandle: '@acme-payments' 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: id: pty_019cd1798d617f65a79cb965dda9eac3 name: Acme Payments handle: '@acme-payments' initiatorAgent: id: agt_019cd1798d627ad9bc302511c4f2c115 name: Billing Bot handle: '@acme-billing' 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 wallet: data: type: wallet id: wal_550e8400e29b41d4a716446655440000 payerParty: data: null payerAgent: data: null payment: data: null meta: pagination: hasMore: false nextCursor: 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: 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: forbidden detail: You do not have permission to perform this action. status: '403' meta: supportId: req_a1b2c3d4e5f6 '404': description: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. 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: not_found detail: The requested resource was not found. status: '404' meta: supportId: req_a1b2c3d4e5f6 '409': description: Conflict 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: conflict detail: The request conflicts with the current resource state. status: '409' meta: supportId: req_a1b2c3d4e5f6 '422': 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: '422' source: pointer: /data/attributes/email meta: supportId: req_a1b2c3d4e5f6 '428': description: Precondition Required 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: mfa_required detail: MFA verification required status: '428' meta: supportId: req_a1b2c3d4e5f6 '429': description: Too Many Requests 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: rate_limited detail: Too many requests. Please try again later. status: '429' meta: supportId: req_a1b2c3d4e5f6 headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer 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 '500': description: Internal Server 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: server_error detail: Something went wrong. status: '500' meta: supportId: req_a1b2c3d4e5f6 '501': description: Not Implemented 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: not_implemented detail: This operation is not available. status: '501' meta: supportId: req_a1b2c3d4e5f6 '502': description: Bad Gateway 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: bad_gateway detail: We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. status: '502' meta: supportId: req_a1b2c3d4e5f6 '503': description: Service Unavailable 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: service_unavailable detail: The service is temporarily unavailable. status: '503' meta: supportId: req_a1b2c3d4e5f6 security: - HTTPBearer: [] /payment-requests/incoming: get: operationId: paymentRequests.listIncoming summary: List incoming payment requests tags: - Payment Requests parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Maximum results per page. allowEmptyValue: true allowReserved: true - name: cursor in: query schema: type: string maxLength: 1024 description: Cursor from the previous page. allowEmptyValue: true allowReserved: true - name: partyId in: query schema: type: string pattern: ^pty_[0-9a-f]{32}$ description: Effective party ID (pty_*) for delegated payment request access. allowEmptyValue: true allowReserved: true - name: X-Agent-ID in: header required: false schema: anyOf: - type: string maxLength: 36 pattern: ^agt_[0-9a-f]{32}$ - type: 'null' description: Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity. - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money. responses: '200': description: Successful Response content: application/json: schema: type: object properties: data: type: array items: 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. wallet: type: object properties: data: type: object properties: type: type: string enum: - wallet id: type: string pattern: ^wal_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: Wallet that receives the funds. 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. payerAgent: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - agent id: type: string pattern: ^agt_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payer agent, or null unless addressed by agent ID or agent handle. payment: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - payment id: type: string pattern: ^pay_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payment submitted for this payment request, if one exists. required: - requesterParty - wallet - payerParty - payerAgent - payment additionalProperties: false title: PaymentRequestRelationships required: - type - id - attributes - relationships additionalProperties: false title: PaymentRequestResource meta: type: object properties: pagination: type: object properties: hasMore: type: boolean description: Whether more results are available. nextCursor: anyOf: - type: string - type: 'null' description: Cursor for the next page, or null when there are no more results. required: - hasMore - nextCursor additionalProperties: false title: PaginationMeta required: - pagination additionalProperties: false required: - data - meta additionalProperties: false title: PaymentRequestListResponse examples: default: summary: Default value: data: - type: paymentRequest id: prq_550e8400e29b41d4a716446655440000 attributes: amount: 500 currency: USD status: OPEN requesterName: Natural Coffee requesterEmail: billing@natural.test requesterAvatarUrl: https://static.natural.com/avatars/natural-coffee.png requesterHandle: '@natural-coffee' walletName: null description: Invoice 7 payerName: Ada Lovelace payerEmail: ada@example.com payerPhone: '+14155550100' payerAvatarUrl: https://static.natural.com/avatars/ada-lovelace.png payerHandle: '@ada-lovelace' payerPartyId: pty_550e8400e29b41d4a716446655440000 payerIdentifierType: party_id payerIdentifier: pty_550e8400e29b41d4a716446655440000 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 wallet: data: type: wallet id: wal_550e8400e29b41d4a716446655440000 payerParty: data: type: party id: pty_550e8400e29b41d4a716446655440000 payerAgent: data: null payment: data: null meta: pagination: hasMore: false nextCursor: 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: 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: forbidden detail: You do not have permission to perform this action. status: '403' meta: supportId: req_a1b2c3d4e5f6 '404': description: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. 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: not_found detail: The requested resource was not found. status: '404' meta: supportId: req_a1b2c3d4e5f6 '409': description: Conflict 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: conflict detail: The request conflicts with the current resource state. status: '409' meta: supportId: req_a1b2c3d4e5f6 '422': 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: '422' source: pointer: /data/attributes/email meta: supportId: req_a1b2c3d4e5f6 '428': description: Precondition Required 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: mfa_required detail: MFA verification required status: '428' meta: supportId: req_a1b2c3d4e5f6 '429': description: Too Many Requests 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: rate_limited detail: Too many requests. Please try again later. status: '429' meta: supportId: req_a1b2c3d4e5f6 headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer 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 '500': description: Internal Server 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: server_error detail: Something went wrong. status: '500' meta: supportId: req_a1b2c3d4e5f6 '501': description: Not Implemented 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: not_implemented detail: This operation is not available. status: '501' meta: supportId: req_a1b2c3d4e5f6 '502': description: Bad Gateway 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: bad_gateway detail: We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. status: '502' meta: supportId: req_a1b2c3d4e5f6 '503': description: Service Unavailable 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: service_unavailable detail: The service is temporarily unavailable. status: '503' meta: supportId: req_a1b2c3d4e5f6 security: - HTTPBearer: [] /payment-requests/{paymentRequestId}: get: operationId: paymentRequests.get summary: Get payment request description: Get a payment request tags: - Payment Requests parameters: - name: paymentRequestId in: path required: true schema: type: string pattern: ^prq_[0-9a-f]{32}$ description: Payment request ID (prq_*). - name: partyId in: query required: false schema: type: string pattern: ^pty_[0-9a-f]{32}$ description: Effective party ID (pty_*) for delegated payment request access. allowEmptyValue: true allowReserved: true - name: X-Agent-ID in: header required: false schema: anyOf: - type: string maxLength: 36 pattern: ^agt_[0-9a-f]{32}$ - type: 'null' description: Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity. - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money. responses: '200': 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. wallet: type: object properties: data: type: object properties: type: type: string enum: - wallet id: type: string pattern: ^wal_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: Wallet that receives the funds. 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. payerAgent: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - agent id: type: string pattern: ^agt_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payer agent, or null unless addressed by agent ID or agent handle. payment: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - payment id: type: string pattern: ^pay_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payment submitted for this payment request, if one exists. required: - requesterParty - wallet - payerParty - payerAgent - payment additionalProperties: false title: PaymentRequestRelationships required: - type - id - attributes - relationships additionalProperties: false title: PaymentRequestResource required: - data additionalProperties: false title: PaymentRequestResponse examples: default: summary: Default value: data: type: paymentRequest id: prq_550e8400e29b41d4a716446655440000 attributes: amount: 2500 currency: USD status: OPEN description: Invoice 7 requesterName: Acme Payments requesterEmail: billing@acmepayments.com requesterAvatarUrl: https://static.natural.com/avatars/acme-payments.png requesterHandle: '@acme-payments' 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: id: pty_019cd1798d617f65a79cb965dda9eac3 name: Acme Payments handle: '@acme-payments' initiatorAgent: id: agt_019cd1798d627ad9bc302511c4f2c115 name: Billing Bot handle: '@acme-billing' 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 wallet: data: type: wallet id: wal_550e8400e29b41d4a716446655440000 payerParty: data: null payerAgent: data: null payment: 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: 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: forbidden detail: You do not have permission to perform this action. status: '403' meta: supportId: req_a1b2c3d4e5f6 '404': description: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. 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: not_found detail: The requested resource was not found. status: '404' meta: supportId: req_a1b2c3d4e5f6 '409': description: Conflict 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: conflict detail: The request conflicts with the current resource state. status: '409' meta: supportId: req_a1b2c3d4e5f6 '422': 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: '422' source: pointer: /data/attributes/email meta: supportId: req_a1b2c3d4e5f6 '428': description: Precondition Required 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: mfa_required detail: MFA verification required status: '428' meta: supportId: req_a1b2c3d4e5f6 '429': description: Too Many Requests 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: rate_limited detail: Too many requests. Please try again later. status: '429' meta: supportId: req_a1b2c3d4e5f6 headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer 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 '500': description: Internal Server 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: server_error detail: Something went wrong. status: '500' meta: supportId: req_a1b2c3d4e5f6 '501': description: Not Implemented 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: not_implemented detail: This operation is not available. status: '501' meta: supportId: req_a1b2c3d4e5f6 '502': description: Bad Gateway 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: bad_gateway detail: We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. status: '502' meta: supportId: req_a1b2c3d4e5f6 '503': description: Service Unavailable 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: service_unavailable detail: The service is temporarily unavailable. status: '503' meta: supportId: req_a1b2c3d4e5f6 security: - HTTPBearer: [] /payment-requests/{paymentRequestId}/fulfill: post: operationId: paymentRequests.fulfill summary: Fulfill payment request description: Fulfill an open payment request from a wallet or a verified linked bank account tags: - Payment Requests parameters: - name: paymentRequestId in: path required: true schema: type: string pattern: ^prq_[0-9a-f]{32}$ description: Payment request ID (prq_*). - name: Idempotency-Key in: header required: true schema: type: string maxLength: 255 description: Unique key for safely retrying a request without creating duplicates. - name: X-Agent-ID in: header required: false schema: anyOf: - type: string maxLength: 36 pattern: ^agt_[0-9a-f]{32}$ - type: 'null' description: Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity. - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money. requestBody: required: true content: application/json: schema: type: object properties: partyId: type: string pattern: ^pty_[0-9a-f]{32}$ description: Effective payer party ID (pty_*) for delegated payment request fulfillment. data: type: object properties: attributes: type: object properties: paymentSource: anyOf: - type: object properties: type: type: string enum: - wallet walletId: type: string pattern: ^wal_[0-9a-f]{32}$ description: Wallet used to pay. required: - type - walletId additionalProperties: false - type: object properties: type: type: string enum: - external_account externalAccountId: type: string pattern: ^eac_[0-9a-f]{32}$ description: Verified linked bank account used to pay. required: - type - externalAccountId additionalProperties: false description: Source of funds for the payment. required: - paymentSource additionalProperties: false required: - attributes additionalProperties: false required: - data additionalProperties: false examples: default: summary: Default value: data: attributes: paymentSource: type: wallet walletId: wal_550e8400e29b41d4a716446655440000 responses: '200': description: Successful Response content: application/json: schema: type: object properties: data: type: object properties: type: type: string enum: - payment id: type: string pattern: ^pay_[0-9a-f]{32}$ attributes: type: object properties: amount: type: integer description: Amount in cents. currency: type: string description: Currency code. status: enum: - CREATED - PROCESSING - PENDING_CLAIM - IN_REVIEW - COMPLETED - FAILED - RETURNED - APPROVAL_DENIED - CANCELED type: string description: Payment status. description: anyOf: - type: string - type: 'null' description: Payment description. createdAt: type: string description: When this payment was created. updatedAt: anyOf: - type: string - type: 'null' description: When this payment was last updated. required: - amount - currency - status - description - createdAt - updatedAt additionalProperties: false title: PaymentAttributes relationships: type: object properties: sender: 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: Party that initiated the payment, when the sender is on Natural. senderAgent: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - agent id: type: string pattern: ^agt_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Sending agent, or null when the payment was not sent by an agent. recipient: 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: Recipient party for this payment, when known. recipientAgent: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - agent id: type: string pattern: ^agt_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Recipient agent, or null unless addressed by agent ID or agent handle. transaction: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - transaction id: type: string required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Sender-side transaction for this payment, when available. paymentRequest: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - paymentRequest id: type: string pattern: ^prq_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payment request that produced this payment, when applicable. required: - sender - senderAgent - recipient - recipientAgent - transaction - paymentRequest additionalProperties: false title: PaymentRelationships required: - type - id - attributes - relationships additionalProperties: false title: PaymentResource required: - data additionalProperties: false examples: default: summary: Default value: data: type: payment id: pay_550e8400e29b41d4a716446655440000 attributes: amount: 2500 currency: USD status: PROCESSING description: Invoice 7 createdAt: '2026-04-15T00:00:00.000Z' updatedAt: '2026-04-15T00:00:00.000Z' relationships: sender: data: type: party id: pty_550e8400e29b41d4a716446655440000 senderAgent: data: null recipient: data: type: party id: pty_019cd1798d617f65a79cb965dda9eac3 recipientAgent: data: null transaction: data: null paymentRequest: data: type: paymentRequest id: prq_550e8400e29b41d4a716446655440000 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: 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: forbidden detail: You do not have permission to perform this action. status: '403' meta: supportId: req_a1b2c3d4e5f6 '404': description: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. 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: not_found detail: The requested resource was not found. status: '404' meta: supportId: req_a1b2c3d4e5f6 '409': description: Conflict 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: conflict detail: The request conflicts with the current resource state. status: '409' meta: supportId: req_a1b2c3d4e5f6 '422': 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: '422' source: pointer: /data/attributes/email meta: supportId: req_a1b2c3d4e5f6 '428': description: Precondition Required 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: mfa_required detail: MFA verification required status: '428' meta: supportId: req_a1b2c3d4e5f6 '429': description: Too Many Requests 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: rate_limited detail: Too many requests. Please try again later. status: '429' meta: supportId: req_a1b2c3d4e5f6 headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer 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 '500': description: Internal Server 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: server_error detail: Something went wrong. status: '500' meta: supportId: req_a1b2c3d4e5f6 '501': description: Not Implemented 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: not_implemented detail: This operation is not available. status: '501' meta: supportId: req_a1b2c3d4e5f6 '502': description: Bad Gateway 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: bad_gateway detail: We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. status: '502' meta: supportId: req_a1b2c3d4e5f6 '503': description: Service Unavailable 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: service_unavailable detail: The service is temporarily unavailable. status: '503' meta: supportId: req_a1b2c3d4e5f6 security: - HTTPBearer: [] /payment-requests/{paymentRequestId}/decline: post: operationId: paymentRequests.decline summary: Decline payment request description: Decline an open incoming payment request tags: - Payment Requests parameters: - name: paymentRequestId in: path required: true schema: type: string pattern: ^prq_[0-9a-f]{32}$ description: Payment request ID (prq_*). - name: Idempotency-Key in: header required: true schema: type: string maxLength: 255 description: Unique key for safely retrying a request without creating duplicates. - name: X-Agent-ID in: header required: false schema: anyOf: - type: string maxLength: 36 pattern: ^agt_[0-9a-f]{32}$ - type: 'null' description: Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity. - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money. responses: '200': 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. wallet: type: object properties: data: type: object properties: type: type: string enum: - wallet id: type: string pattern: ^wal_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: Wallet that receives the funds. 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. payerAgent: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - agent id: type: string pattern: ^agt_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payer agent, or null unless addressed by agent ID or agent handle. payment: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - payment id: type: string pattern: ^pay_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payment submitted for this payment request, if one exists. required: - requesterParty - wallet - payerParty - payerAgent - payment additionalProperties: false title: PaymentRequestRelationships required: - type - id - attributes - relationships additionalProperties: false title: PaymentRequestResource required: - data additionalProperties: false title: PaymentRequestResponse examples: default: summary: Default value: data: type: paymentRequest id: prq_550e8400e29b41d4a716446655440000 attributes: amount: 500 currency: USD status: DECLINED requesterName: Natural Coffee requesterEmail: billing@natural.test requesterAvatarUrl: https://static.natural.com/avatars/natural-coffee.png requesterHandle: '@natural-coffee' walletName: null description: Invoice 7 payerName: Ada Lovelace payerEmail: ada@example.com payerPhone: '+14155550100' payerAvatarUrl: https://static.natural.com/avatars/ada-lovelace.png payerHandle: '@ada-lovelace' payerPartyId: pty_550e8400e29b41d4a716446655440000 payerIdentifierType: party_id payerIdentifier: pty_550e8400e29b41d4a716446655440000 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 wallet: data: type: wallet id: wal_550e8400e29b41d4a716446655440000 payerParty: data: type: party id: pty_550e8400e29b41d4a716446655440000 payerAgent: data: null payment: 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: 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: forbidden detail: You do not have permission to perform this action. status: '403' meta: supportId: req_a1b2c3d4e5f6 '404': description: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. 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: not_found detail: The requested resource was not found. status: '404' meta: supportId: req_a1b2c3d4e5f6 '409': description: Conflict 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: conflict detail: The request conflicts with the current resource state. status: '409' meta: supportId: req_a1b2c3d4e5f6 '422': 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: '422' source: pointer: /data/attributes/email meta: supportId: req_a1b2c3d4e5f6 '428': description: Precondition Required 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: mfa_required detail: MFA verification required status: '428' meta: supportId: req_a1b2c3d4e5f6 '429': description: Too Many Requests 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: rate_limited detail: Too many requests. Please try again later. status: '429' meta: supportId: req_a1b2c3d4e5f6 headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer 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 '500': description: Internal Server 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: server_error detail: Something went wrong. status: '500' meta: supportId: req_a1b2c3d4e5f6 '501': description: Not Implemented 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: not_implemented detail: This operation is not available. status: '501' meta: supportId: req_a1b2c3d4e5f6 '502': description: Bad Gateway 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: bad_gateway detail: We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. status: '502' meta: supportId: req_a1b2c3d4e5f6 '503': description: Service Unavailable 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: service_unavailable detail: The service is temporarily unavailable. status: '503' meta: supportId: req_a1b2c3d4e5f6 security: - HTTPBearer: [] /payment-requests/{paymentRequestId}/cancel: post: operationId: paymentRequests.cancel summary: Cancel payment request description: Cancel an open outgoing payment request tags: - Payment Requests parameters: - name: paymentRequestId in: path required: true schema: type: string pattern: ^prq_[0-9a-f]{32}$ description: Payment request ID (prq_*). - name: Idempotency-Key in: header required: true schema: type: string maxLength: 255 description: Unique key for safely retrying a request without creating duplicates. - name: X-Agent-ID in: header required: false schema: anyOf: - type: string maxLength: 36 pattern: ^agt_[0-9a-f]{32}$ - type: 'null' description: Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity. - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money. responses: '200': 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. wallet: type: object properties: data: type: object properties: type: type: string enum: - wallet id: type: string pattern: ^wal_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: Wallet that receives the funds. 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. payerAgent: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - agent id: type: string pattern: ^agt_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payer agent, or null unless addressed by agent ID or agent handle. payment: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - payment id: type: string pattern: ^pay_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Payment submitted for this payment request, if one exists. required: - requesterParty - wallet - payerParty - payerAgent - payment additionalProperties: false title: PaymentRequestRelationships required: - type - id - attributes - relationships additionalProperties: false title: PaymentRequestResource required: - data additionalProperties: false title: PaymentRequestResponse examples: default: summary: Default value: data: type: paymentRequest id: prq_550e8400e29b41d4a716446655440000 attributes: amount: 500 currency: USD status: CANCELED requesterName: Natural Coffee requesterEmail: billing@natural.test requesterAvatarUrl: https://static.natural.com/avatars/natural-coffee.png requesterHandle: '@natural-coffee' walletName: Main wallet description: Invoice 7 payerName: Ada Lovelace payerEmail: ada@example.com payerPhone: '+14155550100' payerAvatarUrl: https://static.natural.com/avatars/ada-lovelace.png payerHandle: '@ada-lovelace' payerPartyId: pty_550e8400e29b41d4a716446655440000 payerIdentifierType: party_id payerIdentifier: pty_550e8400e29b41d4a716446655440000 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 wallet: data: type: wallet id: wal_550e8400e29b41d4a716446655440000 payerParty: data: type: party id: pty_550e8400e29b41d4a716446655440000 payerAgent: data: null payment: 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: 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: forbidden detail: You do not have permission to perform this action. status: '403' meta: supportId: req_a1b2c3d4e5f6 '404': description: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. 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: not_found detail: The requested resource was not found. status: '404' meta: supportId: req_a1b2c3d4e5f6 '409': description: Conflict 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: conflict detail: The request conflicts with the current resource state. status: '409' meta: supportId: req_a1b2c3d4e5f6 '422': 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: '422' source: pointer: /data/attributes/email meta: supportId: req_a1b2c3d4e5f6 '428': description: Precondition Required 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: mfa_required detail: MFA verification required status: '428' meta: supportId: req_a1b2c3d4e5f6 '429': description: Too Many Requests 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: rate_limited detail: Too many requests. Please try again later. status: '429' meta: supportId: req_a1b2c3d4e5f6 headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer 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 '500': description: Internal Server 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: server_error detail: Something went wrong. status: '500' meta: supportId: req_a1b2c3d4e5f6 '501': description: Not Implemented 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: not_implemented detail: This operation is not available. status: '501' meta: supportId: req_a1b2c3d4e5f6 '502': description: Bad Gateway 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: bad_gateway detail: We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. status: '502' meta: supportId: req_a1b2c3d4e5f6 '503': description: Service Unavailable 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: service_unavailable detail: The service is temporarily unavailable. status: '503' meta: supportId: req_a1b2c3d4e5f6 security: - HTTPBearer: [] components: securitySchemes: HTTPBearer: type: http scheme: bearer description: 'Bearer authentication: send your API key, agent key, or OAuth access token as `Authorization: Bearer `.'