> ## 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. # Sandbox: refund a card purchase > Simulate the merchant refunding part of a captured card purchase. The refund settles at once and is returned as its own card transaction. Sandbox only. ## OpenAPI ````yaml /api-reference/openapi-early-access.json post /simulations/card-transactions/{cardTransactionId}/refund 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: 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: /simulations/card-transactions/{cardTransactionId}/refund: post: tags: - Simulations summary: 'Sandbox: refund a card purchase' description: >- Simulate the merchant refunding part of a captured card purchase. The refund settles at once and is returned as its own card transaction. Sandbox only. operationId: simulations.refundCardPurchase parameters: - name: cardTransactionId in: path required: true schema: type: string pattern: ^cit_[0-9a-f]{32}$ description: A purchase returned by the authorize simulation (cit_*). - 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-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: amount: type: integer minimum: 1 maximum: 1000000 description: >- The amount to refund, in cents, at most the captured amount not yet refunded. currency: description: Currency code. Only USD is supported. type: string enum: - USD customerPartyId: type: string pattern: ^pty_[0-9a-f]{32}$ description: >- Customer party to act for (pty_*). Omit to act as your own party. A connected agent passes the customer whose wallet the card spends from. required: - amount - currency additionalProperties: false title: SimulateCardPurchaseRefundAttributes required: - attributes additionalProperties: false required: - data additionalProperties: false examples: default: summary: Default value: data: attributes: amount: 500 currency: USD responses: '200': description: Successful Response content: application/json: schema: type: object properties: data: type: object properties: type: description: Resource type. Always `cardTransaction`. type: string enum: - cardTransaction id: type: string pattern: ^cit_[0-9a-f]{32}$ description: Card transaction ID (cit_*). attributes: type: object properties: kind: enum: - purchase - refund type: string description: >- purchase: money paid to a merchant. refund: money a merchant returned. status: enum: - pending - authorized - partially_captured - captured - reversed - declined - refunded type: string description: >- pending: a refund the merchant approved that hasn't settled. authorized: a purchase holds money. partially_captured: part of the hold was spent and part is still held or released. captured: the purchase settled. reversed: the hold was released and nothing was spent. declined: the card declined it. refunded: the refund settled. merchant: type: object properties: name: type: string description: Merchant name as the card network sent it. categoryCode: anyOf: - type: string - type: 'null' description: >- Merchant category code (MCC), when the network sent one. city: anyOf: - type: string - type: 'null' description: Merchant city, when the network sent one. country: anyOf: - type: string - type: 'null' description: >- Merchant country as an ISO 3166-1 alpha-2 code, when known. required: - name - categoryCode - city - country additionalProperties: false title: CardTransactionMerchant amounts: type: object properties: attempted: type: integer description: Amount the merchant asked for, in cents. authorized: type: integer description: Amount the card approved, in cents. captured: type: integer description: Amount spent, in cents. released: type: integer description: >- Amount of the hold given back unspent, in cents. refunded: type: integer description: Amount refunded and settled, in cents. outstandingHold: type: integer description: Amount still held on the wallet, in cents. required: - attempted - authorized - captured - released - refunded - outstandingHold additionalProperties: false title: CardTransactionAmounts description: >- Each amount is a separate fact. Zero means that fact hasn't moved money. currency: description: Currency code. Only USD is supported. type: string enum: - USD decline: anyOf: - type: object properties: code: type: string description: >- Stable decline code, such as insufficient_funds. message: type: string description: >- A plain-language explanation of the decline. required: - code - message additionalProperties: false title: CardTransactionDecline - type: 'null' description: Why the card declined it, or null. actor: anyOf: - type: object properties: type: type: string enum: - person userId: type: string pattern: ^usr_[0-9a-f]{32}$ description: The person who used the card (usr_*). required: - type - userId additionalProperties: false title: CardTransactionPersonActor - type: object properties: type: type: string enum: - agent agentId: type: string pattern: ^agt_[0-9a-f]{32}$ description: The agent that used the card (agt_*). agentDelegationId: anyOf: - type: string pattern: ^adl_[0-9a-f]{32}$ - type: 'null' description: >- The connection the agent acted through (adl_*), when a connected agent used the card for a customer. Null for your own agent. required: - type - agentId - agentDelegationId additionalProperties: false title: CardTransactionAgentActor title: CardTransactionActor description: Who used the card. timeline: type: array items: type: object properties: kind: enum: - attempted - authorized - declined - captured - released - reversed - refunded type: string description: What happened. occurredAt: type: string description: RFC 3339 timestamp when it happened. amount: type: integer description: Amount of this event, in cents. decline: anyOf: - type: object properties: code: type: string description: >- Stable decline code, such as insufficient_funds. message: type: string description: >- A plain-language explanation of the decline. required: - code - message additionalProperties: false title: CardTransactionDecline - type: 'null' description: Why it declined, on a declined event. required: - kind - occurredAt - amount - decline additionalProperties: false title: CardTransactionTimelineEvent description: >- Every event on this card transaction, oldest first. occurredAt: type: string description: RFC 3339 timestamp when the card was first used. updatedAt: type: string description: >- RFC 3339 timestamp when Natural last recorded a change. required: - kind - status - merchant - amounts - currency - decline - actor - timeline - occurredAt - updatedAt additionalProperties: false title: CardTransactionAttributes relationships: type: object properties: card: type: object properties: data: type: object properties: type: description: Resource type. Always `card`. type: string enum: - card id: type: string pattern: ^pcd_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: >- The card used (pcd_*). Card numbers are never returned. wallet: type: object properties: data: type: object properties: type: description: Resource type. Always `wallet`. 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 the card draws on. transaction: type: object properties: data: type: object properties: type: description: Resource type. Always `transaction`. type: string enum: - transaction id: type: string pattern: ^txn_[0-9a-f]{32}$ description: Transaction ID (txn_*). required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: The same activity in GET /transactions. purchase: type: object properties: data: anyOf: - type: object properties: type: description: Resource type. Always `cardTransaction`. type: string enum: - cardTransaction id: type: string pattern: ^cit_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: >- For a refund, the purchase it returns money for, when known. Null on a purchase. refunds: type: object properties: data: type: array items: type: object properties: type: description: Resource type. Always `cardTransaction`. type: string enum: - cardTransaction id: type: string pattern: ^cit_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToManyRelationship description: For a purchase, its refunds. Empty on a refund. required: - card - wallet - transaction - purchase - refunds additionalProperties: false title: CardTransactionRelationships required: - type - id - attributes - relationships additionalProperties: false title: CardTransactionResource required: - data additionalProperties: false title: CardTransactionResponse examples: default: summary: Default value: data: type: cardTransaction id: cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f32 attributes: kind: refund status: refunded merchant: name: Sandbox Coffee categoryCode: '5999' city: null country: US amounts: attempted: 500 authorized: 500 captured: 0 released: 0 refunded: 500 outstandingHold: 0 currency: USD decline: null actor: type: agent agentId: agt_01a0e6466ba3713bba0f0d9d36803b93 agentDelegationId: null timeline: - kind: refunded occurredAt: '2026-10-14T18:01:00.000Z' amount: 500 decline: null occurredAt: '2026-10-14T18:01:00.000Z' updatedAt: '2026-10-14T18:01:02.000Z' relationships: card: data: type: card id: pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f31 wallet: data: type: wallet id: wal_01a0e6466ba3713bba0f0d9d36803b92 transaction: data: type: transaction id: txn_01a0e6a1d4c27b1a9f3e5d7c8b6a4f32 purchase: data: type: cardTransaction id: cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f31 refunds: data: [] 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.