> ## Documentation Index > Fetch the complete documentation index at: https://docs.natural.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python. > When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`. > When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`. > Use the Natural CLI for terminal and CI automation. > Use REST only for unsupported languages or when the user explicitly requests raw HTTP. > Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it. > For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer. > REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code. # Create payment intent > Create a payment intent. The hosted checkout link is returned only once, or not at all when collect charges a card agreement. ## OpenAPI ````yaml /api-reference/openapi-early-access.json post /payment-intents openapi: 3.1.1 info: title: Natural API (early access) version: 0.2.0 description: |- Early-access endpoints of Natural's payments API. **Base URL:** `https://api.natural.com` For access: hi@natural.com servers: - url: https://api.natural.com description: Production security: [] tags: - name: Payment Intents description: Accept card payments by link or over voice - name: Voice description: Collect a payment intent over a phone call - name: Refunds description: Return card payments to the payer paths: /payment-intents: post: tags: - Payment Intents summary: Create payment intent description: >- Create a payment intent. The hosted checkout link is returned only once, or not at all when collect charges a card agreement. operationId: paymentIntents.create parameters: - 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: data: type: object properties: attributes: type: object properties: customerPartyId: type: string pattern: ^pty_[0-9a-f]{32}$ description: >- Customer party to create the intent for (pty_*), when acting under a delegation. Absent = act as own party. cardMandate: type: object properties: frequency: type: string enum: - unscheduled amountType: enum: - fixed - variable type: string amountMinor: type: integer exclusiveMinimum: 0 description: type: string minLength: 1 maxLength: 200 required: - frequency - amountType - amountMinor - description additionalProperties: false collect: type: object properties: mandateId: type: string pattern: ^mdt_[0-9a-f]{32}$ required: - mandateId additionalProperties: false amountMinor: type: integer minimum: 1 description: Amount in cents. currency: description: Currency code. USD only. type: string enum: - USD description: type: string minLength: 1 maxLength: 80 description: What the payment is for. expiresAt: type: string maxLength: 64 description: >- RFC 3339 timestamp after which the intent can no longer be paid. taxMode: enum: - exclusive - inclusive type: string default: exclusive description: How tax relates to line totals. taxAmountMinor: type: integer minimum: 0 default: 0 description: Tax in cents. lineItems: type: array maxItems: 100 items: type: object properties: merchantReference: type: string minLength: 1 maxLength: 255 description: >- Your own reference for the line, such as a SKU. description: type: string minLength: 1 maxLength: 255 description: What this line sells. quantity: type: integer minimum: 1 maximum: 1000000 description: Unit count. unitAmountMinor: type: integer minimum: 0 maximum: 1000000000000 description: Per-unit amount in cents. subtotalMinor: type: integer minimum: 0 maximum: 1000000000000 description: Must equal quantity × unit amount. taxMinor: type: integer minimum: 0 maximum: 1000000000000 description: Line tax in cents. totalMinor: type: integer minimum: 0 maximum: 1000000000000 description: Line total in cents. taxCode: type: string minLength: 1 maxLength: 50 description: Merchant tax code for this line. required: - description - quantity - unitAmountMinor - subtotalMinor - taxMinor - totalMinor additionalProperties: false title: CreatePaymentIntentLineItem default: [] description: >- Sale lines in display order. Optional; immutable once created. required: - amountMinor - currency additionalProperties: false title: CreatePaymentIntentAttributes required: - attributes additionalProperties: false required: - data additionalProperties: false title: CreatePaymentIntentRequest examples: default: summary: Default value: data: attributes: amountMinor: 4620 currency: USD description: Order 8842 taxMode: exclusive taxAmountMinor: 420 lineItems: - merchantReference: menu_item_31 description: Margherita pizza quantity: 2 unitAmountMinor: 1800 subtotalMinor: 3600 taxMinor: 320 totalMinor: 3920 taxCode: prepared_food - merchantReference: menu_item_77 description: Sparkling water quantity: 1 unitAmountMinor: 600 subtotalMinor: 600 taxMinor: 100 totalMinor: 700 taxCode: beverage responses: '201': description: Successful Response content: application/json: schema: type: object properties: data: type: object properties: id: type: string pattern: ^pmi_[0-9a-f]{32}$ type: description: Resource type. type: string enum: - paymentIntent attributes: type: object properties: mandateSetup: anyOf: - type: object properties: status: enum: - active - pending - failed type: string mandateId: anyOf: - type: string pattern: ^mdt_[0-9a-f]{32}$ - type: 'null' required: - status - mandateId additionalProperties: false - type: 'null' amountMinor: type: integer description: Amount in cents. currency: type: string description: Currency code. description: anyOf: - type: string - type: 'null' description: What the payment is for. status: enum: - open - processing - completed - canceled - declined - expired type: string description: Payment intent status. paymentId: anyOf: - type: string pattern: ^cpy_[0-9a-f]{32}$ - type: 'null' description: The active or successful card payment (cpy_*). taxMode: enum: - exclusive - inclusive type: string description: How tax relates to line totals. taxAmountMinor: type: integer description: Tax in cents. lineItems: type: array items: type: object properties: id: type: string pattern: ^pli_[0-9a-f]{32}$ description: >- Line item ID (pli_*). Stable; rows are immutable. position: type: integer description: Zero-based display order. merchantReference: anyOf: - type: string - type: 'null' description: >- Your own reference for the line, such as a SKU. description: type: string description: What this line sells. quantity: type: integer description: Unit count. unitAmountMinor: type: integer description: Per-unit amount in cents. subtotalMinor: type: integer description: quantity × unit amount, in cents. taxMinor: type: integer description: Line tax in cents. totalMinor: type: integer description: Line total in cents. taxCode: anyOf: - type: string - type: 'null' description: Merchant tax code for this line. required: - id - position - merchantReference - description - quantity - unitAmountMinor - subtotalMinor - taxMinor - totalMinor - taxCode additionalProperties: false title: PaymentIntentLineItem description: Immutable sale lines, in position order. expiresAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp after which the intent can no longer be paid. canceledAt: anyOf: - type: string - type: 'null' description: When the intent was canceled. createdAt: type: string description: ISO creation timestamp. updatedAt: type: string description: ISO update timestamp. cardPayment: anyOf: - type: object properties: id: type: string pattern: ^cpy_[0-9a-f]{32}$ description: Card payment ID (cpy_*). mandateId: type: string pattern: ^mdt_[0-9a-f]{32}$ status: enum: - processing - reconciling - succeeded - failed type: string description: Card payment status. failureReason: anyOf: - enum: - declined - processor_error - mm_refused type: string - type: 'null' description: >- Why the payment failed: the issuer declined it, the processor errored, or Natural refused it before it reached the processor (mm_refused). declineCode: anyOf: - enum: - generic_decline - insufficient_funds - limit_exceeded - issuer_unavailable - processor_error - card_expired - incorrect_card_number - incorrect_cvc - incorrect_address - authentication_required - card_not_supported - card_inactive_or_closed - stop_payment - card_lost_stolen - suspected_fraud - duplicate_transaction type: string - type: 'null' description: >- Normalized decline reason when status is failed. declineAdvice: anyOf: - enum: - do_not_retry - try_again_later - confirm_card_data type: string - type: 'null' description: >- Recommended payer action when status is failed. networkDeclineCode: anyOf: - type: string pattern: ^[\s\S]{0,10}$ - type: 'null' description: >- Raw card-network response code when available. merchantAdviceCode: anyOf: - type: string pattern: ^[\s\S]{0,10}$ - type: 'null' description: Raw merchant advice code when available. amountMinor: type: integer description: Amount in cents. currency: type: string description: Currency code. externalAccountId: anyOf: - type: string pattern: ^eac_[0-9a-f]{32}$ - type: 'null' description: >- Stored card credential that paid, when tender was external_account. cardBrand: anyOf: - type: string - type: 'null' description: Card brand from the processor response. cardLast4: anyOf: - type: string - type: 'null' description: Card last four digits. channel: enum: - link - api - voice type: string description: >- How the card was collected: the hosted checkout link, a voice call, or a direct API submission. acceptanceId: anyOf: - type: string pattern: ^acp_[0-9a-f]{32}$ - type: 'null' description: >- The payer's recorded consent for this payment. dispatchedAt: anyOf: - type: string - type: 'null' description: >- When the payment was sent to the card processor. refundedAmountMinor: type: integer description: >- Cents returned to the card by succeeded refunds. refundableAmountMinor: type: integer description: >- Cents still refundable, net of pending and succeeded refunds. refunded: type: boolean description: >- True once nothing refundable remains and something was refunded. createdAt: type: string description: ISO creation timestamp. updatedAt: type: string description: ISO update timestamp. required: - id - status - failureReason - declineCode - declineAdvice - networkDeclineCode - merchantAdviceCode - amountMinor - currency - externalAccountId - cardBrand - cardLast4 - channel - acceptanceId - dispatchedAt - refundedAmountMinor - refundableAmountMinor - refunded - createdAt - updatedAt additionalProperties: false title: PaymentIntentCardPayment - type: 'null' description: Most recent card payment for this intent. required: - mandateSetup - amountMinor - currency - description - status - paymentId - taxMode - taxAmountMinor - lineItems - expiresAt - canceledAt - createdAt - updatedAt - cardPayment additionalProperties: false title: PaymentIntentAttributes relationships: type: object properties: customerParty: 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: The party being paid. voiceSession: type: object properties: data: anyOf: - type: object properties: type: type: string enum: - voiceSession id: type: string pattern: ^vos_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: >- Latest voice session collecting this intent. Null when no call was placed. required: - customerParty - voiceSession additionalProperties: false title: PaymentIntentRelationships required: - id - type - attributes - relationships additionalProperties: false title: PaymentIntentResource meta: type: object properties: payUrl: type: string description: >- Single-use hosted checkout URL. Returned only here; there is no regenerate. Absent when the intent was collected under a card agreement. additionalProperties: false required: - data - meta additionalProperties: false title: CreatePaymentIntentResponse examples: default: summary: Default value: data: type: paymentIntent id: pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 attributes: amountMinor: 4620 currency: USD description: Order 8842 status: open paymentId: null mandateSetup: null taxMode: exclusive taxAmountMinor: 420 lineItems: - id: pli_019d0a1b2c3d4e5f60718293a4b5c6e1 position: 0 merchantReference: menu_item_31 description: Margherita pizza quantity: 2 unitAmountMinor: 1800 subtotalMinor: 3600 taxMinor: 320 totalMinor: 3920 taxCode: prepared_food - id: pli_019d0a1b2c3d4e5f60718293a4b5c6e2 position: 1 merchantReference: menu_item_77 description: Sparkling water quantity: 1 unitAmountMinor: 600 subtotalMinor: 600 taxMinor: 100 totalMinor: 700 taxCode: beverage expiresAt: null canceledAt: null createdAt: '2026-09-09T18:00:00.000Z' updatedAt: '2026-09-09T18:00:00.000Z' cardPayment: null relationships: customerParty: data: type: party id: pty_019cd1798d617f65a79cb965dda9eac3 voiceSession: data: null meta: payUrl: https://www.natural.com/checkout#chk_3f9a1c7e2b8d4e6f 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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. The response contains one error object for each invalid request value. 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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: 'Too big: expected string to have <=80 characters' status: '422' source: pointer: /data/attributes/description 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. 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 `. ````