> ## 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.

# Payment Intents

> Public error codes for Payment Intents API endpoints

All error responses follow the standard [error format](/api-reference/errors/error-handling).
Validation errors (422) and rate limit errors (429) apply to all endpoints and are documented in the [Error Handling guide](/api-reference/errors/error-handling).

| Code                                             | Status | Detail                                                                                                                 |
| ------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `card_mandate_amount_not_allowed`                | 400    | This amount does not match the agreement.                                                                              |
| `card_mandate_capability_off`                    | 400    | Future payment agreements are not enabled for this business.                                                           |
| `card_mandate_card_last4_required`               | 400    | Enter your card details before agreeing.                                                                               |
| `card_mandate_card_needs_update`                 | 400    | This card needs updated details.                                                                                       |
| `card_mandate_card_unusable`                     | 400    | This card has been removed.                                                                                            |
| `card_mandate_consent_required`                  | 400    | Agree to the future payment terms before paying.                                                                       |
| `card_mandate_network_unsupported`               | 400    | Future payments require a Visa or Mastercard.                                                                          |
| `card_mandate_not_active`                        | 400    | This agreement has ended.                                                                                              |
| `card_mandate_payer_required`                    | 400    | Verify your phone number for this checkout before paying.                                                              |
| `card_mandate_profile_incomplete`                | 400    | The merchant contact details and refund policy are required.                                                           |
| `card_mandate_terms_missing`                     | 400    | This checkout has no future payment terms.                                                                             |
| `invalid_value`                                  | 400    | The information you entered isn't valid. Please check it and try again.                                                |
| `merchant_payout_wallet_unavailable`             | 400    | The merchant has no wallet that can receive this payment.                                                              |
| `pagination_invalid_cursor`                      | 400    | The page cursor is not valid. Start the list again.                                                                    |
| `payment_intent_amount_above_cap`                | 400    | This amount is above the current card payment cap.                                                                     |
| `payment_intent_amount_component_mismatch`       | 400    | The payment amounts don't add up. Check the line items and tax.                                                        |
| `payment_intent_expired`                         | 400    | This payment intent has expired.                                                                                       |
| `payment_intent_merchant_descriptor_unavailable` | 400    | The merchant has no valid statement descriptor for card payments.                                                      |
| `payment_intent_merchant_limit_exceeded`         | 400    | This business cannot take this payment right now.                                                                      |
| `payment_intent_merchant_not_active`             | 400    | Card acceptance is not active for this business yet.                                                                   |
| `payment_intent_merchant_not_ready`              | 400    | This business cannot take card payments yet.                                                                           |
| `payment_intent_not_open`                        | 400    | This payment intent already has a payment in progress or completed.                                                    |
| `unauthenticated`                                | 401    | Authentication is required.                                                                                            |
| `forbidden`                                      | 403    | You do not have permission to perform this action.                                                                     |
| `party_mismatch`                                 | 403    | You can only act for your own party or a party that has authorized you.                                                |
| `payment_intent_not_found`                       | 404    | Payment intent not found.                                                                                              |
| `already_exists`                                 | 409    | The resource already exists.                                                                                           |
| `conflict`                                       | 409    | The request conflicts with the current resource state.                                                                 |
| `rate_limited`                                   | 429    | Too many requests. Please try again later.                                                                             |
| `server_error`                                   | 500    | Something went wrong.                                                                                                  |
| `bad_gateway`                                    | 502    | We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. |
| `service_unavailable`                            | 503    | The service is temporarily unavailable.                                                                                |