> ## 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 searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`. > Use the Natural CLI for terminal and CI automation. > 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. # Get setup intent > Get a setup intent and its status ## OpenAPI ````yaml /api-reference/openapi-early-access.json get /setup-intents/{setupIntentId} 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 attachments description: Private supporting documents for payments - name: Subscriptions description: Subscriptions and installments paid by card - name: Setup intents description: Save a card under a mandate, with no charge now - name: Mandates description: A payer's consent to charge a saved card later - name: Payment Intents description: Holds on a saved card, captured later - name: Agent Cards description: Cards an agent requests for one purchase at one merchant - name: Card Transactions description: Purchases and refunds on Natural-issued cards - name: Simulations description: Sandbox-only simulation controls paths: /setup-intents/{setupIntentId}: get: tags: - Setup intents summary: Get setup intent description: Get a setup intent and its status operationId: setupIntents.get parameters: - name: setupIntentId in: path required: true schema: type: string pattern: ^set_[0-9a-f]{32}$ description: Setup intent ID (set_*). - name: customerPartyId in: query schema: type: string pattern: ^pty_[0-9a-f]{32}$ description: >- Customer party to act for (pty_*). Omit for your own account. Requires authorization from that customer. allowEmptyValue: true allowReserved: true - 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: id: type: string pattern: ^set_[0-9a-f]{32}$ description: Setup intent ID (set_*). type: description: Resource type. Always `setupIntent`. type: string enum: - setupIntent attributes: type: object properties: status: enum: - open - processing - completed - canceled - declined - expired type: string description: >- open until the guest saves a card, and again after a failed verification. processing while Natural verifies the card. completed once the card is saved and the agreement is active. canceled when you cancel it. declined once five cards failed on the link; it saves no more and the link is closed. expired once `expiresAt` passes while it's open. setupUrl: anyOf: - type: string - type: 'null' description: >- Hosted page where the guest saves a card, while the setup intent is open or processing. Null after that. clientSecret: anyOf: - type: string - type: 'null' description: >- Pass to natural.js in the browser to show the save card form on your page. Available whenever `setupUrl` is. Treat it like a password: send it only to the guest's browser. lastFailure: anyOf: - type: object properties: code: anyOf: - type: string - type: 'null' description: >- Failure code, when known. New codes may be added. reason: anyOf: - type: string - type: 'null' description: Explanation of the failure. advice: anyOf: - enum: - doNotRetry - tryAgainLater - confirmCardData type: string - type: 'null' description: Recommended payer action, when known. required: - code - reason - advice additionalProperties: false - type: 'null' description: >- Why the latest card failed, while the setup intent is open for another try or declined. Null otherwise. expiresAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp after which the guest can no longer save a card. No later than the agreement's `validUntil`. canceledAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the setup intent was canceled. createdAt: type: string description: >- RFC 3339 timestamp when the setup intent was created. updatedAt: type: string description: >- RFC 3339 timestamp when the setup intent record last changed. expired is read live. required: - status - setupUrl - clientSecret - lastFailure - expiresAt - canceledAt - createdAt - updatedAt additionalProperties: false title: SetupIntentAttributes relationships: type: object properties: mandate: type: object properties: data: anyOf: - type: object properties: type: description: Resource type. Always `mandate`. type: string enum: - mandate id: type: string pattern: ^mdt_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: >- The card agreement the saved card is charged under. Read its terms with `GET /mandates/{mandateId}`. Null until completed. required: - mandate additionalProperties: false title: SetupIntentRelationships required: - id - type - attributes - relationships additionalProperties: false title: SetupIntentResource required: - data additionalProperties: false title: SetupIntentResponse examples: default: summary: Default value: data: id: set_019d0a1b2c3d4e5f60718293a4b5c6e1 type: setupIntent attributes: status: completed setupUrl: null clientSecret: null lastFailure: null expiresAt: '2026-10-30T00:00:00Z' canceledAt: null createdAt: '2026-10-27T15:00:00Z' updatedAt: '2026-10-27T15:04:12Z' relationships: mandate: data: type: mandate id: mdt_019d0a1b2c3d4e5f60718293a4b5c6e2 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 `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.