{ "servers": [ { "url": "https://api.natural.com", "description": "Production" } ], "components": { "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer", "description": "Bearer authentication: send your API key, agent key, or OAuth access token as `Authorization: Bearer `." } }, "schemas": { "ComplianceSessionStatusResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Compliance verification session ID." }, "type": { "type": "string", "enum": [ "complianceSessionStatus" ] }, "attributes": { "type": "object", "properties": { "programId": { "type": "string", "description": "Compliance program identifier." }, "programVersionId": { "type": "string", "description": "Compliance program version identifier." }, "status": { "enum": [ "UNSPECIFIED", "NOT_READY", "READY", "PENDING", "MET", "DENIED", "ACTION_NEEDED", "DEPRECATED", "USER_ACTION", "ADMIN_REVIEW" ], "type": "string", "description": "Current compliance case status." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique requirement identifier." }, "key": { "type": "string", "description": "Stable requirement key." }, "description": { "type": "string", "description": "Requirement description." } }, "required": [ "id", "key", "description" ], "additionalProperties": false }, "description": "Requirements currently attached to this compliance case." } }, "required": [ "programId", "programVersionId", "status", "requirements" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "PartyComplianceStatusResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*) being verified." }, "type": { "type": "string", "enum": [ "partyComplianceStatus" ] }, "attributes": { "type": "object", "properties": { "programCode": { "type": "string", "description": "Compliance program code." }, "caseStatus": { "enum": [ "UNSPECIFIED", "NOT_READY", "READY", "PENDING", "MET", "DENIED", "ACTION_NEEDED", "DEPRECATED", "USER_ACTION", "ADMIN_REVIEW" ], "type": "string", "description": "Current compliance case status." }, "displayState": { "enum": [ "verified", "underReview", "inProgress", "documentsRequired", "rejected" ], "type": "string", "description": "Customer-facing verification state." }, "title": { "type": "string", "description": "User-friendly title for the current state." }, "message": { "type": "string", "description": "User-friendly message explaining the current state." }, "canProceed": { "type": "boolean", "description": "Whether the party can proceed with platform features." }, "requirementsDue": { "type": "array", "items": { "type": "string" }, "description": "Requirement keys that still need user action or review." } }, "required": [ "programCode", "caseStatus", "displayState", "title", "message", "canProceed", "requirementsDue" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "TransactionLimits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "TransactionLimits" }, "PaymentIntent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$" }, "type": { "description": "Resource type. Always `paymentIntent`.", "type": "string", "enum": [ "paymentIntent" ] }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total amount in US cents." }, "currency": { "description": "Currency code.", "type": "string", "enum": [ "USD" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the payment is for." }, "payUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Hosted checkout URL while the intent is open or processing. Null when the intent is closed or no link is available." }, "clientSecret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass to natural.js in the browser to show the payment form. Available whenever `payUrl` is. Treat it like a password: send it only to the payer's browser." }, "status": { "enum": [ "open", "processing", "completed", "canceled", "declined", "expired" ], "type": "string", "description": "Payment collection status. A completed intent has a successful payment, but funds may not be settled yet." }, "taxMode": { "enum": [ "exclusive", "inclusive" ], "type": "string", "description": "Whether tax is added to or included in line amounts." }, "taxAmount": { "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_*). Replacing the lines issues new IDs." }, "position": { "type": "integer", "description": "Zero-based display order." }, "referenceId": { "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." }, "unitAmount": { "type": "integer", "description": "Per-unit amount in cents." }, "subtotalAmount": { "type": "integer", "description": "Line total before tax, in cents. Equals totalAmount minus taxAmount." }, "taxAmount": { "type": "integer", "description": "Line tax in cents." }, "totalAmount": { "type": "integer", "description": "Line total in cents." }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your tax code for this line." } }, "required": [ "id", "position", "referenceId", "description", "quantity", "unitAmount", "subtotalAmount", "taxAmount", "totalAmount", "taxCode" ], "additionalProperties": false, "title": "PaymentIntentLineItem" }, "description": "Line items in display order. Replaceable while the intent is open." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp after which no new payment attempt may start." }, "canceledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the intent was canceled." }, "createdAt": { "type": "string", "description": "RFC 3339 creation timestamp." }, "updatedAt": { "type": "string", "description": "RFC 3339 update timestamp." } }, "required": [ "amount", "currency", "description", "payUrl", "clientSecret", "status", "taxMode", "taxAmount", "lineItems", "expiresAt", "canceledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentIntentAttributes" }, "relationships": { "type": "object", "properties": { "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "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." }, "cardPayment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `cardPayment`.", "type": "string", "enum": [ "cardPayment" ] }, "id": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Successful card payment. Null until a payment succeeds." }, "voiceSession": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `voiceSession`.", "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 for this intent. Null when no session has been created." } }, "required": [ "customerParty", "cardPayment", "voiceSession" ], "additionalProperties": false, "title": "PaymentIntentRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentIntentResource" }, "CardPayment": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$", "description": "Card payment ID (cpy_*)." }, "type": { "description": "Resource type. Always `cardPayment`.", "type": "string", "enum": [ "cardPayment" ] }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Attempted amount in US cents." }, "currency": { "description": "Currency code.", "type": "string", "enum": [ "USD" ] }, "status": { "enum": [ "processing", "succeeded", "failed" ], "type": "string", "description": "Payment attempt status. A succeeded payment was accepted, but funds may not be settled yet." }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Card brand, when known." }, "last4": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last four card digits, when known." }, "channel": { "enum": [ "link", "voice" ], "type": "string", "description": "Where the payer submitted the payment." }, "receiptUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Hosted receipt page for the payer. Null until the payment succeeds." }, "failure": { "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": "Failure details. Null unless the attempt failed." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "recipient" ] }, "applied": { "description": "The fee is subtracted from the principal amount before the recipient receives it.", "type": "string", "enum": [ "deducted" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "RecipientDeductedFee" }, { "type": "null" } ], "description": "Fee deducted from your proceeds as the recipient. Null when no fee applies, the payment failed, the fee was voided, or your party is not the fee payer." }, "refundedAmount": { "type": "integer", "description": "Cents returned by successful refunds." }, "refundableAmount": { "type": "integer", "description": "Amount in US cents remaining after pending and successful refunds. Zero unless the payment succeeded. Other refund restrictions may apply." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds reached your wallet, or null while the payout is still settling." }, "createdAt": { "type": "string", "description": "RFC 3339 creation timestamp." }, "updatedAt": { "type": "string", "description": "RFC 3339 update timestamp. Refund changes may not advance this timestamp." } }, "required": [ "amount", "currency", "status", "brand", "last4", "channel", "receiptUrl", "failure", "fee", "refundedAmount", "refundableAmount", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "CardPaymentAttributes" }, "relationships": { "type": "object", "properties": { "paymentIntent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentIntent`.", "type": "string", "enum": [ "paymentIntent" ] }, "id": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The payment intent this attempt belongs to." }, "refunds": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `refund`.", "type": "string", "enum": [ "refund" ] }, "id": { "type": "string", "pattern": "^rfd_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } } }, "required": [ "data" ], "additionalProperties": false, "title": "ToManyRelationship", "description": "Up to 25 newest refund references, including pending and failed refunds. List refunds by cardPaymentId for the full history." } }, "required": [ "paymentIntent", "refunds" ], "additionalProperties": false, "title": "CardPaymentRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "CardPaymentResource" }, "VoiceSession": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^vos_[0-9a-f]{32}$", "description": "Voice session ID (vos_*)." }, "type": { "description": "Resource type. Always `voiceSession`.", "type": "string", "enum": [ "voiceSession" ] }, "attributes": { "anyOf": [ { "type": "object", "properties": { "kind": { "description": "Collects payment for a payment intent.", "type": "string", "enum": [ "payment" ] }, "status": { "enum": [ "awaitingCall", "inProgress", "ended", "failed", "canceled", "expired" ], "type": "string", "description": "Call lifecycle, independent of payment outcome. `ended` requires a recorded call end. `expired` means the dial window or call time limit passed without a recorded end." }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reference supplied when the session was created, or null." }, "callerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Supplied caller phone number, or null for a session without one." }, "dialUri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Dial destination while the session accepts a call and you have permission to create payment voice sessions. Otherwise null." }, "dialExpiresAt": { "type": "string", "description": "RFC 3339 deadline for starting the session's one permitted call." }, "returnTarget": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Requested return destination, or null. This does not confirm the destination answered." }, "call": { "type": "object", "properties": { "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reported call start time in RFC 3339, or null when unavailable." }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Time the call was recorded as ended in RFC 3339, or null." }, "durationSeconds": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Reported call duration in seconds, or null." }, "endedBy": { "anyOf": [ { "enum": [ "caller", "assistant", "unknown" ], "type": "string" }, { "type": "null" } ], "description": "Reported party ending the call. Null before an end is recorded." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Redacted call summary, or null." }, "returnRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Time a return transfer was requested in RFC 3339, or null. This does not confirm the return leg connected." } }, "required": [ "startedAt", "endedAt", "durationSeconds", "endedBy", "summary", "returnRequestedAt" ], "additionalProperties": false, "title": "VoiceSessionCall" }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 time the session completed, or null. Set once the call has ended and the kind's block holds its result. `voiceSession.completed` fires then." }, "createdAt": { "type": "string", "description": "RFC 3339 time the session was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 time the stored session last changed." }, "payment": { "type": "object", "properties": { "outcome": { "anyOf": [ { "enum": [ "paid", "linkSent", "unpaid" ], "type": "string" }, { "type": "null" } ], "description": "`paid` when the card was charged on the call. `linkSent` when voice payment did not succeed and the caller was texted the payment link. `unpaid` otherwise. Null until the result is known, which can be while the call is still in progress. A later link payment does not change it. New values may be added." }, "linkSentAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 time the payment link was texted to the caller, or null." }, "failedAttempts": { "type": "integer", "minimum": 0, "description": "Card payments that failed during this session." }, "failure": { "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": "The last failed card payment in this session, or null." } }, "required": [ "outcome", "linkSentAt", "failedAttempts", "failure" ], "additionalProperties": false, "title": "VoiceSessionPayment" } }, "required": [ "kind", "status", "referenceId", "callerPhone", "dialUri", "dialExpiresAt", "returnTarget", "call", "completedAt", "createdAt", "updatedAt", "payment" ], "additionalProperties": false, "title": "PaymentVoiceSessionAttributes" } ], "title": "VoiceSessionAttributes", "description": "`kind` is the session's purpose and names the block that holds its result. New kinds may be added; ignore kinds you don't handle." }, "relationships": { "type": "object", "properties": { "paymentIntent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentIntent`.", "type": "string", "enum": [ "paymentIntent" ] }, "id": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Associated payment intent. Set on `payment` sessions." }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Associated Natural customer, or null when none is associated." } }, "required": [ "paymentIntent", "customerParty" ], "additionalProperties": false, "title": "VoiceSessionRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "VoiceSessionResource" }, "VoiceSessionTranscript": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^vos_[0-9a-f]{32}$", "description": "Parent voice session ID (vos_*)." }, "type": { "description": "Resource type. Always `voiceSessionTranscript`.", "type": "string", "enum": [ "voiceSessionTranscript" ] }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "available", "notAvailable" ], "type": "string", "description": "Transcript availability. `notAvailable` when no call started. A missing provider link after call start is an error." }, "turns": { "type": "array", "items": { "type": "object", "properties": { "role": { "enum": [ "caller", "assistant", "system" ], "type": "string", "description": "Speaker or an explicitly supported call event." }, "text": { "type": "string", "description": "Redacted customer-facing dialogue or a supported system event label." }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp of the turn, or null when unavailable." } }, "required": [ "role", "text", "at" ], "additionalProperties": false, "title": "VoiceTranscriptTurn" }, "description": "Transcript turns in order. Empty when not available." } }, "required": [ "status", "turns" ], "additionalProperties": false, "title": "VoiceTranscriptAttributes" }, "relationships": { "type": "object", "properties": { "voiceSession": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `voiceSession`.", "type": "string", "enum": [ "voiceSession" ] }, "id": { "type": "string", "pattern": "^vos_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Parent voice session." } }, "required": [ "voiceSession" ], "additionalProperties": false, "title": "VoiceTranscriptRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "VoiceTranscriptResource" }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rfd_[0-9a-f]{32}$", "description": "Refund ID (rfd_*)." }, "type": { "description": "Resource type. Always `refund`.", "type": "string", "enum": [ "refund" ] }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in US cents." }, "currency": { "description": "Currency code.", "type": "string", "enum": [ "USD" ] }, "reason": { "anyOf": [ { "enum": [ "duplicate", "fraudulent", "requestedByPayer" ], "type": "string" }, { "type": "null" } ], "description": "Why the refund was requested." }, "status": { "enum": [ "pending", "succeeded", "failed" ], "type": "string", "description": "Refund status. Succeeded means the refund was processed, but the cardholder’s bank may not have posted the credit yet." }, "failure": { "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." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details. Null unless the refund failed." }, "receiptUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The refunded payment's hosted receipt page, which lists this refund." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the refund was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the refund was last updated." } }, "required": [ "amount", "currency", "reason", "status", "failure", "receiptUrl", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "RefundAttributes" }, "relationships": { "type": "object", "properties": { "paymentIntent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentIntent`.", "type": "string", "enum": [ "paymentIntent" ] }, "id": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The intent whose payment is refunded." }, "cardPayment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `cardPayment`.", "type": "string", "enum": [ "cardPayment" ] }, "id": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The card payment refunded." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "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 that received the original payment." } }, "required": [ "paymentIntent", "cardPayment", "customerParty" ], "additionalProperties": false, "title": "RefundRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "RefundResource" } } }, "info": { "title": "Natural API", "version": "0.2.0", "description": "Natural's payments API for autonomous agents.\n\n**Base URL:** `https://api.natural.com`\n\nAI agents, including coding agents, should prefer the hosted MCP server at `https://mcp.natural.com` when an MCP-aware host runs the agent, the Natural CLI for terminal/CI workflows, and the official SDKs for application runtimes they own. Use direct HTTP only for explicit low-level integrations, unsupported SDK gaps, or infrastructure work where REST is required.\n\nFor support: support@natural.com" }, "openapi": "3.1.1", "paths": { "/agents": { "post": { "operationId": "agents.create", "summary": "Create agent", "description": "Create an agent", "tags": [ "Agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Agent display name." }, "description": { "type": "string", "maxLength": 100, "description": "Agent description." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.", "maxProperties": 30 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._]{1,28}[a-z0-9]$", "description": "Agent-specific part of the handle, such as support in @acme-support." }, "limits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "description": "Agent spending limits. Agent credentials cannot set them." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet (wal_*) the agent is granted access to. Defaults to the party's default wallet." } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "name": "Procurement Agent", "description": "Buys supplies", "tags": { "department": "procurement" }, "slug": "procurementagent", "limits": { "perTransaction": 100000 } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status: ACTIVE, or REVOKED after deletion." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this agent was created, or null when unknown." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the agent last authenticated, or null when it never has." } }, "required": [ "name", "description", "tags", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d", "attributes": { "name": "Procurement Agent", "description": "Buys supplies", "tags": { "department": "procurement" }, "handle": "@acme-procurementagent", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00.000Z", "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "lastActiveAt": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "agents.list", "summary": "List agents", "description": "List agents", "tags": [ "Agents" ], "parameters": [ { "name": "status", "in": "query", "schema": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Filter by status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status: ACTIVE, or REVOKED after deletion." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this agent was created, or null when unknown." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the agent last authenticated, or null when it never has." } }, "required": [ "name", "description", "tags", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d", "attributes": { "name": "Procurement Agent", "description": "Buys supplies", "tags": { "department": "procurement" }, "handle": "@acme-procurementagent", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00.000Z", "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "lastActiveAt": "2026-01-05T09:12:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/agents/{agentId}": { "get": { "operationId": "agents.get", "summary": "Get agent", "description": "Get an agent", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status: ACTIVE, or REVOKED after deletion." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this agent was created, or null when unknown." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the agent last authenticated, or null when it never has." } }, "required": [ "name", "description", "tags", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d", "attributes": { "name": "Procurement Agent", "description": "Buys supplies", "tags": { "department": "procurement" }, "handle": "@acme-procurementagent", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00.000Z", "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "lastActiveAt": "2026-01-05T09:12:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] }, "patch": { "operationId": "agents.update", "summary": "Update agent", "description": "Update an agent", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "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": { "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ], "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "Agent description." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "description": "Metadata changes. A null value removes the key." }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._]{1,28}[a-z0-9]$", "description": "Agent-specific part of the handle, such as support in @acme-support. Renames the handle; omission leaves it unchanged. Handles cannot be cleared." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Agent spending limits. Null clears all limits; omission leaves them unchanged. Within the object, a null or omitted window clears that limit." } }, "additionalProperties": false, "title": "AgentUpdateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentUpdateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "name": "Procurement Agent v2.1", "description": "Autonomous agent that pays contractors", "tags": { "release": "v2.1" } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status: ACTIVE, or REVOKED after deletion." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this agent was created, or null when unknown." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the agent last authenticated, or null when it never has." } }, "required": [ "name", "description", "tags", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d", "attributes": { "name": "Procurement Agent v2.1", "description": "Autonomous agent that pays contractors", "tags": { "department": "procurement", "release": "v2.1" }, "handle": "@acme-procurementagent", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00.000Z", "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "lastActiveAt": "2026-01-05T09:12:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] }, "delete": { "operationId": "agents.remove", "summary": "Delete agent", "description": "Delete an agent and revoke its active customer authorizations and pending invitations", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status: ACTIVE, or REVOKED after deletion." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this agent was created, or null when unknown." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this agent (usr_*)." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the agent last authenticated, or null when it never has." } }, "required": [ "name", "description", "tags", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "AgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d", "attributes": { "name": "Procurement Agent", "description": "Buys supplies", "tags": { "department": "procurement" }, "handle": "@acme-procurementagent", "status": "REVOKED", "limits": null, "createdAt": "2026-01-04T15:30:00.000Z", "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "lastActiveAt": "2026-01-05T09:12:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } }, "meta": { "deleted": true } } } } } }, "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": [] } ] } }, "/customers": { "get": { "operationId": "customers.list", "summary": "List customers", "description": "List customers who have authorized an agent to act for them", "tags": [ "Customers" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "active", "revoked", "all" ], "type": "string", "default": "active", "description": "Filter by connection state. Active returns any non-revoked connection (including suspended and expired). Revoked returns customers whose access was revoked. All returns both." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `customer`.", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the customer's party was created, or null when unknown." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Connection status: ACTIVE, SUSPENDED (paused by the customer), REVOKED, or EXPIRED." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted by the customer." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the customer connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when access was revoked, or null while active." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted to this agent." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CustomerListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "pty_019cd1798d627ad9bc302511c4f2c115", "type": "customer", "attributes": { "name": "Bistro Roma", "email": "ops@bistroroma.com", "avatarUrl": "https://static.natural.com/avatars/bistro-roma.png", "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_019cd1798d937c77f6c0ecee3c32893b", "status": "ACTIVE", "permissions": [ "payments.read", "payments.create", "external_accounts.create", "wallets.balance", "wallets.update", "party.read", "party.update" ], "createdAt": "2026-01-10T12:00:00.000Z", "revokedAt": null }, "agents": [ { "id": "agt_019cd1798d637a4da75dce386343931d", "name": "Procurement Agent", "handle": "@acme-procurementagent", "status": "ACTIVE", "permissions": [ "payments.read", "payments.create", "external_accounts.create", "wallets.balance", "wallets.update", "party.read", "party.update" ], "limits": { "perTransaction": 100000 } } ] } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/customers/{customerId}": { "get": { "operationId": "customers.get", "summary": "Get customer", "description": "Get a customer who has authorized an agent", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `customer`.", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the customer's party was created, or null when unknown." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Connection status: ACTIVE, SUSPENDED (paused by the customer), REVOKED, or EXPIRED." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted by the customer." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the customer connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when access was revoked, or null while active." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted to this agent." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." } }, "required": [ "data" ], "additionalProperties": false, "title": "CustomerResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d627ad9bc302511c4f2c115", "type": "customer", "attributes": { "name": "Bistro Roma", "email": "ops@bistroroma.com", "avatarUrl": "https://static.natural.com/avatars/bistro-roma.png", "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_019cd1798d937c77f6c0ecee3c32893b", "status": "ACTIVE", "permissions": [ "payments.read", "payments.create", "external_accounts.create", "wallets.balance", "wallets.update", "party.read", "party.update" ], "createdAt": "2026-01-10T12:00:00.000Z", "revokedAt": null }, "agents": [ { "id": "agt_019cd1798d637a4da75dce386343931d", "name": "Procurement Agent", "handle": "@acme-procurementagent", "status": "ACTIVE", "permissions": [ "payments.read", "payments.create", "external_accounts.create", "wallets.balance", "wallets.update", "party.read", "party.update" ], "limits": { "perTransaction": 100000 } } ] } } } } } } }, "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": [] } ] }, "delete": { "operationId": "customers.remove", "summary": "Disconnect customer", "description": "Revoke the customer connection and all remaining agent access", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `customer`.", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the customer's party was created, or null when unknown." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Connection status: ACTIVE, SUSPENDED (paused by the customer), REVOKED, or EXPIRED." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted by the customer." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the customer connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when access was revoked, or null while active." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted to this agent." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CustomerDisconnectResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d6900dd9b05291c37c47803", "type": "customer", "attributes": { "name": "Globex Inc", "email": "finance@globex.com", "avatarUrl": null, "createdAt": "2025-11-20T09:00:00.000Z", "delegation": { "id": "dlg_019cd1798d946415ecb7952c3df4d1ea", "status": "REVOKED", "permissions": [], "createdAt": "2025-11-22T09:30:00.000Z", "revokedAt": "2026-01-08T17:45:00.000Z" }, "agents": [ { "id": "agt_019cd1798d637a4da75dce386343931d", "name": "Procurement Agent", "handle": "@acme-procurementagent", "status": "REVOKED", "permissions": [ "payments.read" ], "limits": null } ] } }, "meta": { "deleted": true } } } } } }, "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": [] } ] } }, "/customers/invitations": { "get": { "operationId": "customers.listInvitations", "summary": "List customer invitations", "description": "List pending invitations addressed to specific customers", "tags": [ "Customers" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `customerInvitation`.", "type": "string", "enum": [ "customerInvitation" ] }, "id": { "type": "string", "description": "Recipient email." }, "attributes": { "type": "object", "properties": { "status": { "type": "string", "description": "Invitation status." }, "party": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the customer's party was created, or null when unknown." } }, "required": [ "id", "name", "email", "avatarUrl", "createdAt" ], "additionalProperties": false, "title": "CustomerParty" }, { "type": "null" } ], "description": "Customer party, or null until they join Natural." }, "email": { "type": "string", "description": "Recipient email." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the invitation was created." }, "agentInvitations": { "type": "array", "items": { "type": "object", "properties": { "invitationId": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." }, "agent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false, "title": "CustomerAgent", "description": "Invited agent." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions requested for this agent." }, "url": { "type": "string", "format": "uri", "description": "Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the invitation was created." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation expires, or null when it never expires." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "invitationId", "agent", "permissions", "url", "createdAt", "expiresAt", "tags" ], "additionalProperties": false, "title": "AgentInvitation" }, "description": "Agent invitations sent to this recipient." } }, "required": [ "status", "party", "email", "createdAt", "agentInvitations" ], "additionalProperties": false, "title": "CustomerInvitationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerInvitationResource", "description": "Pending customer invitation grouped by recipient." } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PendingInvitationListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "customerInvitation", "id": "ops@bistroroma.com", "attributes": { "status": "PENDING", "party": null, "email": "ops@bistroroma.com", "createdAt": "2026-01-05T10:15:00.000Z", "agentInvitations": [ { "invitationId": "adi_019cd1798d96adc082e235b426d4e04c", "agent": { "id": "agt_019cd1798d637a4da75dce386343931d", "name": "Procurement Agent", "handle": "@acme-procurementagent" }, "permissions": [ "payments.read", "payments.create", "external_accounts.create", "wallets.balance", "wallets.update", "party.read", "party.update" ], "url": "https://www.natural.com/connect/adi_019cd1798d96adc082e235b426d4e04c", "createdAt": "2026-01-05T10:15:00.000Z", "expiresAt": "2026-01-12T10:15:00.000Z", "tags": { "campaign": "q3_reactivation" } }, { "invitationId": "adi_019cd1798d97b93db1935d55e7d844da", "agent": { "id": "agt_019cd1798d6bdfcd56bce194520e6f50", "name": "Refunds Agent", "handle": "@acme-refunds" }, "permissions": [ "payments.create", "payments.read" ], "url": "https://www.natural.com/connect/adi_019cd1798d97b93db1935d55e7d844da", "createdAt": "2026-01-05T10:15:00.000Z", "expiresAt": "2026-01-12T10:15:00.000Z", "tags": { "campaign": "q3_reactivation" } } ] } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] }, "post": { "operationId": "customers.createInvitations", "summary": "Invite customers", "description": "Invite specific customers by email or phone to approve a set of your agents, each with its own permissions and limits", "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "recipients": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "maxLength": 254, "format": "email", "description": "Email address." } }, "required": [ "type", "value" ], "additionalProperties": false, "title": "Email recipient" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "maxLength": 16, "description": "Phone number." } }, "required": [ "type", "value" ], "additionalProperties": false, "title": "Phone recipient" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)." } }, "required": [ "type", "value" ], "additionalProperties": false, "title": "Existing customer" } ], "title": "CustomerInvitationCreateRecipient" }, "description": "Each recipient is one of three shapes: an email recipient (which may carry onboarding details), a phone recipient, or an existing customer referenced by party ID." }, "agents": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "permissions": { "anyOf": [ { "type": "array", "minItems": 1, "items": { "enum": [ "disputes.read", "disputes.create", "payments.read", "payments.create", "external_parties.read", "external_parties.create", "direct.read", "direct.create", "external_accounts.create", "wallets.read", "wallets.balance", "wallets.create", "wallets.update", "wallets.fund", "wallets.deposit", "wallets.transfer", "wallets.withdraw", "party.read", "party.update", "payment_intents.create", "payment_intents.read", "card_payments.read", "refunds.read", "refunds.create", "voice_sessions.read", "voice_sessions.create", "chargebacks.read", "chargebacks.respond", "mandates.read", "enrollment.read", "cards.read", "saved_cards.use" ], "type": "string" }, "title": "PermissionList", "description": "Specific permissions to request." }, { "type": "object", "properties": { "type": { "description": "Set to `ALL`.", "type": "string", "enum": [ "ALL" ] } }, "required": [ "type" ], "additionalProperties": false, "title": "AllPermissions", "description": "Request every permission available to your party today." } ], "description": "Permissions for this agent, or `{\"type\":\"ALL\"}` for all of them. Fixed when the invitation is created." }, "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "limits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." } }, "additionalProperties": false, "description": "Transaction limits for this agent." } }, "required": [ "permissions", "agentId" ], "additionalProperties": false, "title": "CustomerInvitationAgentSpec" }, "description": "Agents to grant access to. Each recipient receives an invitation for every agent listed." }, "expiresAt": { "type": "string", "maxLength": 64, "format": "date-time", "description": "RFC 3339 timestamp when the invitation expires. Defaults to 30 days from now; maximum 90 days." }, "message": { "type": "string", "maxLength": 180, "description": "Message stored with each recipient's invitation. It is not included in the invitation email." }, "redirectUrl": { "type": "string", "maxLength": 2048, "description": "Where to send the customer after they accept and finish setup on Natural: an https URL, an app deep link, or an sms: link." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Tags applied to each invitation.", "maxProperties": 30 } }, "required": [ "recipients", "agents" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CustomerInvitationCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "recipients": [ { "type": "email", "value": "ops@bistroroma.com" } ], "agents": [ { "agentId": "agt_019cd1798d637a4da75dce386343931d", "permissions": [ "payments.read", "payments.create", "external_accounts.create", "wallets.balance", "wallets.update", "party.read", "party.update" ], "limits": { "perTransaction": 100000 } } ], "expiresAt": "2026-01-12T10:15:00.000Z", "message": "We use Natural to let our agents help manage payments for your business.", "redirectUrl": "https://app.acmepayments.com/connected", "tags": { "campaign": "q3_reactivation" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agentDelegationInvitation`.", "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name." }, "email": { "type": "string", "description": "Recipient email." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone." }, "url": { "type": "string", "format": "uri", "description": "Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations." }, "agentName": { "type": "string", "description": "Agent name." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits." }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status." }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Status after applying expiry: reads EXPIRED once `expiresAt` has passed even while `status` is still PENDING." }, "expiresAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation expires." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation was accepted, or null." }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation was declined, or null." }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED", "CONNECTION_ESTABLISHED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation." }, "redirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the customer is sent after accepting and finishing setup, or null." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation was last updated." } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "redirectUrl", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details." }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent." }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party that accepted the invitation, or null until acceptance." } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" }, "description": "Created invitations." }, "meta": { "type": "object", "properties": { "failedRecipients": { "type": "array", "items": { "type": "object", "properties": { "recipient": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "maxLength": 254, "format": "email", "description": "Email address." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "maxLength": 16, "description": "Phone number." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)." } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "CustomerInvitationRecipient", "description": "Recipient that failed." }, "reason": { "type": "string", "description": "Why this recipient's invitations failed." } }, "required": [ "recipient", "reason" ], "additionalProperties": false }, "description": "Recipients whose invitations could not be created." }, "alreadyConnected": { "type": "array", "items": { "type": "object", "properties": { "recipient": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "maxLength": 254, "format": "email", "description": "Email address." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "maxLength": 16, "description": "Phone number." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)." } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "CustomerInvitationRecipient", "description": "Recipient whose party already has an active connection to the agent." }, "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent that is already connected." }, "agentDelegationId": { "type": "string", "pattern": "^adl_[0-9a-f]{32}$", "description": "Existing active agent delegation that satisfied the request." } }, "required": [ "recipient", "agentId", "agentDelegationId" ], "additionalProperties": false, "title": "AlreadyConnectedAgent" }, "description": "Agent-recipient pairs skipped because the agent is already connected to the recipient's party. Requested permissions and limits were not applied." } }, "required": [ "failedRecipients", "alreadyConnected" ], "additionalProperties": false, "description": "Metadata about the batch." } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CustomerInvitationCreateResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agentDelegationInvitation", "id": "adi_019cd1798d96adc082e235b426d4e04c", "attributes": { "developerName": "Acme Payments", "email": "ops@bistroroma.com", "phone": null, "url": "https://www.natural.com/connect/adi_019cd1798d96adc082e235b426d4e04c", "agentName": "Procurement Agent", "permissions": [ "payments.read", "payments.create", "external_accounts.create", "wallets.balance", "wallets.update", "party.read", "party.update" ], "limits": { "perTransaction": 100000 }, "status": "PENDING", "effectiveStatus": "PENDING", "expiresAt": "2026-01-12T10:15:00.000Z", "acceptedAt": null, "declinedAt": null, "cancelReason": null, "redirectUrl": "https://app.acmepayments.com/connected", "tags": { "campaign": "q3_reactivation" }, "createdAt": "2026-01-05T10:15:00.000Z", "updatedAt": "2026-01-05T10:15:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "customerParty": { "data": null } } } ], "meta": { "failedRecipients": [], "alreadyConnected": [] } } } } } }, "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": [] } ], "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." } ] } }, "/customers/invitations/{invitationId}": { "delete": { "operationId": "customers.revokeInvitation", "summary": "Revoke customer invitation", "description": "Revoke a pending customer invitation", "tags": [ "Customers" ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agentDelegationInvitation`.", "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name." }, "email": { "type": "string", "description": "Recipient email." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone." }, "url": { "type": "string", "format": "uri", "description": "Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations." }, "agentName": { "type": "string", "description": "Agent name." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits." }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status." }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Status after applying expiry: reads EXPIRED once `expiresAt` has passed even while `status` is still PENDING." }, "expiresAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation expires." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation was accepted, or null." }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation was declined, or null." }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED", "CONNECTION_ESTABLISHED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation." }, "redirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the customer is sent after accepting and finishing setup, or null." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation was last updated." } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "redirectUrl", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details." }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent." }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party that accepted the invitation, or null until acceptance." } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CustomerInvitationSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentDelegationInvitation", "id": "adi_019cd1798d96adc082e235b426d4e04c", "attributes": { "developerName": "Acme Payments", "email": "ops@bistroroma.com", "phone": null, "url": "https://www.natural.com/connect/adi_019cd1798d96adc082e235b426d4e04c", "agentName": "Procurement Agent", "permissions": [ "payments.read", "payments.create", "external_accounts.create", "wallets.balance", "wallets.update", "party.read", "party.update" ], "limits": { "perTransaction": 100000 }, "status": "CANCELED", "effectiveStatus": "CANCELED", "expiresAt": "2026-01-12T10:15:00.000Z", "acceptedAt": null, "declinedAt": null, "cancelReason": "DEVELOPER_REVOKED", "redirectUrl": "https://app.acmepayments.com/connected", "tags": { "campaign": "q3_reactivation" }, "createdAt": "2026-01-05T10:15:00.000Z", "updatedAt": "2026-01-05T10:20:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "customerParty": { "data": null } } }, "meta": { "deleted": true } } } } } }, "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": [] } ] } }, "/customers/{customerId}/agents/{agentId}": { "delete": { "operationId": "customers.revokeAgent", "summary": "Revoke agent access", "description": "Remove an agent's access to a customer", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "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": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `customer`.", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the customer's party was created, or null when unknown." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Connection status: ACTIVE, SUSPENDED (paused by the customer), REVOKED, or EXPIRED." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted by the customer." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the customer connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when access was revoked, or null while active." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted to this agent." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." } }, "required": [ "data" ], "additionalProperties": false, "title": "CustomerResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `customer`.", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the customer's party was created, or null when unknown." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Connection status: ACTIVE, SUSPENDED (paused by the customer), REVOKED, or EXPIRED." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted by the customer." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the customer connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when access was revoked, or null while active." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted to this agent." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false } ], "title": "CustomerAgentRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d627ad9bc302511c4f2c115", "type": "customer", "attributes": { "name": "Bistro Roma", "email": "ops@bistroroma.com", "avatarUrl": "https://static.natural.com/avatars/bistro-roma.png", "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_019cd1798d937c77f6c0ecee3c32893b", "status": "ACTIVE", "permissions": [], "createdAt": "2026-01-10T12:00:00.000Z", "revokedAt": null }, "agents": [] } } } } } } }, "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": [] } ] } }, "/customers/invitation-links": { "post": { "operationId": "invitationLinks.create", "summary": "Create invitation link", "description": "Create a shareable link offering your agents, with the permissions and limits you set, to any customer who opens it", "tags": [ "Invitation Links" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "proposedAgents": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "permissions": { "type": "array", "minItems": 1, "items": { "enum": [ "disputes.read", "disputes.create", "payments.read", "payments.create", "external_parties.read", "external_parties.create", "direct.read", "direct.create", "external_accounts.create", "wallets.read", "wallets.balance", "wallets.create", "wallets.update", "wallets.fund", "wallets.deposit", "wallets.transfer", "wallets.withdraw", "party.read", "party.update", "payment_intents.create", "payment_intents.read", "card_payments.read", "refunds.read", "refunds.create", "voice_sessions.read", "voice_sessions.create", "chargebacks.read", "chargebacks.respond", "mandates.read", "enrollment.read", "cards.read", "saved_cards.use" ], "type": "string" }, "description": "Permissions requested for this agent." }, "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "limits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive per-transaction limit in cents. Null means no per-transaction limit." } }, "additionalProperties": false, "description": "Spending limits for this agent. Only `perTransaction` is supported, in cents." } }, "required": [ "permissions", "agentId" ], "additionalProperties": false }, "description": "Agents to offer, with the permissions and limits granted on approval." }, "expiresAt": { "type": "string", "maxLength": 64, "format": "date-time", "description": "RFC 3339 timestamp when the link stops accepting new customers. Omit for a link that never expires." }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Label for this link." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.", "maxProperties": 30 } }, "required": [ "proposedAgents", "name" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateInvitationLinkInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "proposedAgents": [ { "agentId": "agt_019cd1798d637a4da75dce386343931d", "permissions": [ "payments.read", "payments.create" ], "limits": { "perTransaction": 100000 } } ], "name": "Q3 carrier onboarding", "tags": { "campaign": "q3_carrier_onboarding" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `invitationLink`.", "type": "string", "enum": [ "invitationLink" ] }, "id": { "type": "string", "pattern": "^ivl_[0-9a-f]{32}$", "description": "Invitation link ID (ivl_*)." }, "attributes": { "type": "object", "properties": { "proposedAgents": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "permissions": { "type": "array", "items": { "enum": [ "disputes.read", "disputes.create", "payments.read", "payments.create", "external_parties.read", "external_parties.create", "direct.read", "direct.create", "external_accounts.create", "wallets.read", "wallets.balance", "wallets.create", "wallets.update", "wallets.fund", "wallets.deposit", "wallets.transfer", "wallets.withdraw", "party.read", "party.update", "payment_intents.create", "payment_intents.read", "card_payments.read", "refunds.read", "refunds.create", "voice_sessions.read", "voice_sessions.create", "chargebacks.read", "chargebacks.respond", "mandates.read", "enrollment.read", "cards.read", "saved_cards.use", "paymentRequests.read", "paymentRequests.create", "externalParties.read", "externalParties.create", "externalAccounts.read", "externalAccounts.create", "paymentIntents.read", "paymentIntents.create", "cardPayments.read", "voiceSessions.read", "voiceSessions.create", "savedCards.use" ], "type": "string" }, "description": "Permissions granted to this agent when a customer approves." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "type": "integer", "exclusiveMinimum": 0, "description": "Per-transaction limit in cents." } }, "required": [ "perTransaction" ], "additionalProperties": false }, { "type": "null" } ], "description": "Proposed per-transaction limit, or null when no limit is offered." } }, "required": [ "agentId", "permissions", "limits" ], "additionalProperties": false }, "description": "Agents offered to customers who open this link." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Link status." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this link was created." }, "name": { "type": "string", "description": "Label for this link." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this link stops accepting new customers, or null when it never expires." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "token": { "type": "string", "description": "Link token. Returned only when the link is created; list and get return `maskedToken`." }, "url": { "type": "string", "description": "Shareable URL for this link. Returned only when the link is created." } }, "required": [ "proposedAgents", "status", "createdAt", "name", "expiresAt", "tags", "token", "url" ], "additionalProperties": false, "title": "InvitationLinkAttributes" }, "relationships": { "type": "object", "properties": { "delegateeParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that created this link." } }, "required": [ "delegateeParty" ], "additionalProperties": false, "title": "InvitationLinkRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "InvitationLinkResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "invitationLink", "id": "ivl_019cd1798d9a054033f6006d22544b56", "attributes": { "proposedAgents": [ { "agentId": "agt_019cd1798d637a4da75dce386343931d", "permissions": [ "payments.read", "payments.create" ], "limits": { "perTransaction": 100000 } } ], "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "name": "Q3 carrier onboarding", "expiresAt": null, "tags": { "campaign": "q3_carrier_onboarding" }, "token": "hV3nwqumSGr7fcAJZQyLtN", "url": "https://www.natural.com/connect/hV3nwqumSGr7fcAJZQyLtN" }, "relationships": { "delegateeParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ], "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." } ] }, "get": { "operationId": "invitationLinks.list", "summary": "List invitation links", "description": "List the invitation links you have created, with masked tokens", "tags": [ "Invitation Links" ], "parameters": [ { "name": "statusFilter", "in": "query", "schema": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Filter by status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `invitationLink`.", "type": "string", "enum": [ "invitationLink" ] }, "id": { "type": "string", "pattern": "^ivl_[0-9a-f]{32}$", "description": "Invitation link ID (ivl_*)." }, "attributes": { "type": "object", "properties": { "proposedAgents": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "permissions": { "type": "array", "items": { "enum": [ "disputes.read", "disputes.create", "payments.read", "payments.create", "external_parties.read", "external_parties.create", "direct.read", "direct.create", "external_accounts.create", "wallets.read", "wallets.balance", "wallets.create", "wallets.update", "wallets.fund", "wallets.deposit", "wallets.transfer", "wallets.withdraw", "party.read", "party.update", "payment_intents.create", "payment_intents.read", "card_payments.read", "refunds.read", "refunds.create", "voice_sessions.read", "voice_sessions.create", "chargebacks.read", "chargebacks.respond", "mandates.read", "enrollment.read", "cards.read", "saved_cards.use", "paymentRequests.read", "paymentRequests.create", "externalParties.read", "externalParties.create", "externalAccounts.read", "externalAccounts.create", "paymentIntents.read", "paymentIntents.create", "cardPayments.read", "voiceSessions.read", "voiceSessions.create", "savedCards.use" ], "type": "string" }, "description": "Permissions granted to this agent when a customer approves." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "type": "integer", "exclusiveMinimum": 0, "description": "Per-transaction limit in cents." } }, "required": [ "perTransaction" ], "additionalProperties": false }, { "type": "null" } ], "description": "Proposed per-transaction limit, or null when no limit is offered." } }, "required": [ "agentId", "permissions", "limits" ], "additionalProperties": false }, "description": "Agents offered to customers who open this link." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Link status." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this link was created." }, "name": { "type": "string", "description": "Label for this link." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this link stops accepting new customers, or null when it never expires." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "maskedToken": { "type": "string", "description": "Link token with all but the last 4 characters masked (for example ***bc4d). The full token and URL are returned only when the link is created." } }, "required": [ "proposedAgents", "status", "createdAt", "name", "expiresAt", "tags", "maskedToken" ], "additionalProperties": false, "title": "InvitationLinkMetadataAttributes" }, "relationships": { "type": "object", "properties": { "delegateeParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that created this link." } }, "required": [ "delegateeParty" ], "additionalProperties": false, "title": "InvitationLinkRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "InvitationLinkMetadataResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "invitationLink", "id": "ivl_019cd1798d9a054033f6006d22544b56", "attributes": { "proposedAgents": [ { "agentId": "agt_019cd1798d637a4da75dce386343931d", "permissions": [ "payments.read", "payments.create" ], "limits": { "perTransaction": 100000 } } ], "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "name": "Q3 carrier onboarding", "expiresAt": null, "tags": { "campaign": "q3_carrier_onboarding" }, "maskedToken": "***yLtN" }, "relationships": { "delegateeParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/customers/invitation-links/{linkId}": { "get": { "operationId": "invitationLinks.get", "summary": "Get invitation link", "description": "Get an invitation link and its offered agents, with a masked token", "tags": [ "Invitation Links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ivl_[0-9a-f]{32}$", "description": "Invitation link ID (ivl_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `invitationLink`.", "type": "string", "enum": [ "invitationLink" ] }, "id": { "type": "string", "pattern": "^ivl_[0-9a-f]{32}$", "description": "Invitation link ID (ivl_*)." }, "attributes": { "type": "object", "properties": { "proposedAgents": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "permissions": { "type": "array", "items": { "enum": [ "disputes.read", "disputes.create", "payments.read", "payments.create", "external_parties.read", "external_parties.create", "direct.read", "direct.create", "external_accounts.create", "wallets.read", "wallets.balance", "wallets.create", "wallets.update", "wallets.fund", "wallets.deposit", "wallets.transfer", "wallets.withdraw", "party.read", "party.update", "payment_intents.create", "payment_intents.read", "card_payments.read", "refunds.read", "refunds.create", "voice_sessions.read", "voice_sessions.create", "chargebacks.read", "chargebacks.respond", "mandates.read", "enrollment.read", "cards.read", "saved_cards.use", "paymentRequests.read", "paymentRequests.create", "externalParties.read", "externalParties.create", "externalAccounts.read", "externalAccounts.create", "paymentIntents.read", "paymentIntents.create", "cardPayments.read", "voiceSessions.read", "voiceSessions.create", "savedCards.use" ], "type": "string" }, "description": "Permissions granted to this agent when a customer approves." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "type": "integer", "exclusiveMinimum": 0, "description": "Per-transaction limit in cents." } }, "required": [ "perTransaction" ], "additionalProperties": false }, { "type": "null" } ], "description": "Proposed per-transaction limit, or null when no limit is offered." } }, "required": [ "agentId", "permissions", "limits" ], "additionalProperties": false }, "description": "Agents offered to customers who open this link." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Link status." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this link was created." }, "name": { "type": "string", "description": "Label for this link." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this link stops accepting new customers, or null when it never expires." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "maskedToken": { "type": "string", "description": "Link token with all but the last 4 characters masked (for example ***bc4d). The full token and URL are returned only when the link is created." } }, "required": [ "proposedAgents", "status", "createdAt", "name", "expiresAt", "tags", "maskedToken" ], "additionalProperties": false, "title": "InvitationLinkMetadataAttributes" }, "relationships": { "type": "object", "properties": { "delegateeParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that created this link." } }, "required": [ "delegateeParty" ], "additionalProperties": false, "title": "InvitationLinkRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "InvitationLinkMetadataResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "invitationLink", "id": "ivl_019cd1798d9a054033f6006d22544b56", "attributes": { "proposedAgents": [ { "agentId": "agt_019cd1798d637a4da75dce386343931d", "permissions": [ "payments.read", "payments.create" ], "limits": { "perTransaction": 100000 } } ], "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "name": "Q3 carrier onboarding", "expiresAt": null, "tags": { "campaign": "q3_carrier_onboarding" }, "maskedToken": "***yLtN" }, "relationships": { "delegateeParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] } }, "/customers/invitation-links/{linkId}/revoke": { "post": { "operationId": "invitationLinks.revoke", "summary": "Revoke invitation link", "description": "Revoke an invitation link so it stops connecting new customers", "tags": [ "Invitation Links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ivl_[0-9a-f]{32}$", "description": "Invitation link ID (ivl_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `invitationLink`.", "type": "string", "enum": [ "invitationLink" ] }, "id": { "type": "string", "pattern": "^ivl_[0-9a-f]{32}$", "description": "Invitation link ID (ivl_*)." }, "attributes": { "type": "object", "properties": { "proposedAgents": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "permissions": { "type": "array", "items": { "enum": [ "disputes.read", "disputes.create", "payments.read", "payments.create", "external_parties.read", "external_parties.create", "direct.read", "direct.create", "external_accounts.create", "wallets.read", "wallets.balance", "wallets.create", "wallets.update", "wallets.fund", "wallets.deposit", "wallets.transfer", "wallets.withdraw", "party.read", "party.update", "payment_intents.create", "payment_intents.read", "card_payments.read", "refunds.read", "refunds.create", "voice_sessions.read", "voice_sessions.create", "chargebacks.read", "chargebacks.respond", "mandates.read", "enrollment.read", "cards.read", "saved_cards.use", "paymentRequests.read", "paymentRequests.create", "externalParties.read", "externalParties.create", "externalAccounts.read", "externalAccounts.create", "paymentIntents.read", "paymentIntents.create", "cardPayments.read", "voiceSessions.read", "voiceSessions.create", "savedCards.use" ], "type": "string" }, "description": "Permissions granted to this agent when a customer approves." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "type": "integer", "exclusiveMinimum": 0, "description": "Per-transaction limit in cents." } }, "required": [ "perTransaction" ], "additionalProperties": false }, { "type": "null" } ], "description": "Proposed per-transaction limit, or null when no limit is offered." } }, "required": [ "agentId", "permissions", "limits" ], "additionalProperties": false }, "description": "Agents offered to customers who open this link." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Link status." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this link was created." }, "name": { "type": "string", "description": "Label for this link." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this link stops accepting new customers, or null when it never expires." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "maskedToken": { "type": "string", "description": "Link token with all but the last 4 characters masked (for example ***bc4d). The full token and URL are returned only when the link is created." } }, "required": [ "proposedAgents", "status", "createdAt", "name", "expiresAt", "tags", "maskedToken" ], "additionalProperties": false, "title": "InvitationLinkMetadataAttributes" }, "relationships": { "type": "object", "properties": { "delegateeParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that created this link." } }, "required": [ "delegateeParty" ], "additionalProperties": false, "title": "InvitationLinkRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "InvitationLinkMetadataResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "invitationLink", "id": "ivl_019cd1798d9a054033f6006d22544b56", "attributes": { "proposedAgents": [ { "agentId": "agt_019cd1798d637a4da75dce386343931d", "permissions": [ "payments.read", "payments.create" ], "limits": { "perTransaction": 100000 } } ], "status": "REVOKED", "createdAt": "2026-01-04T15:30:00.000Z", "name": "Q3 carrier onboarding", "expiresAt": null, "tags": { "campaign": "q3_carrier_onboarding" }, "maskedToken": "***yLtN" }, "relationships": { "delegateeParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] } }, "/payments": { "post": { "operationId": "payments.create", "summary": "Create payment", "description": "Create a payment", "tags": [ "Payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "maxLength": 254, "format": "email", "description": "Email address." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "maxLength": 16, "description": "Phone number." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent_id" ] }, "value": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Natural agent ID (agt_*)." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "handle" ] }, "value": { "type": "string", "maxLength": 62, "description": "Natural handle (@handle or @handle-slug)." } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "PaymentRecipientCounterparty", "description": "Payment recipient. Agent recipients use their preferred wallet or their party's default wallet." }, "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code." }, "description": { "type": "string", "maxLength": 80, "description": "Payment description. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.", "maxProperties": 30 }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Source wallet ID (wal_*). Omit to use the party default for user or party API calls, or the agent default for the current customer connection when acting through a connected agent. Owned agents use their own agent default." } }, "required": [ "amount", "counterparty" ], "additionalProperties": false, "title": "PaymentCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 50000, "currency": "USD", "counterparty": { "type": "party_id", "value": "pty_019cd1798d681091fcf1dc98afb72d01" }, "description": "Q4 development work", "tags": { "order_id": "ord_123" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was submitted to money movement, or null while unsubmitted." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment reached a terminal status, or null while in flight." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this payment failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this payment was returned." }, "claim": { "anyOf": [ { "type": "object", "properties": { "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient began claiming this payment, or null while unclaimed or unobserved." }, "claimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient claimed this payment, or null while unclaimed." }, "unboundAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when a claimed payment detached from its recipient, or null." } }, "required": [ "startedAt", "claimedAt", "unboundAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Claim lifecycle for payments sent to an off-platform recipient, or null when this payment is not claim-based." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was last updated, or null." }, "claimLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Link an off-platform recipient uses to claim this payment, or null when the recipient is already on Natural. Returned only here, when the payment is created. The token behind it is never stored, so it cannot be fetched later. It stays valid even if the payment goes through approval. Treat it as a secret: anyone holding the link can claim the funds." } }, "required": [ "amount", "currency", "status", "description", "tags", "fee", "submittedAt", "terminalAt", "failure", "return", "claim", "createdAt", "updatedAt" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "initiatorAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentCreateResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_019cd1798d77ef3e74d16143bd39940a", "attributes": { "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Q4 development work", "tags": { "order_id": "ord_123" }, "fee": { "amount": 50, "currency": "USD", "payer": "sender", "applied": "on_top" }, "submittedAt": "2026-01-04T15:30:00.000Z", "terminalAt": null, "failure": null, "return": null, "claim": null, "claimLink": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "sender": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d6672a7b828eee780291b72" } }, "paymentRequest": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "payments.list", "summary": "List payments", "description": "List sent payments", "tags": [ "Payments" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was submitted to money movement, or null while unsubmitted." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment reached a terminal status, or null while in flight." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this payment failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this payment was returned." }, "claim": { "anyOf": [ { "type": "object", "properties": { "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient began claiming this payment, or null while unclaimed or unobserved." }, "claimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient claimed this payment, or null while unclaimed." }, "unboundAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when a claimed payment detached from its recipient, or null." } }, "required": [ "startedAt", "claimedAt", "unboundAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Claim lifecycle for payments sent to an off-platform recipient, or null when this payment is not claim-based." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was last updated, or null." } }, "required": [ "amount", "currency", "status", "description", "tags", "fee", "submittedAt", "terminalAt", "failure", "return", "claim", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "initiatorAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PaymentListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "payment", "id": "pay_019cd1798d77ef3e74d16143bd39940a", "attributes": { "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Q4 development work", "tags": { "order_id": "ord_123" }, "fee": { "amount": 50, "currency": "USD", "payer": "sender", "applied": "on_top" }, "submittedAt": "2026-01-04T15:30:00.000Z", "terminalAt": null, "failure": null, "return": null, "claim": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "sender": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d6672a7b828eee780291b72" } }, "paymentRequest": { "data": null } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/payments/{paymentId}": { "get": { "operationId": "payments.get", "summary": "Get payment", "description": "Get a sent payment", "tags": [ "Payments" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was submitted to money movement, or null while unsubmitted." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment reached a terminal status, or null while in flight." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this payment failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this payment was returned." }, "claim": { "anyOf": [ { "type": "object", "properties": { "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient began claiming this payment, or null while unclaimed or unobserved." }, "claimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient claimed this payment, or null while unclaimed." }, "unboundAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when a claimed payment detached from its recipient, or null." } }, "required": [ "startedAt", "claimedAt", "unboundAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Claim lifecycle for payments sent to an off-platform recipient, or null when this payment is not claim-based." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was last updated, or null." } }, "required": [ "amount", "currency", "status", "description", "tags", "fee", "submittedAt", "terminalAt", "failure", "return", "claim", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "initiatorAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_019cd1798d77ef3e74d16143bd39940a", "attributes": { "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Q4 development work", "tags": { "order_id": "ord_123" }, "fee": { "amount": 50, "currency": "USD", "payer": "sender", "applied": "on_top" }, "submittedAt": "2026-01-04T15:30:00.000Z", "terminalAt": null, "failure": null, "return": null, "claim": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "sender": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d6672a7b828eee780291b72" } }, "paymentRequest": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/payments/{paymentId}/cancel": { "post": { "operationId": "payments.cancel", "summary": "Cancel payment", "description": "Cancel a payment before the recipient begins claiming it", "tags": [ "Payments" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." } }, { "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": false, "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": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." } }, "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "customerPartyId": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was submitted to money movement, or null while unsubmitted." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment reached a terminal status, or null while in flight." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this payment failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this payment was returned." }, "claim": { "anyOf": [ { "type": "object", "properties": { "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient began claiming this payment, or null while unclaimed or unobserved." }, "claimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient claimed this payment, or null while unclaimed." }, "unboundAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when a claimed payment detached from its recipient, or null." } }, "required": [ "startedAt", "claimedAt", "unboundAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Claim lifecycle for payments sent to an off-platform recipient, or null when this payment is not claim-based." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was last updated, or null." } }, "required": [ "amount", "currency", "status", "description", "tags", "fee", "submittedAt", "terminalAt", "failure", "return", "claim", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "initiatorAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_019cd1798d77ef3e74d16143bd39940a", "attributes": { "amount": 50000, "currency": "USD", "status": "CANCELED", "description": "Q4 development work", "tags": { "order_id": "ord_123" }, "fee": null, "submittedAt": "2026-01-04T15:30:00.000Z", "terminalAt": null, "failure": null, "return": null, "claim": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:35:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "sender": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d6672a7b828eee780291b72" } }, "paymentRequest": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/external-parties": { "post": { "operationId": "externalParties.create", "summary": "Create external party", "description": "Create an external party to transact with over Direct", "tags": [ "External Parties" ], "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "External party name." }, "email": { "type": "string", "maxLength": 254, "format": "email", "description": "External party email address." }, "phone": { "type": "string", "minLength": 1, "maxLength": 32, "description": "External party phone number. It is normalized to E.164." }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Street address line 1." }, "line2": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Street address line 2." }, "city": { "type": "string", "minLength": 1, "maxLength": 255, "description": "City." }, "state": { "type": "string", "minLength": 1, "maxLength": 255, "description": "State or province. Required for US addresses." }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Postal or ZIP code. Required for US addresses." }, "countryCode": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 country code." } }, "required": [ "line1", "city", "countryCode" ], "additionalProperties": false, "description": "Address. US addresses require `state` and `postalCode`." } }, "required": [ "kind", "name" ], "additionalProperties": false, "title": "CreateExternalPartyAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateExternalPartyRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "kind": "individual", "name": "Jordan Rivera", "email": "jordan@example.com", "phone": "+1 415 555 0132", "address": { "line1": "123 Market St", "city": "San Francisco", "state": "CA", "postalCode": "94105", "countryCode": "US" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party ID (epty_*)." }, "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "attributes": { "type": "object", "properties": { "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "name": { "type": "string", "description": "External party display or legal name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized email address, if supplied." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized E.164 phone number, if supplied." }, "address": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Street address line 1." }, "line2": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Street address line 2, or null." }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "City." }, "state": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "State or province, or null." }, "postalCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ], "description": "Postal or ZIP code, or null." }, "countryCode": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2 country code." } }, "required": [ "line1", "line2", "city", "state", "postalCode", "countryCode" ], "additionalProperties": false, "title": "ExternalPartyAddress" }, { "type": "null" } ], "description": "External party address." }, "addressVersion": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Address revision for concurrent correction checks. Null on older cached create responses; get the external party before correction." }, "screeningStatus": { "enum": [ "clear", "under_review", "rejected" ], "type": "string", "description": "Sanctions screening disposition." }, "archivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the external party was archived, or null while active." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the external party was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the external party was last updated." } }, "required": [ "kind", "name", "email", "phone", "address", "addressVersion", "screeningStatus", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "ExternalPartyAttributes" }, "relationships": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "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": "Customer party." } }, "required": [ "customer" ], "additionalProperties": false, "title": "ExternalPartyRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalPartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ExternalPartyResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "epty_019cd1798d8d6873421613705e3c1415", "type": "external_party", "attributes": { "kind": "individual", "name": "Jordan Rivera", "email": "jordan@example.com", "phone": "+14155550132", "address": { "line1": "123 Market St", "line2": null, "city": "San Francisco", "state": "CA", "postalCode": "94105", "countryCode": "US" }, "addressVersion": 0, "screeningStatus": "clear", "archivedAt": null, "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T15:30:00.000Z" }, "relationships": { "customer": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "externalParties.list", "summary": "List external parties", "description": "List your external parties", "tags": [ "External Parties" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party ID (epty_*)." }, "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "attributes": { "type": "object", "properties": { "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "name": { "type": "string", "description": "External party display or legal name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized email address, if supplied." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized E.164 phone number, if supplied." }, "address": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Street address line 1." }, "line2": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Street address line 2, or null." }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "City." }, "state": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "State or province, or null." }, "postalCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ], "description": "Postal or ZIP code, or null." }, "countryCode": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2 country code." } }, "required": [ "line1", "line2", "city", "state", "postalCode", "countryCode" ], "additionalProperties": false, "title": "ExternalPartyAddress" }, { "type": "null" } ], "description": "External party address." }, "addressVersion": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Address revision for concurrent correction checks. Null on older cached create responses; get the external party before correction." }, "screeningStatus": { "enum": [ "clear", "under_review", "rejected" ], "type": "string", "description": "Sanctions screening disposition." }, "archivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the external party was archived, or null while active." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the external party was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the external party was last updated." } }, "required": [ "kind", "name", "email", "phone", "address", "addressVersion", "screeningStatus", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "ExternalPartyAttributes" }, "relationships": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "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": "Customer party." } }, "required": [ "customer" ], "additionalProperties": false, "title": "ExternalPartyRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalPartyResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ExternalPartyListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "epty_019cd1798d8d6873421613705e3c1415", "type": "external_party", "attributes": { "kind": "individual", "name": "Jordan Rivera", "email": "jordan@example.com", "phone": "+14155550132", "address": { "line1": "123 Market St", "line2": null, "city": "San Francisco", "state": "CA", "postalCode": "94105", "countryCode": "US" }, "addressVersion": 0, "screeningStatus": "clear", "archivedAt": null, "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T15:30:00.000Z" }, "relationships": { "customer": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/external-parties/{externalPartyId}": { "get": { "operationId": "externalParties.get", "summary": "Get external party", "description": "Get an external party", "tags": [ "External Parties" ], "parameters": [ { "name": "externalPartyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party ID (epty_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": "^epty_[0-9a-f]{32}$", "description": "External party ID (epty_*)." }, "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "attributes": { "type": "object", "properties": { "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "name": { "type": "string", "description": "External party display or legal name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized email address, if supplied." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized E.164 phone number, if supplied." }, "address": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Street address line 1." }, "line2": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Street address line 2, or null." }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "City." }, "state": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "State or province, or null." }, "postalCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ], "description": "Postal or ZIP code, or null." }, "countryCode": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2 country code." } }, "required": [ "line1", "line2", "city", "state", "postalCode", "countryCode" ], "additionalProperties": false, "title": "ExternalPartyAddress" }, { "type": "null" } ], "description": "External party address." }, "addressVersion": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Address revision for concurrent correction checks. Null on older cached create responses; get the external party before correction." }, "screeningStatus": { "enum": [ "clear", "under_review", "rejected" ], "type": "string", "description": "Sanctions screening disposition." }, "archivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the external party was archived, or null while active." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the external party was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the external party was last updated." } }, "required": [ "kind", "name", "email", "phone", "address", "addressVersion", "screeningStatus", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "ExternalPartyAttributes" }, "relationships": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "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": "Customer party." } }, "required": [ "customer" ], "additionalProperties": false, "title": "ExternalPartyRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalPartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ExternalPartyResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "epty_019cd1798d8d6873421613705e3c1415", "type": "external_party", "attributes": { "kind": "individual", "name": "Jordan Rivera", "email": "jordan@example.com", "phone": "+14155550132", "address": { "line1": "123 Market St", "line2": null, "city": "San Francisco", "state": "CA", "postalCode": "94105", "countryCode": "US" }, "addressVersion": 0, "screeningStatus": "clear", "archivedAt": null, "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T15:30:00.000Z" }, "relationships": { "customer": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] } }, "/external-parties/{externalPartyId}/address": { "patch": { "operationId": "externalParties.correctAddress", "summary": "Correct an external party address", "description": "Update an external party's address and resynchronize its bank accounts", "tags": [ "External Parties" ], "parameters": [ { "name": "externalPartyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party ID (epty_*)." } }, { "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "expectedAddressVersion": { "type": "integer", "minimum": 0, "description": "`addressVersion` read from the external party. The correction is rejected with `external_party.address_conflict` when it has changed." }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Street address line 1." }, "line2": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Street address line 2." }, "city": { "type": "string", "minLength": 1, "maxLength": 255, "description": "City." }, "state": { "type": "string", "minLength": 1, "maxLength": 255, "description": "State or province. Required for US addresses." }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Postal or ZIP code. Required for US addresses." }, "countryCode": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 country code." } }, "required": [ "line1", "city", "countryCode" ], "additionalProperties": false, "title": "ExternalPartyCompleteAddress", "description": "Complete replacement address." } }, "required": [ "expectedAddressVersion", "address" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "expectedAddressVersion": 0, "address": { "line1": "456 Market St", "city": "San Francisco", "state": "CA", "postalCode": "94105", "countryCode": "US" } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party ID (epty_*)." }, "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "attributes": { "type": "object", "properties": { "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "name": { "type": "string", "description": "External party display or legal name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized email address, if supplied." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized E.164 phone number, if supplied." }, "address": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Street address line 1." }, "line2": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Street address line 2, or null." }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "City." }, "state": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "State or province, or null." }, "postalCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ], "description": "Postal or ZIP code, or null." }, "countryCode": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2 country code." } }, "required": [ "line1", "line2", "city", "state", "postalCode", "countryCode" ], "additionalProperties": false, "title": "ExternalPartyAddress" }, { "type": "null" } ], "description": "External party address." }, "addressVersion": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Address revision for concurrent correction checks. Null on older cached create responses; get the external party before correction." }, "screeningStatus": { "enum": [ "clear", "under_review", "rejected" ], "type": "string", "description": "Sanctions screening disposition." }, "archivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the external party was archived, or null while active." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the external party was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the external party was last updated." } }, "required": [ "kind", "name", "email", "phone", "address", "addressVersion", "screeningStatus", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "ExternalPartyAttributes" }, "relationships": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "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": "Customer party." } }, "required": [ "customer" ], "additionalProperties": false, "title": "ExternalPartyRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalPartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ExternalPartyResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "epty_019cd1798d8d6873421613705e3c1415", "type": "external_party", "attributes": { "kind": "individual", "name": "Jordan Rivera", "email": "jordan@example.com", "phone": "+14155550132", "address": { "line1": "456 Market St", "line2": null, "city": "San Francisco", "state": "CA", "postalCode": "94105", "countryCode": "US" }, "addressVersion": 1, "screeningStatus": "clear", "archivedAt": null, "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T16:00:00.000Z" }, "relationships": { "customer": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] } }, "/external-party-accounts": { "post": { "operationId": "externalPartyAccounts.create", "summary": "Store banking details for an external party", "description": "Store an external party's bank account details", "tags": [ "External Party Accounts" ], "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party ID (epty_*)." }, "accountDetails": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Account details type.", "type": "string", "enum": [ "us_bank_account" ] }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "accountNumber": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Bank account number." }, "routingNumber": { "type": "string", "minLength": 1, "maxLength": 500, "description": "9-digit ABA routing number." } }, "required": [ "type", "accountType", "accountNumber", "routingNumber" ], "additionalProperties": false, "title": "CreateUsBankAccountDetails" } ], "title": "CreateExternalPartyAccountDetails", "description": "Type-specific account details." }, "institutionName": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "Institution display name." } }, "required": [ "externalPartyId", "accountDetails" ], "additionalProperties": false, "title": "CreateExternalPartyAccountAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateExternalPartyAccountRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "externalPartyId": "epty_019cd1798d8d6873421613705e3c1415", "accountDetails": { "type": "us_bank_account", "accountType": "checking", "accountNumber": "123456786789", "routingNumber": "121000358" }, "institutionName": "First National Bank" } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account ID (epa_*)." }, "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "attributes": { "type": "object", "properties": { "accountDetails": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Account details type.", "type": "string", "enum": [ "us_bank_account" ] }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "type", "accountType", "last4", "mask" ], "additionalProperties": false, "title": "UsBankAccountDetails" } ], "title": "ExternalPartyAccountDetails", "description": "Type-specific account details." }, "validationState": { "enum": [ "pending", "validated", "failed" ], "type": "string", "description": "Account validation state. `pending` when validation could not complete at creation; it resolves asynchronously to `validated` or `failed`." }, "supportedRails": { "type": "array", "items": { "enum": [ "ach", "realtime", "wire" ], "type": "string" }, "description": "Advisory list of payment rails this account is expected to accept. Refreshed periodically from the payment network; the authoritative check happens when a payment is created." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the account was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the account was last updated." } }, "required": [ "accountDetails", "validationState", "supportedRails", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "ExternalPartyAccountAttributes" }, "relationships": { "type": "object", "properties": { "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party that owns the account." } }, "required": [ "externalParty" ], "additionalProperties": false, "title": "ExternalPartyAccountRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalPartyAccountResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ExternalPartyAccountResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a", "type": "external_party_account", "attributes": { "accountDetails": { "type": "us_bank_account", "accountType": "checking", "last4": "6789", "mask": "****6789" }, "validationState": "pending", "supportedRails": [ "ach", "realtime" ], "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T15:30:00.000Z" }, "relationships": { "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "externalPartyAccounts.list", "summary": "List external party accounts", "description": "List the accounts that belong to an external party", "tags": [ "External Party Accounts" ], "parameters": [ { "name": "externalPartyId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party ID (epty_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "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": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account ID (epa_*)." }, "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "attributes": { "type": "object", "properties": { "accountDetails": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Account details type.", "type": "string", "enum": [ "us_bank_account" ] }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "type", "accountType", "last4", "mask" ], "additionalProperties": false, "title": "UsBankAccountDetails" } ], "title": "ExternalPartyAccountDetails", "description": "Type-specific account details." }, "validationState": { "enum": [ "pending", "validated", "failed" ], "type": "string", "description": "Account validation state. `pending` when validation could not complete at creation; it resolves asynchronously to `validated` or `failed`." }, "supportedRails": { "type": "array", "items": { "enum": [ "ach", "realtime", "wire" ], "type": "string" }, "description": "Advisory list of payment rails this account is expected to accept. Refreshed periodically from the payment network; the authoritative check happens when a payment is created." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the account was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the account was last updated." } }, "required": [ "accountDetails", "validationState", "supportedRails", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "ExternalPartyAccountAttributes" }, "relationships": { "type": "object", "properties": { "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party that owns the account." } }, "required": [ "externalParty" ], "additionalProperties": false, "title": "ExternalPartyAccountRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalPartyAccountResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ExternalPartyAccountListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a", "type": "external_party_account", "attributes": { "accountDetails": { "type": "us_bank_account", "accountType": "checking", "last4": "6789", "mask": "****6789" }, "validationState": "validated", "supportedRails": [ "ach", "realtime" ], "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T15:30:00.000Z" }, "relationships": { "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/external-party-accounts/{externalPartyAccountId}": { "get": { "operationId": "externalPartyAccounts.get", "summary": "Get external party account", "description": "Get an external party account", "tags": [ "External Party Accounts" ], "parameters": [ { "name": "externalPartyAccountId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account ID (epa_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": "^epa_[0-9a-f]{32}$", "description": "External party account ID (epa_*)." }, "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "attributes": { "type": "object", "properties": { "accountDetails": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Account details type.", "type": "string", "enum": [ "us_bank_account" ] }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "type", "accountType", "last4", "mask" ], "additionalProperties": false, "title": "UsBankAccountDetails" } ], "title": "ExternalPartyAccountDetails", "description": "Type-specific account details." }, "validationState": { "enum": [ "pending", "validated", "failed" ], "type": "string", "description": "Account validation state. `pending` when validation could not complete at creation; it resolves asynchronously to `validated` or `failed`." }, "supportedRails": { "type": "array", "items": { "enum": [ "ach", "realtime", "wire" ], "type": "string" }, "description": "Advisory list of payment rails this account is expected to accept. Refreshed periodically from the payment network; the authoritative check happens when a payment is created." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the account was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the account was last updated." } }, "required": [ "accountDetails", "validationState", "supportedRails", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "ExternalPartyAccountAttributes" }, "relationships": { "type": "object", "properties": { "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party that owns the account." } }, "required": [ "externalParty" ], "additionalProperties": false, "title": "ExternalPartyAccountRelationships" } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalPartyAccountResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ExternalPartyAccountResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a", "type": "external_party_account", "attributes": { "accountDetails": { "type": "us_bank_account", "accountType": "checking", "last4": "6789", "mask": "****6789" }, "validationState": "validated", "supportedRails": [ "ach", "realtime" ], "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T15:30:00.000Z" }, "relationships": { "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } } } } } } } } }, "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": [] } ] } }, "/ach": { "post": { "operationId": "ach.create", "summary": "Create ACH payment", "description": "Create an ACH payment to an external party account", "tags": [ "ACH" ], "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "direction": { "enum": [ "credit" ], "type": "string", "description": "Direction of the payment." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code. Defaults to USD." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet (wal_*) that funds an ACH credit or receives an ACH debit. Omit to use the party default for user or party API calls, or the agent default for the current customer connection when acting through a connected agent. Owned agents use their own agent default." }, "externalPartyAccountId": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*) to pay." }, "companyEntryDescription": { "type": "string", "minLength": 1, "maxLength": 10, "description": "ACH company entry description. Delivered to the receiving bank on the entry. Maximum 10 characters." }, "internalDescription": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Description for your internal reference. Never shared with the counterparty or the banking network. Maximum 255 characters." }, "addenda": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Payment-related information carried to the receiving bank as the NACHA addenda record. Maximum 80 characters." } }, "required": [ "direction", "amount", "externalPartyAccountId", "companyEntryDescription" ], "additionalProperties": false, "title": "AchCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "AchCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "direction": "credit", "amount": 25000, "currency": "USD", "externalPartyAccountId": "epa_019cd1798d8e5a2f8ceb96020cc3991a", "companyEntryDescription": "PAYOUT", "addenda": "Invoice 1042, July services", "internalDescription": "July contractor payout, ledger 1042" } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `ach`.", "type": "string", "enum": [ "ach" ] }, "id": { "type": "string", "pattern": "^ach_[0-9a-f]{32}$", "description": "ACH payment ID (ach_*)." }, "attributes": { "type": "object", "properties": { "direction": { "enum": [ "credit" ], "type": "string", "description": "Direction of the payment." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "SETTLED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "ACH payment status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, SETTLED; APPROVAL_DENIED, FAILED, RETURNED, or CANCELED end it." }, "companyEntryDescription": { "type": "string", "description": "The company entry description requested at creation. Echoes the create input verbatim; see `submittedDescriptor` for what was sent to the bank." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "addenda": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment-related information carried to the receiving bank as the NACHA addenda record, or null when none was provided." }, "secCode": { "enum": [ "WEB", "PPD", "TEL", "CCD" ], "type": "string", "description": "ACH SEC code the entry is submitted under: WEB, PPD, TEL, or CCD." }, "submittedDescriptor": { "type": "object", "properties": { "companyName": { "type": "string", "description": "Company name submitted on the ACH payment." }, "companyEntryDescription": { "type": "string", "description": "Company entry description submitted on the ACH payment." } }, "required": [ "companyName", "companyEntryDescription" ], "additionalProperties": false }, "traceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ACH trace number assigned at submission, or null before submission." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the payment failed, or null." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "ACH return code, such as R01." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, or null." }, "returnedAt": { "type": "string", "description": "RFC 3339 timestamp when the return was received." }, "dishonoredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the return was dishonored, or null." }, "contestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the dishonor was contested, or null." }, "fundsUnlockedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the returned funds were released, or null." } }, "required": [ "code", "reason", "returnedAt", "dishonoredAt", "contestedAt", "fundsUnlockedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when the payment was returned, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment was submitted to the bank, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the ACH payment settled, or null. A return can still arrive after settlement." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the ACH payment was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the ACH payment was last updated." } }, "required": [ "direction", "amount", "currency", "fee", "status", "companyEntryDescription", "internalDescription", "addenda", "secCode", "submittedDescriptor", "traceNumber", "failure", "return", "submittedAt", "settledAt", "expectedAvailableAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AchAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the payment was created for." }, "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 used for this payment." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party the payment is with." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account used." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": true, "title": "AchRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AchResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "ach", "id": "ach_019cd1798d838f575681880edfaa4c6f", "attributes": { "direction": "credit", "amount": 25000, "currency": "USD", "fee": { "amount": 25, "currency": "USD", "payer": "sender", "applied": "on_top" }, "status": "PROCESSING", "companyEntryDescription": "PAYOUT", "internalDescription": "July contractor payout, ledger 1042", "addenda": "Invoice 1042, July services", "secCode": "PPD", "submittedDescriptor": { "companyName": "Acme Payments", "companyEntryDescription": "PAYOUT" }, "traceNumber": null, "failure": null, "return": null, "submittedAt": "2026-08-04T15:30:00.000Z", "settledAt": null, "expectedAvailableAt": "2026-08-05T14:00:00.000Z", "terminalAt": null, "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "ach.list", "summary": "List ACH payments", "description": "List your ACH payments", "tags": [ "ACH" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "SETTLED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Filter by status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "direction", "in": "query", "schema": { "enum": [ "credit" ], "type": "string", "description": "Filter by direction." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "externalPartyId", "in": "query", "schema": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "Only payments to this external party (epty_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "externalPartyAccountId", "in": "query", "schema": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "Only payments using this account (epa_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `ach`.", "type": "string", "enum": [ "ach" ] }, "id": { "type": "string", "pattern": "^ach_[0-9a-f]{32}$", "description": "ACH payment ID (ach_*)." }, "attributes": { "type": "object", "properties": { "direction": { "enum": [ "credit" ], "type": "string", "description": "Direction of the payment." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "SETTLED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "ACH payment status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, SETTLED; APPROVAL_DENIED, FAILED, RETURNED, or CANCELED end it." }, "companyEntryDescription": { "type": "string", "description": "The company entry description requested at creation. Echoes the create input verbatim; see `submittedDescriptor` for what was sent to the bank." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "addenda": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment-related information carried to the receiving bank as the NACHA addenda record, or null when none was provided." }, "secCode": { "enum": [ "WEB", "PPD", "TEL", "CCD" ], "type": "string", "description": "ACH SEC code the entry is submitted under: WEB, PPD, TEL, or CCD." }, "submittedDescriptor": { "type": "object", "properties": { "companyName": { "type": "string", "description": "Company name submitted on the ACH payment." }, "companyEntryDescription": { "type": "string", "description": "Company entry description submitted on the ACH payment." } }, "required": [ "companyName", "companyEntryDescription" ], "additionalProperties": false }, "traceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ACH trace number assigned at submission, or null before submission." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the payment failed, or null." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "ACH return code, such as R01." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, or null." }, "returnedAt": { "type": "string", "description": "RFC 3339 timestamp when the return was received." }, "dishonoredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the return was dishonored, or null." }, "contestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the dishonor was contested, or null." }, "fundsUnlockedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the returned funds were released, or null." } }, "required": [ "code", "reason", "returnedAt", "dishonoredAt", "contestedAt", "fundsUnlockedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when the payment was returned, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment was submitted to the bank, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the ACH payment settled, or null. A return can still arrive after settlement." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the ACH payment was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the ACH payment was last updated." } }, "required": [ "direction", "amount", "currency", "fee", "status", "companyEntryDescription", "internalDescription", "addenda", "secCode", "submittedDescriptor", "traceNumber", "failure", "return", "submittedAt", "settledAt", "expectedAvailableAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AchAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the payment was created for." }, "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 used for this payment." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party the payment is with." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account used." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": true, "title": "AchRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AchResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "ach", "id": "ach_019cd1798d838f575681880edfaa4c6f", "attributes": { "direction": "credit", "amount": 25000, "currency": "USD", "fee": { "amount": 25, "currency": "USD", "payer": "sender", "applied": "on_top" }, "status": "PROCESSING", "companyEntryDescription": "PAYOUT", "internalDescription": "July contractor payout, ledger 1042", "addenda": "Invoice 1042, July services", "secCode": "PPD", "submittedDescriptor": { "companyName": "Acme Payments", "companyEntryDescription": "PAYOUT" }, "traceNumber": null, "failure": null, "return": null, "submittedAt": "2026-08-04T15:30:00.000Z", "settledAt": null, "expectedAvailableAt": "2026-08-05T14:00:00.000Z", "terminalAt": null, "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/ach/{achId}": { "get": { "operationId": "ach.get", "summary": "Get ACH payment", "description": "Get an ACH payment", "tags": [ "ACH" ], "parameters": [ { "name": "achId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ach_[0-9a-f]{32}$", "description": "ACH payment ID (ach_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "type": { "description": "Resource type. Always `ach`.", "type": "string", "enum": [ "ach" ] }, "id": { "type": "string", "pattern": "^ach_[0-9a-f]{32}$", "description": "ACH payment ID (ach_*)." }, "attributes": { "type": "object", "properties": { "direction": { "enum": [ "credit" ], "type": "string", "description": "Direction of the payment." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "SETTLED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "ACH payment status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, SETTLED; APPROVAL_DENIED, FAILED, RETURNED, or CANCELED end it." }, "companyEntryDescription": { "type": "string", "description": "The company entry description requested at creation. Echoes the create input verbatim; see `submittedDescriptor` for what was sent to the bank." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "addenda": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment-related information carried to the receiving bank as the NACHA addenda record, or null when none was provided." }, "secCode": { "enum": [ "WEB", "PPD", "TEL", "CCD" ], "type": "string", "description": "ACH SEC code the entry is submitted under: WEB, PPD, TEL, or CCD." }, "submittedDescriptor": { "type": "object", "properties": { "companyName": { "type": "string", "description": "Company name submitted on the ACH payment." }, "companyEntryDescription": { "type": "string", "description": "Company entry description submitted on the ACH payment." } }, "required": [ "companyName", "companyEntryDescription" ], "additionalProperties": false }, "traceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ACH trace number assigned at submission, or null before submission." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the payment failed, or null." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "ACH return code, such as R01." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, or null." }, "returnedAt": { "type": "string", "description": "RFC 3339 timestamp when the return was received." }, "dishonoredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the return was dishonored, or null." }, "contestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the dishonor was contested, or null." }, "fundsUnlockedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the returned funds were released, or null." } }, "required": [ "code", "reason", "returnedAt", "dishonoredAt", "contestedAt", "fundsUnlockedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when the payment was returned, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment was submitted to the bank, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the ACH payment settled, or null. A return can still arrive after settlement." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the ACH payment was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the ACH payment was last updated." } }, "required": [ "direction", "amount", "currency", "fee", "status", "companyEntryDescription", "internalDescription", "addenda", "secCode", "submittedDescriptor", "traceNumber", "failure", "return", "submittedAt", "settledAt", "expectedAvailableAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AchAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the payment was created for." }, "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 used for this payment." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party the payment is with." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account used." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": true, "title": "AchRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AchResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "ach", "id": "ach_019cd1798d838f575681880edfaa4c6f", "attributes": { "direction": "credit", "amount": 25000, "currency": "USD", "fee": { "amount": 25, "currency": "USD", "payer": "sender", "applied": "on_top" }, "status": "PROCESSING", "companyEntryDescription": "PAYOUT", "internalDescription": "July contractor payout, ledger 1042", "addenda": "Invoice 1042, July services", "secCode": "PPD", "submittedDescriptor": { "companyName": "Acme Payments", "companyEntryDescription": "PAYOUT" }, "traceNumber": null, "failure": null, "return": null, "submittedAt": "2026-08-04T15:30:00.000Z", "settledAt": null, "expectedAvailableAt": "2026-08-05T14:00:00.000Z", "terminalAt": null, "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } } } } } }, "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": [] } ] } }, "/ach/{achId}/cancel": { "post": { "operationId": "ach.cancel", "summary": "Cancel ACH payment", "description": "Cancel an ACH payment before submission", "tags": [ "ACH" ], "parameters": [ { "name": "achId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ach_[0-9a-f]{32}$", "description": "ACH payment ID (ach_*)." } }, { "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": { "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "reason": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Why the payment is being canceled. Maximum 100 characters." } }, "required": [ "reason" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "AchCancelRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "reason": "Duplicate payout" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `ach`.", "type": "string", "enum": [ "ach" ] }, "id": { "type": "string", "pattern": "^ach_[0-9a-f]{32}$", "description": "ACH payment ID (ach_*)." }, "attributes": { "type": "object", "properties": { "direction": { "enum": [ "credit" ], "type": "string", "description": "Direction of the payment." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "SETTLED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "ACH payment status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, SETTLED; APPROVAL_DENIED, FAILED, RETURNED, or CANCELED end it." }, "companyEntryDescription": { "type": "string", "description": "The company entry description requested at creation. Echoes the create input verbatim; see `submittedDescriptor` for what was sent to the bank." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "addenda": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment-related information carried to the receiving bank as the NACHA addenda record, or null when none was provided." }, "secCode": { "enum": [ "WEB", "PPD", "TEL", "CCD" ], "type": "string", "description": "ACH SEC code the entry is submitted under: WEB, PPD, TEL, or CCD." }, "submittedDescriptor": { "type": "object", "properties": { "companyName": { "type": "string", "description": "Company name submitted on the ACH payment." }, "companyEntryDescription": { "type": "string", "description": "Company entry description submitted on the ACH payment." } }, "required": [ "companyName", "companyEntryDescription" ], "additionalProperties": false }, "traceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ACH trace number assigned at submission, or null before submission." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the payment failed, or null." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "description": "ACH return code, such as R01." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, or null." }, "returnedAt": { "type": "string", "description": "RFC 3339 timestamp when the return was received." }, "dishonoredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the return was dishonored, or null." }, "contestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the dishonor was contested, or null." }, "fundsUnlockedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the returned funds were released, or null." } }, "required": [ "code", "reason", "returnedAt", "dishonoredAt", "contestedAt", "fundsUnlockedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when the payment was returned, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment was submitted to the bank, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the ACH payment settled, or null. A return can still arrive after settlement." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the ACH payment was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the ACH payment was last updated." } }, "required": [ "direction", "amount", "currency", "fee", "status", "companyEntryDescription", "internalDescription", "addenda", "secCode", "submittedDescriptor", "traceNumber", "failure", "return", "submittedAt", "settledAt", "expectedAvailableAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AchAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the payment was created for." }, "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 used for this payment." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party the payment is with." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account used." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": true, "title": "AchRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AchResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "ach", "id": "ach_019cd1798d838f575681880edfaa4c6f", "attributes": { "direction": "credit", "amount": 25000, "currency": "USD", "fee": null, "status": "CANCELED", "companyEntryDescription": "PAYOUT", "internalDescription": "July contractor payout, ledger 1042", "addenda": "Invoice 1042, July services", "secCode": "PPD", "submittedDescriptor": { "companyName": "Acme Payments", "companyEntryDescription": "PAYOUT" }, "traceNumber": null, "failure": null, "return": null, "submittedAt": null, "settledAt": null, "expectedAvailableAt": null, "terminalAt": "2026-08-04T16:00:00.000Z", "createdAt": "2026-08-04T15:30:00.000Z", "updatedAt": "2026-08-04T16:00:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } } } } } }, "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": [] } ] } }, "/realtime": { "post": { "operationId": "realtime.create", "summary": "Create realtime payment", "description": "Create a realtime payment to an external party account", "tags": [ "Realtime" ], "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code. Defaults to USD." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet (wal_*) to pay from. Omit to use the party default for user or party API calls, or the agent default for the current customer connection when acting through a connected agent. Owned agents use their own agent default." }, "externalPartyAccountId": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*) to pay." }, "description": { "type": "string", "minLength": 1, "maxLength": 140, "pattern": "^[A-Za-z0-9 /?:().,'+-]+$", "description": "Payment description delivered to the recipient bank with the payment. Maximum 140 characters from the ISO 20022 character set (letters, digits, spaces, and / - ? : ( ) . , ' +)." }, "internalDescription": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Description for your internal reference. Never shared with the counterparty or the banking network. Maximum 255 characters." } }, "required": [ "amount", "externalPartyAccountId", "description" ], "additionalProperties": false, "title": "RealtimeCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "RealtimeCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 25000, "currency": "USD", "externalPartyAccountId": "epa_019cd1798d8e5a2f8ceb96020cc3991a", "description": "Invoice 1042 settlement", "internalDescription": "Vendor settlement, ledger 1042" } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `realtime`.", "type": "string", "enum": [ "realtime" ] }, "id": { "type": "string", "pattern": "^rt_[0-9a-f]{32}$", "description": "Realtime payment ID (rt_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the payment failed, was denied, or was canceled, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "SETTLED", "FAILED", "CANCELED" ], "type": "string", "description": "Realtime payment status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, SETTLED; APPROVAL_DENIED, FAILED, or CANCELED end it." }, "description": { "type": "string", "description": "Payment description delivered to the recipient bank." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the payment failed, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment was submitted to the network, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment settled, or null. Settled realtime payments cannot be returned." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the realtime payment was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the realtime payment was last updated." } }, "required": [ "amount", "currency", "fee", "status", "description", "internalDescription", "failure", "submittedAt", "settledAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "RealtimeAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the payment was created for." }, "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 payment pays from." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party paid." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account paid." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": false, "title": "RealtimeRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "RealtimeResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "realtime", "id": "rt_019cd1798d855ae91a83bde5392f3664", "attributes": { "amount": 25000, "currency": "USD", "fee": { "amount": 50, "currency": "USD", "payer": "sender", "applied": "on_top" }, "status": "PROCESSING", "description": "Invoice 1042 settlement", "internalDescription": "Vendor settlement, ledger 1042", "failure": null, "submittedAt": "2026-09-03T15:30:00.000Z", "settledAt": null, "terminalAt": null, "createdAt": "2026-09-03T15:30:00.000Z", "updatedAt": "2026-09-03T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "realtime.list", "summary": "List realtime payments", "description": "List your realtime payments", "tags": [ "Realtime" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "SETTLED", "FAILED", "CANCELED" ], "type": "string", "description": "Filter by status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "externalPartyId", "in": "query", "schema": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "Only payments to this external party (epty_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "externalPartyAccountId", "in": "query", "schema": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "Only payments using this account (epa_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `realtime`.", "type": "string", "enum": [ "realtime" ] }, "id": { "type": "string", "pattern": "^rt_[0-9a-f]{32}$", "description": "Realtime payment ID (rt_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the payment failed, was denied, or was canceled, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "SETTLED", "FAILED", "CANCELED" ], "type": "string", "description": "Realtime payment status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, SETTLED; APPROVAL_DENIED, FAILED, or CANCELED end it." }, "description": { "type": "string", "description": "Payment description delivered to the recipient bank." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the payment failed, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment was submitted to the network, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment settled, or null. Settled realtime payments cannot be returned." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the realtime payment was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the realtime payment was last updated." } }, "required": [ "amount", "currency", "fee", "status", "description", "internalDescription", "failure", "submittedAt", "settledAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "RealtimeAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the payment was created for." }, "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 payment pays from." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party paid." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account paid." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": false, "title": "RealtimeRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "RealtimeResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "realtime", "id": "rt_019cd1798d855ae91a83bde5392f3664", "attributes": { "amount": 25000, "currency": "USD", "fee": { "amount": 50, "currency": "USD", "payer": "sender", "applied": "on_top" }, "status": "SETTLED", "description": "Invoice 1042 settlement", "internalDescription": "Vendor settlement, ledger 1042", "failure": null, "submittedAt": "2026-09-03T15:30:00.000Z", "settledAt": "2026-09-03T15:30:05.000Z", "terminalAt": "2026-09-03T15:30:05.000Z", "createdAt": "2026-09-03T15:30:00.000Z", "updatedAt": "2026-09-03T15:30:05.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/realtime/{realtimeId}": { "get": { "operationId": "realtime.get", "summary": "Get realtime payment", "description": "Get a realtime payment", "tags": [ "Realtime" ], "parameters": [ { "name": "realtimeId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rt_[0-9a-f]{32}$", "description": "Realtime payment ID (rt_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "type": { "description": "Resource type. Always `realtime`.", "type": "string", "enum": [ "realtime" ] }, "id": { "type": "string", "pattern": "^rt_[0-9a-f]{32}$", "description": "Realtime payment ID (rt_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the payment failed, was denied, or was canceled, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "SETTLED", "FAILED", "CANCELED" ], "type": "string", "description": "Realtime payment status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, SETTLED; APPROVAL_DENIED, FAILED, or CANCELED end it." }, "description": { "type": "string", "description": "Payment description delivered to the recipient bank." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the payment failed, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment was submitted to the network, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment settled, or null. Settled realtime payments cannot be returned." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the realtime payment was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the realtime payment was last updated." } }, "required": [ "amount", "currency", "fee", "status", "description", "internalDescription", "failure", "submittedAt", "settledAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "RealtimeAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the payment was created for." }, "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 payment pays from." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party paid." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account paid." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": false, "title": "RealtimeRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "RealtimeResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "realtime", "id": "rt_019cd1798d855ae91a83bde5392f3664", "attributes": { "amount": 25000, "currency": "USD", "fee": { "amount": 50, "currency": "USD", "payer": "sender", "applied": "on_top" }, "status": "SETTLED", "description": "Invoice 1042 settlement", "internalDescription": "Vendor settlement, ledger 1042", "failure": null, "submittedAt": "2026-09-03T15:30:00.000Z", "settledAt": "2026-09-03T15:30:05.000Z", "terminalAt": "2026-09-03T15:30:05.000Z", "createdAt": "2026-09-03T15:30:00.000Z", "updatedAt": "2026-09-03T15:30:05.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } } } } } }, "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": [] } ] } }, "/realtime/{realtimeId}/cancel": { "post": { "operationId": "realtime.cancel", "summary": "Cancel realtime payment", "description": "Cancel a realtime payment before submission", "tags": [ "Realtime" ], "parameters": [ { "name": "realtimeId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rt_[0-9a-f]{32}$", "description": "Realtime payment ID (rt_*)." } }, { "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": { "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "reason": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Why the payment is being canceled. Maximum 100 characters." } }, "required": [ "reason" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "RealtimeCancelRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "reason": "Duplicate payment" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `realtime`.", "type": "string", "enum": [ "realtime" ] }, "id": { "type": "string", "pattern": "^rt_[0-9a-f]{32}$", "description": "Realtime payment ID (rt_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the payment failed, was denied, or was canceled, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "SETTLED", "FAILED", "CANCELED" ], "type": "string", "description": "Realtime payment status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, SETTLED; APPROVAL_DENIED, FAILED, or CANCELED end it." }, "description": { "type": "string", "description": "Payment description delivered to the recipient bank." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the payment failed, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment was submitted to the network, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment settled, or null. Settled realtime payments cannot be returned." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the payment reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the realtime payment was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the realtime payment was last updated." } }, "required": [ "amount", "currency", "fee", "status", "description", "internalDescription", "failure", "submittedAt", "settledAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "RealtimeAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the payment was created for." }, "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 payment pays from." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party paid." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account paid." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": false, "title": "RealtimeRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "RealtimeResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "realtime", "id": "rt_019cd1798d855ae91a83bde5392f3664", "attributes": { "amount": 25000, "currency": "USD", "fee": null, "status": "CANCELED", "description": "Invoice 1042 settlement", "internalDescription": "Vendor settlement, ledger 1042", "failure": null, "submittedAt": null, "settledAt": null, "terminalAt": "2026-09-03T16:00:00.000Z", "createdAt": "2026-09-03T15:30:00.000Z", "updatedAt": "2026-09-03T16:00:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } } } } } }, "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": [] } ] } }, "/wire": { "post": { "operationId": "wire.create", "summary": "Create wire payment", "description": "Create a wire payment to an external party account", "tags": [ "Wire" ], "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code. Defaults to USD." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet (wal_*) to pay from. Omit to use the party default for user or party API calls, or the agent default for the current customer connection when acting through a connected agent. Owned agents use their own agent default." }, "externalPartyAccountId": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*) to pay." }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Payment description stored for the sender's records. Not sent over Fedwire. Maximum 1000 characters." }, "remittanceInfo": { "type": "string", "minLength": 1, "maxLength": 105, "pattern": "^[A-Za-z0-9 /?:().,'+-]+$", "description": "Remittance information delivered to the beneficiary, combined with the originator name into the Fedwire OBI field. Maximum 105 characters: letters, digits, spaces, and / - ? : ( ) . , ' +." }, "internalDescription": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Description for your internal reference. Never shared with the counterparty or the banking network. Maximum 255 characters." } }, "required": [ "amount", "externalPartyAccountId", "description" ], "additionalProperties": false, "title": "WireCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "WireCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 25000, "currency": "USD", "externalPartyAccountId": "epa_019cd1798d8e5a2f8ceb96020cc3991a", "description": "Invoice 1042 settlement", "internalDescription": "Vendor settlement, ledger 1042" } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `wire`.", "type": "string", "enum": [ "wire" ] }, "id": { "type": "string", "pattern": "^wire_[0-9a-f]{32}$", "description": "Wire ID (wire_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the wire ended before network submission, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "COMPLETED", "REJECTED", "FAILED", "CANCELED" ], "type": "string", "description": "Wire status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, COMPLETED; APPROVAL_DENIED, REJECTED, FAILED, or CANCELED end it." }, "remittanceInfo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Remittance information delivered to the beneficiary, or null." }, "description": { "type": "string", "description": "Payment description stored for the sender's records. Not sent over Fedwire." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the wire failed, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire was submitted, or null." }, "rejectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire was rejected, or null." }, "expectedCompletionAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 estimate of when the wire completes, or null. Not a guarantee." }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire completed, or null." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the wire was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the wire was last updated." } }, "required": [ "amount", "currency", "fee", "status", "remittanceInfo", "description", "internalDescription", "failure", "submittedAt", "rejectedAt", "expectedCompletionAt", "completedAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WireAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the wire was created for." }, "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 wire pays from." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party paid." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account paid." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": false, "title": "WireRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WireResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wire", "id": "wire_019cd1798d875d7c0a4165d10dc4db29", "attributes": { "amount": 25000, "currency": "USD", "fee": { "amount": 50, "currency": "USD", "payer": "sender", "applied": "on_top" }, "status": "PROCESSING", "description": "Invoice 1042 settlement", "internalDescription": "Vendor settlement, ledger 1042", "failure": null, "remittanceInfo": null, "rejectedAt": null, "expectedCompletionAt": null, "submittedAt": "2026-09-03T15:30:00.000Z", "completedAt": null, "terminalAt": null, "createdAt": "2026-09-03T15:30:00.000Z", "updatedAt": "2026-09-03T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "wire.list", "summary": "List wire payments", "description": "List your wire payments", "tags": [ "Wire" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "COMPLETED", "REJECTED", "FAILED", "CANCELED" ], "type": "string", "description": "Filter by status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "externalPartyId", "in": "query", "schema": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "Only payments to this external party (epty_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "externalPartyAccountId", "in": "query", "schema": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "Only payments using this account (epa_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `wire`.", "type": "string", "enum": [ "wire" ] }, "id": { "type": "string", "pattern": "^wire_[0-9a-f]{32}$", "description": "Wire ID (wire_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the wire ended before network submission, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "COMPLETED", "REJECTED", "FAILED", "CANCELED" ], "type": "string", "description": "Wire status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, COMPLETED; APPROVAL_DENIED, REJECTED, FAILED, or CANCELED end it." }, "remittanceInfo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Remittance information delivered to the beneficiary, or null." }, "description": { "type": "string", "description": "Payment description stored for the sender's records. Not sent over Fedwire." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the wire failed, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire was submitted, or null." }, "rejectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire was rejected, or null." }, "expectedCompletionAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 estimate of when the wire completes, or null. Not a guarantee." }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire completed, or null." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the wire was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the wire was last updated." } }, "required": [ "amount", "currency", "fee", "status", "remittanceInfo", "description", "internalDescription", "failure", "submittedAt", "rejectedAt", "expectedCompletionAt", "completedAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WireAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the wire was created for." }, "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 wire pays from." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party paid." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account paid." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": false, "title": "WireRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WireResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "wire", "id": "wire_019cd1798d875d7c0a4165d10dc4db29", "attributes": { "amount": 25000, "currency": "USD", "fee": { "amount": 50, "currency": "USD", "payer": "sender", "applied": "on_top" }, "status": "COMPLETED", "description": "Invoice 1042 settlement", "internalDescription": "Vendor settlement, ledger 1042", "failure": null, "remittanceInfo": null, "rejectedAt": null, "expectedCompletionAt": null, "submittedAt": "2026-09-03T15:30:00.000Z", "completedAt": "2026-09-03T15:30:05.000Z", "terminalAt": "2026-09-03T15:30:05.000Z", "createdAt": "2026-09-03T15:30:00.000Z", "updatedAt": "2026-09-03T15:30:05.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/wire/{wireId}": { "get": { "operationId": "wire.get", "summary": "Get wire payment", "description": "Get a wire payment", "tags": [ "Wire" ], "parameters": [ { "name": "wireId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wire_[0-9a-f]{32}$", "description": "Wire ID (wire_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "type": { "description": "Resource type. Always `wire`.", "type": "string", "enum": [ "wire" ] }, "id": { "type": "string", "pattern": "^wire_[0-9a-f]{32}$", "description": "Wire ID (wire_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the wire ended before network submission, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "COMPLETED", "REJECTED", "FAILED", "CANCELED" ], "type": "string", "description": "Wire status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, COMPLETED; APPROVAL_DENIED, REJECTED, FAILED, or CANCELED end it." }, "remittanceInfo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Remittance information delivered to the beneficiary, or null." }, "description": { "type": "string", "description": "Payment description stored for the sender's records. Not sent over Fedwire." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the wire failed, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire was submitted, or null." }, "rejectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire was rejected, or null." }, "expectedCompletionAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 estimate of when the wire completes, or null. Not a guarantee." }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire completed, or null." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the wire was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the wire was last updated." } }, "required": [ "amount", "currency", "fee", "status", "remittanceInfo", "description", "internalDescription", "failure", "submittedAt", "rejectedAt", "expectedCompletionAt", "completedAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WireAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the wire was created for." }, "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 wire pays from." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party paid." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account paid." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": false, "title": "WireRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WireResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wire", "id": "wire_019cd1798d875d7c0a4165d10dc4db29", "attributes": { "amount": 25000, "currency": "USD", "fee": { "amount": 50, "currency": "USD", "payer": "sender", "applied": "on_top" }, "status": "COMPLETED", "description": "Invoice 1042 settlement", "internalDescription": "Vendor settlement, ledger 1042", "failure": null, "remittanceInfo": null, "rejectedAt": null, "expectedCompletionAt": null, "submittedAt": "2026-09-03T15:30:00.000Z", "completedAt": "2026-09-03T15:30:05.000Z", "terminalAt": "2026-09-03T15:30:05.000Z", "createdAt": "2026-09-03T15:30:00.000Z", "updatedAt": "2026-09-03T15:30:05.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } } } } } }, "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": [] } ] } }, "/wire/{wireId}/cancel": { "post": { "operationId": "wire.cancel", "summary": "Cancel wire payment", "description": "Cancel a wire payment before submission", "tags": [ "Wire" ], "parameters": [ { "name": "wireId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wire_[0-9a-f]{32}$", "description": "Wire ID (wire_*)." } }, { "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": { "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the wire is being canceled. Maximum 500 characters." } }, "required": [ "reason" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "WireCancelRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "reason": "Duplicate payment" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `wire`.", "type": "string", "enum": [ "wire" ] }, "id": { "type": "string", "pattern": "^wire_[0-9a-f]{32}$", "description": "Wire ID (wire_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the wire ended before network submission, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "AWAITING_APPROVAL", "APPROVAL_DENIED", "PROCESSING", "COMPLETED", "REJECTED", "FAILED", "CANCELED" ], "type": "string", "description": "Wire status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, COMPLETED; APPROVAL_DENIED, REJECTED, FAILED, or CANCELED end it." }, "remittanceInfo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Remittance information delivered to the beneficiary, or null." }, "description": { "type": "string", "description": "Payment description stored for the sender's records. Not sent over Fedwire." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for your internal reference, or null. Never shared with the counterparty or the banking network." }, "failure": { "anyOf": [ { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, or null." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, or null." } }, "required": [ "reason", "code" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when the wire failed, or null." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire was submitted, or null." }, "rejectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire was rejected, or null." }, "expectedCompletionAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 estimate of when the wire completes, or null. Not a guarantee." }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire completed, or null." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wire reached a terminal status, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the wire was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the wire was last updated." } }, "required": [ "amount", "currency", "fee", "status", "remittanceInfo", "description", "internalDescription", "failure", "submittedAt", "rejectedAt", "expectedCompletionAt", "completedAt", "terminalAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WireAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party the wire was created for." }, "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 wire pays from." }, "externalParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party`.", "type": "string", "enum": [ "external_party" ] }, "id": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party paid." }, "externalPartyAccount": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `external_party_account`.", "type": "string", "enum": [ "external_party_account" ] }, "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "External party account paid." } }, "required": [ "initiatorAgent", "customerParty", "wallet", "externalParty", "externalPartyAccount" ], "additionalProperties": false, "title": "WireRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WireResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wire", "id": "wire_019cd1798d875d7c0a4165d10dc4db29", "attributes": { "amount": 25000, "currency": "USD", "fee": null, "status": "CANCELED", "description": "Invoice 1042 settlement", "internalDescription": "Vendor settlement, ledger 1042", "failure": null, "remittanceInfo": null, "rejectedAt": null, "expectedCompletionAt": null, "submittedAt": null, "completedAt": null, "terminalAt": "2026-09-03T16:00:00.000Z", "createdAt": "2026-09-03T15:30:00.000Z", "updatedAt": "2026-09-03T16:00:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalParty": { "data": { "type": "external_party", "id": "epty_019cd1798d8d6873421613705e3c1415" } }, "externalPartyAccount": { "data": { "type": "external_party_account", "id": "epa_019cd1798d8e5a2f8ceb96020cc3991a" } } } } } } } } }, "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": [] } ] } }, "/payment-intents": { "post": { "operationId": "paymentIntents.create", "summary": "Create payment intent", "description": "Create a payment intent with a hosted checkout link", "tags": [ "Payment Intents" ], "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 act for (pty_*). Omit for your own account. Requires authorization from that customer." }, "amount": { "type": "integer", "minimum": 1, "description": "Total amount in US 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 no new payment attempt may start." }, "taxMode": { "enum": [ "exclusive", "inclusive" ], "type": "string", "default": "exclusive", "description": "Whether tax is added to or included in line amounts." }, "taxAmount": { "type": "integer", "minimum": 0, "description": "Tax in cents when lineItems is empty. Defaults to zero." }, "lineItems": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "referenceId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Your 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." }, "unitAmount": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Per-unit amount in cents." }, "taxAmount": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Total tax for this line in cents. Defaults to zero." }, "taxCode": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Your tax code for this line." } }, "required": [ "description", "quantity", "unitAmount" ], "additionalProperties": false, "title": "CreatePaymentIntentLineItem" }, "default": [], "description": "Sale lines in display order. Totals are calculated by Natural." } }, "required": [ "amount", "currency" ], "additionalProperties": false, "title": "CreatePaymentIntentAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CreatePaymentIntentRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 3920, "currency": "USD", "description": "Order 8842", "taxMode": "exclusive", "lineItems": [ { "referenceId": "menu_item_31", "description": "Margherita pizza", "quantity": 2, "unitAmount": 1800, "taxAmount": 320, "taxCode": "prepared_food" } ] } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaymentIntent" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentIntentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7", "type": "paymentIntent", "attributes": { "amount": 3920, "currency": "USD", "description": "Order 8842", "status": "open", "payUrl": "https://checkout.natural.com/#chk_example", "clientSecret": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7_secret_live_tcTy4NoQJkF6ShQTh5Y8ubLmbQikz5K9JBobGtauWws", "taxMode": "exclusive", "taxAmount": 320, "lineItems": [ { "id": "pli_019d0a1b2c3d4e5f60718293a4b5c6e1", "position": 0, "referenceId": "menu_item_31", "description": "Margherita pizza", "quantity": 2, "unitAmount": 1800, "taxAmount": 320, "taxCode": "prepared_food", "subtotalAmount": 3600, "totalAmount": 3920 } ], "expiresAt": null, "canceledAt": null, "createdAt": "2026-09-17T18:00:00.000Z", "updatedAt": "2026-09-17T18:00:00.000Z" }, "relationships": { "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "cardPayment": { "data": null }, "voiceSession": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "paymentIntents.list", "summary": "List payment intents", "description": "List payment intents, newest first", "tags": [ "Payment Intents" ], "parameters": [ { "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": "status", "in": "query", "schema": { "enum": [ "open", "processing", "completed", "canceled", "declined", "expired" ], "type": "string", "description": "Only intents with this status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "maxLength": 64, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$", "description": "Only intents created after this RFC 3339 timestamp (exclusive)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "maxLength": 64, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$", "description": "Only intents created before this RFC 3339 timestamp (exclusive)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentIntent" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PaymentIntentListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7", "type": "paymentIntent", "attributes": { "amount": 3920, "currency": "USD", "description": "Order 8842", "status": "completed", "payUrl": null, "clientSecret": null, "taxMode": "exclusive", "taxAmount": 320, "lineItems": [ { "id": "pli_019d0a1b2c3d4e5f60718293a4b5c6e1", "position": 0, "referenceId": "menu_item_31", "description": "Margherita pizza", "quantity": 2, "unitAmount": 1800, "taxAmount": 320, "taxCode": "prepared_food", "subtotalAmount": 3600, "totalAmount": 3920 } ], "expiresAt": null, "canceledAt": null, "createdAt": "2026-09-17T18:00:00.000Z", "updatedAt": "2026-09-17T18:05:00.000Z" }, "relationships": { "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "cardPayment": { "data": { "type": "cardPayment", "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8" } }, "voiceSession": { "data": null } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/payment-intents/{paymentIntentId}": { "get": { "operationId": "paymentIntents.get", "summary": "Get payment intent", "description": "Get a payment intent", "tags": [ "Payment Intents" ], "parameters": [ { "name": "paymentIntentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$", "description": "Payment intent ID (pmi_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "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": { "$ref": "#/components/schemas/PaymentIntent" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentIntentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7", "type": "paymentIntent", "attributes": { "amount": 3920, "currency": "USD", "description": "Order 8842", "status": "completed", "payUrl": null, "clientSecret": null, "taxMode": "exclusive", "taxAmount": 320, "lineItems": [ { "id": "pli_019d0a1b2c3d4e5f60718293a4b5c6e1", "position": 0, "referenceId": "menu_item_31", "description": "Margherita pizza", "quantity": 2, "unitAmount": 1800, "taxAmount": 320, "taxCode": "prepared_food", "subtotalAmount": 3600, "totalAmount": 3920 } ], "expiresAt": null, "canceledAt": null, "createdAt": "2026-09-17T18:00:00.000Z", "updatedAt": "2026-09-17T18:05:00.000Z" }, "relationships": { "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "cardPayment": { "data": { "type": "cardPayment", "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8" } }, "voiceSession": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] }, "patch": { "operationId": "paymentIntents.update", "summary": "Update payment intent", "description": "Change the amount, line items, or other details of an open payment intent", "tags": [ "Payment Intents" ], "parameters": [ { "name": "paymentIntentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$", "description": "Payment intent ID (pmi_*)." } }, { "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": { "customerPartyId": { "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." }, "amount": { "type": "integer", "minimum": 1, "description": "New total amount in US cents. Must equal the line totals when lines exist." }, "description": { "type": "string", "minLength": 1, "maxLength": 80, "description": "What the payment is for." }, "expiresAt": { "type": "string", "maxLength": 64, "description": "New RFC 3339 timestamp after which no new payment attempt may start. Must be in the future." }, "taxMode": { "enum": [ "exclusive", "inclusive" ], "type": "string", "description": "Whether tax is added to or included in line amounts." }, "taxAmount": { "type": "integer", "minimum": 0, "description": "Tax in cents when the intent has no line items." }, "lineItems": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "referenceId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Your 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." }, "unitAmount": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Per-unit amount in cents." }, "taxAmount": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Total tax for this line in cents. Defaults to zero." }, "taxCode": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Your tax code for this line." } }, "required": [ "description", "quantity", "unitAmount" ], "additionalProperties": false, "title": "CreatePaymentIntentLineItem" }, "description": "Replaces every line, in display order. Send an empty list to remove them." } }, "additionalProperties": false, "title": "UpdatePaymentIntentAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "UpdatePaymentIntentRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 5840, "lineItems": [ { "referenceId": "menu_item_31", "description": "Margherita pizza", "quantity": 2, "unitAmount": 1800, "taxAmount": 320, "taxCode": "prepared_food" }, { "description": "Garlic knots", "quantity": 1, "unitAmount": 1800, "taxAmount": 120 } ] } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaymentIntent" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentIntentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7", "type": "paymentIntent", "attributes": { "amount": 5840, "currency": "USD", "description": "Order 8842", "status": "open", "payUrl": "https://checkout.natural.com/#chk_example", "clientSecret": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7_secret_live_tcTy4NoQJkF6ShQTh5Y8ubLmbQikz5K9JBobGtauWws", "taxMode": "exclusive", "taxAmount": 440, "lineItems": [ { "id": "pli_019d0a1b2c3d4e5f60718293a4b5c6e2", "position": 0, "referenceId": "menu_item_31", "description": "Margherita pizza", "quantity": 2, "unitAmount": 1800, "taxAmount": 320, "taxCode": "prepared_food", "subtotalAmount": 3600, "totalAmount": 3920 }, { "id": "pli_019d0a1b2c3d4e5f60718293a4b5c6e3", "position": 1, "referenceId": null, "description": "Garlic knots", "quantity": 1, "unitAmount": 1800, "taxAmount": 120, "subtotalAmount": 1800, "totalAmount": 1920, "taxCode": null } ], "expiresAt": null, "canceledAt": null, "createdAt": "2026-09-17T18:00:00.000Z", "updatedAt": "2026-09-17T18:03:00.000Z" }, "relationships": { "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "cardPayment": { "data": null }, "voiceSession": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/payment-intents/{paymentIntentId}/cancel": { "post": { "operationId": "paymentIntents.cancel", "summary": "Cancel payment intent", "description": "Cancel an open payment intent", "tags": [ "Payment Intents" ], "parameters": [ { "name": "paymentIntentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$", "description": "Payment intent ID (pmi_*)." } }, { "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": { "customerPartyId": { "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." } }, "additionalProperties": false, "title": "CancelPaymentIntentAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CancelPaymentIntentRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": {} } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaymentIntent" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentIntentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7", "type": "paymentIntent", "attributes": { "amount": 3920, "currency": "USD", "description": "Order 8842", "status": "canceled", "payUrl": null, "clientSecret": null, "taxMode": "exclusive", "taxAmount": 320, "lineItems": [ { "id": "pli_019d0a1b2c3d4e5f60718293a4b5c6e1", "position": 0, "referenceId": "menu_item_31", "description": "Margherita pizza", "quantity": 2, "unitAmount": 1800, "taxAmount": 320, "taxCode": "prepared_food", "subtotalAmount": 3600, "totalAmount": 3920 } ], "expiresAt": null, "canceledAt": "2026-09-17T18:05:00.000Z", "createdAt": "2026-09-17T18:00:00.000Z", "updatedAt": "2026-09-17T18:05:00.000Z" }, "relationships": { "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "cardPayment": { "data": null }, "voiceSession": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/card-payments": { "get": { "operationId": "cardPayments.list", "summary": "List card payments", "description": "List card payment attempts, newest first. Filter by paymentIntentId to see attempts for one intent.", "tags": [ "Card Payments" ], "parameters": [ { "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": "paymentIntentId", "in": "query", "schema": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$", "description": "Only attempts for this payment intent (pmi_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "processing", "succeeded", "failed" ], "type": "string", "description": "Only attempts with this status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "maxLength": 64, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$", "description": "Only attempts created after this RFC 3339 timestamp (exclusive)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "maxLength": 64, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$", "description": "Only attempts created before this RFC 3339 timestamp (exclusive)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CardPayment" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CardPaymentListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8", "type": "cardPayment", "attributes": { "amount": 3920, "currency": "USD", "status": "succeeded", "brand": "visa", "last4": "4242", "channel": "link", "receiptUrl": "https://checkout.natural.com/receipts#example", "failure": null, "fee": { "amount": 144, "currency": "USD", "payer": "recipient", "applied": "deducted" }, "refundedAmount": 0, "refundableAmount": 3920, "settledAt": "2026-09-18T09:00:00.000Z", "createdAt": "2026-09-17T18:02:39.000Z", "updatedAt": "2026-09-17T18:02:41.000Z" }, "relationships": { "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "refunds": { "data": [] } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/card-payments/{cardPaymentId}": { "get": { "operationId": "cardPayments.get", "summary": "Get card payment", "description": "Get one card payment attempt, including its status, failure details, and refund totals.", "tags": [ "Card Payments" ], "parameters": [ { "name": "cardPaymentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$", "description": "Card payment ID (cpy_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "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": { "$ref": "#/components/schemas/CardPayment" } }, "required": [ "data" ], "additionalProperties": false, "title": "CardPaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8", "type": "cardPayment", "attributes": { "amount": 3920, "currency": "USD", "status": "succeeded", "brand": "visa", "last4": "4242", "channel": "link", "receiptUrl": "https://checkout.natural.com/receipts#example", "failure": null, "fee": { "amount": 144, "currency": "USD", "payer": "recipient", "applied": "deducted" }, "refundedAmount": 0, "refundableAmount": 3920, "settledAt": "2026-09-18T09:00:00.000Z", "createdAt": "2026-09-17T18:02:39.000Z", "updatedAt": "2026-09-17T18:02:41.000Z" }, "relationships": { "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "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": [] } ] } }, "/voice/sessions": { "post": { "operationId": "voice.create", "summary": "Create voice session", "description": "Create a voice session for an open payment intent", "tags": [ "Voice" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "kind": { "description": "Purpose of the session. Only payment is supported.", "type": "string", "enum": [ "payment" ] }, "paymentIntentId": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$", "description": "Open payment intent to collect during this call." }, "customerPartyId": { "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." }, "callerPhone": { "type": "string", "maxLength": 16, "description": "Supplied caller phone number in E.164 for payment messages. This does not verify caller identity." }, "referenceId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Your reference for this voice session." }, "returnTarget": { "type": "string", "maxLength": 255, "description": "SIP URI to request a return transfer to when the payment call finishes." } }, "required": [ "kind", "paymentIntentId", "callerPhone" ], "additionalProperties": false, "title": "CreateVoiceSessionAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateVoiceSessionRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "kind": "payment", "paymentIntentId": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7", "callerPhone": "+14155550123", "referenceId": "call_8842", "returnTarget": "sip:agent-9920@sip.partner.example.com" } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VoiceSession" } }, "required": [ "data" ], "additionalProperties": false, "title": "VoiceSessionResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "vos_019d0a1b2c3d4e5f60718293a4b5c6f0", "type": "voiceSession", "attributes": { "kind": "payment", "status": "awaitingCall", "referenceId": "call_8842", "callerPhone": "+14155550123", "dialUri": "sip:vos_019d0a1b2c3d4e5f60718293a4b5c6f0@sip.natural.com", "dialExpiresAt": "2026-09-09T18:15:00.000Z", "returnTarget": "sip:agent-9920@sip.partner.example.com", "call": { "startedAt": null, "endedAt": null, "durationSeconds": null, "endedBy": null, "summary": null, "returnRequestedAt": null }, "completedAt": null, "payment": { "outcome": null, "linkSentAt": null, "failedAttempts": 0, "failure": null }, "createdAt": "2026-09-09T18:00:00.000Z", "updatedAt": "2026-09-09T18:00:00.000Z" }, "relationships": { "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "voice.list", "summary": "List voice sessions", "description": "List voice sessions", "tags": [ "Voice" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit for your account's call log, including delegated activity. Requires authorization from that customer." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "paymentIntentId", "in": "query", "schema": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$", "description": "Only sessions associated with this payment intent." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "awaitingCall", "inProgress", "ended", "failed", "canceled", "expired" ], "type": "string", "description": "Filter by call-session status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "maxLength": 64, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$", "description": "Only sessions created after this RFC 3339 timestamp (exclusive)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "maxLength": 64, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$", "description": "Only sessions created before this RFC 3339 timestamp (exclusive)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page with the same customer and filters." }, "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": "array", "items": { "$ref": "#/components/schemas/VoiceSession" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "VoiceSessionListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "vos_019d0a1b2c3d4e5f60718293a4b5c6f0", "type": "voiceSession", "attributes": { "kind": "payment", "status": "ended", "referenceId": "call_8842", "callerPhone": "+14155550123", "dialUri": null, "dialExpiresAt": "2026-09-09T18:15:00.000Z", "returnTarget": "sip:agent-9920@sip.partner.example.com", "call": { "startedAt": "2026-09-09T18:01:05.000Z", "endedAt": "2026-09-09T18:02:50.000Z", "durationSeconds": 105, "endedBy": "assistant", "summary": "The caller confirmed the order and paid. A return transfer was requested.", "returnRequestedAt": "2026-09-09T18:02:50.000Z" }, "completedAt": "2026-09-09T18:02:31.000Z", "payment": { "outcome": "paid", "linkSentAt": null, "failedAttempts": 0, "failure": null }, "createdAt": "2026-09-09T18:00:00.000Z", "updatedAt": "2026-09-09T18:02:50.000Z" }, "relationships": { "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/voice/sessions/{voiceSessionId}": { "get": { "operationId": "voice.get", "summary": "Get voice session", "description": "Get a voice session", "tags": [ "Voice" ], "parameters": [ { "name": "voiceSessionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^vos_[0-9a-f]{32}$", "description": "Voice session ID (vos_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit for your account's call log, including delegated activity. 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": { "$ref": "#/components/schemas/VoiceSession" } }, "required": [ "data" ], "additionalProperties": false, "title": "VoiceSessionResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "vos_019d0a1b2c3d4e5f60718293a4b5c6f0", "type": "voiceSession", "attributes": { "kind": "payment", "status": "ended", "referenceId": "call_8842", "callerPhone": "+14155550123", "dialUri": null, "dialExpiresAt": "2026-09-09T18:15:00.000Z", "returnTarget": "sip:agent-9920@sip.partner.example.com", "call": { "startedAt": "2026-09-09T18:01:05.000Z", "endedAt": "2026-09-09T18:02:50.000Z", "durationSeconds": 105, "endedBy": "assistant", "summary": "The caller confirmed the order and paid. A return transfer was requested.", "returnRequestedAt": "2026-09-09T18:02:50.000Z" }, "completedAt": "2026-09-09T18:02:31.000Z", "payment": { "outcome": "paid", "linkSentAt": null, "failedAttempts": 0, "failure": null }, "createdAt": "2026-09-09T18:00:00.000Z", "updatedAt": "2026-09-09T18:02:50.000Z" }, "relationships": { "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } } } } } }, "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": [] } ] } }, "/voice/sessions/{voiceSessionId}/transcript": { "get": { "operationId": "voice.transcript", "summary": "Get voice session transcript", "description": "Get a voice session's transcript", "tags": [ "Voice" ], "parameters": [ { "name": "voiceSessionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^vos_[0-9a-f]{32}$", "description": "Voice session ID (vos_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit for your account's call log, including delegated activity. 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": { "$ref": "#/components/schemas/VoiceSessionTranscript" } }, "required": [ "data" ], "additionalProperties": false, "title": "VoiceTranscriptResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "vos_019d0a1b2c3d4e5f60718293a4b5c6f0", "type": "voiceSessionTranscript", "attributes": { "status": "available", "turns": [ { "role": "assistant", "text": "Please read the number on your card.", "at": "2026-09-09T18:01:07.000Z" }, { "role": "caller", "text": "It's ••••.", "at": "2026-09-09T18:01:21.000Z" }, { "role": "system", "text": "Return transfer requested", "at": "2026-09-09T18:02:50.000Z" } ] }, "relationships": { "voiceSession": { "data": { "type": "voiceSession", "id": "vos_019d0a1b2c3d4e5f60718293a4b5c6f0" } } } } } } } } }, "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": [] } ] } }, "/refunds": { "post": { "operationId": "refunds.create", "summary": "Create refund", "description": "Refund a card payment", "tags": [ "Refunds" ], "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 act for (pty_*). Omit for your own account. Requires authorization from that customer." }, "paymentIntentId": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$", "description": "Payment intent to refund (pmi_*). Supply either paymentIntentId or cardPaymentId, not both." }, "cardPaymentId": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$", "description": "Successful card payment to refund (cpy_*). Supply either cardPaymentId or paymentIntentId, not both." }, "amount": { "type": "integer", "minimum": 1, "description": "Amount in US cents. Omit to refund the full remaining amount." }, "reason": { "enum": [ "duplicate", "fraudulent", "requestedByPayer" ], "type": "string", "description": "Why the refund was requested." } }, "additionalProperties": false, "title": "CreateRefundAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateRefundRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "paymentIntentId": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7", "amount": 1000, "reason": "requestedByPayer" } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Refund" } }, "required": [ "data" ], "additionalProperties": false, "title": "RefundResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "rfd_019d0a1b2c3d4e5f60718293a4b5c701", "type": "refund", "attributes": { "amount": 1000, "currency": "USD", "reason": "requestedByPayer", "status": "pending", "failure": null, "receiptUrl": "https://checkout.natural.com/receipts#Qm9vazJoYXNoYnJvd25zMg", "createdAt": "2026-09-18T15:00:00.000Z", "updatedAt": "2026-09-18T15:00:00.000Z" }, "relationships": { "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "cardPayment": { "data": { "type": "cardPayment", "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "refunds.list", "summary": "List refunds", "description": "List refunds, newest first", "tags": [ "Refunds" ], "parameters": [ { "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": "paymentIntentId", "in": "query", "schema": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$", "description": "Only refunds of this payment intent." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cardPaymentId", "in": "query", "schema": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$", "description": "Only refunds of this card payment. If paymentIntentId is also supplied, both filters must match." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "RefundListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "rfd_019d0a1b2c3d4e5f60718293a4b5c701", "type": "refund", "attributes": { "amount": 1000, "currency": "USD", "reason": "requestedByPayer", "status": "succeeded", "failure": null, "receiptUrl": "https://checkout.natural.com/receipts#Qm9vazJoYXNoYnJvd25zMg", "createdAt": "2026-09-18T15:00:00.000Z", "updatedAt": "2026-09-18T15:00:03.000Z" }, "relationships": { "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "cardPayment": { "data": { "type": "cardPayment", "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/refunds/{refundId}": { "get": { "operationId": "refunds.get", "summary": "Get refund", "description": "Get a refund", "tags": [ "Refunds" ], "parameters": [ { "name": "refundId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rfd_[0-9a-f]{32}$", "description": "Refund ID (rfd_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "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": { "$ref": "#/components/schemas/Refund" } }, "required": [ "data" ], "additionalProperties": false, "title": "RefundResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "rfd_019d0a1b2c3d4e5f60718293a4b5c701", "type": "refund", "attributes": { "amount": 1000, "currency": "USD", "reason": "requestedByPayer", "status": "succeeded", "failure": null, "receiptUrl": "https://checkout.natural.com/receipts#Qm9vazJoYXNoYnJvd25zMg", "createdAt": "2026-09-18T15:00:00.000Z", "updatedAt": "2026-09-18T15:00:03.000Z" }, "relationships": { "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "cardPayment": { "data": { "type": "cardPayment", "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } } } } } }, "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": [] } ] } }, "/chargebacks": { "get": { "operationId": "chargebacks.list", "summary": "List chargebacks", "description": "List chargebacks on card payments received by the customer", "tags": [ "Chargebacks" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Connected customer to act on behalf of." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cardPaymentId", "in": "query", "schema": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "paymentIntentId", "in": "query", "schema": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "needsResponse", "expired", "accepted", "submitted", "underReview", "won", "lost" ], "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024 }, "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": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" }, "type": { "type": "string", "enum": [ "chargeback" ] }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "description": "Disputed amount in the currency's smallest unit." }, "currency": { "type": "string", "description": "Reported ISO 4217 currency of the disputed amount." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." } }, "required": [ "amount", "currency" ], "additionalProperties": false, "title": "ChargebackFee" }, { "type": "null" } ], "description": "Natural's fee for this case, billed once when the case opens. It can be billed before the disputed amount is withheld and isn't refunded if you win. Null when no fee applies or the fee was voided." }, "status": { "enum": [ "needsResponse", "expired", "accepted", "submitted", "underReview", "won", "lost" ], "type": "string", "description": "Response and outcome state. Submitted means Natural accepted the response. Under review requires provider acknowledgment. Accepted and expired are not provider-reported losses. While the case is needsResponse, submitted, or underReview, the disputed amount is withheld from your available balance. The hold can post shortly after the case is created. Won returns the amount. Lost, accepted, and expired do not." }, "network": { "enum": [ "visa", "mastercard", "discover", "unknown" ], "type": "string", "description": "Card network that reported the case." }, "reason": { "type": "object", "properties": { "category": { "enum": [ "fraud", "authorization", "processingError", "duplicate", "notReceived", "unacceptableOrCanceled", "creditNotProcessed", "unknown" ], "type": "string" }, "networkCode": { "type": "string", "description": "Network reason code, interpreted with the network." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readable reason description, or null when unavailable." } }, "required": [ "category", "networkCode", "description" ], "additionalProperties": false }, "responseDueAt": { "type": "string", "format": "date-time", "description": "Deadline for accepting or responding to this chargeback. Enforced." }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When Natural accepted and froze the response. This does not establish provider acknowledgment." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "amount", "currency", "fee", "status", "network", "reason", "responseDueAt", "submittedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "cardPayment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `cardPayment`.", "type": "string", "enum": [ "cardPayment" ] }, "id": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" }, "paymentIntent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentIntent`.", "type": "string", "enum": [ "paymentIntent" ] }, "id": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "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" } }, "required": [ "cardPayment", "paymentIntent", "customerParty" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "Chargeback" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "cbk_019d0a1b2c3d4e5f60718293a4b5c700", "type": "chargeback", "attributes": { "amount": 4620, "currency": "USD", "fee": { "amount": 1500, "currency": "USD" }, "status": "needsResponse", "network": "visa", "reason": { "category": "notReceived", "networkCode": "13.1", "description": "Merchandise or services not received" }, "responseDueAt": "2026-09-27T23:59:59.999Z", "submittedAt": null, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:02:00.000Z" }, "relationships": { "cardPayment": { "data": { "type": "cardPayment", "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8" } }, "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/chargebacks/{chargebackId}": { "get": { "operationId": "chargebacks.get", "summary": "Get chargeback", "description": "Get a chargeback", "tags": [ "Chargebacks" ], "parameters": [ { "name": "chargebackId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Connected customer to act on behalf of." }, "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": "^cbk_[0-9a-f]{32}$" }, "type": { "type": "string", "enum": [ "chargeback" ] }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "description": "Disputed amount in the currency's smallest unit." }, "currency": { "type": "string", "description": "Reported ISO 4217 currency of the disputed amount." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." } }, "required": [ "amount", "currency" ], "additionalProperties": false, "title": "ChargebackFee" }, { "type": "null" } ], "description": "Natural's fee for this case, billed once when the case opens. It can be billed before the disputed amount is withheld and isn't refunded if you win. Null when no fee applies or the fee was voided." }, "status": { "enum": [ "needsResponse", "expired", "accepted", "submitted", "underReview", "won", "lost" ], "type": "string", "description": "Response and outcome state. Submitted means Natural accepted the response. Under review requires provider acknowledgment. Accepted and expired are not provider-reported losses. While the case is needsResponse, submitted, or underReview, the disputed amount is withheld from your available balance. The hold can post shortly after the case is created. Won returns the amount. Lost, accepted, and expired do not." }, "network": { "enum": [ "visa", "mastercard", "discover", "unknown" ], "type": "string", "description": "Card network that reported the case." }, "reason": { "type": "object", "properties": { "category": { "enum": [ "fraud", "authorization", "processingError", "duplicate", "notReceived", "unacceptableOrCanceled", "creditNotProcessed", "unknown" ], "type": "string" }, "networkCode": { "type": "string", "description": "Network reason code, interpreted with the network." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readable reason description, or null when unavailable." } }, "required": [ "category", "networkCode", "description" ], "additionalProperties": false }, "responseDueAt": { "type": "string", "format": "date-time", "description": "Deadline for accepting or responding to this chargeback. Enforced." }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When Natural accepted and froze the response. This does not establish provider acknowledgment." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "amount", "currency", "fee", "status", "network", "reason", "responseDueAt", "submittedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "cardPayment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `cardPayment`.", "type": "string", "enum": [ "cardPayment" ] }, "id": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" }, "paymentIntent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentIntent`.", "type": "string", "enum": [ "paymentIntent" ] }, "id": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "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" } }, "required": [ "cardPayment", "paymentIntent", "customerParty" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "Chargeback" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "cbk_019d0a1b2c3d4e5f60718293a4b5c700", "type": "chargeback", "attributes": { "amount": 4620, "currency": "USD", "fee": { "amount": 1500, "currency": "USD" }, "status": "needsResponse", "network": "visa", "reason": { "category": "notReceived", "networkCode": "13.1", "description": "Merchandise or services not received" }, "responseDueAt": "2026-09-27T23:59:59.999Z", "submittedAt": null, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:02:00.000Z" }, "relationships": { "cardPayment": { "data": { "type": "cardPayment", "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8" } }, "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } } } } } }, "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": [] } ] } }, "/chargebacks/{chargebackId}/evidence": { "get": { "operationId": "chargebacks.getEvidence", "summary": "Get chargeback evidence", "description": "Get the saved evidence for a chargeback", "tags": [ "Chargebacks" ], "parameters": [ { "name": "chargebackId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Connected customer to act on behalf of." }, "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": "^cbk_[0-9a-f]{32}$", "description": "The chargeback ID. Evidence has no ID of its own." }, "type": { "type": "string", "enum": [ "chargebackEvidence" ] }, "attributes": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "description": "Version of the case. Send it when updating or submitting evidence." }, "responseReason": { "anyOf": [ { "enum": [ "cardholderWithdrew", "authorizedPurchase", "alreadyRefunded", "receivedProduct", "other" ], "type": "string" }, { "type": "null" } ], "description": "Why you are contesting the chargeback." }, "productType": { "anyOf": [ { "enum": [ "physical", "digital", "inPersonService", "other" ], "type": "string" }, { "type": "null" } ], "description": "Type of goods or services sold." }, "shippedOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Date the goods were shipped. Applies when productType is physical. Natural clears it for other product types." }, "serviceDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Date the service was provided. Applies when productType is inPersonService. Natural clears it for other product types." }, "productDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description of the goods or services sold. Recorded sale details satisfy this requirement when omitted." }, "explanation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explanation of why the chargeback should be reversed." }, "deliveryDetails": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How the goods or services were delivered." }, "usageDetails": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How the cardholder received or used the purchase, such as access or download records." }, "shippingAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address the goods were shipped to, as one line. Applies when productType is physical. Natural clears it for other product types." }, "shippingCarrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Shipping carrier. Applies when productType is physical. Natural clears it for other product types." }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Carrier tracking number. Applies when productType is physical. Natural clears it for other product types." }, "cardholderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cardholder name supplied to support the response." }, "cardholderEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cardholder email supplied to support the response." }, "cardholderPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cardholder phone supplied to support the response." }, "billingAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full billing address supplied as evidence. This does not change recorded billing facts." }, "refundPolicyDisclosure": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How and when the refund policy was disclosed." }, "refundDetails": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Additional explanation of a refund. Natural includes its recorded refund facts." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^evf_[0-9a-f]{32}$", "description": "ID of a validated file uploaded for this chargeback." }, "purposes": { "type": "array", "minItems": 1, "maxItems": 11, "items": { "enum": [ "cardholderCommunications", "receipt", "authorizationProof", "duplicatePaymentReceipt", "fulfillmentProof", "productDescription", "cancellationPolicy", "refundProof", "refundPolicy", "disputeWithdrawal", "otherEvidence" ], "type": "string" }, "description": "Evidence categories supported by this file." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file": { "type": "object", "properties": { "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sanitized filename. Null for files uploaded before filename capture was available." }, "contentType": { "enum": [ "application/pdf", "image/jpeg", "image/png" ], "type": "string" }, "sizeBytes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Original uploaded bytes. Null for historical files whose original size was not recorded." }, "pageCount": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of pages this file contributes to the evidence packet." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the file was uploaded and validated." } }, "required": [ "filename", "contentType", "sizeBytes", "pageCount", "createdAt" ], "additionalProperties": false } }, "required": [ "fileId", "purposes", "note", "file" ], "additionalProperties": false }, "description": "Files attached to the response, in packet order." }, "recommendedPurposes": { "type": "array", "items": { "enum": [ "cardholderCommunications", "receipt", "authorizationProof", "duplicatePaymentReceipt", "fulfillmentProof", "productDescription", "cancellationPolicy", "refundProof", "refundPolicy", "disputeWithdrawal", "otherEvidence" ], "type": "string" }, "description": "Evidence categories Natural recommends for this reason and response. Empty when the case can no longer be edited." } }, "required": [ "version", "responseReason", "productType", "shippedOn", "serviceDate", "productDescription", "explanation", "deliveryDetails", "usageDetails", "shippingAddress", "shippingCarrier", "trackingNumber", "cardholderName", "cardholderEmail", "cardholderPhone", "billingAddress", "refundPolicyDisclosure", "refundDetails", "attachments", "recommendedPurposes" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "chargeback": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `chargeback`.", "type": "string", "enum": [ "chargeback" ] }, "id": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" } }, "required": [ "chargeback" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "ChargebackEvidence" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "cbk_019d0a1b2c3d4e5f60718293a4b5c700", "type": "chargebackEvidence", "attributes": { "version": 2, "responseReason": "receivedProduct", "productType": "physical", "productDescription": "A cotton shirt", "explanation": "The cardholder confirmed receiving the order.", "deliveryDetails": null, "usageDetails": null, "shippingAddress": "1 Main St, Boston, MA 02101", "shippingCarrier": "UPS", "trackingNumber": "1Z9990000000000001", "shippedOn": "2026-09-14", "serviceDate": null, "cardholderName": null, "cardholderEmail": null, "cardholderPhone": null, "billingAddress": null, "refundPolicyDisclosure": null, "refundDetails": null, "attachments": [ { "fileId": "evf_019d0a1b2c3d4e5f60718293a4b5c701", "purposes": [ "fulfillmentProof" ], "note": "Signed delivery confirmation for the order.", "file": { "filename": "delivery-confirmation.pdf", "contentType": "application/pdf", "sizeBytes": 2048, "pageCount": 1, "createdAt": "2026-09-17T12:01:00.000Z" } } ], "recommendedPurposes": [ "fulfillmentProof", "cardholderCommunications" ] }, "relationships": { "chargeback": { "data": { "type": "chargeback", "id": "cbk_019d0a1b2c3d4e5f60718293a4b5c700" } } } } } } } } }, "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": [] } ] }, "patch": { "operationId": "chargebacks.updateEvidence", "summary": "Update chargeback evidence", "description": "Save evidence changes without submitting the response", "tags": [ "Chargebacks" ], "parameters": [ { "name": "chargebackId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, { "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": { "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Connected customer to act on behalf of." }, "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "responseReason": { "anyOf": [ { "enum": [ "cardholderWithdrew", "authorizedPurchase", "alreadyRefunded", "receivedProduct", "other" ], "type": "string" }, { "type": "null" } ], "description": "Why you are contesting the chargeback." }, "productType": { "anyOf": [ { "enum": [ "physical", "digital", "inPersonService", "other" ], "type": "string" }, { "type": "null" } ], "description": "Type of goods or services sold." }, "shippedOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Date the goods were shipped. Applies when productType is physical. Natural clears it for other product types." }, "serviceDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Date the service was provided. Applies when productType is inPersonService. Natural clears it for other product types." }, "productDescription": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "description": "Description of the goods or services sold. Recorded sale details satisfy this requirement when omitted." }, "explanation": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "description": "Explanation of why the chargeback should be reversed." }, "deliveryDetails": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "description": "How the goods or services were delivered." }, "usageDetails": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "description": "How the cardholder received or used the purchase, such as access or download records." }, "shippingAddress": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Address the goods were shipped to, as one line. Applies when productType is physical. Natural clears it for other product types." }, "shippingCarrier": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "Shipping carrier. Applies when productType is physical. Natural clears it for other product types." }, "trackingNumber": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "Carrier tracking number. Applies when productType is physical. Natural clears it for other product types." }, "cardholderName": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ], "description": "Cardholder name supplied to support the response." }, "cardholderEmail": { "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ], "description": "Cardholder email supplied to support the response." }, "cardholderPhone": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ], "description": "Cardholder phone supplied to support the response." }, "billingAddress": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "description": "Full billing address supplied as evidence. This does not change recorded billing facts." }, "refundPolicyDisclosure": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "description": "How and when the refund policy was disclosed." }, "refundDetails": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "description": "Additional explanation of a refund. Natural includes its recorded refund facts." }, "attachments": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^evf_[0-9a-f]{32}$", "description": "ID of a validated file uploaded for this chargeback." }, "purposes": { "type": "array", "minItems": 1, "maxItems": 11, "items": { "enum": [ "cardholderCommunications", "receipt", "authorizationProof", "duplicatePaymentReceipt", "fulfillmentProof", "productDescription", "cancellationPolicy", "refundProof", "refundPolicy", "disputeWithdrawal", "otherEvidence" ], "type": "string" }, "description": "Evidence categories supported by this file." }, "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "Explanation of what this file demonstrates." } }, "required": [ "fileId", "purposes", "note" ], "additionalProperties": false }, "description": "Replaces the attached files and their order." }, "version": { "type": "integer", "exclusiveMinimum": 0, "description": "Version of the case. Send it when updating or submitting evidence." } }, "required": [ "version" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "UpdateChargebackEvidenceRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "version": 1, "responseReason": "receivedProduct", "productType": "physical", "explanation": "The cardholder confirmed receiving the order.", "trackingNumber": "1Z9990000000000001" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$", "description": "The chargeback ID. Evidence has no ID of its own." }, "type": { "type": "string", "enum": [ "chargebackEvidence" ] }, "attributes": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "description": "Version of the case. Send it when updating or submitting evidence." }, "responseReason": { "anyOf": [ { "enum": [ "cardholderWithdrew", "authorizedPurchase", "alreadyRefunded", "receivedProduct", "other" ], "type": "string" }, { "type": "null" } ], "description": "Why you are contesting the chargeback." }, "productType": { "anyOf": [ { "enum": [ "physical", "digital", "inPersonService", "other" ], "type": "string" }, { "type": "null" } ], "description": "Type of goods or services sold." }, "shippedOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Date the goods were shipped. Applies when productType is physical. Natural clears it for other product types." }, "serviceDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Date the service was provided. Applies when productType is inPersonService. Natural clears it for other product types." }, "productDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description of the goods or services sold. Recorded sale details satisfy this requirement when omitted." }, "explanation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explanation of why the chargeback should be reversed." }, "deliveryDetails": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How the goods or services were delivered." }, "usageDetails": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How the cardholder received or used the purchase, such as access or download records." }, "shippingAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address the goods were shipped to, as one line. Applies when productType is physical. Natural clears it for other product types." }, "shippingCarrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Shipping carrier. Applies when productType is physical. Natural clears it for other product types." }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Carrier tracking number. Applies when productType is physical. Natural clears it for other product types." }, "cardholderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cardholder name supplied to support the response." }, "cardholderEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cardholder email supplied to support the response." }, "cardholderPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cardholder phone supplied to support the response." }, "billingAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full billing address supplied as evidence. This does not change recorded billing facts." }, "refundPolicyDisclosure": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How and when the refund policy was disclosed." }, "refundDetails": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Additional explanation of a refund. Natural includes its recorded refund facts." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^evf_[0-9a-f]{32}$", "description": "ID of a validated file uploaded for this chargeback." }, "purposes": { "type": "array", "minItems": 1, "maxItems": 11, "items": { "enum": [ "cardholderCommunications", "receipt", "authorizationProof", "duplicatePaymentReceipt", "fulfillmentProof", "productDescription", "cancellationPolicy", "refundProof", "refundPolicy", "disputeWithdrawal", "otherEvidence" ], "type": "string" }, "description": "Evidence categories supported by this file." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file": { "type": "object", "properties": { "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sanitized filename. Null for files uploaded before filename capture was available." }, "contentType": { "enum": [ "application/pdf", "image/jpeg", "image/png" ], "type": "string" }, "sizeBytes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Original uploaded bytes. Null for historical files whose original size was not recorded." }, "pageCount": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of pages this file contributes to the evidence packet." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the file was uploaded and validated." } }, "required": [ "filename", "contentType", "sizeBytes", "pageCount", "createdAt" ], "additionalProperties": false } }, "required": [ "fileId", "purposes", "note", "file" ], "additionalProperties": false }, "description": "Files attached to the response, in packet order." }, "recommendedPurposes": { "type": "array", "items": { "enum": [ "cardholderCommunications", "receipt", "authorizationProof", "duplicatePaymentReceipt", "fulfillmentProof", "productDescription", "cancellationPolicy", "refundProof", "refundPolicy", "disputeWithdrawal", "otherEvidence" ], "type": "string" }, "description": "Evidence categories Natural recommends for this reason and response. Empty when the case can no longer be edited." } }, "required": [ "version", "responseReason", "productType", "shippedOn", "serviceDate", "productDescription", "explanation", "deliveryDetails", "usageDetails", "shippingAddress", "shippingCarrier", "trackingNumber", "cardholderName", "cardholderEmail", "cardholderPhone", "billingAddress", "refundPolicyDisclosure", "refundDetails", "attachments", "recommendedPurposes" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "chargeback": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `chargeback`.", "type": "string", "enum": [ "chargeback" ] }, "id": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" } }, "required": [ "chargeback" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "ChargebackEvidence" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "cbk_019d0a1b2c3d4e5f60718293a4b5c700", "type": "chargebackEvidence", "attributes": { "version": 2, "responseReason": "receivedProduct", "productType": "physical", "productDescription": "A cotton shirt", "explanation": "The cardholder confirmed receiving the order.", "deliveryDetails": null, "usageDetails": null, "shippingAddress": "1 Main St, Boston, MA 02101", "shippingCarrier": "UPS", "trackingNumber": "1Z9990000000000001", "shippedOn": "2026-09-14", "serviceDate": null, "cardholderName": null, "cardholderEmail": null, "cardholderPhone": null, "billingAddress": null, "refundPolicyDisclosure": null, "refundDetails": null, "attachments": [ { "fileId": "evf_019d0a1b2c3d4e5f60718293a4b5c701", "purposes": [ "fulfillmentProof" ], "note": "Signed delivery confirmation for the order.", "file": { "filename": "delivery-confirmation.pdf", "contentType": "application/pdf", "sizeBytes": 2048, "pageCount": 1, "createdAt": "2026-09-17T12:01:00.000Z" } } ], "recommendedPurposes": [ "fulfillmentProof", "cardholderCommunications" ] }, "relationships": { "chargeback": { "data": { "type": "chargeback", "id": "cbk_019d0a1b2c3d4e5f60718293a4b5c700" } } } } } } } } }, "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": [] } ] } }, "/chargebacks/{chargebackId}/files": { "post": { "operationId": "chargebacks.uploadFile", "summary": "Upload chargeback file", "description": "Upload and validate one evidence file for this chargeback", "tags": [ "Chargebacks" ], "parameters": [ { "name": "chargebackId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, { "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": { "multipart/form-data": { "schema": { "type": "object", "properties": { "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Connected customer to act on behalf of." }, "file": { "type": "string", "format": "binary", "description": "PDF, JPEG, or PNG. Maximum 2 MiB." } }, "required": [ "file" ], "additionalProperties": false, "title": "UploadChargebackFileRequest" }, "encoding": { "file": { "contentType": "application/pdf,image/jpeg,image/png" } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evf_[0-9a-f]{32}$" }, "type": { "type": "string", "enum": [ "chargebackEvidenceFile" ] }, "attributes": { "type": "object", "properties": { "filename": { "type": "string" }, "contentType": { "enum": [ "application/pdf", "image/jpeg", "image/png" ], "type": "string" }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0 }, "pageCount": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of pages this file contributes to the evidence packet." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the file was uploaded and validated." } }, "required": [ "filename", "contentType", "sizeBytes", "pageCount", "createdAt" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "chargeback": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `chargeback`.", "type": "string", "enum": [ "chargeback" ] }, "id": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" } }, "required": [ "chargeback" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "ChargebackEvidenceFile" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "evf_019d0a1b2c3d4e5f60718293a4b5c701", "type": "chargebackEvidenceFile", "attributes": { "filename": "delivery-confirmation.pdf", "contentType": "application/pdf", "sizeBytes": 2048, "pageCount": 1, "createdAt": "2026-09-17T12:01:00.000Z" }, "relationships": { "chargeback": { "data": { "type": "chargeback", "id": "cbk_019d0a1b2c3d4e5f60718293a4b5c700" } } } } } } } } }, "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": [] } ] } }, "/chargebacks/{chargebackId}/evidence/preview": { "get": { "operationId": "chargebacks.previewEvidence", "summary": "Preview chargeback evidence", "description": "Render the saved evidence as a PDF without submitting it", "tags": [ "Chargebacks" ], "parameters": [ { "name": "chargebackId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Connected customer to act on behalf of." }, "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/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf", "description": "The compiled evidence packet as it stands, for the merchant's review." } } }, "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": [] } ] } }, "/chargebacks/{chargebackId}/submit": { "post": { "operationId": "chargebacks.submit", "summary": "Submit chargeback evidence", "description": "Validate and freeze the saved evidence for submission", "tags": [ "Chargebacks" ], "parameters": [ { "name": "chargebackId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, { "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": { "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Connected customer to act on behalf of." }, "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "description": "Version of the case. Send it when updating or submitting evidence." } }, "required": [ "version" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "SubmitChargebackRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "version": 2 } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" }, "type": { "type": "string", "enum": [ "chargeback" ] }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "description": "Disputed amount in the currency's smallest unit." }, "currency": { "type": "string", "description": "Reported ISO 4217 currency of the disputed amount." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." } }, "required": [ "amount", "currency" ], "additionalProperties": false, "title": "ChargebackFee" }, { "type": "null" } ], "description": "Natural's fee for this case, billed once when the case opens. It can be billed before the disputed amount is withheld and isn't refunded if you win. Null when no fee applies or the fee was voided." }, "status": { "enum": [ "needsResponse", "expired", "accepted", "submitted", "underReview", "won", "lost" ], "type": "string", "description": "Response and outcome state. Submitted means Natural accepted the response. Under review requires provider acknowledgment. Accepted and expired are not provider-reported losses. While the case is needsResponse, submitted, or underReview, the disputed amount is withheld from your available balance. The hold can post shortly after the case is created. Won returns the amount. Lost, accepted, and expired do not." }, "network": { "enum": [ "visa", "mastercard", "discover", "unknown" ], "type": "string", "description": "Card network that reported the case." }, "reason": { "type": "object", "properties": { "category": { "enum": [ "fraud", "authorization", "processingError", "duplicate", "notReceived", "unacceptableOrCanceled", "creditNotProcessed", "unknown" ], "type": "string" }, "networkCode": { "type": "string", "description": "Network reason code, interpreted with the network." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readable reason description, or null when unavailable." } }, "required": [ "category", "networkCode", "description" ], "additionalProperties": false }, "responseDueAt": { "type": "string", "format": "date-time", "description": "Deadline for accepting or responding to this chargeback. Enforced." }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When Natural accepted and froze the response. This does not establish provider acknowledgment." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "amount", "currency", "fee", "status", "network", "reason", "responseDueAt", "submittedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "cardPayment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `cardPayment`.", "type": "string", "enum": [ "cardPayment" ] }, "id": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" }, "paymentIntent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentIntent`.", "type": "string", "enum": [ "paymentIntent" ] }, "id": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "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" } }, "required": [ "cardPayment", "paymentIntent", "customerParty" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "Chargeback" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "cbk_019d0a1b2c3d4e5f60718293a4b5c700", "type": "chargeback", "attributes": { "amount": 4620, "currency": "USD", "fee": { "amount": 1500, "currency": "USD" }, "status": "submitted", "network": "visa", "reason": { "category": "notReceived", "networkCode": "13.1", "description": "Merchandise or services not received" }, "responseDueAt": "2026-09-27T23:59:59.999Z", "submittedAt": "2026-09-17T12:04:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:04:00.000Z" }, "relationships": { "cardPayment": { "data": { "type": "cardPayment", "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8" } }, "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } } } } } }, "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": [] } ] } }, "/chargebacks/{chargebackId}/accept": { "post": { "operationId": "chargebacks.accept", "summary": "Accept chargeback", "description": "Accept the chargeback without contesting it", "tags": [ "Chargebacks" ], "parameters": [ { "name": "chargebackId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Connected customer to act on behalf of." }, "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": "^cbk_[0-9a-f]{32}$" }, "type": { "type": "string", "enum": [ "chargeback" ] }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "description": "Disputed amount in the currency's smallest unit." }, "currency": { "type": "string", "description": "Reported ISO 4217 currency of the disputed amount." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." } }, "required": [ "amount", "currency" ], "additionalProperties": false, "title": "ChargebackFee" }, { "type": "null" } ], "description": "Natural's fee for this case, billed once when the case opens. It can be billed before the disputed amount is withheld and isn't refunded if you win. Null when no fee applies or the fee was voided." }, "status": { "enum": [ "needsResponse", "expired", "accepted", "submitted", "underReview", "won", "lost" ], "type": "string", "description": "Response and outcome state. Submitted means Natural accepted the response. Under review requires provider acknowledgment. Accepted and expired are not provider-reported losses. While the case is needsResponse, submitted, or underReview, the disputed amount is withheld from your available balance. The hold can post shortly after the case is created. Won returns the amount. Lost, accepted, and expired do not." }, "network": { "enum": [ "visa", "mastercard", "discover", "unknown" ], "type": "string", "description": "Card network that reported the case." }, "reason": { "type": "object", "properties": { "category": { "enum": [ "fraud", "authorization", "processingError", "duplicate", "notReceived", "unacceptableOrCanceled", "creditNotProcessed", "unknown" ], "type": "string" }, "networkCode": { "type": "string", "description": "Network reason code, interpreted with the network." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Readable reason description, or null when unavailable." } }, "required": [ "category", "networkCode", "description" ], "additionalProperties": false }, "responseDueAt": { "type": "string", "format": "date-time", "description": "Deadline for accepting or responding to this chargeback. Enforced." }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When Natural accepted and froze the response. This does not establish provider acknowledgment." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "amount", "currency", "fee", "status", "network", "reason", "responseDueAt", "submittedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "cardPayment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `cardPayment`.", "type": "string", "enum": [ "cardPayment" ] }, "id": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" }, "paymentIntent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentIntent`.", "type": "string", "enum": [ "paymentIntent" ] }, "id": { "type": "string", "pattern": "^pmi_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship" }, "customerParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "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" } }, "required": [ "cardPayment", "paymentIntent", "customerParty" ], "additionalProperties": false } }, "required": [ "id", "type", "attributes", "relationships" ], "additionalProperties": false, "title": "Chargeback" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "cbk_019d0a1b2c3d4e5f60718293a4b5c700", "type": "chargeback", "attributes": { "amount": 4620, "currency": "USD", "fee": { "amount": 1500, "currency": "USD" }, "status": "accepted", "network": "visa", "reason": { "category": "notReceived", "networkCode": "13.1", "description": "Merchandise or services not received" }, "responseDueAt": "2026-09-27T23:59:59.999Z", "submittedAt": null, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:04:00.000Z" }, "relationships": { "cardPayment": { "data": { "type": "cardPayment", "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8" } }, "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } } } } } }, "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": [] } ] } }, "/transactions": { "get": { "operationId": "transactions.list", "summary": "List transactions", "description": "List transactions", "tags": [ "Transactions" ], "parameters": [ { "name": "type", "in": "query", "schema": { "enum": [ "payment", "transfer", "refund", "chargeback", "all" ], "type": "string", "default": "all", "description": "Filter by transaction type. Chargeback rows need `chargebacks.read`. Without it, `all` leaves them out and `chargeback` returns an empty page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "counterpartyPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Restrict results to transactions whose payment counterparty is this party." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "walletId", "in": "query", "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Restrict results to transactions visible through this wallet." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Restrict results to delegated activity performed for this customer, not activity involving it as a payment counterparty." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "delegated", "in": "query", "schema": { "type": "boolean", "description": "When true, return only transactions an agent performed for a connected 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": "array", "items": { "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_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "type": "string", "description": "Transaction status. A chargeback row is `COMPLETED` once the disputed amount is debited from your wallet, and `RETURNED` if that amount is released back to you, as when you win the case." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this transaction was created." }, "transactionType": { "enum": [ "payment", "transfer", "refund", "chargeback" ], "type": "string", "description": "Transaction type. A `chargeback` row is the disputed amount of a card payment chargeback, debited from your wallet." }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Direction relative to your party." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction description." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transaction was last updated, or null." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." } }, "required": [ "amount", "currency", "status", "createdAt", "transactionType", "direction", "description", "updatedAt", "expectedAvailableAt" ], "additionalProperties": false, "title": "TransactionAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "sourceParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Source party." }, "destinationParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination party." }, "payment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related payment, when accessible." }, "cardPayment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `cardPayment`.", "type": "string", "enum": [ "cardPayment" ] }, "id": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related card payment, when accessible. On a chargeback row, the disputed payment." }, "refund": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `refund`.", "type": "string", "enum": [ "refund" ] }, "id": { "type": "string", "pattern": "^rfd_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related refund, when accessible." }, "chargeback": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `chargeback`.", "type": "string", "enum": [ "chargeback" ] }, "id": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "The chargeback case a chargeback row debits for." }, "transfer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `transfer`.", "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related transfer, when accessible." }, "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, "description": "Wallet through which this transaction is visible." } }, "required": [ "initiatorAgent", "sourceParty", "destinationParty" ], "additionalProperties": false, "title": "TransactionRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransactionResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "TransactionListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "transaction", "id": "txn_019cd1798d7fbad660f55b2bf67e5434", "attributes": { "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Wallet top-up", "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:31:00.000Z", "transactionType": "transfer", "direction": "INBOUND", "expectedAvailableAt": null }, "relationships": { "initiatorAgent": { "data": null }, "sourceParty": { "data": null }, "destinationParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "transfer": { "data": { "type": "transfer", "id": "trf_019cd1798d7b524eed60a8023c379326" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/transactions/{transactionId}": { "get": { "operationId": "transactions.get", "summary": "Get transaction", "description": "Get a transaction", "tags": [ "Transactions" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^txn_[0-9a-f]{32}$", "description": "Transaction ID (txn_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string", "pattern": "^txn_[0-9a-f]{32}$", "description": "Transaction ID (txn_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "type": "string", "description": "Transaction status. A chargeback row is `COMPLETED` once the disputed amount is debited from your wallet, and `RETURNED` if that amount is released back to you, as when you win the case." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this transaction was created." }, "transactionType": { "enum": [ "payment", "transfer", "refund", "chargeback" ], "type": "string", "description": "Transaction type. A `chargeback` row is the disputed amount of a card payment chargeback, debited from your wallet." }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Direction relative to your party." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction description." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transaction was last updated, or null." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." } }, "required": [ "amount", "currency", "status", "createdAt", "transactionType", "direction", "description", "updatedAt", "expectedAvailableAt" ], "additionalProperties": false, "title": "TransactionAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "sourceParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Source party." }, "destinationParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination party." }, "payment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related payment, when accessible." }, "cardPayment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `cardPayment`.", "type": "string", "enum": [ "cardPayment" ] }, "id": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related card payment, when accessible. On a chargeback row, the disputed payment." }, "refund": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `refund`.", "type": "string", "enum": [ "refund" ] }, "id": { "type": "string", "pattern": "^rfd_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related refund, when accessible." }, "chargeback": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `chargeback`.", "type": "string", "enum": [ "chargeback" ] }, "id": { "type": "string", "pattern": "^cbk_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "The chargeback case a chargeback row debits for." }, "transfer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `transfer`.", "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "description": "Related transfer, when accessible." }, "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, "description": "Wallet through which this transaction is visible." } }, "required": [ "initiatorAgent", "sourceParty", "destinationParty" ], "additionalProperties": false, "title": "TransactionRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransactionResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "TransactionSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transaction", "id": "txn_019cd1798d6672a7b828eee780291b72", "attributes": { "amount": 50000, "currency": "USD", "status": "COMPLETED", "description": "Q4 development work", "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:31:00.000Z", "transactionType": "payment", "direction": "OUTBOUND", "expectedAvailableAt": null }, "relationships": { "initiatorAgent": { "data": null }, "sourceParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "destinationParty": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "payment": { "data": { "type": "payment", "id": "pay_019cd1798d77ef3e74d16143bd39940a" } } } } } } } } }, "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": [] } ] } }, "/transfers/deposit": { "post": { "operationId": "transfers.initiateDeposit", "summary": "Initiate deposit", "description": "Move funds from a linked bank account into a wallet", "tags": [ "Transfers" ], "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "amount": { "type": "integer", "minimum": 100, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code." }, "externalAccountId": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet (wal_*) to deposit into. Omit to use the party default for user or party API calls, or the agent default for the current customer connection when acting through a connected agent. Owned agents use their own agent default." }, "description": { "type": "string", "maxLength": 80, "description": "Transfer description. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.", "maxProperties": 30 } }, "required": [ "amount", "externalAccountId" ], "additionalProperties": false, "title": "DepositCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "DepositCreateData" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 50000, "currency": "USD", "externalAccountId": "eac_019cd1798d75c7ec27e4218aeac1d282", "description": "Wallet top-up", "tags": { "workflow": "treasury" } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `transfer`.", "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$", "description": "Transfer ID (trf_*)." }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender for an instant withdrawal. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "method": { "anyOf": [ { "enum": [ "standard", "instant", "wire" ], "type": "string" }, { "type": "null" } ], "description": "Requested delivery method, when available." }, "rail": { "anyOf": [ { "enum": [ "ach", "wire", "internal", "realtime" ], "type": "string" }, { "type": "null" } ], "description": "Executed transfer rail, when available." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was returned, or null." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was submitted, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer settled, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was last updated, or null." } }, "required": [ "type", "amount", "currency", "fee", "status", "method", "rail", "description", "tags", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "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 for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "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." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `externalAccount`.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "initiatorAgent", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_019cd1798d7b524eed60a8023c379326", "attributes": { "type": "deposit", "amount": 50000, "currency": "USD", "fee": null, "status": "PROCESSING", "method": null, "rail": null, "description": "Wallet top-up", "tags": { "workflow": "treasury" }, "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00.000Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_019cd1798d75c7ec27e4218aeac1d282" } }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d7fbad660f55b2bf67e5434" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-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." } ] } }, "/transfers/withdraw": { "post": { "operationId": "transfers.initiateWithdrawal", "summary": "Initiate withdrawal", "description": "Move funds from a wallet to a linked bank account", "tags": [ "Transfers" ], "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code." }, "externalAccountId": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." }, "method": { "enum": [ "standard", "instant", "wire" ], "type": "string", "default": "standard", "description": "Delivery method. Defaults to standard. To request instant withdrawal access and pricing, contact hi@natural.com." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet (wal_*) to withdraw from. Omit to use the party default for user or party API calls, or the agent default for the current customer connection when acting through a connected agent. Owned agents use their own agent default." }, "description": { "type": "string", "maxLength": 80, "description": "Transfer description. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.", "maxProperties": 30 } }, "required": [ "amount", "externalAccountId" ], "additionalProperties": false, "title": "WithdrawCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WithdrawCreateData" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 12500, "currency": "USD", "externalAccountId": "eac_019cd1798d75c7ec27e4218aeac1d282", "method": "instant", "description": "Payout transfer", "tags": { "workflow": "treasury" } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `transfer`.", "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$", "description": "Transfer ID (trf_*)." }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender for an instant withdrawal. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "method": { "anyOf": [ { "enum": [ "standard", "instant", "wire" ], "type": "string" }, { "type": "null" } ], "description": "Requested delivery method, when available." }, "rail": { "anyOf": [ { "enum": [ "ach", "wire", "internal", "realtime" ], "type": "string" }, { "type": "null" } ], "description": "Executed transfer rail, when available." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was returned, or null." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was submitted, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer settled, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was last updated, or null." } }, "required": [ "type", "amount", "currency", "fee", "status", "method", "rail", "description", "tags", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "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 for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "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." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `externalAccount`.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "initiatorAgent", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_019cd1798d7c2d1e06b4d1fa807538e1", "attributes": { "type": "withdrawal", "amount": 12500, "currency": "USD", "fee": { "amount": 125, "currency": "USD", "payer": "sender", "applied": "on_top" }, "status": "PROCESSING", "method": "instant", "rail": "realtime", "description": "Payout transfer", "tags": { "workflow": "treasury" }, "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00.000Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_019cd1798d75c7ec27e4218aeac1d282" } }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d800e18b53a2c01f57eb56a" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-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." } ] } }, "/transfers/internal": { "post": { "operationId": "transfers.initiateInternal", "summary": "Initiate internal transfer", "description": "Move funds between two wallets", "tags": [ "Transfers" ], "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "sourceWalletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Source wallet ID (wal_*)." }, "destWalletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Destination wallet ID (wal_*)." }, "description": { "type": "string", "maxLength": 80, "description": "Transfer description. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.", "maxProperties": 30 } }, "required": [ "amount", "sourceWalletId", "destWalletId" ], "additionalProperties": false, "title": "InternalTransferCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "InternalTransferCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "InternalTransferCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 5000, "sourceWalletId": "wal_019cd1798d714ce765e0486a417c23dc", "destWalletId": "wal_019cd1798d72cf01303c7c04148c9b8d", "description": "Sweep to Vault", "tags": { "workflow": "treasury" } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `transfer`.", "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$", "description": "Transfer ID (trf_*)." }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender for an instant withdrawal. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "method": { "anyOf": [ { "enum": [ "standard", "instant", "wire" ], "type": "string" }, { "type": "null" } ], "description": "Requested delivery method, when available." }, "rail": { "anyOf": [ { "enum": [ "ach", "wire", "internal", "realtime" ], "type": "string" }, { "type": "null" } ], "description": "Executed transfer rail, when available." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was returned, or null." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was submitted, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer settled, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was last updated, or null." } }, "required": [ "type", "amount", "currency", "fee", "status", "method", "rail", "description", "tags", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "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 for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "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." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `externalAccount`.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "initiatorAgent", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "InternalTransferResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_019cd1798d7d74273a6591925ddbeded", "attributes": { "type": "internal", "amount": 5000, "currency": "USD", "fee": null, "status": "PROCESSING", "method": null, "rail": null, "description": "Sweep to Vault", "tags": { "workflow": "treasury" }, "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": null, "settledAt": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalAccount": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d81eff6df9226e1cc4b9471" } }, "destWallet": { "data": { "type": "wallet", "id": "wal_019cd1798d72cf01303c7c04148c9b8d" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-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." } ] } }, "/transfers": { "get": { "operationId": "transfers.list", "summary": "List transfers", "description": "List transfers", "tags": [ "Transfers" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `transfer`.", "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$", "description": "Transfer ID (trf_*)." }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender for an instant withdrawal. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "method": { "anyOf": [ { "enum": [ "standard", "instant", "wire" ], "type": "string" }, { "type": "null" } ], "description": "Requested delivery method, when available." }, "rail": { "anyOf": [ { "enum": [ "ach", "wire", "internal", "realtime" ], "type": "string" }, { "type": "null" } ], "description": "Executed transfer rail, when available." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was returned, or null." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was submitted, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer settled, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was last updated, or null." } }, "required": [ "type", "amount", "currency", "fee", "status", "method", "rail", "description", "tags", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "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 for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "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." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `externalAccount`.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "initiatorAgent", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "TransferListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "transfer", "id": "trf_019cd1798d7b524eed60a8023c379326", "attributes": { "type": "deposit", "amount": 50000, "currency": "USD", "fee": null, "status": "PROCESSING", "method": null, "rail": null, "description": "Wallet top-up", "tags": { "workflow": "treasury" }, "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00.000Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_019cd1798d75c7ec27e4218aeac1d282" } }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d7fbad660f55b2bf67e5434" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/transfers/{transferId}": { "get": { "operationId": "transfers.get", "summary": "Get transfer", "description": "Get a transfer", "tags": [ "Transfers" ], "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$", "description": "Transfer ID (trf_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "type": { "description": "Resource type. Always `transfer`.", "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$", "description": "Transfer ID (trf_*)." }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender for an instant withdrawal. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "method": { "anyOf": [ { "enum": [ "standard", "instant", "wire" ], "type": "string" }, { "type": "null" } ], "description": "Requested delivery method, when available." }, "rail": { "anyOf": [ { "enum": [ "ach", "wire", "internal", "realtime" ], "type": "string" }, { "type": "null" } ], "description": "Executed transfer rail, when available." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was returned, or null." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was submitted, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer settled, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was last updated, or null." } }, "required": [ "type", "amount", "currency", "fee", "status", "method", "rail", "description", "tags", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "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 for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "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." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `externalAccount`.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "initiatorAgent", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "TransferResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_019cd1798d7b524eed60a8023c379326", "attributes": { "type": "deposit", "amount": 50000, "currency": "USD", "fee": null, "status": "PROCESSING", "method": null, "rail": null, "description": "Wallet top-up", "tags": { "workflow": "treasury" }, "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00.000Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_019cd1798d75c7ec27e4218aeac1d282" } }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d7fbad660f55b2bf67e5434" } } } } } } } } }, "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": [] } ] } }, "/payment-requests": { "post": { "operationId": "paymentRequests.create", "summary": "Create payment request", "description": "Create a payment request", "tags": [ "PaymentRequests" ], "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet (wal_*) that should receive the funds. Omit to use the party default for user or party API calls, or the agent default for the current customer connection when acting through a connected agent. Owned agents use their own agent default." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code." }, "description": { "type": "string", "maxLength": 80, "description": "Free-form description shown to the payer. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.", "maxProperties": 30 }, "payerName": { "type": "string", "maxLength": 32, "description": "Display name of the payer. Maximum 32 characters." }, "payer": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "maxLength": 254, "format": "email", "description": "Email address." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "maxLength": 16, "description": "Phone number." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent_id" ] }, "value": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Natural agent ID (agt_*)." } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "handle" ] }, "value": { "type": "string", "maxLength": 62, "description": "Natural handle (@handle or @handle-slug)." } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "PaymentRequestPayer", "description": "Who pays: exactly one typed email, phone, party ID, agent ID, or handle value." } }, "required": [ "amount", "payer" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 2500, "currency": "USD", "description": "Invoice 7", "tags": { "invoice_id": "inv_7" }, "payerName": "Ada Lovelace", "payer": { "type": "email", "value": "ada@example.com" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "recipient" ] }, "applied": { "description": "The fee is subtracted from the principal amount before the recipient receives it.", "type": "string", "enum": [ "deducted" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "RecipientDeductedFee" }, { "type": "null" } ], "description": "Fee deducted from your proceeds as the recipient. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "payerCanPay": { "type": "boolean", "description": "Whether the payer can still fulfill this request: it is OPEN, unexpired, and has no payment attempt. Does not check the payer's authorization or funding." }, "payerCanDecline": { "type": "boolean", "description": "Whether the payer can still decline this request: it is OPEN. Does not check the payer's authorization." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "name": { "type": "string", "description": "Party display name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle, such as @acme, or null when none is set." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction (txn_*) created by the most recent payment attempt, or null when none has been made." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment request expires, or null when it does not expire." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was last updated." } }, "required": [ "amount", "currency", "fee", "status", "payerCanPay", "payerCanDecline", "description", "tags", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "paymentLinkUrl", "transactionId", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Payer agent, or null unless addressed by agent ID or agent handle." } }, "required": [ "initiatorAgent", "requesterParty", "payerParty", "payerAgent" ], "additionalProperties": false, "title": "PaymentRequestCreateRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestCreateResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_019cd1798d7a68fe07c972bed48fb7fd", "attributes": { "amount": 2500, "currency": "USD", "fee": null, "status": "OPEN", "payerCanPay": true, "payerCanDecline": true, "description": "Invoice 7", "tags": { "invoice_id": "inv_7" }, "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "requesterAvatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp", "requesterHandle": "@acme", "walletName": "Operating", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png", "payerHandle": "@ada-lovelace", "payerPartyId": "pty_019cd1798d681091fcf1dc98afb72d01", "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "initiatorParty": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "name": "Acme Payments", "handle": "@acme" }, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "expiresAt": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "payerParty": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "payerAgent": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "paymentRequests.list", "summary": "List payment requests", "description": "List outgoing payment requests", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeCompleted", "in": "query", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "pattern": "^(true|false|yes|no|on|off|1|0|y|n|enabled|disabled)$" } ], "default": true, "description": "Whether to include completed payment requests." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "includeCanceled", "in": "query", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "pattern": "^(true|false|yes|no|on|off|1|0|y|n|enabled|disabled)$" } ], "default": false, "description": "Whether to include canceled payment requests." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "group", "in": "query", "schema": { "enum": [ "open", "completed", "closed" ], "type": "string", "description": "Limit the list to one outgoing group. Open is still waiting on the payer. Completed is in flight or settled and not returned. Closed is failed, declined, canceled, expired, and returned. When set, this replaces includeCompleted and includeCanceled." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "initiatedByAgent", "in": "query", "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Only payment requests created by this agent (agt_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "addressedToAgent", "in": "query", "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Only payment requests addressed to this agent (agt_*) as payer." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "recipient" ] }, "applied": { "description": "The fee is subtracted from the principal amount before the recipient receives it.", "type": "string", "enum": [ "deducted" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "RecipientDeductedFee" }, { "type": "null" } ], "description": "Fee deducted from your proceeds as the recipient. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "payerCanPay": { "type": "boolean", "description": "Whether the payer can still fulfill this request: it is OPEN, unexpired, and has no payment attempt. Does not check the payer's authorization or funding." }, "payerCanDecline": { "type": "boolean", "description": "Whether the payer can still decline this request: it is OPEN. Does not check the payer's authorization." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "name": { "type": "string", "description": "Party display name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle, such as @acme, or null when none is set." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction (txn_*) created by the most recent payment attempt, or null when none has been made." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment request expires, or null when it does not expire." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was last updated." } }, "required": [ "amount", "currency", "fee", "status", "payerCanPay", "payerCanDecline", "description", "tags", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "paymentLinkUrl", "transactionId", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "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 that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "initiatorAgent", "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PaymentRequestListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "paymentRequest", "id": "prq_019cd1798d7a68fe07c972bed48fb7fd", "attributes": { "amount": 2500, "currency": "USD", "fee": null, "status": "OPEN", "payerCanPay": true, "payerCanDecline": true, "description": "Invoice 7", "tags": { "invoice_id": "inv_7" }, "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "requesterAvatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp", "requesterHandle": "@acme", "walletName": "Operating", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png", "payerHandle": "@ada-lovelace", "payerPartyId": "pty_019cd1798d681091fcf1dc98afb72d01", "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "initiatorParty": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "name": "Acme Payments", "handle": "@acme" }, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "expiresAt": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "payerParty": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "payerAgent": { "data": null }, "payment": { "data": null } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/payment-requests/incoming": { "get": { "operationId": "paymentRequests.listIncoming", "summary": "List incoming payment requests", "description": "List incoming payment requests", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "addressedToAgent", "in": "query", "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Only payment requests addressed to this agent (agt_*) as payer." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "recipient" ] }, "applied": { "description": "The fee is subtracted from the principal amount before the recipient receives it.", "type": "string", "enum": [ "deducted" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "RecipientDeductedFee" }, { "type": "null" } ], "description": "Fee deducted from your proceeds as the recipient. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "payerCanPay": { "type": "boolean", "description": "Whether the payer can still fulfill this request: it is OPEN, unexpired, and has no payment attempt. Does not check the payer's authorization or funding." }, "payerCanDecline": { "type": "boolean", "description": "Whether the payer can still decline this request: it is OPEN. Does not check the payer's authorization." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "name": { "type": "string", "description": "Party display name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle, such as @acme, or null when none is set." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction (txn_*) created by the most recent payment attempt, or null when none has been made." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment request expires, or null when it does not expire." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was last updated." } }, "required": [ "amount", "currency", "fee", "status", "payerCanPay", "payerCanDecline", "description", "tags", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "paymentLinkUrl", "transactionId", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "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 that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "initiatorAgent", "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PaymentRequestListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "paymentRequest", "id": "prq_019cd1798d7a68fe07c972bed48fb7fd", "attributes": { "amount": 2500, "currency": "USD", "fee": null, "status": "OPEN", "payerCanPay": true, "payerCanDecline": true, "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "requesterAvatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp", "requesterHandle": "@acme", "walletName": "Operating", "description": "Invoice 7", "tags": { "invoice_id": "inv_7" }, "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png", "payerHandle": "@ada-lovelace", "payerPartyId": "pty_019cd1798d681091fcf1dc98afb72d01", "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "initiatorParty": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "name": "Acme Payments", "handle": "@acme" }, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "expiresAt": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "payerParty": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "payerAgent": { "data": null }, "payment": { "data": null } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/payment-requests/{paymentRequestId}": { "get": { "operationId": "paymentRequests.get", "summary": "Get payment request", "description": "Get a payment request", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "recipient" ] }, "applied": { "description": "The fee is subtracted from the principal amount before the recipient receives it.", "type": "string", "enum": [ "deducted" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "RecipientDeductedFee" }, { "type": "null" } ], "description": "Fee deducted from your proceeds as the recipient. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "payerCanPay": { "type": "boolean", "description": "Whether the payer can still fulfill this request: it is OPEN, unexpired, and has no payment attempt. Does not check the payer's authorization or funding." }, "payerCanDecline": { "type": "boolean", "description": "Whether the payer can still decline this request: it is OPEN. Does not check the payer's authorization." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "name": { "type": "string", "description": "Party display name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle, such as @acme, or null when none is set." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction (txn_*) created by the most recent payment attempt, or null when none has been made." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment request expires, or null when it does not expire." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was last updated." } }, "required": [ "amount", "currency", "fee", "status", "payerCanPay", "payerCanDecline", "description", "tags", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "paymentLinkUrl", "transactionId", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "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 that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "initiatorAgent", "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_019cd1798d7a68fe07c972bed48fb7fd", "attributes": { "amount": 2500, "currency": "USD", "fee": { "amount": 25, "currency": "USD", "payer": "recipient", "applied": "deducted" }, "status": "COMPLETED", "payerCanPay": false, "payerCanDecline": false, "description": "Invoice 7", "tags": { "invoice_id": "inv_7" }, "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "requesterAvatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp", "requesterHandle": "@acme", "walletName": "Operating", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png", "payerHandle": "@ada-lovelace", "payerPartyId": "pty_019cd1798d681091fcf1dc98afb72d01", "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "initiatorParty": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "name": "Acme Payments", "handle": "@acme" }, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": "txn_019cd1798d7ea271f8ca44ea83de9af8", "expiresAt": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "payerParty": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "payerAgent": { "data": null }, "payment": { "data": { "type": "payment", "id": "pay_019cd1798d78f1129dd012ce651d1ff1" } } } } } } } } }, "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": [] } ] } }, "/payment-requests/{paymentRequestId}/fulfill": { "post": { "operationId": "paymentRequests.fulfill", "summary": "Fulfill payment request", "description": "Fulfill an open payment request from a wallet or a verified linked bank account", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "paymentSource": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet (wal_*) to pay from. Omit to use the party default for user or party API calls, or the agent default for the current customer connection when acting through a connected agent. Owned agents use their own agent default." } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "external_account" ] }, "externalAccountId": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "Verified linked bank account (eac_*) to pay from." } }, "required": [ "type", "externalAccountId" ], "additionalProperties": false } ], "description": "Source of funds for the payment." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.", "maxProperties": 30 } }, "required": [ "paymentSource" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "paymentSource": { "type": "wallet", "walletId": "wal_019cd1798d714ce765e0486a417c23dc" }, "tags": { "invoice_id": "inv_7" } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was submitted to money movement, or null while unsubmitted." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment reached a terminal status, or null while in flight." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this payment failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this payment was returned." }, "claim": { "anyOf": [ { "type": "object", "properties": { "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient began claiming this payment, or null while unclaimed or unobserved." }, "claimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient claimed this payment, or null while unclaimed." }, "unboundAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when a claimed payment detached from its recipient, or null." } }, "required": [ "startedAt", "claimedAt", "unboundAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Claim lifecycle for payments sent to an off-platform recipient, or null when this payment is not claim-based." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was last updated, or null." } }, "required": [ "amount", "currency", "status", "description", "tags", "fee", "submittedAt", "terminalAt", "failure", "return", "claim", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "initiatorAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_019cd1798d78f1129dd012ce651d1ff1", "attributes": { "amount": 2500, "currency": "USD", "status": "PROCESSING", "description": "Invoice 7", "tags": { "invoice_id": "inv_7" }, "fee": null, "submittedAt": "2026-04-15T00:00:00.000Z", "terminalAt": null, "failure": null, "return": null, "claim": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "sender": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "recipientAgent": { "data": null }, "transaction": { "data": null }, "paymentRequest": { "data": { "type": "paymentRequest", "id": "prq_019cd1798d7a68fe07c972bed48fb7fd" } } } } } } } } }, "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": [] } ] } }, "/payment-requests/{paymentRequestId}/decline": { "post": { "operationId": "paymentRequests.decline", "summary": "Decline payment request", "description": "Decline an open incoming payment request", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "recipient" ] }, "applied": { "description": "The fee is subtracted from the principal amount before the recipient receives it.", "type": "string", "enum": [ "deducted" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "RecipientDeductedFee" }, { "type": "null" } ], "description": "Fee deducted from your proceeds as the recipient. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "payerCanPay": { "type": "boolean", "description": "Whether the payer can still fulfill this request: it is OPEN, unexpired, and has no payment attempt. Does not check the payer's authorization or funding." }, "payerCanDecline": { "type": "boolean", "description": "Whether the payer can still decline this request: it is OPEN. Does not check the payer's authorization." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "name": { "type": "string", "description": "Party display name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle, such as @acme, or null when none is set." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction (txn_*) created by the most recent payment attempt, or null when none has been made." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment request expires, or null when it does not expire." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was last updated." } }, "required": [ "amount", "currency", "fee", "status", "payerCanPay", "payerCanDecline", "description", "tags", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "paymentLinkUrl", "transactionId", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "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 that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "initiatorAgent", "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_019cd1798d7a68fe07c972bed48fb7fd", "attributes": { "amount": 2500, "currency": "USD", "fee": null, "status": "DECLINED", "payerCanPay": false, "payerCanDecline": false, "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "requesterAvatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp", "requesterHandle": "@acme", "walletName": "Operating", "description": "Invoice 7", "tags": { "invoice_id": "inv_7" }, "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png", "payerHandle": "@ada-lovelace", "payerPartyId": "pty_019cd1798d681091fcf1dc98afb72d01", "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "initiatorParty": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "name": "Acme Payments", "handle": "@acme" }, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "expiresAt": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:05:00.000Z" }, "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "payerParty": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "payerAgent": { "data": null }, "payment": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/payment-requests/{paymentRequestId}/cancel": { "post": { "operationId": "paymentRequests.cancel", "summary": "Cancel payment request", "description": "Cancel an open outgoing payment request", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-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": false, "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." } }, "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "customerPartyId": "pty_019cd1798d627ad9bc302511c4f2c115" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "recipient" ] }, "applied": { "description": "The fee is subtracted from the principal amount before the recipient receives it.", "type": "string", "enum": [ "deducted" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "RecipientDeductedFee" }, { "type": "null" } ], "description": "Fee deducted from your proceeds as the recipient. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "payerCanPay": { "type": "boolean", "description": "Whether the payer can still fulfill this request: it is OPEN, unexpired, and has no payment attempt. Does not check the payer's authorization or funding." }, "payerCanDecline": { "type": "boolean", "description": "Whether the payer can still decline this request: it is OPEN. Does not check the payer's authorization." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "name": { "type": "string", "description": "Party display name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle, such as @acme, or null when none is set." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction (txn_*) created by the most recent payment attempt, or null when none has been made." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment request expires, or null when it does not expire." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was last updated." } }, "required": [ "amount", "currency", "fee", "status", "payerCanPay", "payerCanDecline", "description", "tags", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "paymentLinkUrl", "transactionId", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "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 that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "initiatorAgent", "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_019cd1798d7a68fe07c972bed48fb7fd", "attributes": { "amount": 2500, "currency": "USD", "fee": null, "status": "CANCELED", "payerCanPay": false, "payerCanDecline": false, "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "requesterAvatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp", "requesterHandle": "@acme", "walletName": "Operating", "description": "Invoice 7", "tags": { "invoice_id": "inv_7" }, "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png", "payerHandle": "@ada-lovelace", "payerPartyId": "pty_019cd1798d681091fcf1dc98afb72d01", "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "initiatorParty": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "name": "Acme Payments", "handle": "@acme" }, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "expiresAt": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:05:00.000Z" }, "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "payerParty": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "payerAgent": { "data": null }, "payment": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/approvals": { "get": { "operationId": "approvals.list", "summary": "List approvals", "description": "List approvals", "tags": [ "Approvals" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Filter by status. Defaults to pending." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `approval`.", "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID (apr_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Approval status." }, "target": { "type": "object", "properties": { "type": { "enum": [ "payment", "paymentRequest", "deposit", "withdrawal", "ach", "realtime", "wire", "check" ], "type": "string", "description": "Type of operation under approval." }, "id": { "type": "string", "description": "Public ID of the operation under approval. Legacy payment-request approvals reference the parent payment request (prq_), never an internal fulfillment." } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Operation that needs approval." }, "payment": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "amount", "currency" ], "additionalProperties": false }, { "type": "null" } ], "description": "Amount of the operation under review. Null when the underlying amount is unavailable." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee the sender pays on top of `payment.amount`. Before the operation is submitted, including just after approval, a quote at the price in effect when it was created. After, the same fee the operation's own resource reports. Null when no fee applies, including denied or canceled approvals, operations that ended before submission, and operations whose own resource hides the fee. Also null when Billing can't quote the fee at read time; the fee still applies when the operation is submitted." }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Reason type. Always `limitExceeded`.", "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Type of limit that was exceeded." }, "limitAmount": { "type": "integer", "description": "Configured limit amount in cents." }, "actualAmount": { "type": "integer", "description": "Amount that exceeded the limit, in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review." }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party (pty_*) whose wallet a delegated payment spends from." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the customer party, or null when unresolved." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Customer the agent is spending on behalf of, or null when the approval isn't a delegated payment." }, "ach": { "anyOf": [ { "type": "object", "properties": { "direction": { "enum": [ "credit" ], "type": "string", "description": "Direction of the payment." }, "secCode": { "enum": [ "WEB", "PPD", "TEL", "CCD" ], "type": "string", "description": "ACH SEC code the entry is submitted under." }, "companyEntryDescription": { "type": "string", "description": "Company entry description submitted on the ACH entry." }, "addenda": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment-related information submitted as the NACHA addenda record, or null." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "companyName": { "type": "string", "description": "Company name submitted on the ACH entry." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the ACH payment uses." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalAchCounterparty" }, { "type": "null" } ], "description": "Counterparty and masked account, or null when it can no longer be resolved." } }, "required": [ "direction", "secCode", "companyEntryDescription", "addenda", "internalDescription", "companyName", "expectedAvailableAt", "counterparty" ], "additionalProperties": true, "title": "ApprovalAch" }, { "type": "null" } ], "description": "ACH-specific review context. Null unless the target is an ACH." }, "wire": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string", "description": "Description supplied when the wire was created." }, "remittanceInfo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Remittance information, or null." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the payment credits." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalRealtimeCounterparty" }, { "type": "null" } ], "description": "Destination party and masked account, or null when it can no longer be resolved." } }, "required": [ "description", "remittanceInfo", "internalDescription", "counterparty" ], "additionalProperties": false, "title": "ApprovalWire" }, { "type": "null" } ], "description": "Wire-specific review context. Null unless the target is a wire." }, "check": { "anyOf": [ { "type": "object", "properties": { "payeeName": { "type": "string", "description": "Name printed on the check." }, "payeeCity": { "type": "string", "description": "Payee mailing address city." }, "payeeState": { "type": "string", "description": "Payee mailing address state." }, "amount": { "type": "integer", "description": "Check amount in cents." }, "memo": { "type": "string", "description": "Memo printed on the check." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never printed on the check or shared with the counterparty." } }, "required": [ "payeeName", "payeeCity", "payeeState", "amount", "memo", "internalDescription" ], "additionalProperties": false, "title": "ApprovalCheck" }, { "type": "null" } ], "description": "Check-specific review context. Null unless the target is a check." }, "realtime": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string", "description": "Description supplied when the payment was created." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the payment credits." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalRealtimeCounterparty" }, { "type": "null" } ], "description": "Destination party and masked account, or null when it can no longer be resolved." } }, "required": [ "description", "internalDescription", "counterparty" ], "additionalProperties": false, "title": "ApprovalRealtime" }, { "type": "null" } ], "description": "Realtime-specific review context. Null unless the target is a realtime payment." }, "denialReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason recorded when the approval was denied, when one was given." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the approval was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the approval was last updated." }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the approval was resolved, or null while pending." } }, "required": [ "status", "target", "payment", "fee", "reasons", "customer", "ach", "wire", "check", "realtime", "denialReason", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." } }, "required": [ "initiatorAgent" ], "additionalProperties": false } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } }, "type": "approval", "id": "apr_019cd1798d8a74dd75c16fc6d843db81", "attributes": { "status": "pending", "target": { "type": "payment", "id": "pay_019cd1798d794c2f2ccf31b4e8394f2d" }, "payment": { "amount": 500000, "currency": "USD" }, "fee": { "amount": 100, "currency": "USD", "payer": "sender", "applied": "on_top" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "customer": null, "ach": null, "realtime": null, "wire": null, "check": null, "denialReason": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z", "resolvedAt": null } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/approvals/{approvalId}": { "get": { "operationId": "approvals.get", "summary": "Get approval", "description": "Get an approval", "tags": [ "Approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apr_[0-9a-f]{32}$", "description": "Approval ID (apr_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `approval`.", "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID (apr_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Approval status." }, "target": { "type": "object", "properties": { "type": { "enum": [ "payment", "paymentRequest", "deposit", "withdrawal", "ach", "realtime", "wire", "check" ], "type": "string", "description": "Type of operation under approval." }, "id": { "type": "string", "description": "Public ID of the operation under approval. Legacy payment-request approvals reference the parent payment request (prq_), never an internal fulfillment." } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Operation that needs approval." }, "payment": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "amount", "currency" ], "additionalProperties": false }, { "type": "null" } ], "description": "Amount of the operation under review. Null when the underlying amount is unavailable." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee the sender pays on top of `payment.amount`. Before the operation is submitted, including just after approval, a quote at the price in effect when it was created. After, the same fee the operation's own resource reports. Null when no fee applies, including denied or canceled approvals, operations that ended before submission, and operations whose own resource hides the fee. Also null when Billing can't quote the fee at read time; the fee still applies when the operation is submitted." }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Reason type. Always `limitExceeded`.", "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Type of limit that was exceeded." }, "limitAmount": { "type": "integer", "description": "Configured limit amount in cents." }, "actualAmount": { "type": "integer", "description": "Amount that exceeded the limit, in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review." }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party (pty_*) whose wallet a delegated payment spends from." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the customer party, or null when unresolved." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Customer the agent is spending on behalf of, or null when the approval isn't a delegated payment." }, "ach": { "anyOf": [ { "type": "object", "properties": { "direction": { "enum": [ "credit" ], "type": "string", "description": "Direction of the payment." }, "secCode": { "enum": [ "WEB", "PPD", "TEL", "CCD" ], "type": "string", "description": "ACH SEC code the entry is submitted under." }, "companyEntryDescription": { "type": "string", "description": "Company entry description submitted on the ACH entry." }, "addenda": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment-related information submitted as the NACHA addenda record, or null." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "companyName": { "type": "string", "description": "Company name submitted on the ACH entry." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the ACH payment uses." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalAchCounterparty" }, { "type": "null" } ], "description": "Counterparty and masked account, or null when it can no longer be resolved." } }, "required": [ "direction", "secCode", "companyEntryDescription", "addenda", "internalDescription", "companyName", "expectedAvailableAt", "counterparty" ], "additionalProperties": true, "title": "ApprovalAch" }, { "type": "null" } ], "description": "ACH-specific review context. Null unless the target is an ACH." }, "wire": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string", "description": "Description supplied when the wire was created." }, "remittanceInfo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Remittance information, or null." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the payment credits." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalRealtimeCounterparty" }, { "type": "null" } ], "description": "Destination party and masked account, or null when it can no longer be resolved." } }, "required": [ "description", "remittanceInfo", "internalDescription", "counterparty" ], "additionalProperties": false, "title": "ApprovalWire" }, { "type": "null" } ], "description": "Wire-specific review context. Null unless the target is a wire." }, "check": { "anyOf": [ { "type": "object", "properties": { "payeeName": { "type": "string", "description": "Name printed on the check." }, "payeeCity": { "type": "string", "description": "Payee mailing address city." }, "payeeState": { "type": "string", "description": "Payee mailing address state." }, "amount": { "type": "integer", "description": "Check amount in cents." }, "memo": { "type": "string", "description": "Memo printed on the check." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never printed on the check or shared with the counterparty." } }, "required": [ "payeeName", "payeeCity", "payeeState", "amount", "memo", "internalDescription" ], "additionalProperties": false, "title": "ApprovalCheck" }, { "type": "null" } ], "description": "Check-specific review context. Null unless the target is a check." }, "realtime": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string", "description": "Description supplied when the payment was created." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the payment credits." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalRealtimeCounterparty" }, { "type": "null" } ], "description": "Destination party and masked account, or null when it can no longer be resolved." } }, "required": [ "description", "internalDescription", "counterparty" ], "additionalProperties": false, "title": "ApprovalRealtime" }, { "type": "null" } ], "description": "Realtime-specific review context. Null unless the target is a realtime payment." }, "denialReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason recorded when the approval was denied, when one was given." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the approval was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the approval was last updated." }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the approval was resolved, or null while pending." } }, "required": [ "status", "target", "payment", "fee", "reasons", "customer", "ach", "wire", "check", "realtime", "denialReason", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." } }, "required": [ "initiatorAgent" ], "additionalProperties": false } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } }, "type": "approval", "id": "apr_019cd1798d8a74dd75c16fc6d843db81", "attributes": { "status": "pending", "target": { "type": "payment", "id": "pay_019cd1798d794c2f2ccf31b4e8394f2d" }, "payment": { "amount": 500000, "currency": "USD" }, "fee": { "amount": 100, "currency": "USD", "payer": "sender", "applied": "on_top" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "customer": null, "ach": null, "realtime": null, "wire": null, "check": null, "denialReason": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z", "resolvedAt": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/approvals/{approvalId}/approve": { "post": { "operationId": "approvals.approve", "summary": "Approve payment or transfer", "description": "Approve the operation under review", "tags": [ "Approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apr_[0-9a-f]{32}$", "description": "Approval ID (apr_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `approval`.", "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID (apr_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Approval status." }, "target": { "type": "object", "properties": { "type": { "enum": [ "payment", "paymentRequest", "deposit", "withdrawal", "ach", "realtime", "wire", "check" ], "type": "string", "description": "Type of operation under approval." }, "id": { "type": "string", "description": "Public ID of the operation under approval. Legacy payment-request approvals reference the parent payment request (prq_), never an internal fulfillment." } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Operation that needs approval." }, "payment": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "amount", "currency" ], "additionalProperties": false }, { "type": "null" } ], "description": "Amount of the operation under review. Null when the underlying amount is unavailable." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee the sender pays on top of `payment.amount`. Before the operation is submitted, including just after approval, a quote at the price in effect when it was created. After, the same fee the operation's own resource reports. Null when no fee applies, including denied or canceled approvals, operations that ended before submission, and operations whose own resource hides the fee. Also null when Billing can't quote the fee at read time; the fee still applies when the operation is submitted." }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Reason type. Always `limitExceeded`.", "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Type of limit that was exceeded." }, "limitAmount": { "type": "integer", "description": "Configured limit amount in cents." }, "actualAmount": { "type": "integer", "description": "Amount that exceeded the limit, in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review." }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party (pty_*) whose wallet a delegated payment spends from." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the customer party, or null when unresolved." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Customer the agent is spending on behalf of, or null when the approval isn't a delegated payment." }, "ach": { "anyOf": [ { "type": "object", "properties": { "direction": { "enum": [ "credit" ], "type": "string", "description": "Direction of the payment." }, "secCode": { "enum": [ "WEB", "PPD", "TEL", "CCD" ], "type": "string", "description": "ACH SEC code the entry is submitted under." }, "companyEntryDescription": { "type": "string", "description": "Company entry description submitted on the ACH entry." }, "addenda": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment-related information submitted as the NACHA addenda record, or null." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "companyName": { "type": "string", "description": "Company name submitted on the ACH entry." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the ACH payment uses." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalAchCounterparty" }, { "type": "null" } ], "description": "Counterparty and masked account, or null when it can no longer be resolved." } }, "required": [ "direction", "secCode", "companyEntryDescription", "addenda", "internalDescription", "companyName", "expectedAvailableAt", "counterparty" ], "additionalProperties": true, "title": "ApprovalAch" }, { "type": "null" } ], "description": "ACH-specific review context. Null unless the target is an ACH." }, "wire": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string", "description": "Description supplied when the wire was created." }, "remittanceInfo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Remittance information, or null." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the payment credits." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalRealtimeCounterparty" }, { "type": "null" } ], "description": "Destination party and masked account, or null when it can no longer be resolved." } }, "required": [ "description", "remittanceInfo", "internalDescription", "counterparty" ], "additionalProperties": false, "title": "ApprovalWire" }, { "type": "null" } ], "description": "Wire-specific review context. Null unless the target is a wire." }, "check": { "anyOf": [ { "type": "object", "properties": { "payeeName": { "type": "string", "description": "Name printed on the check." }, "payeeCity": { "type": "string", "description": "Payee mailing address city." }, "payeeState": { "type": "string", "description": "Payee mailing address state." }, "amount": { "type": "integer", "description": "Check amount in cents." }, "memo": { "type": "string", "description": "Memo printed on the check." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never printed on the check or shared with the counterparty." } }, "required": [ "payeeName", "payeeCity", "payeeState", "amount", "memo", "internalDescription" ], "additionalProperties": false, "title": "ApprovalCheck" }, { "type": "null" } ], "description": "Check-specific review context. Null unless the target is a check." }, "realtime": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string", "description": "Description supplied when the payment was created." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the payment credits." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalRealtimeCounterparty" }, { "type": "null" } ], "description": "Destination party and masked account, or null when it can no longer be resolved." } }, "required": [ "description", "internalDescription", "counterparty" ], "additionalProperties": false, "title": "ApprovalRealtime" }, { "type": "null" } ], "description": "Realtime-specific review context. Null unless the target is a realtime payment." }, "denialReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason recorded when the approval was denied, when one was given." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the approval was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the approval was last updated." }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the approval was resolved, or null while pending." } }, "required": [ "status", "target", "payment", "fee", "reasons", "customer", "ach", "wire", "check", "realtime", "denialReason", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." } }, "required": [ "initiatorAgent" ], "additionalProperties": false } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } }, "type": "approval", "id": "apr_019cd1798d8a74dd75c16fc6d843db81", "attributes": { "status": "approved", "target": { "type": "payment", "id": "pay_019cd1798d794c2f2ccf31b4e8394f2d" }, "payment": { "amount": 500000, "currency": "USD" }, "fee": { "amount": 100, "currency": "USD", "payer": "sender", "applied": "on_top" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "customer": null, "ach": null, "realtime": null, "wire": null, "check": null, "denialReason": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:45:00.000Z", "resolvedAt": "2026-01-04T15:45:00.000Z" } } } } } } }, "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": [] } ] } }, "/approvals/{approvalId}/deny": { "post": { "operationId": "approvals.deny", "summary": "Deny payment or transfer", "description": "Deny the operation under review", "tags": [ "Approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apr_[0-9a-f]{32}$", "description": "Approval ID (apr_*)." } }, { "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": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the approval was denied, recorded on the approval for audit. Maximum 500 characters." } }, "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false, "description": "Denial details. Send empty attributes to deny without a reason." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "reason": "Invoice does not match the vendor's bank account on file" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `approval`.", "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID (apr_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Approval status." }, "target": { "type": "object", "properties": { "type": { "enum": [ "payment", "paymentRequest", "deposit", "withdrawal", "ach", "realtime", "wire", "check" ], "type": "string", "description": "Type of operation under approval." }, "id": { "type": "string", "description": "Public ID of the operation under approval. Legacy payment-request approvals reference the parent payment request (prq_), never an internal fulfillment." } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Operation that needs approval." }, "payment": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "amount", "currency" ], "additionalProperties": false }, { "type": "null" } ], "description": "Amount of the operation under review. Null when the underlying amount is unavailable." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee the sender pays on top of `payment.amount`. Before the operation is submitted, including just after approval, a quote at the price in effect when it was created. After, the same fee the operation's own resource reports. Null when no fee applies, including denied or canceled approvals, operations that ended before submission, and operations whose own resource hides the fee. Also null when Billing can't quote the fee at read time; the fee still applies when the operation is submitted." }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Reason type. Always `limitExceeded`.", "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Type of limit that was exceeded." }, "limitAmount": { "type": "integer", "description": "Configured limit amount in cents." }, "actualAmount": { "type": "integer", "description": "Amount that exceeded the limit, in cents." }, "currency": { "type": "string", "description": "Currency code." } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review." }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party (pty_*) whose wallet a delegated payment spends from." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the customer party, or null when unresolved." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Customer the agent is spending on behalf of, or null when the approval isn't a delegated payment." }, "ach": { "anyOf": [ { "type": "object", "properties": { "direction": { "enum": [ "credit" ], "type": "string", "description": "Direction of the payment." }, "secCode": { "enum": [ "WEB", "PPD", "TEL", "CCD" ], "type": "string", "description": "ACH SEC code the entry is submitted under." }, "companyEntryDescription": { "type": "string", "description": "Company entry description submitted on the ACH entry." }, "addenda": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment-related information submitted as the NACHA addenda record, or null." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "companyName": { "type": "string", "description": "Company name submitted on the ACH entry." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the ACH payment uses." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalAchCounterparty" }, { "type": "null" } ], "description": "Counterparty and masked account, or null when it can no longer be resolved." } }, "required": [ "direction", "secCode", "companyEntryDescription", "addenda", "internalDescription", "companyName", "expectedAvailableAt", "counterparty" ], "additionalProperties": true, "title": "ApprovalAch" }, { "type": "null" } ], "description": "ACH-specific review context. Null unless the target is an ACH." }, "wire": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string", "description": "Description supplied when the wire was created." }, "remittanceInfo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Remittance information, or null." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the payment credits." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalRealtimeCounterparty" }, { "type": "null" } ], "description": "Destination party and masked account, or null when it can no longer be resolved." } }, "required": [ "description", "remittanceInfo", "internalDescription", "counterparty" ], "additionalProperties": false, "title": "ApprovalWire" }, { "type": "null" } ], "description": "Wire-specific review context. Null unless the target is a wire." }, "check": { "anyOf": [ { "type": "object", "properties": { "payeeName": { "type": "string", "description": "Name printed on the check." }, "payeeCity": { "type": "string", "description": "Payee mailing address city." }, "payeeState": { "type": "string", "description": "Payee mailing address state." }, "amount": { "type": "integer", "description": "Check amount in cents." }, "memo": { "type": "string", "description": "Memo printed on the check." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never printed on the check or shared with the counterparty." } }, "required": [ "payeeName", "payeeCity", "payeeState", "amount", "memo", "internalDescription" ], "additionalProperties": false, "title": "ApprovalCheck" }, { "type": "null" } ], "description": "Check-specific review context. Null unless the target is a check." }, "realtime": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string", "description": "Description supplied when the payment was created." }, "internalDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network." }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "externalPartyId": { "type": "string", "pattern": "^epty_[0-9a-f]{32}$", "description": "External party being paid (epty_*)." }, "name": { "type": "string", "description": "External party display or legal name." }, "kind": { "enum": [ "individual", "business" ], "type": "string", "description": "External party type." }, "account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^epa_[0-9a-f]{32}$", "description": "External party account (epa_*)." }, "accountType": { "enum": [ "checking", "savings" ], "type": "string", "description": "Bank account type." }, "last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four account number digits." }, "mask": { "type": "string", "description": "Masked account number." } }, "required": [ "id", "accountType", "last4", "mask" ], "additionalProperties": false, "description": "Masked bank account the payment credits." } }, "required": [ "externalPartyId", "name", "kind", "account" ], "additionalProperties": false, "title": "ApprovalRealtimeCounterparty" }, { "type": "null" } ], "description": "Destination party and masked account, or null when it can no longer be resolved." } }, "required": [ "description", "internalDescription", "counterparty" ], "additionalProperties": false, "title": "ApprovalRealtime" }, { "type": "null" } ], "description": "Realtime-specific review context. Null unless the target is a realtime payment." }, "denialReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason recorded when the approval was denied, when one was given." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the approval was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the approval was last updated." }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the approval was resolved, or null while pending." } }, "required": [ "status", "target", "payment", "fee", "reasons", "customer", "ach", "wire", "check", "realtime", "denialReason", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." } }, "required": [ "initiatorAgent" ], "additionalProperties": false } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } }, "type": "approval", "id": "apr_019cd1798d8a74dd75c16fc6d843db81", "attributes": { "status": "denied", "target": { "type": "payment", "id": "pay_019cd1798d794c2f2ccf31b4e8394f2d" }, "payment": { "amount": 500000, "currency": "USD" }, "fee": null, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "customer": null, "ach": null, "realtime": null, "wire": null, "check": null, "denialReason": null, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:45:00.000Z", "resolvedAt": "2026-01-04T15:45:00.000Z" } } } } } } }, "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": [] } ] } }, "/party-invitations": { "post": { "operationId": "invitations.create", "summary": "Create party invitations", "description": "Invite people to join the party. Available for business parties.", "tags": [ "Invitations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "invitations": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 80, "format": "email", "description": "Email address to invite." }, "role": { "enum": [ "ADMIN", "MEMBER" ], "type": "string", "description": "Role to assign on acceptance." } }, "required": [ "email", "role" ], "additionalProperties": false, "title": "InvitationItem", "description": "Single invitation in batch request." }, "description": "List of invitations to create (max 100)." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Tags applied to each invitation.", "maxProperties": 30 } }, "required": [ "invitations" ], "additionalProperties": false, "title": "InvitationCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "InvitationCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateInvitationsInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "invitations": [ { "email": "engineer@acmepayments.com", "role": "MEMBER" }, { "email": "cfo@acmepayments.com", "role": "ADMIN" } ], "tags": { "team": "operations" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `invitation`.", "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "pattern": "^inv_[0-9a-f]{32}$", "description": "Invitation ID (inv_*)." }, "attributes": { "type": "object", "properties": { "email": { "type": "string", "description": "Invitee email address." }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER" ], "type": "string", "description": "Role assigned on acceptance." }, "status": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Invitation status." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "expiresAt": { "type": "string", "description": "RFC 3339 timestamp when this invitation expires." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this invitation was created." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this invitation was accepted, or null." } }, "required": [ "email", "role", "status", "tags", "expiresAt", "createdAt", "acceptedAt" ], "additionalProperties": false, "title": "InvitationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "InvitationResource" }, "description": "Successfully created invitation resources." }, "meta": { "type": "object", "properties": { "failed": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address that could not be invited." }, "error": { "type": "string", "description": "Reason the invitation failed." } }, "required": [ "email", "error" ], "additionalProperties": false, "title": "InvitationResult", "description": "Failed invitation result." }, "description": "Failed invitation attempts with error details." } }, "required": [ "failed" ], "additionalProperties": false, "title": "CreateInvitationsMeta", "description": "Batch invitation metadata." } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CreateInvitationsOutput" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "invitation", "id": "inv_019cd4a832f37c4b8a1d63e94b7c8d12", "attributes": { "email": "engineer@acmepayments.com", "role": "MEMBER", "status": "PENDING", "tags": { "team": "operations" }, "expiresAt": "2026-01-11T15:30:00.000Z", "createdAt": "2026-01-04T15:30:00.000Z", "acceptedAt": null } } ], "meta": { "failed": [ { "email": "cfo@acmepayments.com", "error": "User is already a member of this party" } ] } } } } } }, "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": [] } ], "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." } ] }, "get": { "operationId": "invitations.list", "summary": "List party invitations", "description": "List party invitations", "tags": [ "Invitations" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party to filter by; only your own party is accepted." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "email", "in": "query", "schema": { "type": "string", "maxLength": 254, "description": "Filter by email." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Filter by status." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `invitation`.", "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "pattern": "^inv_[0-9a-f]{32}$", "description": "Invitation ID (inv_*)." }, "attributes": { "type": "object", "properties": { "email": { "type": "string", "description": "Invitee email address." }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER" ], "type": "string", "description": "Role assigned on acceptance." }, "status": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Invitation status." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "expiresAt": { "type": "string", "description": "RFC 3339 timestamp when this invitation expires." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this invitation was created." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this invitation was accepted, or null." } }, "required": [ "email", "role", "status", "tags", "expiresAt", "createdAt", "acceptedAt" ], "additionalProperties": false, "title": "InvitationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "InvitationResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "InvitationListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "invitation", "id": "inv_019cd4a832f37c4b8a1d63e94b7c8d12", "attributes": { "email": "engineer@acmepayments.com", "role": "MEMBER", "status": "PENDING", "tags": { "team": "operations" }, "expiresAt": "2026-01-11T15:30:00.000Z", "createdAt": "2026-01-04T15:30:00.000Z", "acceptedAt": null } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/party-invitations/{invitationId}": { "delete": { "operationId": "invitations.revoke", "summary": "Revoke party invitation", "description": "Revoke a pending party invitation", "tags": [ "Invitations" ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "Invitation ID (inv_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `invitation`.", "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "pattern": "^inv_[0-9a-f]{32}$", "description": "Invitation ID (inv_*)." }, "attributes": { "type": "object", "properties": { "email": { "type": "string", "description": "Invitee email address." }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER" ], "type": "string", "description": "Role assigned on acceptance." }, "status": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Invitation status." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "expiresAt": { "type": "string", "description": "RFC 3339 timestamp when this invitation expires." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this invitation was created." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this invitation was accepted, or null." } }, "required": [ "email", "role", "status", "tags", "expiresAt", "createdAt", "acceptedAt" ], "additionalProperties": false, "title": "InvitationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "InvitationResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "InvitationRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "invitation", "id": "inv_019cd4a832f37c4b8a1d63e94b7c8d12", "attributes": { "email": "engineer@acmepayments.com", "role": "MEMBER", "status": "REVOKED", "tags": { "team": "operations" }, "expiresAt": "2026-01-11T15:30:00.000Z", "createdAt": "2026-01-04T15:30:00.000Z", "acceptedAt": null } }, "meta": { "deleted": true } } } } } }, "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": [] } ] } }, "/parties/me": { "get": { "operationId": "parties.get", "summary": "Get party", "description": "Get the current party", "tags": [ "Parties" ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "attributes": { "type": "object", "properties": { "partyType": { "enum": [ "PERSON", "ORG" ], "type": "string", "description": "Party type." }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal business name for `ORG` parties." }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal first name for `PERSON` parties." }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal last name for `PERSON` parties." }, "status": { "enum": [ "PROVISIONAL", "ACTIVE", "SUSPENDED", "INACTIVE" ], "type": "string", "description": "Party status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the party was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the party was last updated." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for the party." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle, such as @acme, or null when none is set." }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "persona": { "anyOf": [ { "enum": [ "INDIVIDUAL", "DEVELOPER" ], "type": "string" }, { "type": "null" } ], "description": "Party persona, when available." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary contact email." }, "primaryPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary phone number." }, "addressLine1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Street address line 1." }, "addressCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City." }, "addressState": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province." }, "addressPostalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal or ZIP code." }, "addressCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code (e.g., US)." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this party (usr_*)." } }, "required": [ "partyType", "legalName", "firstName", "lastName", "status", "createdAt", "updatedAt", "displayName", "handle", "avatarUrl", "persona", "email", "primaryPhone", "addressLine1", "addressCity", "addressState", "addressPostalCode", "addressCountry", "createdBy" ], "additionalProperties": false, "title": "PartyAttributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false, "title": "PartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "type": "party", "attributes": { "partyType": "ORG", "legalName": "Acme Payments, Inc.", "firstName": null, "lastName": null, "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z", "displayName": "Acme Payments", "handle": "@acme", "avatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp", "persona": "DEVELOPER", "email": "billing@acmepayments.com", "primaryPhone": "+1-555-555-0100", "addressLine1": "123 Main Street", "addressCity": "San Francisco", "addressState": "CA", "addressPostalCode": "94105", "addressCountry": "US", "createdBy": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ], "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." } ] }, "patch": { "operationId": "parties.update", "summary": "Update party", "description": "Update the current party", "tags": [ "Parties" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32 }, { "type": "null" } ], "description": "New display name. For person parties the display name is derived from the legal name and this field is ignored. Pass null to clear it." } }, "additionalProperties": false, "title": "PartyUpdateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "PartyUpdateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "UpdateOwnPartyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "displayName": "Acme Payments Inc." } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "attributes": { "type": "object", "properties": { "partyType": { "enum": [ "PERSON", "ORG" ], "type": "string", "description": "Party type." }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal business name for `ORG` parties." }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal first name for `PERSON` parties." }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal last name for `PERSON` parties." }, "status": { "enum": [ "PROVISIONAL", "ACTIVE", "SUSPENDED", "INACTIVE" ], "type": "string", "description": "Party status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the party was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the party was last updated." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for the party." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle, such as @acme, or null when none is set." }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "persona": { "anyOf": [ { "enum": [ "INDIVIDUAL", "DEVELOPER" ], "type": "string" }, { "type": "null" } ], "description": "Party persona, when available." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary contact email." }, "primaryPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary phone number." }, "addressLine1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Street address line 1." }, "addressCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City." }, "addressState": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province." }, "addressPostalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal or ZIP code." }, "addressCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code (e.g., US)." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this party (usr_*)." } }, "required": [ "partyType", "legalName", "firstName", "lastName", "status", "createdAt", "updatedAt", "displayName", "handle", "avatarUrl", "persona", "email", "primaryPhone", "addressLine1", "addressCity", "addressState", "addressPostalCode", "addressCountry", "createdBy" ], "additionalProperties": false, "title": "PartyAttributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false, "title": "PartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "type": "party", "attributes": { "partyType": "ORG", "legalName": "Acme Payments, Inc.", "firstName": null, "lastName": null, "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-15T10:30:00.000Z", "displayName": "Acme Payments Inc.", "handle": "@acme", "avatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp", "persona": "DEVELOPER", "email": "billing@acmepayments.com", "primaryPhone": "+1-555-555-0100", "addressLine1": "123 Main Street", "addressCity": "San Francisco", "addressState": "CA", "addressPostalCode": "94105", "addressCountry": "US", "createdBy": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ], "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." } ] } }, "/parties/me/members": { "get": { "operationId": "parties.listMembers", "summary": "List party members", "description": "List active members of the party. Available for business parties.", "tags": [ "Parties" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `user`.", "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "pattern": "^usr_[0-9a-f]{32}$", "description": "User ID (usr_*)." }, "attributes": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER" ], "type": "string", "description": "User's role in the party." }, "status": { "enum": [ "ACTIVE", "REVOKED", "DELETED" ], "type": "string", "description": "Membership status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the membership was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the membership was last updated." }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name of the user." }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name of the user." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address of the user." }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public avatar URL of the member's own person party, or null when none is set." } }, "required": [ "partyId", "role", "status", "createdAt", "updatedAt", "firstName", "lastName", "email", "avatarUrl" ], "title": "UserMemberAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "UserMemberResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PartyMembersListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "user", "id": "usr_019cd1798d657de5b5fed4198cb9fac0", "attributes": { "partyId": "pty_019cd1798d617f65a79cb965dda9eac3", "role": "MEMBER", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z", "firstName": "Eric", "lastName": "Smith", "email": "eric@acmepayments.com", "avatarUrl": null } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/parties/{partyId}/compliance": { "get": { "operationId": "parties.getCompliance", "summary": "Get party compliance", "description": "Get a party's current compliance status", "tags": [ "Parties" ], "parameters": [ { "name": "partyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." } }, { "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": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Compliance case ID." }, "type": { "description": "Resource type. Always `compliance_case`.", "type": "string", "enum": [ "compliance_case" ] }, "attributes": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*) this compliance status applies to." }, "status": { "enum": [ "preparingSubmission", "submitted", "actionRequired", "approved", "rejected" ], "type": "string", "description": "Current compliance status." }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when compliance was most recently approved, or null when it has not been." } }, "required": [ "partyId", "status", "verifiedAt" ], "additionalProperties": false, "title": "ComplianceCaseAttributes" }, "version": { "type": "integer", "description": "Version of the compliance case." } }, "required": [ "id", "type", "attributes", "version" ], "additionalProperties": false, "title": "ComplianceCaseResource" }, { "type": "null" } ], "description": "Compliance case for the party, or null when none exists." } }, "required": [ "data" ], "additionalProperties": false, "title": "PartyComplianceResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "cpc_019cd1798d9baf48d79b8d6445879c46", "type": "compliance_case", "attributes": { "partyId": "pty_019cd1798d617f65a79cb965dda9eac3", "status": "approved", "verifiedAt": "2026-01-04T15:30:00.000Z" }, "version": 7 } } } } } }, "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": [] } ] } }, "/parties/{partyId}/branding": { "get": { "operationId": "parties.getBrandingForParty", "summary": "Get party branding", "description": "Get branding for your party or a party that has delegated party read permission to you", "tags": [ "Parties" ], "parameters": [ { "name": "partyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "partyBranding" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "brandColor": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-F]{6}$" }, { "type": "null" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public business profile photo URL, or null when absent" } }, "required": [ "brandColor" ] } }, "required": [ "type", "id", "attributes" ] } }, "required": [ "data" ] }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "partyBranding", "id": "pty_019cd1798d617f65a79cb965dda9eac3", "attributes": { "brandColor": "#2563EB" } } } } } } }, "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": [] } ] }, "patch": { "operationId": "parties.updateBrandingForParty", "summary": "Update party branding", "description": "Update branding for your party or a party that has delegated party update permission to you. Profile photo changes require a business party in Live.", "tags": [ "Parties" ], "parameters": [ { "name": "partyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, { "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": { "brandColor": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }, { "type": "null" } ] }, "avatarObjectKey": { "anyOf": [ { "type": "string", "pattern": "^party-avatars\\/pty_[0-9a-f]{32}\\/\\d{4}-\\d{2}-\\d{2}_[a-f0-9]{16}\\.(jpg|png|webp)$" }, { "type": "null" } ], "description": "Uploaded business photo object key; null removes the photo. Omit to leave unchanged." } }, "additionalProperties": false, "minProperties": 1 } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "brandColor": "#2563EB" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "partyBranding" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "brandColor": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-F]{6}$" }, { "type": "null" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public business profile photo URL, or null when absent" } }, "required": [ "brandColor" ] } }, "required": [ "type", "id", "attributes" ] } }, "required": [ "data" ] }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "partyBranding", "id": "pty_019cd1798d617f65a79cb965dda9eac3", "attributes": { "brandColor": "#2563EB" } } } } } } }, "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": [] } ] } }, "/parties/{partyId}/branding/photo-uploads": { "post": { "operationId": "parties.createBrandingPhotoUpload", "summary": "Create branding photo upload", "description": "Create an upload for a business profile photo in Live using your own or delegated party update permission", "tags": [ "Parties" ], "parameters": [ { "name": "partyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, { "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": { "contentType": { "enum": [ "image/jpeg", "image/png", "image/webp" ], "type": "string", "description": "Avatar image MIME type" }, "sizeBytes": { "type": "integer", "maximum": 5242880, "exclusiveMinimum": 0, "description": "Avatar image size in bytes" } }, "required": [ "contentType", "sizeBytes" ], "additionalProperties": false, "title": "CreatePartyAvatarUploadInput" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "contentType": "image/png", "sizeBytes": 128000 } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "partyAvatarUpload" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "uploadUrl": { "type": "string", "format": "uri", "description": "Presigned S3 POST URL for the avatar upload" }, "uploadFields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Form fields for the presigned S3 POST" }, "objectKey": { "type": "string", "description": "Opaque avatar object key to pass to completeAvatarUpload" } }, "required": [ "uploadUrl", "uploadFields", "objectKey" ], "additionalProperties": false, "title": "CreatePartyAvatarUploadOutput" } }, "required": [ "type", "id", "attributes" ] } }, "required": [ "data" ] }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "partyAvatarUpload", "id": "pty_019cd1798d617f65a79cb965dda9eac3", "attributes": { "uploadUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com", "uploadFields": { "key": "party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-09-15_0123456789abcdef.png", "Content-Type": "image/png", "policy": "example-presigned-policy", "x-amz-signature": "example-signature" }, "objectKey": "party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-09-15_0123456789abcdef.png" } } } } } } }, "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": [] } ] } }, "/parties/me/handle": { "put": { "operationId": "parties.setHandle", "summary": "Set party handle", "description": "Set your party's handle", "tags": [ "Parties" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "handle": { "type": "string", "maxLength": 30, "pattern": "^[a-z0-9][a-z0-9._]{1,28}[a-z0-9]$", "description": "Party handle without the \"@\" prefix, such as \"acme\". Renames the handle; it cannot be cleared. For 14 days after a rename, only the same party can reclaim the released name." } }, "required": [ "handle" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "SetPartyHandleInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "handle": "acme" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "attributes": { "type": "object", "properties": { "partyType": { "enum": [ "PERSON", "ORG" ], "type": "string", "description": "Party type." }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal business name for `ORG` parties." }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal first name for `PERSON` parties." }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal last name for `PERSON` parties." }, "status": { "enum": [ "PROVISIONAL", "ACTIVE", "SUSPENDED", "INACTIVE" ], "type": "string", "description": "Party status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the party was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the party was last updated." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for the party." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle, such as @acme, or null when none is set." }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "persona": { "anyOf": [ { "enum": [ "INDIVIDUAL", "DEVELOPER" ], "type": "string" }, { "type": "null" } ], "description": "Party persona, when available." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary contact email." }, "primaryPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary phone number." }, "addressLine1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Street address line 1." }, "addressCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City." }, "addressState": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province." }, "addressPostalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal or ZIP code." }, "addressCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code (e.g., US)." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this party (usr_*)." } }, "required": [ "partyType", "legalName", "firstName", "lastName", "status", "createdAt", "updatedAt", "displayName", "handle", "avatarUrl", "persona", "email", "primaryPhone", "addressLine1", "addressCity", "addressState", "addressPostalCode", "addressCountry", "createdBy" ], "additionalProperties": false, "title": "PartyAttributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false, "title": "PartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "type": "party", "attributes": { "partyType": "ORG", "legalName": "Acme Payments, Inc.", "firstName": null, "lastName": null, "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z", "displayName": "Acme Payments", "handle": "@acme", "avatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp", "persona": "DEVELOPER", "email": "billing@acmepayments.com", "primaryPhone": "+1-555-555-0100", "addressLine1": "123 Main Street", "addressCity": "San Francisco", "addressState": "CA", "addressPostalCode": "94105", "addressCountry": "US", "createdBy": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ], "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." } ] } }, "/parties/me/limits": { "get": { "operationId": "parties.getLimits", "summary": "Get party approval limits", "description": "Get the party's approval limits", "tags": [ "Parties" ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `partyLimitPolicy`.", "type": "string", "enum": [ "partyLimitPolicy" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-transaction spend cap in cents, or null when unset." }, "perDay": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Daily (UTC) spend cap in cents, or null when unset." }, "perMonth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Calendar-month (UTC) spend cap in cents, or null when unset." } }, "required": [ "perTransaction", "perDay", "perMonth" ], "additionalProperties": false, "title": "PartyLimits" }, { "type": "null" } ], "description": "Party-wide spend caps applied to money movement, or null when no limits are set." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currency of the configured limits, or null when none are set." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the limits were last updated, or null." } }, "required": [ "limits", "currency", "updatedAt" ], "additionalProperties": false, "title": "PartyLimitPolicyAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "PartyLimitPolicyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartyLimitPolicyResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "partyLimitPolicy", "id": "pty_019cd1798d617f65a79cb965dda9eac3", "attributes": { "limits": { "perTransaction": 250000, "perDay": 1000000, "perMonth": null }, "currency": "USD", "updatedAt": "2026-01-04T15:30:00.000Z" } } } } } } }, "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": [] } ], "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." } ] }, "put": { "operationId": "parties.setLimits", "summary": "Set party approval limits", "description": "Set the party's approval limits", "tags": [ "Parties" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents. Pass null or omit to clear it." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents. Pass null or omit to clear it." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents. Pass null or omit to clear it." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency of the configured limits." } }, "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "SetPartyLimitsInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "perTransaction": 250000, "perDay": 1000000, "perMonth": null, "currency": "USD" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `partyLimitPolicy`.", "type": "string", "enum": [ "partyLimitPolicy" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-transaction spend cap in cents, or null when unset." }, "perDay": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Daily (UTC) spend cap in cents, or null when unset." }, "perMonth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Calendar-month (UTC) spend cap in cents, or null when unset." } }, "required": [ "perTransaction", "perDay", "perMonth" ], "additionalProperties": false, "title": "PartyLimits" }, { "type": "null" } ], "description": "Party-wide spend caps applied to money movement, or null when no limits are set." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currency of the configured limits, or null when none are set." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the limits were last updated, or null." } }, "required": [ "limits", "currency", "updatedAt" ], "additionalProperties": false, "title": "PartyLimitPolicyAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "PartyLimitPolicyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartyLimitPolicyResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "partyLimitPolicy", "id": "pty_019cd1798d617f65a79cb965dda9eac3", "attributes": { "limits": { "perTransaction": 250000, "perDay": 1000000, "perMonth": null }, "currency": "USD", "updatedAt": "2026-01-04T15:30:00.000Z" } } } } } } }, "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": [] } ], "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." } ] }, "delete": { "operationId": "parties.disableLimits", "summary": "Disable party approval limits", "description": "Disable all approval limits for the party", "tags": [ "Parties" ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `partyLimitPolicy`.", "type": "string", "enum": [ "partyLimitPolicy" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-transaction spend cap in cents, or null when unset." }, "perDay": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Daily (UTC) spend cap in cents, or null when unset." }, "perMonth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Calendar-month (UTC) spend cap in cents, or null when unset." } }, "required": [ "perTransaction", "perDay", "perMonth" ], "additionalProperties": false, "title": "PartyLimits" }, { "type": "null" } ], "description": "Party-wide spend caps applied to money movement, or null when no limits are set." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currency of the configured limits, or null when none are set." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the limits were last updated, or null." } }, "required": [ "limits", "currency", "updatedAt" ], "additionalProperties": false, "title": "PartyLimitPolicyAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "PartyLimitPolicyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartyLimitPolicyResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "partyLimitPolicy", "id": "pty_019cd1798d617f65a79cb965dda9eac3", "attributes": { "limits": null, "currency": null, "updatedAt": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ], "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." } ] } }, "/parties/me/members/{userId}": { "delete": { "operationId": "parties.removeMember", "summary": "Remove party member", "description": "Remove a member from the party", "tags": [ "Parties" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^usr_[0-9a-f]{32}$", "description": "User ID (usr_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `user`.", "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "pattern": "^usr_[0-9a-f]{32}$", "description": "User ID (usr_*)." } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "RemovedMemberResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "user", "id": "usr_019cd1798d657de5b5fed4198cb9fac0" }, "meta": { "deleted": true } } } } } }, "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": [] } ] } }, "/wallets": { "get": { "operationId": "wallets.list", "summary": "List wallets", "description": "List party wallets or the wallets granted to the acting agent", "tags": [ "Wallets" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `wallet`.", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the owning party's default. Agent calls resolve their default from wallet grants." }, "agentDefault": { "type": "boolean", "description": "Present for agent wallet list and detail reads. Whether this wallet is the agent's default in the current context. For a connected customer, this is the default for that customer connection, independently of the party's isDefault." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wallet was created, or null when unknown." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount available to spend or withdraw, in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total amount of payments awaiting claim, in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account number for ACH deposits. Returned when fetching a single wallet, null in list responses." }, "routingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank routing number for ACH deposits. Returned when fetching a single wallet, null in list responses." } }, "required": [ "bankName", "accountNumber", "routingNumber" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "tags", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false, "title": "WalletListMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WalletListResponse", "description": "Wallet resources visible to this credential. Agents receive the same wallet fields, limited to wallets granted to their current agent or customer connection, with an additional agentDefault flag." }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc", "attributes": { "status": "active", "walletType": "standard", "isDefault": true, "createdAt": "2026-01-04T15:30:00.000Z", "displayName": "Operating", "description": null, "tags": { "environment": "production" }, "balance": { "available": 120000, "total": 125000, "currency": "USD" }, "claims": { "amount": 5000, "count": 1 }, "depositInstructions": { "bankName": "Natural", "accountNumber": null, "routingNumber": null } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } }, { "type": "wallet", "id": "wal_019cd1798d72cf01303c7c04148c9b8d", "attributes": { "status": "active", "walletType": "vault", "isDefault": false, "createdAt": "2026-01-04T15:30:00.000Z", "displayName": "Vault", "description": null, "tags": {}, "balance": { "available": 500000, "total": 500000, "currency": "USD" }, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Natural", "accountNumber": null, "routingNumber": null } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] }, "post": { "operationId": "wallets.create", "summary": "Create wallet", "description": "Create a standard wallet", "tags": [ "Wallets" ], "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 act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "displayName": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Wallet name." }, "description": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "User-facing wallet description." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.", "maxProperties": 30 } }, "required": [ "displayName" ], "additionalProperties": false, "title": "WalletCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WalletCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "displayName": "Payroll", "description": "Dedicated wallet for payroll runs", "tags": { "department": "payroll" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "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}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the owning party's default. Agent calls resolve their default from wallet grants." }, "agentDefault": { "type": "boolean", "description": "Present for agent wallet list and detail reads. Whether this wallet is the agent's default in the current context. For a connected customer, this is the default for that customer connection, independently of the party's isDefault." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wallet was created, or null when unknown." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount available to spend or withdraw, in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total amount of payments awaiting claim, in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account number for ACH deposits. Returned when fetching a single wallet, null in list responses." }, "routingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank routing number for ACH deposits. Returned when fetching a single wallet, null in list responses." } }, "required": [ "bankName", "accountNumber", "routingNumber" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "tags", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_019cd1798d73e6f55d90188bb8ddbd9b", "attributes": { "status": "active", "walletType": "standard", "isDefault": false, "createdAt": "2026-01-04T15:30:00.000Z", "displayName": "Payroll", "description": "Dedicated wallet for payroll runs", "tags": { "department": "payroll" }, "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Natural", "accountNumber": null, "routingNumber": null } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-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." } ] } }, "/wallets/{walletId}": { "get": { "operationId": "wallets.get", "summary": "Get wallet", "description": "Get a wallet", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "type": { "description": "Resource type. Always `wallet`.", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the owning party's default. Agent calls resolve their default from wallet grants." }, "agentDefault": { "type": "boolean", "description": "Present for agent wallet list and detail reads. Whether this wallet is the agent's default in the current context. For a connected customer, this is the default for that customer connection, independently of the party's isDefault." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wallet was created, or null when unknown." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount available to spend or withdraw, in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total amount of payments awaiting claim, in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account number for ACH deposits. Returned when fetching a single wallet, null in list responses." }, "routingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank routing number for ACH deposits. Returned when fetching a single wallet, null in list responses." } }, "required": [ "bankName", "accountNumber", "routingNumber" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "tags", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc", "attributes": { "status": "active", "walletType": "standard", "isDefault": true, "createdAt": "2026-01-04T15:30:00.000Z", "displayName": "Operating", "description": null, "tags": { "environment": "production" }, "balance": { "available": 120000, "total": 125000, "currency": "USD" }, "claims": { "amount": 5000, "count": 1 }, "depositInstructions": { "bankName": "Natural", "accountNumber": "8412300199", "routingNumber": "084106768" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] }, "patch": { "operationId": "wallets.update", "summary": "Update wallet", "description": "Update a wallet's display name, description, or tags", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "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": { "displayName": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Wallet name." }, "description": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "User-facing wallet description." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "description": "Metadata changes. A null value removes the key." } }, "additionalProperties": false, "title": "WalletUpdateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WalletUpdateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletUpdateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "displayName": "Operating (US)", "description": "Primary USD operating wallet", "tags": { "region": "us", "legacy_key": null } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "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}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the owning party's default. Agent calls resolve their default from wallet grants." }, "agentDefault": { "type": "boolean", "description": "Present for agent wallet list and detail reads. Whether this wallet is the agent's default in the current context. For a connected customer, this is the default for that customer connection, independently of the party's isDefault." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wallet was created, or null when unknown." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount available to spend or withdraw, in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total amount of payments awaiting claim, in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account number for ACH deposits. Returned when fetching a single wallet, null in list responses." }, "routingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank routing number for ACH deposits. Returned when fetching a single wallet, null in list responses." } }, "required": [ "bankName", "accountNumber", "routingNumber" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "tags", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc", "attributes": { "status": "active", "walletType": "standard", "isDefault": true, "createdAt": "2026-01-04T15:30:00.000Z", "displayName": "Operating (US)", "description": "Primary USD operating wallet", "tags": { "environment": "production", "region": "us" }, "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Natural", "accountNumber": null, "routingNumber": null } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] } }, "/wallets/{walletId}/default": { "post": { "operationId": "wallets.setDefault", "summary": "Set default wallet", "description": "Set the party's default wallet, where payments addressed to their email, phone number, or handle land", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "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}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the owning party's default. Agent calls resolve their default from wallet grants." }, "agentDefault": { "type": "boolean", "description": "Present for agent wallet list and detail reads. Whether this wallet is the agent's default in the current context. For a connected customer, this is the default for that customer connection, independently of the party's isDefault." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wallet was created, or null when unknown." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount available to spend or withdraw, in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total amount of payments awaiting claim, in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account number for ACH deposits. Returned when fetching a single wallet, null in list responses." }, "routingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank routing number for ACH deposits. Returned when fetching a single wallet, null in list responses." } }, "required": [ "bankName", "accountNumber", "routingNumber" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "tags", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc", "attributes": { "status": "active", "walletType": "standard", "isDefault": true, "createdAt": "2026-01-04T15:30:00.000Z", "displayName": "Operating", "description": null, "tags": { "environment": "production" }, "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Natural", "accountNumber": null, "routingNumber": null } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] } }, "/wallets/{walletId}/freeze": { "post": { "operationId": "wallets.freeze", "summary": "Freeze wallet", "description": "Freeze a wallet", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `wallet`.", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the owning party's default. Agent calls resolve their default from wallet grants." }, "agentDefault": { "type": "boolean", "description": "Present for agent wallet list and detail reads. Whether this wallet is the agent's default in the current context. For a connected customer, this is the default for that customer connection, independently of the party's isDefault." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wallet was created, or null when unknown." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount available to spend or withdraw, in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total amount of payments awaiting claim, in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account number for ACH deposits. Returned when fetching a single wallet, null in list responses." }, "routingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank routing number for ACH deposits. Returned when fetching a single wallet, null in list responses." } }, "required": [ "bankName", "accountNumber", "routingNumber" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "tags", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc", "attributes": { "status": "frozen", "walletType": "standard", "isDefault": false, "createdAt": "2026-01-04T15:30:00.000Z", "displayName": "Operating", "description": null, "tags": { "environment": "production" }, "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Natural", "accountNumber": null, "routingNumber": null } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] } }, "/wallets/{walletId}/unfreeze": { "post": { "operationId": "wallets.unfreeze", "summary": "Unfreeze wallet", "description": "Unfreeze a wallet that was frozen through the API", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `wallet`.", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet status." }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet type: a spendable standard wallet or the vault." }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the owning party's default. Agent calls resolve their default from wallet grants." }, "agentDefault": { "type": "boolean", "description": "Present for agent wallet list and detail reads. Whether this wallet is the agent's default in the current context. For a connected customer, this is the default for that customer connection, independently of the party's isDefault." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the wallet was created, or null when unknown." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Wallet name, when set." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount available to spend or withdraw, in cents." }, "total": { "type": "integer", "description": "Total wallet ledger balance in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code." } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance, when available." }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total amount of payments awaiting claim, in cents." }, "count": { "type": "integer", "description": "Number of unclaimed product payments." } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Party-level claimable payment totals, surfaced on the default wallet (or the first wallet when none is default)." }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account number for ACH deposits. Returned when fetching a single wallet, null in list responses." }, "routingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank routing number for ACH deposits. Returned when fetching a single wallet, null in list responses." } }, "required": [ "bankName", "accountNumber", "routingNumber" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "Receiving bank for ACH deposits to this wallet, when available." } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "tags", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the wallet." } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc", "attributes": { "status": "active", "walletType": "standard", "isDefault": false, "createdAt": "2026-01-04T15:30:00.000Z", "displayName": "Operating", "description": null, "tags": { "environment": "production" }, "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Natural", "accountNumber": null, "routingNumber": null } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] } }, "/wallets/{walletId}/agents": { "post": { "operationId": "wallets.attachAgent", "summary": "Grant agent access to wallet", "description": "Grant an owned or customer-connected agent access to a standard wallet. Customer connections also require delegations.update. The first wallet becomes the default; adding another preserves the existing default. Agent credentials and delegated callers cannot manage wallet access.", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "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": { "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Owned agent or active customer-connected agent (agt_*) to grant access to." } }, "required": [ "agentId" ], "additionalProperties": false, "title": "WalletAgentAttachAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WalletAgentAttachData" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletAgentAttachRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "agentId": "agt_019cd1798d637a4da75dce386343931d" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description. Null for connected agents." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Agent tags. Empty for connected agents." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status: ACTIVE, or REVOKED after deletion." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Agent limits for an owned agent, or this customer's connection limits for a connected agent." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent was created. Null for connected agents." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created the agent. Null for connected agents." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated. Null for connected agents." } }, "required": [ "name", "description", "tags", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "WalletAgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" }, "meta": { "type": "object", "properties": { "walletAccess": { "type": "object", "properties": { "accessType": { "enum": [ "owned", "connected" ], "type": "string", "description": "Whether the wallet owner owns the agent or has an active customer connection to it." }, "isDefault": { "type": "boolean", "description": "Whether this is the agent's default wallet." }, "attachedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the agent was attached to this wallet." } }, "required": [ "isDefault", "attachedAt" ], "additionalProperties": false, "title": "WalletAgentAccessMeta", "description": "The agent's access to this wallet." } }, "required": [ "walletAccess" ], "additionalProperties": false, "title": "WalletAgentMeta" } }, "required": [ "type", "id", "attributes", "relationships", "meta" ], "additionalProperties": false, "title": "WalletAgentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletAgentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d", "attributes": { "name": "Procurement Agent", "description": "Buys supplies", "tags": { "department": "procurement" }, "handle": "@acme-procurementagent", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00.000Z", "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "lastActiveAt": "2026-01-05T09:12:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } }, "meta": { "walletAccess": { "accessType": "owned", "isDefault": true, "attachedAt": "2026-01-05T10:00:00.000Z" } } } } } } } }, "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": [] } ] }, "get": { "operationId": "wallets.listAgents", "summary": "List wallet agents", "description": "List owned and customer-connected agents granted access to a wallet. Connected agents include customer connection limits and omit private metadata from the agent owner.", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description. Null for connected agents." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Agent tags. Empty for connected agents." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status: ACTIVE, or REVOKED after deletion." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Agent limits for an owned agent, or this customer's connection limits for a connected agent." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent was created. Null for connected agents." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created the agent. Null for connected agents." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated. Null for connected agents." } }, "required": [ "name", "description", "tags", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "WalletAgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" }, "meta": { "type": "object", "properties": { "walletAccess": { "type": "object", "properties": { "accessType": { "enum": [ "owned", "connected" ], "type": "string", "description": "Whether the wallet owner owns the agent or has an active customer connection to it." }, "isDefault": { "type": "boolean", "description": "Whether this is the agent's default wallet." }, "attachedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the agent was attached to this wallet." } }, "required": [ "isDefault", "attachedAt" ], "additionalProperties": false, "title": "WalletAgentAccessMeta", "description": "The agent's access to this wallet." } }, "required": [ "walletAccess" ], "additionalProperties": false, "title": "WalletAgentMeta" } }, "required": [ "type", "id", "attributes", "relationships", "meta" ], "additionalProperties": false, "title": "WalletAgentResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WalletAgentListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d", "attributes": { "name": "Procurement Agent", "description": "Buys supplies", "tags": { "department": "procurement" }, "handle": "@acme-procurementagent", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00.000Z", "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "lastActiveAt": "2026-01-05T09:12:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } }, "meta": { "walletAccess": { "accessType": "owned", "isDefault": true, "attachedAt": "2026-01-05T10:00:00.000Z" } } }, { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343932d", "attributes": { "name": "Penny", "description": null, "tags": {}, "handle": "@meridian-penny", "status": "ACTIVE", "limits": { "perTransaction": 5000 }, "createdAt": null, "createdBy": null, "lastActiveAt": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9ead3" } } }, "meta": { "walletAccess": { "accessType": "connected", "isDefault": true, "attachedAt": "2026-01-05T10:00:00.000Z" } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/wallets/{walletId}/agents/{agentId}/default": { "post": { "operationId": "wallets.setAgentDefaultWallet", "summary": "Set agent default wallet", "description": "Make this wallet the default for the attached agent. For a connected agent, the default applies only to this customer connection and also requires delegations.update. Omitted walletId calls use this default. Agent credentials and delegated callers cannot change it.", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description. Null for connected agents." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Agent tags. Empty for connected agents." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status: ACTIVE, or REVOKED after deletion." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Agent limits for an owned agent, or this customer's connection limits for a connected agent." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent was created. Null for connected agents." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created the agent. Null for connected agents." }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the agent last authenticated. Null for connected agents." } }, "required": [ "name", "description", "tags", "handle", "status", "limits", "createdAt", "createdBy", "lastActiveAt" ], "additionalProperties": false, "title": "WalletAgentAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent." } }, "required": [ "party" ], "additionalProperties": false, "title": "AgentRelationships" }, "meta": { "type": "object", "properties": { "walletAccess": { "type": "object", "properties": { "accessType": { "enum": [ "owned", "connected" ], "type": "string", "description": "Whether the wallet owner owns the agent or has an active customer connection to it." }, "isDefault": { "type": "boolean", "description": "Whether this is the agent's default wallet." }, "attachedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the agent was attached to this wallet." } }, "required": [ "isDefault", "attachedAt" ], "additionalProperties": false, "title": "WalletAgentAccessMeta", "description": "The agent's access to this wallet." } }, "required": [ "walletAccess" ], "additionalProperties": false, "title": "WalletAgentMeta" } }, "required": [ "type", "id", "attributes", "relationships", "meta" ], "additionalProperties": false, "title": "WalletAgentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletAgentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d", "attributes": { "name": "Procurement Agent", "description": "Buys supplies", "tags": { "department": "procurement" }, "handle": "@acme-procurementagent", "status": "ACTIVE", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00.000Z", "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "lastActiveAt": "2026-01-05T09:12:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } }, "meta": { "walletAccess": { "accessType": "owned", "isDefault": true, "attachedAt": "2026-01-05T10:00:00.000Z" } } } } } } } }, "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": [] } ] } }, "/wallets/{walletId}/agents/{agentId}": { "delete": { "operationId": "wallets.detachAgent", "summary": "Detach agent from wallet", "description": "Remove an owned or customer-connected agent from a wallet. The default wallet cannot be removed; select another default first. Connected-agent changes also require delegations.update and leave the customer connection active. Agent credentials and delegated callers cannot remove access.", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID (wal_*)." } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "WalletAgentDetachedResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WalletAgentDetachResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" }, "meta": { "deleted": true } } } } } }, "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": [] } ] } }, "/external-accounts": { "get": { "operationId": "externalAccounts.list", "summary": "List external accounts", "description": "List linked external accounts", "tags": [ "External Accounts" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to read for (pty_*). Requires a connected agent with wallets.read permission. Omit to read your own party's banking information." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `externalAccount`.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." }, "attributes": { "type": "object", "properties": { "lastFour": { "type": "string", "description": "Last four digits of the external bank account." }, "status": { "enum": [ "pending", "new", "active", "disabled", "deleted", "unknown" ], "type": "string", "description": "Lifecycle status of the external account." }, "connectionStatus": { "enum": [ "active", "login_required", "disconnected" ], "type": "string", "description": "Bank connection health. Relink the account when it is `login_required` or `disconnected`." }, "availableMethods": { "type": "array", "items": { "enum": [ "standard", "instant" ], "type": "string" }, "description": "Withdrawal delivery methods this account supports." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the account was linked." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank institution name, when available." }, "accountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account display name, when available." }, "accountType": { "anyOf": [ { "enum": [ "checking", "savings", "unknown" ], "type": "string" }, { "type": "null" } ], "description": "Bank account type, when available." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "lastFour", "status", "connectionStatus", "availableMethods", "createdAt", "bankName", "accountName", "accountType", "tags" ], "additionalProperties": false, "title": "ExternalAccountAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the external account." } }, "required": [ "party" ], "additionalProperties": false, "title": "ExternalAccountRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalAccountResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ExternalAccountListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "externalAccount", "id": "eac_019cd1798d75c7ec27e4218aeac1d282", "attributes": { "bankName": "Chase", "accountName": "Business Checking", "accountType": "checking", "lastFour": "6789", "status": "active", "connectionStatus": "active", "availableMethods": [ "standard" ], "createdAt": "2026-01-04T15:30:00.000Z", "tags": {} }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/external-accounts/{externalAccountId}": { "get": { "operationId": "externalAccounts.get", "summary": "Get external account", "description": "Get a linked external account", "tags": [ "External Accounts" ], "parameters": [ { "name": "externalAccountId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to read for (pty_*). Requires a connected agent with wallets.read permission. Omit to read your own party's banking information." }, "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": { "type": { "description": "Resource type. Always `externalAccount`.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." }, "attributes": { "type": "object", "properties": { "lastFour": { "type": "string", "description": "Last four digits of the external bank account." }, "status": { "enum": [ "pending", "new", "active", "disabled", "deleted", "unknown" ], "type": "string", "description": "Lifecycle status of the external account." }, "connectionStatus": { "enum": [ "active", "login_required", "disconnected" ], "type": "string", "description": "Bank connection health. Relink the account when it is `login_required` or `disconnected`." }, "availableMethods": { "type": "array", "items": { "enum": [ "standard", "instant" ], "type": "string" }, "description": "Withdrawal delivery methods this account supports." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the account was linked." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank institution name, when available." }, "accountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account display name, when available." }, "accountType": { "anyOf": [ { "enum": [ "checking", "savings", "unknown" ], "type": "string" }, { "type": "null" } ], "description": "Bank account type, when available." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "lastFour", "status", "connectionStatus", "availableMethods", "createdAt", "bankName", "accountName", "accountType", "tags" ], "additionalProperties": false, "title": "ExternalAccountAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the external account." } }, "required": [ "party" ], "additionalProperties": false, "title": "ExternalAccountRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalAccountResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000", "attributes": { "bankName": "Chase", "accountName": "Business Checking", "accountType": "checking", "lastFour": "6789", "status": "active", "connectionStatus": "active", "availableMethods": [ "standard" ], "tags": { "environment": "production" }, "createdAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } } } } } }, "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": [] } ] }, "delete": { "operationId": "externalAccounts.remove", "summary": "Remove external account", "description": "Remove a linked external account", "tags": [ "External Accounts" ], "parameters": [ { "name": "externalAccountId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `externalAccount`.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." }, "attributes": { "type": "object", "properties": { "lastFour": { "type": "string", "description": "Last four digits of the external bank account." }, "status": { "enum": [ "pending", "new", "active", "disabled", "deleted", "unknown" ], "type": "string", "description": "Lifecycle status of the external account." }, "connectionStatus": { "enum": [ "active", "login_required", "disconnected" ], "type": "string", "description": "Bank connection health. Relink the account when it is `login_required` or `disconnected`." }, "availableMethods": { "type": "array", "items": { "enum": [ "standard", "instant" ], "type": "string" }, "description": "Withdrawal delivery methods this account supports." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the account was linked." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank institution name, when available." }, "accountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account display name, when available." }, "accountType": { "anyOf": [ { "enum": [ "checking", "savings", "unknown" ], "type": "string" }, { "type": "null" } ], "description": "Bank account type, when available." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "lastFour", "status", "connectionStatus", "availableMethods", "createdAt", "bankName", "accountName", "accountType", "tags" ], "additionalProperties": false, "title": "ExternalAccountAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the external account." } }, "required": [ "party" ], "additionalProperties": false, "title": "ExternalAccountRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalAccountResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ExternalAccountDeleteResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "externalAccount", "id": "eac_019cd1798d75c7ec27e4218aeac1d282", "attributes": { "bankName": "Chase", "accountName": "Business Checking", "accountType": "checking", "lastFour": "6789", "status": "disabled", "connectionStatus": "active", "availableMethods": [ "standard" ], "createdAt": "2026-01-04T15:30:00.000Z", "tags": { "environment": "production" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } }, "meta": { "deleted": true } } } } } }, "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": [] } ] } }, "/card-external-accounts": { "get": { "operationId": "externalAccounts.listCards", "summary": "List card external accounts", "description": "List linked card external accounts", "tags": [ "External Accounts" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to read for (pty_*). Requires a connected agent with wallets.read permission. Omit to read your own party's banking information." }, "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": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cardExternalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." }, "attributes": { "type": "object", "properties": { "brand": { "enum": [ "visa", "mastercard", "amex", "discover", "other", "unknown" ], "type": "string", "description": "Card network brand." }, "lastFour": { "type": "string", "description": "Last four digits of the card number." }, "status": { "enum": [ "pending", "new", "active", "disabled", "deleted", "unknown", "verification_failed" ], "type": "string", "description": "Lifecycle status of the external account." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the card was linked." } }, "required": [ "brand", "lastFour", "status", "createdAt" ], "additionalProperties": false, "title": "CardExternalAccountAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the external account." } }, "required": [ "party" ], "additionalProperties": false, "title": "ExternalAccountRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "CardExternalAccountResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CardExternalAccountListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "cardExternalAccount", "id": "eac_01a0e642ed4873d685273ce0e7d1ccab", "attributes": { "brand": "visa", "lastFour": "4242", "status": "active", "createdAt": "2026-09-26T20:10:08.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/api-keys": { "get": { "operationId": "apiKeys.list", "summary": "List API keys", "description": "List API keys", "tags": [ "API Keys" ], "parameters": [ { "name": "status", "in": "query", "schema": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Filter by status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `apiKey`.", "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "API key ID (apy_*)." }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_prod_abc123`." }, "name": { "type": "string", "description": "API key name." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted to this key." }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment the key authenticates in: sandbox or prod." }, "status": { "enum": [ "ACTIVE", "REVOKED", "UNKNOWN" ], "type": "string", "description": "API key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was last used, or null when never used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was revoked, or null while active." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "tags" ], "additionalProperties": false, "title": "ApiKeyAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the API key." } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ApiKeyListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "apiKey", "id": "apy_019cd1798d6f4fd542f897a4115d917c", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "revokedBy": null, "tags": { "service": "checkout" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } }, { "type": "apiKey", "id": "apy_019cd1798d70bfee6bb3db9a1d01eb6d", "attributes": { "apiKeyPrefix": "sk_ntl_prod_Ab12Cd34Ef56Gh78", "name": "Reporting (read-only)", "scopes": [ "payments.read" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "revokedBy": null, "tags": { "service": "reporting" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] }, "post": { "operationId": "apiKeys.create", "summary": "Create API key", "description": "Create an API key. The secret is returned only once.", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32, "description": "API key name." }, "scopes": { "type": "array", "minItems": 1, "items": { "enum": [ "party.read", "party.update", "invite.read", "invite.create", "invite.update", "invite.delete", "membership.create", "membership.read", "membership.update", "membership.delete", "payments.create", "payments.read", "external_parties.create", "external_parties.read", "direct.create", "direct.read", "external_accounts.create", "wallets.read", "wallets.balance", "wallets.create", "wallets.update", "wallets.delete", "wallets.fund", "wallets.deposit", "wallets.transfer", "wallets.withdraw", "delegations.read", "delegations.create", "delegations.update", "delegations.delete", "api_keys.read", "api_keys.create", "api_keys.delete", "agents.read", "agents.create", "agents.update", "agents.delete", "disputes.read", "disputes.create", "payment_intents.read", "payment_intents.create", "card_payments.read", "refunds.read", "refunds.create", "voice_sessions.read", "voice_sessions.create", "chargebacks.read", "chargebacks.respond", "mandates.read", "enrollment.read" ], "type": "string" }, "default": [ "party.read", "party.update", "invite.read", "invite.create", "invite.update", "invite.delete", "membership.create", "membership.read", "membership.update", "membership.delete", "payments.create", "payments.read", "external_parties.create", "external_parties.read", "direct.create", "direct.read", "external_accounts.create", "wallets.read", "wallets.balance", "wallets.create", "wallets.update", "wallets.delete", "wallets.fund", "wallets.deposit", "wallets.transfer", "wallets.withdraw", "delegations.read", "delegations.create", "delegations.update", "delegations.delete", "api_keys.read", "api_keys.create", "api_keys.delete", "agents.read", "agents.create", "agents.update", "agents.delete", "disputes.read", "disputes.create", "payment_intents.read", "payment_intents.create", "card_payments.read", "refunds.read", "refunds.create", "voice_sessions.read", "voice_sessions.create", "chargebacks.read", "chargebacks.respond", "mandates.read", "enrollment.read" ], "description": "Permission scopes for the API key." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Tags applied to this API key.", "maxProperties": 30 } }, "required": [ "name" ], "additionalProperties": false, "title": "ApiKeyCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "ApiKeyCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateApiKeyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "tags": { "service": "checkout" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `apiKey`.", "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "API key ID (apy_*)." }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_prod_abc123`." }, "name": { "type": "string", "description": "API key name." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted to this key." }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment the key authenticates in: sandbox or prod." }, "status": { "enum": [ "ACTIVE", "REVOKED", "UNKNOWN" ], "type": "string", "description": "API key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was last used, or null when never used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was revoked, or null while active." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "apiKey": { "type": "string", "description": "Full API key secret. Returned only once." } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "tags", "apiKey" ], "additionalProperties": false, "title": "ApiKeyCreateResultAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the API key." } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ApiKeyCreateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "apiKey", "id": "apy_019cd1798d6f4fd542f897a4115d917c", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "revokedBy": null, "tags": { "service": "checkout" }, "apiKey": "sk_ntl_prod_sxHp_FRoRTnDEmEHD8FKVJg7P0d3UJMSWCtzQe9GBxk" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ], "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." } ] } }, "/api-keys/{keyId}": { "get": { "operationId": "apiKeys.get", "summary": "Get API key", "description": "Get an API key", "tags": [ "API Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "API key ID (apy_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `apiKey`.", "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "API key ID (apy_*)." }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_prod_abc123`." }, "name": { "type": "string", "description": "API key name." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted to this key." }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment the key authenticates in: sandbox or prod." }, "status": { "enum": [ "ACTIVE", "REVOKED", "UNKNOWN" ], "type": "string", "description": "API key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was last used, or null when never used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was revoked, or null while active." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "tags" ], "additionalProperties": false, "title": "ApiKeyAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the API key." } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ApiKeySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "apiKey", "id": "apy_019cd1798d6f4fd542f897a4115d917c", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "revokedBy": null, "tags": { "service": "checkout" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] }, "delete": { "operationId": "apiKeys.revoke", "summary": "Revoke API key", "description": "Revoke an API key", "tags": [ "API Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "API key ID (apy_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `apiKey`.", "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "API key ID (apy_*)." }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_prod_abc123`." }, "name": { "type": "string", "description": "API key name." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted to this key." }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment the key authenticates in: sandbox or prod." }, "status": { "enum": [ "ACTIVE", "REVOKED", "UNKNOWN" ], "type": "string", "description": "API key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was last used, or null when never used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was revoked, or null while active." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "tags" ], "additionalProperties": false, "title": "ApiKeyAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the API key." } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ApiKeyRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "apiKey", "id": "apy_019cd1798d6f4fd542f897a4115d917c", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "REVOKED", "createdAt": "2026-01-04T15:30:00.000Z", "lastUsedAt": null, "revokedAt": "2026-01-05T10:00:00.000Z", "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "revokedBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "tags": { "service": "checkout" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } }, "meta": { "deleted": true } } } } } }, "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": [] } ] } }, "/agent-keys": { "get": { "operationId": "agentKeys.list", "summary": "List agent keys", "description": "List agent keys", "tags": [ "Agent Keys" ], "parameters": [ { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Filter to keys bound to this agent (agt_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agentKey`.", "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Agent key ID (agk_*)." }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_prod_abc123`." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was last used, or null when never used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was revoked, or null while active." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key stops authenticating, or null when it has no scheduled expiration." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "expiresAt", "tags" ], "additionalProperties": false, "title": "AgentKeyAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent key." }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to." } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentKeyListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agentKey", "id": "agk_019cd1798d6d1353281cf4cdf5d20c8d", "attributes": { "agentKeyPrefix": "ak_ntl_prod_sxHp_FRoRTnDEmEH", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "revokedBy": null, "expiresAt": null, "tags": { "team": "payments" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } }, { "type": "agentKey", "id": "agk_019cd1798d6e1355c6e8fc5b02f7a659", "attributes": { "agentKeyPrefix": "ak_ntl_prod_Ab12Cd34Ef56Gh78", "status": "ACTIVE", "createdAt": "2026-01-05T09:00:00.000Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "revokedBy": null, "expiresAt": null, "tags": { "team": "reconciliation" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] }, "post": { "operationId": "agentKeys.create", "summary": "Create agent key", "description": "Create an agent key for an agent. The secret is returned only once.", "tags": [ "Agent Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Tags applied to this agent key.", "maxProperties": 30 } }, "additionalProperties": false, "title": "AgentKeyCreateAttributes" }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Existing agent the key is bound to." } }, "required": [ "agent" ], "additionalProperties": false, "title": "AgentKeyCreateRelationships" } }, "required": [ "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateAgentKeyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "tags": { "team": "payments" } }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agentKey`.", "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Agent key ID (agk_*)." }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_prod_abc123`." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was last used, or null when never used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was revoked, or null while active." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key stops authenticating, or null when it has no scheduled expiration." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "agentKey": { "type": "string", "description": "Full agent key secret. Returned only once." } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "expiresAt", "tags", "agentKey" ], "additionalProperties": false, "title": "AgentKeyCreateResultAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent key." }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to." } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentKeyCreateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentKey", "id": "agk_019cd1798d6d1353281cf4cdf5d20c8d", "attributes": { "agentKeyPrefix": "ak_ntl_prod_sxHp_FRoRTnDEmEH", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00.000Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "revokedBy": null, "expiresAt": null, "tags": { "team": "payments" }, "agentKey": "ak_ntl_prod_sxHp_FRoRTnDEmEHD8FKVJg7P0d3UJMSWCtzQe9GBxk" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } } } } } }, "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": [] } ], "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." } ] } }, "/agent-keys/{keyId}": { "delete": { "operationId": "agentKeys.revoke", "summary": "Revoke agent key", "description": "Revoke an agent key", "tags": [ "Agent Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agk_[0-9a-f]{32}$", "description": "Agent key ID (agk_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agentKey`.", "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Agent key ID (agk_*)." }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_prod_abc123`." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was last used, or null when never used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was revoked, or null while active." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key stops authenticating, or null when it has no scheduled expiration." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "expiresAt", "tags" ], "additionalProperties": false, "title": "AgentKeyAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent key." }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to." } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentKeyRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentKey", "id": "agk_019cd1798d6d1353281cf4cdf5d20c8d", "attributes": { "agentKeyPrefix": "ak_ntl_prod_sxHp_FRoRTnDEmEH", "status": "REVOKED", "createdAt": "2026-01-04T15:30:00.000Z", "lastUsedAt": null, "revokedAt": "2026-01-06T10:00:00.000Z", "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "revokedBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "expiresAt": null, "tags": { "team": "payments" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } }, "meta": { "deleted": true } } } } } }, "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": [] } ] } }, "/agent-keys/{keyId}/rotate": { "post": { "operationId": "agentKeys.rotate", "summary": "Rotate agent key", "description": "Rotate an agent key. The new secret is returned only once.", "tags": [ "Agent Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agk_[0-9a-f]{32}$", "description": "Agent key ID (agk_*)." } }, { "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": { "expiresInSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "Grace period in seconds for the previous key (0 = immediate cutover, max 86400)." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Tags applied to the replacement agent key.", "maxProperties": 30 } }, "required": [ "expiresInSeconds" ], "additionalProperties": false, "title": "AgentKeyRotateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "AgentKeyRotateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "RotateAgentKeyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "expiresInSeconds": 86400, "tags": { "team": "payments" } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agentKey`.", "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Agent key ID (agk_*)." }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_prod_abc123`." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent key status." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this key was created." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was last used, or null when never used." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key was revoked, or null while active." }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)." }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this key stops authenticating, or null when it has no scheduled expiration." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "agentKey": { "type": "string", "description": "Full agent key secret. Returned only once." }, "previousKeyExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the previous key stops authenticating, or null for immediate cutover." } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "expiresAt", "tags", "agentKey", "previousKeyExpiresAt" ], "additionalProperties": false, "title": "AgentKeyRotateResultAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent key." }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to." } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyRotateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentKeyRotateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentKey", "id": "agk_019cd1798d6e1355c6e8fc5b02f7a659", "attributes": { "agentKeyPrefix": "ak_ntl_prod_Ab12Cd34Ef56Gh78", "status": "ACTIVE", "createdAt": "2026-01-06T10:00:00.000Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0", "revokedBy": null, "expiresAt": null, "tags": { "team": "payments" }, "agentKey": "ak_ntl_prod_Ab12Cd34Ef56Gh78mN90Pq12Rs34Tu56Vw78Xy90Za12Bc34", "previousKeyExpiresAt": "2026-01-07T10:00:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } } } } } }, "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": [] } ] } }, "/card-sessions": { "post": { "operationId": "cardSessions.create", "summary": "Create card session", "description": "Open a session to pay for one purchase with one card. Poll it until the user approves, then claim it once for a stand-in card and proxy login.", "tags": [ "Card Sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "cardId": { "anyOf": [ { "type": "string", "pattern": "^crd_[A-Za-z0-9]{1,64}$" }, { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } ], "description": "Card to use: a Natural-issued card (crd_...) or a card the user added on the dashboard (eac_...)." }, "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowedHosts": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "maxLength": 253 }, "description": "Exact hostnames allowed to receive the real card, such as the payment processor's API host the merchant's checkout sends the card to. Required: there is no default." }, "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 900, "description": "How long the stand-in card and proxy login stay valid once claimed. Defaults to 600." }, "purchase": { "type": "object", "properties": { "merchantName": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Merchant name as the user will recognize it." }, "amount": { "type": "integer", "minimum": 1, "description": "Total in minor units (cents) of `currency`." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code, e.g. USD." } }, "required": [ "merchantName", "amount", "currency" ], "additionalProperties": false, "description": "What the agent is buying. Required for a card the user added (eac_): the user approves this exact purchase." } }, "required": [ "cardId", "allowedHosts" ], "additionalProperties": false, "title": "CreateCardSessionAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateCardSessionRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "cardId": "eac_01a0e642ed4873d685273ce0e7d1ccab", "purchase": { "merchantName": "Blue Bottle Coffee", "amount": 2450, "currency": "USD" }, "allowedHosts": [ "api.stripe.com" ], "ttlSeconds": 600 } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "cardId": { "type": "string" }, "cardSource": { "enum": [ "natural_issued", "external" ], "type": "string", "description": "natural_issued: a Natural-issued card. external: a card the user added on the dashboard." }, "status": { "enum": [ "pending_approval", "approved", "declined", "claimed", "expired" ], "type": "string", "description": "pending_approval: waiting for the user; keep polling. approved: claim it now. declined: the user said no. claimed: already collected. expired: open a new session." }, "allowedHosts": { "type": "array", "items": { "type": "string" } }, "claimExpiresAt": { "type": "string", "maxLength": 64, "description": "A pending session must be approved, and an approved one claimed, before this." }, "claimedAt": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "credentialExpiresAt": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "When the claimed proxy login stops working." }, "createdAt": { "type": "string", "maxLength": 64 }, "approvalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cards the user added only: send the user here to approve the purchase. Returned only in this response; it can't be fetched again." } }, "required": [ "sessionId", "cardId", "cardSource", "status", "allowedHosts", "claimExpiresAt", "claimedAt", "credentialExpiresAt", "createdAt", "approvalUrl" ], "title": "CreatedCardSession" }, "examples": { "default": { "summary": "Default", "value": { "sessionId": "csn_01a0e6466ba3713bba0f0d9d36803b92", "cardId": "eac_01a0e642ed4873d685273ce0e7d1ccab", "cardSource": "external", "status": "pending_approval", "allowedHosts": [ "api.stripe.com" ], "claimExpiresAt": "2026-09-29T18:10:00.000Z", "claimedAt": null, "credentialExpiresAt": null, "createdAt": "2026-09-29T18:00:00.000Z", "approvalUrl": "https://natural.com/dashboard/card-approvals/QO9J1KqnWOZT5dY6W7sT5w" } } } } }, "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": [] } ], "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." } ] } }, "/card-sessions/{sessionId}": { "get": { "operationId": "cardSessions.get", "summary": "Get card session", "description": "Get a card session's status. It never includes card data.", "tags": [ "Card Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^csn_[0-9a-f]{32}$" } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "sessionId": { "type": "string" }, "cardId": { "type": "string" }, "cardSource": { "enum": [ "natural_issued", "external" ], "type": "string", "description": "natural_issued: a Natural-issued card. external: a card the user added on the dashboard." }, "status": { "enum": [ "pending_approval", "approved", "declined", "claimed", "expired" ], "type": "string", "description": "pending_approval: waiting for the user; keep polling. approved: claim it now. declined: the user said no. claimed: already collected. expired: open a new session." }, "allowedHosts": { "type": "array", "items": { "type": "string" } }, "claimExpiresAt": { "type": "string", "maxLength": 64, "description": "A pending session must be approved, and an approved one claimed, before this." }, "claimedAt": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "credentialExpiresAt": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "When the claimed proxy login stops working." }, "createdAt": { "type": "string", "maxLength": 64 } }, "required": [ "sessionId", "cardId", "cardSource", "status", "allowedHosts", "claimExpiresAt", "claimedAt", "credentialExpiresAt", "createdAt" ], "title": "CardSession" }, "examples": { "default": { "summary": "Default", "value": { "sessionId": "csn_01a0e6466ba3713bba0f0d9d36803b92", "cardId": "eac_01a0e642ed4873d685273ce0e7d1ccab", "cardSource": "external", "status": "approved", "allowedHosts": [ "api.stripe.com" ], "claimExpiresAt": "2026-09-29T18:10:00.000Z", "claimedAt": null, "credentialExpiresAt": null, "createdAt": "2026-09-29T18:00:00.000Z" } } } } }, "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": [] } ] } }, "/card-sessions/{sessionId}/claim": { "post": { "operationId": "cardSessions.claim", "summary": "Claim card session", "description": "Claim the stand-in card and proxy login for an approved session. It succeeds once, and the credential can't be fetched again.", "tags": [ "Card Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^csn_[0-9a-f]{32}$" } }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "sessionId": { "type": "string" }, "cardId": { "type": "string" }, "card": { "type": "object", "properties": { "number": { "type": "string", "description": "Stand-in card number. Only valid through `proxy`." }, "cvc": { "type": "string", "description": "Stand-in CVC. Only valid through `proxy`." }, "expirationMonth": { "type": "integer" }, "expirationYear": { "type": "integer" }, "holderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cardholder name as printed on the card, for the merchant's checkout name field. Null for Natural-issued cards, which have none on file." } }, "required": [ "number", "cvc", "expirationMonth", "expirationYear", "holderName" ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ZIP/postal code the bank's AVS check validates at checkout." }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "city", "state", "postalCode", "country" ] }, { "type": "null" } ], "description": "The card's billing address on file, for filling the merchant's checkout (the ZIP drives the bank's AVS check). Null for Natural-issued cards, which store none." }, "proxy": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "protocol": { "type": "string", "enum": [ "https" ] }, "username": { "type": "string" }, "password": { "type": "string", "description": "Secret. Grants use of the card on allowedHosts until expiresAt. Never log it." }, "caBundleUrl": { "type": "string", "description": "Root CA the browser runtime must trust for the proxy." } }, "required": [ "host", "port", "protocol", "username", "password", "caBundleUrl" ] }, "allowedHosts": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "maxLength": 64 }, "instructions": { "type": "array", "items": { "type": "string" }, "description": "Instructions for configuring and verifying the checkout proxy before paying." } }, "required": [ "sessionId", "cardId", "card", "billingAddress", "proxy", "allowedHosts", "expiresAt", "instructions" ], "title": "CardSessionCredential" }, "examples": { "default": { "summary": "Default", "value": { "sessionId": "csn_01a0e6466ba3713bba0f0d9d36803b92", "cardId": "eac_01a0e642ed4873d685273ce0e7d1ccab", "card": { "number": "4242423289715897", "cvc": "128", "expirationMonth": 8, "expirationYear": 2030, "holderName": "Jane Appleseed" }, "billingAddress": { "line1": "235 2nd Street", "line2": null, "city": "San Francisco", "state": "CA", "postalCode": "94105", "country": "US" }, "proxy": { "host": "us-va.browser.relay.evervault.app", "port": 443, "protocol": "https", "username": "app_1a2b3c4d5e6f", "password": "eyJhbGciOiJ...redacted", "caBundleUrl": "https://ca.evervault.com" }, "allowedHosts": [ "api.stripe.com" ], "expiresAt": "2026-09-29T18:12:00.000Z", "instructions": [ "Use the stand-in card through the proxy. The returned card fields resolve to the saved card only when sent to allowedHosts through the returned proxy before expiresAt.", "Use the returned connection settings. Configure the proxy using protocol, host, port, username, and password. Keep the claim credentials secret; never include them in logs.", "Trust the proxy certificate. Add the CA from caBundleUrl to the trust configuration used by your browser or HTTP client, preserving its existing trusted certificates. Keep TLS verification enabled.", "Route the payment requests. Ensure requests to allowedHosts from the checkout page and its frames pass through the proxy. Configure routing before submitting payment.", "Keep interception active. If you intercept requests, keep the runtime's event loop running so handlers can receive and forward them. Avoid blocking waits that prevent handlers from executing.", "Verify routing before paying. Use a harmless request to an allowed host to confirm that the browser's traffic actually passes through the proxy.", "Stop on routing failures. Do not forward card requests directly when the proxy fails. Check routing, certificate trust, and credential expiry before retrying payment, and first confirm the previous attempt did not complete." ] } } } } }, "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": [] } ] } }, "/agentic-payments/mandates": { "get": { "operationId": "agenticPayments.listMandates", "summary": "List agentic mandates", "description": "List the party's usable mandates for the calling agent, or all of the owner's mandates", "tags": [ "Agent Tokens" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^amd_[0-9a-f]{32}$" }, "paymentMethodId": { "type": "string", "pattern": "^apm_[0-9a-f]{32}$" }, "provider": { "enum": [ "basis_theory", "simulation" ], "type": "string" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ], "description": "The agent reading this mandate. Mandates belong to the card and every agent with access to the card spends under them; null when the card owner reads one." }, "status": { "enum": [ "creating", "reconciliation_required", "requires_action", "active", "revoked", "error", "outcome_unknown", "expired" ], "type": "string" }, "amount": { "type": "number" }, "available": { "type": "number" }, "perPurchaseLimit": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "description": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "merchantScope": { "type": "string", "enum": [ "any" ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "paymentMethodId", "provider", "agentId", "status", "amount", "available", "perPurchaseLimit", "currency", "description", "expiresAt", "merchantScope", "errorCode" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ] }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "amd_01a0e6466ba3713bba0f0d9d36803b92", "paymentMethodId": "apm_01a0e642ed4873d685273ce0e7d1ccab", "provider": "basis_theory", "agentId": "agt_019cd1798d637a4da75dce386343931d", "status": "active", "amount": 50000, "available": 47550, "perPurchaseLimit": 10000, "currency": "USD", "description": "Office supplies", "expiresAt": "2026-10-31T00:00:00.000Z", "merchantScope": "any", "errorCode": null } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/agentic-payments/mandates/{mandateId}": { "get": { "operationId": "agenticPayments.getMandate", "summary": "Get agentic mandate", "description": "Get the current budget and approval status", "tags": [ "Agent Tokens" ], "parameters": [ { "name": "mandateId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^amd_[0-9a-f]{32}$" } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": "^amd_[0-9a-f]{32}$" }, "paymentMethodId": { "type": "string", "pattern": "^apm_[0-9a-f]{32}$" }, "provider": { "enum": [ "basis_theory", "simulation" ], "type": "string" }, "agentId": { "anyOf": [ { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, { "type": "null" } ], "description": "The agent reading this mandate. Mandates belong to the card and every agent with access to the card spends under them; null when the card owner reads one." }, "status": { "enum": [ "creating", "reconciliation_required", "requires_action", "active", "revoked", "error", "outcome_unknown", "expired" ], "type": "string" }, "amount": { "type": "number" }, "available": { "type": "number" }, "perPurchaseLimit": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "description": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "merchantScope": { "type": "string", "enum": [ "any" ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "paymentMethodId", "provider", "agentId", "status", "amount", "available", "perPurchaseLimit", "currency", "description", "expiresAt", "merchantScope", "errorCode" ] } }, "required": [ "data" ] }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "amd_01a0e6466ba3713bba0f0d9d36803b92", "paymentMethodId": "apm_01a0e642ed4873d685273ce0e7d1ccab", "provider": "basis_theory", "agentId": "agt_019cd1798d637a4da75dce386343931d", "status": "active", "amount": 50000, "available": 47550, "perPurchaseLimit": 10000, "currency": "USD", "description": "Office supplies", "expiresAt": "2026-10-31T00:00:00.000Z", "merchantScope": "any", "errorCode": null } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/agentic-payments/purchases": { "post": { "operationId": "agenticPayments.createPurchase", "summary": "Create agentic purchase", "description": "Reserve budget for a purchase", "tags": [ "Agent Tokens" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "mandateId": { "type": "string", "pattern": "^amd_[0-9a-f]{32}$" }, "amount": { "type": "integer", "maximum": 99999999, "exclusiveMinimum": 0 }, "currency": { "type": "string", "enum": [ "USD" ] }, "merchant": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "maxLength": 1024, "format": "uri" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "name", "url", "countryCode" ], "additionalProperties": false }, "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 600 }, "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." } }, "required": [ "mandateId", "amount", "currency", "merchant", "ttlSeconds" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "mandateId": "amd_01a0e6466ba3713bba0f0d9d36803b92", "amount": 2450, "currency": "USD", "merchant": { "name": "Blue Bottle Coffee", "url": "https://bluebottlecoffee.com", "countryCode": "US" }, "ttlSeconds": 600 } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^apu_[0-9a-f]{32}$" }, "mandateId": { "type": "string", "pattern": "^amd_[0-9a-f]{32}$" }, "provider": { "enum": [ "basis_theory", "simulation" ], "type": "string" }, "confirmationStatus": { "enum": [ "not_requested", "pending", "confirmed", "reconciliation_required" ], "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "merchant": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "maxLength": 1024, "format": "uri" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "name", "url", "countryCode" ], "additionalProperties": false }, "delivery": { "enum": [ "browser_session", "agent_token", "card_token" ], "type": "string" }, "status": { "enum": [ "prepared", "issuing", "issued", "outcome_unknown", "failed", "canceled" ], "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "mandateId", "provider", "confirmationStatus", "amount", "currency", "merchant", "delivery", "status", "expiresAt", "errorCode" ] } }, "required": [ "data" ] }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "apu_01a0e6466ba3713bba0f0d9d36803b93", "mandateId": "amd_01a0e6466ba3713bba0f0d9d36803b92", "provider": "basis_theory", "confirmationStatus": "not_requested", "amount": 2450, "currency": "USD", "merchant": { "name": "Blue Bottle Coffee", "url": "https://bluebottlecoffee.com", "countryCode": "US" }, "delivery": "card_token", "status": "prepared", "expiresAt": null, "errorCode": null } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-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." } ] } }, "/agentic-payments/purchases/{purchaseId}": { "get": { "operationId": "agenticPayments.getPurchase", "summary": "Get agentic purchase", "description": "Get credential issuance status without the credential", "tags": [ "Agent Tokens" ], "parameters": [ { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apu_[0-9a-f]{32}$" } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": "^apu_[0-9a-f]{32}$" }, "mandateId": { "type": "string", "pattern": "^amd_[0-9a-f]{32}$" }, "provider": { "enum": [ "basis_theory", "simulation" ], "type": "string" }, "confirmationStatus": { "enum": [ "not_requested", "pending", "confirmed", "reconciliation_required" ], "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "merchant": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "maxLength": 1024, "format": "uri" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "name", "url", "countryCode" ], "additionalProperties": false }, "delivery": { "enum": [ "browser_session", "agent_token", "card_token" ], "type": "string" }, "status": { "enum": [ "prepared", "issuing", "issued", "outcome_unknown", "failed", "canceled" ], "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "mandateId", "provider", "confirmationStatus", "amount", "currency", "merchant", "delivery", "status", "expiresAt", "errorCode" ] } }, "required": [ "data" ] }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "apu_01a0e6466ba3713bba0f0d9d36803b93", "mandateId": "amd_01a0e6466ba3713bba0f0d9d36803b92", "provider": "basis_theory", "confirmationStatus": "not_requested", "amount": 2450, "currency": "USD", "merchant": { "name": "Blue Bottle Coffee", "url": "https://bluebottlecoffee.com", "countryCode": "US" }, "delivery": "card_token", "status": "issued", "expiresAt": "2026-09-29T18:10:00.000Z", "errorCode": null } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/agentic-payments/purchases/{purchaseId}/claim": { "post": { "operationId": "agenticPayments.claimPurchase", "summary": "Claim purchase credential", "description": "Return the purchase credential exactly once", "tags": [ "Agent Tokens" ], "parameters": [ { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apu_[0-9a-f]{32}$" } }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card_token" ] }, "format": { "type": "string", "enum": [ "card" ] }, "value": { "type": "object", "properties": { "cardNumber": { "type": "string" }, "cvc": { "type": "string" }, "expirationMonth": { "type": "number" }, "expirationYear": { "type": "number" } }, "required": [ "cardNumber", "cvc", "expirationMonth", "expirationYear" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "format", "value", "expiresAt" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "browser_session" ] }, "sessionId": { "type": "string" }, "standInCardNumber": { "type": "string" }, "standInCvc": { "type": "string" }, "proxy": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "number" }, "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "host", "port", "username", "password" ] }, "expirationMonth": { "type": "number" }, "expirationYear": { "type": "number" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "sessionId", "standInCardNumber", "standInCvc", "proxy", "expirationMonth", "expirationYear", "expiresAt" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent_token" ] }, "format": { "type": "string", "enum": [ "network_token" ] }, "value": { "type": "object", "properties": { "token": { "type": "string" }, "expirationMonth": { "type": "number" }, "expirationYear": { "type": "number" }, "eci": { "type": "string" }, "cryptogram": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM" ] }, "value": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "value", "expiresAt" ] } }, "required": [ "token", "expirationMonth", "expirationYear", "eci", "cryptogram" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "format", "value", "expiresAt" ] } ] } }, "required": [ "data" ] }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "card_token", "format": "card", "value": { "cardNumber": "4111119876543210", "cvc": "512", "expirationMonth": 8, "expirationYear": 2030 }, "expiresAt": "2026-09-29T18:10:00.000Z" } } } } } }, "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": [] } ] } }, "/agentic-payments/purchases/{purchaseId}/cancel": { "post": { "operationId": "agenticPayments.cancelPurchase", "summary": "Cancel agentic purchase", "description": "Release budget reserved for a purchase that has not been claimed", "tags": [ "Agent Tokens" ], "parameters": [ { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apu_[0-9a-f]{32}$" } }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": "^apu_[0-9a-f]{32}$" }, "mandateId": { "type": "string", "pattern": "^amd_[0-9a-f]{32}$" }, "provider": { "enum": [ "basis_theory", "simulation" ], "type": "string" }, "confirmationStatus": { "enum": [ "not_requested", "pending", "confirmed", "reconciliation_required" ], "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "merchant": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "maxLength": 1024, "format": "uri" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "name", "url", "countryCode" ], "additionalProperties": false }, "delivery": { "enum": [ "browser_session", "agent_token", "card_token" ], "type": "string" }, "status": { "enum": [ "prepared", "issuing", "issued", "outcome_unknown", "failed", "canceled" ], "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "mandateId", "provider", "confirmationStatus", "amount", "currency", "merchant", "delivery", "status", "expiresAt", "errorCode" ] } }, "required": [ "data" ] }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "apu_01a0e6466ba3713bba0f0d9d36803b93", "mandateId": "amd_01a0e6466ba3713bba0f0d9d36803b92", "provider": "basis_theory", "confirmationStatus": "not_requested", "amount": 2450, "currency": "USD", "merchant": { "name": "Blue Bottle Coffee", "url": "https://bluebottlecoffee.com", "countryCode": "US" }, "delivery": "card_token", "status": "canceled", "expiresAt": null, "errorCode": null } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/agent-cards": { "post": { "operationId": "agentCards.create", "summary": "Create agent card", "description": "Issue a card for one purchase at one merchant, up to a maximum. It approves one authorization, then closes.", "tags": [ "Agent Cards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet the card spends from (wal_*). Omit to use your default wallet, or your only wallet." }, "type": { "enum": [ "single_use" ], "type": "string", "description": "The kind of agent card. Defaults to single_use." }, "merchant": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Merchant name as it appears at checkout. Recorded on the card." }, "networkMerchantId": { "type": "string", "pattern": "^[\\x20-\\x7E]{1,15}$", "description": "The card network's merchant ID. When set, the card works only at this merchant. When omitted, the card isn't limited to one merchant." } }, "required": [ "name" ], "additionalProperties": false, "title": "AgentCardMerchant" }, "maximumAmount": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "The most the one purchase can be, in cents, up to 1000000 ($10000). Larger authorizations decline." }, "currency": { "description": "Currency code. Only USD is supported.", "type": "string", "enum": [ "USD" ] }, "expiresInMinutes": { "type": "integer", "minimum": 5, "maximum": 1440, "description": "How long the card stays usable. Defaults to 60 minutes; at most 24 hours." }, "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." } }, "required": [ "merchant", "maximumAmount", "currency" ], "additionalProperties": false, "title": "CreateAgentCardAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateAgentCardRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "type": "single_use", "merchant": { "name": "Blue Bottle Coffee" }, "maximumAmount": 5000, "currency": "USD", "expiresInMinutes": 60 } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agentCard`.", "type": "string", "enum": [ "agentCard" ] }, "id": { "type": "string", "pattern": "^pcd_[0-9a-f]{32}$", "description": "Agent card ID (pcd_*)." }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "single_use" ], "type": "string", "description": "The kind of agent card. single_use: approves one purchase at one merchant, up to a maximum, then closes." }, "status": { "enum": [ "issuing", "active", "used", "expired", "failed" ], "type": "string", "description": "issuing: Natural is creating the card. active: ready for its one purchase. used: its purchase was approved, so it approves nothing else. expired: its time ran out. failed: it couldn't be issued; request a new card." }, "merchant": { "type": "object", "properties": { "name": { "type": "string" }, "networkMerchantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "networkMerchantId" ], "additionalProperties": false }, "maximumAmount": { "type": "integer", "description": "The most the one purchase can be, in cents." }, "currency": { "type": "string", "enum": [ "USD" ] }, "lastFour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last four digits, once the card is issued." }, "expirationMonth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "expirationYear": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "description": "RFC 3339 timestamp when the card stops working." }, "closedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the card was used or expired, or null while open." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the card was requested." } }, "required": [ "type", "status", "merchant", "maximumAmount", "currency", "lastFour", "expirationMonth", "expirationYear", "expiresAt", "closedAt", "createdAt" ], "additionalProperties": false, "title": "AgentCardAttributes" }, "relationships": { "type": "object", "properties": { "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 spends from." } }, "required": [ "wallet" ], "additionalProperties": false, "title": "AgentCardRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentCardResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentCardResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentCard", "id": "pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21", "attributes": { "type": "single_use", "status": "active", "merchant": { "name": "Blue Bottle Coffee", "networkMerchantId": null }, "maximumAmount": 5000, "currency": "USD", "lastFour": "4821", "expirationMonth": 9, "expirationYear": 2029, "expiresAt": "2026-09-29T19:00:00.000Z", "closedAt": null, "createdAt": "2026-09-29T18:00:00.000Z" }, "relationships": { "wallet": { "data": { "type": "wallet", "id": "wal_01a0e6466ba3713bba0f0d9d36803b92" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-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." } ] } }, "/agent-cards/{cardId}": { "get": { "operationId": "agentCards.get", "summary": "Get agent card", "description": "Get an agent card's status. It never includes the card number.", "tags": [ "Agent Cards" ], "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pcd_[0-9a-f]{32}$", "description": "Agent card ID (pcd_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "type": { "description": "Resource type. Always `agentCard`.", "type": "string", "enum": [ "agentCard" ] }, "id": { "type": "string", "pattern": "^pcd_[0-9a-f]{32}$", "description": "Agent card ID (pcd_*)." }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "single_use" ], "type": "string", "description": "The kind of agent card. single_use: approves one purchase at one merchant, up to a maximum, then closes." }, "status": { "enum": [ "issuing", "active", "used", "expired", "failed" ], "type": "string", "description": "issuing: Natural is creating the card. active: ready for its one purchase. used: its purchase was approved, so it approves nothing else. expired: its time ran out. failed: it couldn't be issued; request a new card." }, "merchant": { "type": "object", "properties": { "name": { "type": "string" }, "networkMerchantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "networkMerchantId" ], "additionalProperties": false }, "maximumAmount": { "type": "integer", "description": "The most the one purchase can be, in cents." }, "currency": { "type": "string", "enum": [ "USD" ] }, "lastFour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last four digits, once the card is issued." }, "expirationMonth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "expirationYear": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "description": "RFC 3339 timestamp when the card stops working." }, "closedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the card was used or expired, or null while open." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the card was requested." } }, "required": [ "type", "status", "merchant", "maximumAmount", "currency", "lastFour", "expirationMonth", "expirationYear", "expiresAt", "closedAt", "createdAt" ], "additionalProperties": false, "title": "AgentCardAttributes" }, "relationships": { "type": "object", "properties": { "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 spends from." } }, "required": [ "wallet" ], "additionalProperties": false, "title": "AgentCardRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentCardResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentCardResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentCard", "id": "pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21", "attributes": { "type": "single_use", "status": "used", "merchant": { "name": "Blue Bottle Coffee", "networkMerchantId": null }, "maximumAmount": 5000, "currency": "USD", "lastFour": "4821", "expirationMonth": 9, "expirationYear": 2029, "expiresAt": "2026-09-29T19:00:00.000Z", "closedAt": "2026-09-29T18:05:00.000Z", "createdAt": "2026-09-29T18:00:00.000Z" }, "relationships": { "wallet": { "data": { "type": "wallet", "id": "wal_01a0e6466ba3713bba0f0d9d36803b92" } } } } } } } } }, "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": [] } ] } }, "/card-transactions": { "get": { "operationId": "cardTransactions.list", "summary": "List card transactions", "description": "List purchases and refunds on Natural-issued cards, newest first. An agent sees only its own card transactions.", "tags": [ "Card Transactions" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "walletId", "in": "query", "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Only card transactions on this wallet (wal_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cardId", "in": "query", "schema": { "type": "string", "pattern": "^pcd_[0-9a-f]{32}$", "description": "Only card transactions on this card (pcd_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Only card transactions this agent made (agt_*)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "pending", "authorized", "partially_captured", "captured", "reversed", "declined", "refunded" ], "type": "string", "description": "Only card transactions in this status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "maxLength": 64, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$", "description": "Only card transactions that happened after this RFC 3339 timestamp." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "maxLength": 64, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$", "description": "Only card transactions that happened before this RFC 3339 timestamp." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to read your own party's card transactions. To read a connected customer's, pass its ID; you need the customer's cards.read grant." }, "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": "array", "items": { "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" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CardTransactionListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "cardTransaction", "id": "cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f22", "attributes": { "kind": "refund", "status": "pending", "merchant": { "name": "BLUE BOTTLE COFFEE", "categoryCode": "5814", "city": "Oakland", "country": "US" }, "amounts": { "attempted": 1200, "authorized": 1200, "captured": 0, "released": 0, "refunded": 0, "outstandingHold": 0 }, "currency": "USD", "decline": null, "actor": { "type": "agent", "agentId": "agt_01a0e6466ba3713bba0f0d9d36803b93", "agentDelegationId": null }, "timeline": [ { "kind": "authorized", "occurredAt": "2026-10-06T15:30:00.000Z", "amount": 1200, "decline": null } ], "occurredAt": "2026-10-06T15:30:00.000Z", "updatedAt": "2026-10-06T15:30:02.000Z" }, "relationships": { "card": { "data": { "type": "card", "id": "pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21" } }, "wallet": { "data": { "type": "wallet", "id": "wal_01a0e6466ba3713bba0f0d9d36803b92" } }, "transaction": { "data": { "type": "transaction", "id": "txn_01a0e6a1d4c27b1a9f3e5d7c8b6a4f22" } }, "purchase": { "data": { "type": "cardTransaction", "id": "cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21" } }, "refunds": { "data": [] } } }, { "type": "cardTransaction", "id": "cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21", "attributes": { "kind": "purchase", "status": "captured", "merchant": { "name": "BLUE BOTTLE COFFEE", "categoryCode": "5814", "city": "Oakland", "country": "US" }, "amounts": { "attempted": 4250, "authorized": 4250, "captured": 4250, "released": 0, "refunded": 0, "outstandingHold": 0 }, "currency": "USD", "decline": null, "actor": { "type": "agent", "agentId": "agt_01a0e6466ba3713bba0f0d9d36803b93", "agentDelegationId": null }, "timeline": [ { "kind": "authorized", "occurredAt": "2026-10-05T18:01:00.000Z", "amount": 4250, "decline": null }, { "kind": "captured", "occurredAt": "2026-10-06T09:12:00.000Z", "amount": 4250, "decline": null } ], "occurredAt": "2026-10-05T18:01:00.000Z", "updatedAt": "2026-10-06T09:12:03.000Z" }, "relationships": { "card": { "data": { "type": "card", "id": "pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21" } }, "wallet": { "data": { "type": "wallet", "id": "wal_01a0e6466ba3713bba0f0d9d36803b92" } }, "transaction": { "data": { "type": "transaction", "id": "txn_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21" } }, "purchase": { "data": null }, "refunds": { "data": [ { "type": "cardTransaction", "id": "cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f22" } ] } } }, { "type": "cardTransaction", "id": "cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f23", "attributes": { "kind": "purchase", "status": "declined", "merchant": { "name": "BLUE BOTTLE COFFEE", "categoryCode": "5814", "city": "Oakland", "country": "US" }, "amounts": { "attempted": 9900, "authorized": 0, "captured": 0, "released": 0, "refunded": 0, "outstandingHold": 0 }, "currency": "USD", "decline": { "code": "single_use_amount_over_maximum", "message": "The purchase was over the agent card's maximum." }, "actor": { "type": "agent", "agentId": "agt_01a0e6466ba3713bba0f0d9d36803b93", "agentDelegationId": null }, "timeline": [ { "kind": "declined", "occurredAt": "2026-10-05T17:58:00.000Z", "amount": 9900, "decline": { "code": "single_use_amount_over_maximum", "message": "The purchase was over the agent card's maximum." } } ], "occurredAt": "2026-10-05T17:58:00.000Z", "updatedAt": "2026-10-05T17:58:01.000Z" }, "relationships": { "card": { "data": { "type": "card", "id": "pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21" } }, "wallet": { "data": { "type": "wallet", "id": "wal_01a0e6466ba3713bba0f0d9d36803b92" } }, "transaction": { "data": { "type": "transaction", "id": "txn_01a0e6a1d4c27b1a9f3e5d7c8b6a4f23" } }, "purchase": { "data": null }, "refunds": { "data": [] } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/card-transactions/{cardTransactionId}": { "get": { "operationId": "cardTransactions.get", "summary": "Get card transaction", "description": "Get a purchase or refund on a Natural-issued card, with its timeline.", "tags": [ "Card Transactions" ], "parameters": [ { "name": "cardTransactionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cit_[0-9a-f]{32}$", "description": "Card transaction ID (cit_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party to act for (pty_*). Omit to read your own party's card transactions. To read a connected customer's, pass its ID; you need the customer's cards.read grant." }, "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": { "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_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21", "attributes": { "kind": "purchase", "status": "captured", "merchant": { "name": "BLUE BOTTLE COFFEE", "categoryCode": "5814", "city": "Oakland", "country": "US" }, "amounts": { "attempted": 4250, "authorized": 4250, "captured": 4250, "released": 0, "refunded": 0, "outstandingHold": 0 }, "currency": "USD", "decline": null, "actor": { "type": "agent", "agentId": "agt_01a0e6466ba3713bba0f0d9d36803b93", "agentDelegationId": null }, "timeline": [ { "kind": "authorized", "occurredAt": "2026-10-05T18:01:00.000Z", "amount": 4250, "decline": null }, { "kind": "captured", "occurredAt": "2026-10-06T09:12:00.000Z", "amount": 4250, "decline": null } ], "occurredAt": "2026-10-05T18:01:00.000Z", "updatedAt": "2026-10-06T09:12:03.000Z" }, "relationships": { "card": { "data": { "type": "card", "id": "pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21" } }, "wallet": { "data": { "type": "wallet", "id": "wal_01a0e6466ba3713bba0f0d9d36803b92" } }, "transaction": { "data": { "type": "transaction", "id": "txn_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21" } }, "purchase": { "data": null }, "refunds": { "data": [ { "type": "cardTransaction", "id": "cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f22" } ] } } } } } } } }, "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": [] } ] } }, "/webhooks": { "post": { "operationId": "webhooks.create", "summary": "Create webhook", "description": "Create a webhook endpoint. The signing secret is returned only once.", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "maxLength": 100, "description": "Webhook description." }, "enabledEvents": { "type": "array", "minItems": 1, "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "invitation_link.created", "invitation_link.revoked", "invitation_link.agent_added", "invitation_link.agent_removed", "invitation_link.redeemed", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "ach.created", "ach.processing", "ach.settled", "ach.failed", "ach.returned", "realtime.created", "realtime.processing", "realtime.settled", "realtime.failed", "wire.created", "wire.processing", "wire.completed", "wire.rejected", "wire.failed", "check.created", "check.processing", "check.completed", "check.returned", "check.canceled", "check.expired", "check.rejected", "check.failed", "check.returned_to_sender", "external_party_account.validated", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming", "paymentIntent.completed", "cardPayment.succeeded", "cardPayment.failed", "paymentIntent.canceled", "cardPayment.created", "voiceSession.completed", "refund.created", "refund.succeeded", "refund.failed", "chargeback.created", "chargeback.updated", "chargeback.closed", "enrollment.applied", "enrollment.activated", "enrollment.rejected", "enrollment.offboarded", "mandate.created", "mandate.updated", "mandate.revoked" ], "type": "string" }, "description": "Event types to subscribe to; use \"*\" to subscribe to all event types." }, "sources": { "type": "array", "minItems": 1, "items": { "enum": [ "own", "connected" ], "type": "string" }, "description": "Event sources to receive: \"own\" for your own party's events, \"connected\" for events of parties connected to you through an active authorization. Defaults to [\"own\"]." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Tags applied to this webhook.", "maxProperties": 30 } }, "required": [ "url", "enabledEvents" ], "additionalProperties": false, "title": "WebhookCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WebhookCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateWebhookInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "sources": [ "own", "connected" ], "tags": { "env": "prod", "team": "payments" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `webhook`.", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "description": "Webhook description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status." }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "invitation_link.created", "invitation_link.revoked", "invitation_link.agent_added", "invitation_link.agent_removed", "invitation_link.redeemed", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "ach.created", "ach.processing", "ach.settled", "ach.failed", "ach.returned", "realtime.created", "realtime.processing", "realtime.settled", "realtime.failed", "wire.created", "wire.processing", "wire.completed", "wire.rejected", "wire.failed", "check.created", "check.processing", "check.completed", "check.returned", "check.canceled", "check.expired", "check.rejected", "check.failed", "check.returned_to_sender", "external_party_account.validated", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming", "paymentIntent.completed", "cardPayment.succeeded", "cardPayment.failed", "paymentIntent.canceled", "cardPayment.created", "voiceSession.completed", "refund.created", "refund.succeeded", "refund.failed", "chargeback.created", "chargeback.updated", "chargeback.closed", "enrollment.applied", "enrollment.activated", "enrollment.rejected", "enrollment.offboarded", "mandate.created", "mandate.updated", "mandate.revoked" ], "type": "string" }, "description": "Event types this webhook listens to." }, "sources": { "type": "array", "items": { "enum": [ "own", "connected" ], "type": "string" }, "description": "Event sources this webhook receives: \"own\" for your own party, \"connected\" for parties connected to you through an active authorization." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this webhook was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this webhook was last updated." }, "signingSecret": { "type": "string", "description": "Webhook signing secret. Returned only once." } }, "required": [ "url", "description", "status", "enabledEvents", "sources", "tags", "createdAt", "updatedAt", "signingSecret" ], "additionalProperties": false, "title": "WebhookCreateResultAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WebhookCreateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_019cd1798d8f8560c82adba1d2912643", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "sources": [ "own", "connected" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00.000Z", "updatedAt": "2026-03-16T12:00:00.000Z", "signingSecret": "whsec_3JZ8aQpL2vR7nXdE5fW1cT0yK6mB4hG9" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ] }, "get": { "operationId": "webhooks.list", "summary": "List webhooks", "description": "List webhook endpoints", "tags": [ "Webhooks" ], "parameters": [ { "name": "status", "in": "query", "schema": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Filter by status." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `webhook`.", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "description": "Webhook description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status." }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "invitation_link.created", "invitation_link.revoked", "invitation_link.agent_added", "invitation_link.agent_removed", "invitation_link.redeemed", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "ach.created", "ach.processing", "ach.settled", "ach.failed", "ach.returned", "realtime.created", "realtime.processing", "realtime.settled", "realtime.failed", "wire.created", "wire.processing", "wire.completed", "wire.rejected", "wire.failed", "check.created", "check.processing", "check.completed", "check.returned", "check.canceled", "check.expired", "check.rejected", "check.failed", "check.returned_to_sender", "external_party_account.validated", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming", "paymentIntent.completed", "cardPayment.succeeded", "cardPayment.failed", "paymentIntent.canceled", "cardPayment.created", "voiceSession.completed", "refund.created", "refund.succeeded", "refund.failed", "chargeback.created", "chargeback.updated", "chargeback.closed", "enrollment.applied", "enrollment.activated", "enrollment.rejected", "enrollment.offboarded", "mandate.created", "mandate.updated", "mandate.revoked" ], "type": "string" }, "description": "Event types this webhook listens to." }, "sources": { "type": "array", "items": { "enum": [ "own", "connected" ], "type": "string" }, "description": "Event sources this webhook receives: \"own\" for your own party, \"connected\" for parties connected to you through an active authorization." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this webhook was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this webhook was last updated." } }, "required": [ "url", "description", "status", "enabledEvents", "sources", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WebhookListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "webhook", "id": "whk_019cd1798d8f8560c82adba1d2912643", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "sources": [ "own", "connected" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00.000Z", "updatedAt": "2026-03-16T12:00:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } }, { "type": "webhook", "id": "whk_019cd1798d900bf6b0b55864f62125f2", "attributes": { "url": "https://example.com/webhooks/funding", "description": "External account notifications", "status": "DISABLED", "enabledEvents": [ "external_account.connected" ], "sources": [ "own" ], "tags": { "env": "prod" }, "createdAt": "2026-03-10T09:00:00.000Z", "updatedAt": "2026-03-14T18:30:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/webhooks/{webhookId}": { "get": { "operationId": "webhooks.get", "summary": "Get webhook", "description": "Get a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[0-9a-f]{32}$", "description": "Webhook ID (whk_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `webhook`.", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "description": "Webhook description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status." }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "invitation_link.created", "invitation_link.revoked", "invitation_link.agent_added", "invitation_link.agent_removed", "invitation_link.redeemed", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "ach.created", "ach.processing", "ach.settled", "ach.failed", "ach.returned", "realtime.created", "realtime.processing", "realtime.settled", "realtime.failed", "wire.created", "wire.processing", "wire.completed", "wire.rejected", "wire.failed", "check.created", "check.processing", "check.completed", "check.returned", "check.canceled", "check.expired", "check.rejected", "check.failed", "check.returned_to_sender", "external_party_account.validated", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming", "paymentIntent.completed", "cardPayment.succeeded", "cardPayment.failed", "paymentIntent.canceled", "cardPayment.created", "voiceSession.completed", "refund.created", "refund.succeeded", "refund.failed", "chargeback.created", "chargeback.updated", "chargeback.closed", "enrollment.applied", "enrollment.activated", "enrollment.rejected", "enrollment.offboarded", "mandate.created", "mandate.updated", "mandate.revoked" ], "type": "string" }, "description": "Event types this webhook listens to." }, "sources": { "type": "array", "items": { "enum": [ "own", "connected" ], "type": "string" }, "description": "Event sources this webhook receives: \"own\" for your own party, \"connected\" for parties connected to you through an active authorization." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this webhook was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this webhook was last updated." } }, "required": [ "url", "description", "status", "enabledEvents", "sources", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WebhookSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_019cd1798d8f8560c82adba1d2912643", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "sources": [ "own", "connected" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00.000Z", "updatedAt": "2026-03-16T12:00:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] }, "patch": { "operationId": "webhooks.update", "summary": "Update webhook", "description": "Update a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[0-9a-f]{32}$", "description": "Webhook ID (whk_*)." } }, { "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": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "New webhook endpoint URL." }, "description": { "type": "string", "maxLength": 100, "description": "New description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "New status." }, "enabledEvents": { "type": "array", "minItems": 1, "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "invitation_link.created", "invitation_link.revoked", "invitation_link.agent_added", "invitation_link.agent_removed", "invitation_link.redeemed", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "ach.created", "ach.processing", "ach.settled", "ach.failed", "ach.returned", "realtime.created", "realtime.processing", "realtime.settled", "realtime.failed", "wire.created", "wire.processing", "wire.completed", "wire.rejected", "wire.failed", "check.created", "check.processing", "check.completed", "check.returned", "check.canceled", "check.expired", "check.rejected", "check.failed", "check.returned_to_sender", "external_party_account.validated", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming", "paymentIntent.completed", "cardPayment.succeeded", "cardPayment.failed", "paymentIntent.canceled", "cardPayment.created", "voiceSession.completed", "refund.created", "refund.succeeded", "refund.failed", "chargeback.created", "chargeback.updated", "chargeback.closed", "enrollment.applied", "enrollment.activated", "enrollment.rejected", "enrollment.offboarded", "mandate.created", "mandate.updated", "mandate.revoked" ], "type": "string" }, "description": "Event types to subscribe to; use \"*\" to subscribe to all event types." }, "sources": { "type": "array", "minItems": 1, "items": { "enum": [ "own", "connected" ], "type": "string" }, "description": "Event sources to receive: \"own\" for your own party's events, \"connected\" for events of parties connected to you through an active authorization." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "description": "Tag updates. Pass null to remove a key." } }, "additionalProperties": false, "title": "WebhookUpdateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WebhookUpdateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "UpdateWebhookInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "description": "Production webhook for wallet, party, and delegation events", "status": "DISABLED", "enabledEvents": [ "wallet.created", "party.updated" ], "sources": [ "own", "connected" ], "tags": { "env": "staging", "team": null } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `webhook`.", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "description": "Webhook description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status." }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "invitation_link.created", "invitation_link.revoked", "invitation_link.agent_added", "invitation_link.agent_removed", "invitation_link.redeemed", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "ach.created", "ach.processing", "ach.settled", "ach.failed", "ach.returned", "realtime.created", "realtime.processing", "realtime.settled", "realtime.failed", "wire.created", "wire.processing", "wire.completed", "wire.rejected", "wire.failed", "check.created", "check.processing", "check.completed", "check.returned", "check.canceled", "check.expired", "check.rejected", "check.failed", "check.returned_to_sender", "external_party_account.validated", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming", "paymentIntent.completed", "cardPayment.succeeded", "cardPayment.failed", "paymentIntent.canceled", "cardPayment.created", "voiceSession.completed", "refund.created", "refund.succeeded", "refund.failed", "chargeback.created", "chargeback.updated", "chargeback.closed", "enrollment.applied", "enrollment.activated", "enrollment.rejected", "enrollment.offboarded", "mandate.created", "mandate.updated", "mandate.revoked" ], "type": "string" }, "description": "Event types this webhook listens to." }, "sources": { "type": "array", "items": { "enum": [ "own", "connected" ], "type": "string" }, "description": "Event sources this webhook receives: \"own\" for your own party, \"connected\" for parties connected to you through an active authorization." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this webhook was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this webhook was last updated." } }, "required": [ "url", "description", "status", "enabledEvents", "sources", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WebhookSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_019cd1798d8f8560c82adba1d2912643", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet, party, and delegation events", "status": "DISABLED", "enabledEvents": [ "wallet.created", "party.updated" ], "sources": [ "own", "connected" ], "tags": { "env": "staging" }, "createdAt": "2026-03-16T12:00:00.000Z", "updatedAt": "2026-03-17T08:15:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] }, "delete": { "operationId": "webhooks.remove", "summary": "Delete webhook", "description": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[0-9a-f]{32}$", "description": "Webhook ID (whk_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `webhook`.", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL." }, "description": { "type": "string", "description": "Webhook description." }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status." }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "invitation_link.created", "invitation_link.revoked", "invitation_link.agent_added", "invitation_link.agent_removed", "invitation_link.redeemed", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "ach.created", "ach.processing", "ach.settled", "ach.failed", "ach.returned", "realtime.created", "realtime.processing", "realtime.settled", "realtime.failed", "wire.created", "wire.processing", "wire.completed", "wire.rejected", "wire.failed", "check.created", "check.processing", "check.completed", "check.returned", "check.canceled", "check.expired", "check.rejected", "check.failed", "check.returned_to_sender", "external_party_account.validated", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming", "paymentIntent.completed", "cardPayment.succeeded", "cardPayment.failed", "paymentIntent.canceled", "cardPayment.created", "voiceSession.completed", "refund.created", "refund.succeeded", "refund.failed", "chargeback.created", "chargeback.updated", "chargeback.closed", "enrollment.applied", "enrollment.activated", "enrollment.rejected", "enrollment.offboarded", "mandate.created", "mandate.updated", "mandate.revoked" ], "type": "string" }, "description": "Event types this webhook listens to." }, "sources": { "type": "array", "items": { "enum": [ "own", "connected" ], "type": "string" }, "description": "Event sources this webhook receives: \"own\" for your own party, \"connected\" for parties connected to you through an active authorization." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this webhook was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this webhook was last updated." } }, "required": [ "url", "description", "status", "enabledEvents", "sources", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WebhookDeleteResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_019cd1798d8f8560c82adba1d2912643", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "sources": [ "own", "connected" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00.000Z", "updatedAt": "2026-03-16T12:00:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } }, "meta": { "deleted": true } } } } } }, "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": [] } ] } }, "/webhooks/{webhookId}/rotate-secret": { "post": { "operationId": "webhooks.rotateSecret", "summary": "Rotate webhook signing secret", "description": "Rotate the webhook signing secret. The new secret is returned only once.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[0-9a-f]{32}$", "description": "Webhook ID (whk_*)." } }, { "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": { "expiresInSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "Grace period in seconds for the previous secret (0 = immediate cutover, max 86400)." } }, "required": [ "expiresInSeconds" ], "additionalProperties": false, "title": "RotateSecretAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "RotateSecretData" } }, "required": [ "data" ], "additionalProperties": false, "title": "RotateSecretInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "expiresInSeconds": 3600 } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `webhook`.", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Webhook ID (whk_*)." }, "attributes": { "type": "object", "properties": { "signingSecret": { "type": "string", "description": "New webhook signing secret. Returned only once." }, "previousSecretExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the previous secret expires, or null for immediate cutover." } }, "required": [ "signingSecret", "previousSecretExpiresAt" ], "additionalProperties": false, "title": "RotateSecretResponseAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook." } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "RotateSecretResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "RotateSecretResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_019cd1798d8f8560c82adba1d2912643", "attributes": { "signingSecret": "whsec_7Yp2KdN9wL4xT8rE1cV5bM0aQ6hJ3fG8", "previousSecretExpiresAt": "2026-03-17T09:15:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } } }, "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": [] } ] } }, "/events": { "get": { "operationId": "events.list", "summary": "List events", "description": "List events", "tags": [ "Events" ], "parameters": [ { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "eventType", "in": "query", "schema": { "enum": [ "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "invitation_link.created", "invitation_link.revoked", "invitation_link.agent_added", "invitation_link.agent_removed", "invitation_link.redeemed", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "ach.created", "ach.processing", "ach.settled", "ach.failed", "ach.returned", "realtime.created", "realtime.processing", "realtime.settled", "realtime.failed", "wire.created", "wire.processing", "wire.completed", "wire.rejected", "wire.failed", "check.created", "check.processing", "check.completed", "check.returned", "check.canceled", "check.expired", "check.rejected", "check.failed", "check.returned_to_sender", "external_party_account.validated", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming", "paymentIntent.completed", "cardPayment.succeeded", "cardPayment.failed", "paymentIntent.canceled", "cardPayment.created", "voiceSession.completed", "refund.created", "refund.succeeded", "refund.failed", "chargeback.created", "chargeback.updated", "chargeback.closed", "enrollment.applied", "enrollment.activated", "enrollment.rejected", "enrollment.offboarded", "mandate.created", "mandate.updated", "mandate.revoked" ], "type": "string", "description": "Filter by event type. Required when customerPartyId names another party." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "maxLength": 64, "format": "date-time", "description": "Only events created after this RFC 3339 timestamp (exclusive)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "maxLength": 64, "format": "date-time", "description": "Only events created before this RFC 3339 timestamp (exclusive)." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 1024, "description": "Cursor from the previous page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum results per page." }, "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": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `event`.", "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "description": "Event ID (evt_*)." }, "attributes": { "type": "object", "properties": { "eventType": { "enum": [ "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "invitation_link.created", "invitation_link.revoked", "invitation_link.agent_added", "invitation_link.agent_removed", "invitation_link.redeemed", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "ach.created", "ach.processing", "ach.settled", "ach.failed", "ach.returned", "realtime.created", "realtime.processing", "realtime.settled", "realtime.failed", "wire.created", "wire.processing", "wire.completed", "wire.rejected", "wire.failed", "check.created", "check.processing", "check.completed", "check.returned", "check.canceled", "check.expired", "check.rejected", "check.failed", "check.returned_to_sender", "external_party_account.validated", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming", "paymentIntent.completed", "cardPayment.succeeded", "cardPayment.failed", "paymentIntent.canceled", "cardPayment.created", "voiceSession.completed", "refund.created", "refund.succeeded", "refund.failed", "chargeback.created", "chargeback.updated", "chargeback.closed", "enrollment.applied", "enrollment.activated", "enrollment.rejected", "enrollment.offboarded", "mandate.created", "mandate.updated", "mandate.revoked" ], "type": "string", "description": "Type of event." }, "resourceId": { "type": "string", "description": "ID of the resource that triggered the event." }, "resourceType": { "type": "string", "description": "Type of the resource (e.g. wallet, payment)." }, "payload": { "type": "object", "properties": { "object": { "description": "Point-in-time resource snapshot." } }, "additionalProperties": {}, "description": "Event payload containing the resource snapshot." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this event was created." } }, "required": [ "eventType", "resourceId", "resourceType", "payload", "createdAt" ], "additionalProperties": false, "title": "EventAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the event." } }, "required": [ "party" ], "additionalProperties": false, "title": "EventRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "EventResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "event", "id": "evt_0192abc1def2789034567890abcdef12", "attributes": { "eventType": "wallet.created", "resourceId": "wal_00000000000000000000000000000001", "resourceType": "wallet", "payload": { "object": { "type": "wallet", "id": "wal_00000000000000000000000000000001", "attributes": { "status": "active", "walletType": "standard", "isDefault": false, "createdAt": "2026-03-16T12:00:00.000Z", "displayName": "Wallet", "description": null, "tags": { "environment": "production" }, "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_00000000000000000000000000000001" } } }, "version": 1 } }, "createdAt": "2026-03-16T12:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_00000000000000000000000000000001" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ] } }, "/events/{eventId}": { "get": { "operationId": "events.get", "summary": "Get event", "description": "Get an event", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Event ID (evt_*)." } }, { "name": "customerPartyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." }, "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": { "type": { "description": "Resource type. Always `event`.", "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "description": "Event ID (evt_*)." }, "attributes": { "type": "object", "properties": { "eventType": { "enum": [ "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "invitation_link.created", "invitation_link.revoked", "invitation_link.agent_added", "invitation_link.agent_removed", "invitation_link.redeemed", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "ach.created", "ach.processing", "ach.settled", "ach.failed", "ach.returned", "realtime.created", "realtime.processing", "realtime.settled", "realtime.failed", "wire.created", "wire.processing", "wire.completed", "wire.rejected", "wire.failed", "check.created", "check.processing", "check.completed", "check.returned", "check.canceled", "check.expired", "check.rejected", "check.failed", "check.returned_to_sender", "external_party_account.validated", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming", "paymentIntent.completed", "cardPayment.succeeded", "cardPayment.failed", "paymentIntent.canceled", "cardPayment.created", "voiceSession.completed", "refund.created", "refund.succeeded", "refund.failed", "chargeback.created", "chargeback.updated", "chargeback.closed", "enrollment.applied", "enrollment.activated", "enrollment.rejected", "enrollment.offboarded", "mandate.created", "mandate.updated", "mandate.revoked" ], "type": "string", "description": "Type of event." }, "resourceId": { "type": "string", "description": "ID of the resource that triggered the event." }, "resourceType": { "type": "string", "description": "Type of the resource (e.g. wallet, payment)." }, "payload": { "type": "object", "properties": { "object": { "description": "Point-in-time resource snapshot." } }, "additionalProperties": {}, "description": "Event payload containing the resource snapshot." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this event was created." } }, "required": [ "eventType", "resourceId", "resourceType", "payload", "createdAt" ], "additionalProperties": false, "title": "EventAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the event." } }, "required": [ "party" ], "additionalProperties": false, "title": "EventRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "EventResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "event", "id": "evt_0192abc1def2789034567890abcdef12", "attributes": { "eventType": "wallet.created", "resourceId": "wal_00000000000000000000000000000001", "resourceType": "wallet", "payload": { "object": { "type": "wallet", "id": "wal_00000000000000000000000000000001", "attributes": { "status": "active", "walletType": "standard", "isDefault": false, "createdAt": "2026-03-16T12:00:00.000Z", "displayName": "Wallet", "description": null, "tags": { "environment": "production" }, "balance": null, "claims": { "amount": 0, "count": 0 }, "depositInstructions": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_00000000000000000000000000000001" } } }, "version": 1 } }, "createdAt": "2026-03-16T12:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_00000000000000000000000000000001" } } } } } } } } }, "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": [] } ] } }, "/webhooks/{webhookId}/events/{eventId}/redeliver": { "post": { "operationId": "events.redeliver", "summary": "Redeliver event", "description": "Send the stored event to the webhook again", "tags": [ "Events" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[0-9a-f]{32}$", "description": "Webhook ID (whk_*)." } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Event ID (evt_*)." } }, { "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." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `redelivery`.", "type": "string", "enum": [ "redelivery" ] }, "id": { "type": "string", "pattern": "^rdy_[0-9a-f]{32}$", "description": "Redelivery ID (rdy_*)." }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "PENDING", "DELIVERING", "DELIVERED", "FAILED", "UNKNOWN", "CANCELED" ], "type": "string", "description": "Redelivery status. UNKNOWN means no response was recorded." }, "attemptCount": { "type": "integer", "description": "Number of attempts made for this redelivery." }, "maxAttempts": { "type": "integer", "description": "Maximum attempts for this redelivery." }, "responseCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP response code, or null when no response was received." }, "errorCategory": { "anyOf": [ { "enum": [ "HTTP", "NETWORK", "SSRF", "CONFIGURATION", "UNKNOWN" ], "type": "string" }, { "type": "null" } ], "description": "Failure category, or null when the delivery succeeded." }, "sanitizedError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure summary, or null when the delivery succeeded." }, "firstAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the redelivery attempt began, or null." }, "lastAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the redelivery attempt finished, or null." }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this redelivery reached a terminal state, or null." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this redelivery was requested." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when this redelivery last changed state." } }, "required": [ "status", "attemptCount", "maxAttempts", "responseCode", "errorCategory", "sanitizedError", "firstAttemptAt", "lastAttemptAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `webhook`.", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "pattern": "^whk_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Parent webhook endpoint." }, "event": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `event`.", "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Event being redelivered." } }, "required": [ "webhook", "event" ], "additionalProperties": false, "title": "RedeliveryRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "RedeliveryResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "RedeliverySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "redelivery", "id": "rdy_019cd1798d9212b2e35f4eb42c656a5b", "attributes": { "status": "PENDING", "attemptCount": 0, "maxAttempts": 1, "responseCode": null, "errorCategory": null, "sanitizedError": null, "firstAttemptAt": null, "lastAttemptAt": null, "completedAt": null, "createdAt": "2026-03-20T09:00:00.000Z", "updatedAt": "2026-03-20T09:00:00.000Z" }, "relationships": { "webhook": { "data": { "type": "webhook", "id": "whk_019cd1798d8f8560c82adba1d2912643" } }, "event": { "data": { "type": "event", "id": "evt_019cd1798d9190112b89219ccb1aaa44" } } } } } } } } }, "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": [] } ] } }, "/simulations/invite-customer": { "post": { "operationId": "simulations.inviteCustomer", "summary": "Invite test customer", "description": "Create a test customer and a pending invitation for each agent you name", "tags": [ "Simulations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "agentIds": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, "description": "Agents (agt_*) to offer. The test customer receives a pending invitation for each." }, "permissions": { "anyOf": [ { "type": "array", "minItems": 1, "maxItems": 32, "items": { "enum": [ "disputes.read", "disputes.create", "payments.read", "payments.create", "external_parties.read", "external_parties.create", "direct.read", "direct.create", "external_accounts.create", "wallets.read", "wallets.balance", "wallets.create", "wallets.update", "wallets.fund", "wallets.deposit", "wallets.transfer", "wallets.withdraw", "party.read", "party.update", "payment_intents.create", "payment_intents.read", "card_payments.read", "refunds.read", "refunds.create", "voice_sessions.read", "voice_sessions.create", "chargebacks.read", "chargebacks.respond", "mandates.read", "enrollment.read", "cards.read", "saved_cards.use" ], "type": "string" }, "title": "PermissionList", "description": "Specific permissions to request." }, { "type": "object", "properties": { "type": { "description": "Set to `ALL`.", "type": "string", "enum": [ "ALL" ] } }, "required": [ "type" ], "additionalProperties": false, "title": "AllPermissions", "description": "Request every permission available to your party today." } ], "description": "Permissions for each agent, or `{\"type\":\"ALL\"}` for all of them. Fixed when the invitation is created." }, "type": { "enum": [ "PERSON", "ORG" ], "type": "string", "description": "Test customer party type. Defaults to PERSON." }, "message": { "type": "string", "maxLength": 180, "description": "Message stored with each pending invitation. Sandbox does not send an invitation email." }, "redirectUrl": { "type": "string", "maxLength": 2048, "description": "Where to send the test customer after they accept and finish setup: an https URL, an app deep link, or an sms: link." } }, "required": [ "agentIds", "permissions" ], "additionalProperties": false, "title": "InviteSandboxCustomerAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "InviteSandboxCustomerData" } }, "required": [ "data" ], "additionalProperties": false, "title": "InviteSandboxCustomerRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "agentIds": [ "agt_019cd1798d637a4da75dce386343931d" ], "permissions": [ "wallets.create", "wallets.deposit", "wallets.withdraw", "wallets.transfer" ], "message": "Please review the agent access request.", "type": "ORG" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agentDelegationInvitation`.", "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name." }, "email": { "type": "string", "description": "Recipient email." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone." }, "url": { "type": "string", "format": "uri", "description": "Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations." }, "agentName": { "type": "string", "description": "Agent name." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits." }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status." }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Status after applying expiry: reads EXPIRED once `expiresAt` has passed even while `status` is still PENDING." }, "expiresAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation expires." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation was accepted, or null." }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation was declined, or null." }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED", "CONNECTION_ESTABLISHED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation." }, "redirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the customer is sent after accepting and finishing setup, or null." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation was last updated." } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "redirectUrl", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details." }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent." }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party that accepted the invitation, or null until acceptance." } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" }, "description": "Pending invitations created, one for each agent listed." }, "meta": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "handle": { "type": "string", "description": "The test customer's handle (@name), assigned automatically." }, "partyType": { "enum": [ "PERSON", "ORG" ], "type": "string", "description": "Test customer party type." } }, "required": [ "partyId", "handle", "partyType" ], "additionalProperties": false } }, "required": [ "customer" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "InviteSandboxCustomerResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agentDelegationInvitation", "id": "adi_019cd1798d98577084df77e7ec734db5", "attributes": { "developerName": "Acme Payments", "email": "test+7f21c4@fixtures.sandbox.natural.test", "phone": null, "url": "https://www.natural.com/connect/adi_019cd1798d98577084df77e7ec734db5", "agentName": "Procurement Agent", "permissions": [ "wallets.create", "wallets.deposit", "wallets.withdraw", "wallets.transfer", "party.read" ], "limits": null, "status": "PENDING", "effectiveStatus": "PENDING", "expiresAt": "2026-02-03T15:30:00.000Z", "acceptedAt": null, "declinedAt": null, "cancelReason": null, "redirectUrl": null, "tags": {}, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "customerParty": { "data": null } } } ], "meta": { "customer": { "partyId": "pty_019cd1798d6a0cf1a6076c62addacb4d", "handle": "@brightside-labs", "partyType": "ORG" } } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-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." } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/customers/{customerId}/transfers/deposit": { "post": { "operationId": "simulations.fundCustomer", "summary": "Fund test customer", "description": "Add test funds to a connected customer's wallet", "tags": [ "Simulations" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." } }, { "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", "exclusiveMinimum": 0, "description": "Amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code. Defaults to USD." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet (wal_*) to credit. Defaults to the customer's default wallet." } }, "required": [ "amount" ], "additionalProperties": false, "title": "SimulatedDepositAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "SimulatedDepositData" } }, "required": [ "data" ], "additionalProperties": false, "title": "SimulateCustomerDepositRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 250000, "currency": "USD" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `transfer`.", "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$", "description": "Transfer ID (trf_*)." }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type." }, "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender for an instant withdrawal. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status." }, "method": { "anyOf": [ { "enum": [ "standard", "instant", "wire" ], "type": "string" }, { "type": "null" } ], "description": "Requested delivery method, when available." }, "rail": { "anyOf": [ { "enum": [ "ach", "wire", "internal", "realtime" ], "type": "string" }, { "type": "null" } ], "description": "Executed transfer rail, when available." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account number." }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the funds are expected to be available, or null when unknown." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available." }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was returned, or null." } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was submitted, or null." }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer settled, or null." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this transfer was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this transfer was last updated, or null." } }, "required": [ "type", "amount", "currency", "fee", "status", "method", "rail", "description", "tags", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the transfer." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "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 for this transfer." }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "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." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `externalAccount`.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction for this transfer, when available." } }, "required": [ "party", "initiatorAgent", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "SimulatedDepositResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_019cd1798d7e558c3112da8c995ecc23", "attributes": { "type": "deposit", "amount": 250000, "currency": "USD", "fee": null, "status": "COMPLETED", "method": null, "rail": null, "description": null, "tags": {}, "externalAccountDisplayMask": null, "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00.000Z", "settledAt": "2026-01-04T15:30:00.000Z", "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d6a0cf1a6076c62addacb4d" } }, "initiatorAgent": { "data": null }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d74c347d791b860e526fc3e" } }, "externalAccount": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d826169e8169920e61556d7" } } } } } } } } }, "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" } } ] } } } } } }, "408": { "description": "408", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] }, "status": { "const": 408 }, "message": { "type": "string", "default": "The deposit was accepted, but its Transfer is not visible yet. Retry with the same Idempotency-Key." }, "data": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] } }, "required": [ "reason" ], "additionalProperties": false, "title": "SandboxNotReadyErrorData" } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/external-accounts/link": { "post": { "operationId": "simulations.linkExternalAccount", "summary": "Link test bank account", "description": "Link a test bank account to your own party", "tags": [ "Simulations" ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type. Always `externalAccount`.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)." }, "attributes": { "type": "object", "properties": { "lastFour": { "type": "string", "description": "Last four digits of the external bank account." }, "status": { "enum": [ "pending", "new", "active", "disabled", "deleted", "unknown" ], "type": "string", "description": "Lifecycle status of the external account." }, "connectionStatus": { "enum": [ "active", "login_required", "disconnected" ], "type": "string", "description": "Bank connection health. Relink the account when it is `login_required` or `disconnected`." }, "availableMethods": { "type": "array", "items": { "enum": [ "standard", "instant" ], "type": "string" }, "description": "Withdrawal delivery methods this account supports." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the account was linked." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank institution name, when available." }, "accountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account display name, when available." }, "accountType": { "anyOf": [ { "enum": [ "checking", "savings", "unknown" ], "type": "string" }, { "type": "null" } ], "description": "Bank account type, when available." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." } }, "required": [ "lastFour", "status", "connectionStatus", "availableMethods", "createdAt", "bankName", "accountName", "accountType", "tags" ], "additionalProperties": false, "title": "ExternalAccountAttributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the external account." } }, "required": [ "party" ], "additionalProperties": false, "title": "ExternalAccountRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalAccountResource" }, "description": "External accounts linked or refreshed by the request." }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null when there are no more results." } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" }, "rejectedAccounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Bank account identifier for the rejected account." }, "accountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the rejected account." }, "accountMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last-four mask of the rejected account." }, "reason": { "enum": [ "profile_identity_missing", "bank_identity_unavailable", "bank_account_name_mismatch", "bank_account_address_mismatch", "bank_account_ownership_mismatch", "bank_account_verification_failed", "link_failed" ], "type": "string", "description": "Reason code explaining why the account was not linked." } }, "required": [ "accountId", "accountName", "accountMask", "reason" ], "additionalProperties": false, "title": "ExternalAccountRejectedAccount" }, "description": "Accounts reviewed during linking but not linked." } }, "required": [ "pagination", "rejectedAccounts" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ExternalAccountListWithRejectedAccountsResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "externalAccount", "id": "eac_019cd1798d76ab44b37e5ebd9d2a2ffb", "attributes": { "bankName": "Natural Test Bank", "accountName": "Test Checking", "accountType": "checking", "lastFour": "0000", "status": "active", "connectionStatus": "active", "availableMethods": [ "standard" ], "createdAt": "2026-01-04T15:30:00.000Z", "tags": {} }, "relationships": { "party": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null }, "rejectedAccounts": [] } } } } } }, "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": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-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." } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/payments/{paymentId}/complete-claim": { "post": { "operationId": "simulations.completePaymentClaim", "summary": "Complete payment claim", "description": "Simulate the recipient of a held payment joining Natural and receiving the funds", "tags": [ "Simulations" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." } }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was submitted to money movement, or null while unsubmitted." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment reached a terminal status, or null while in flight." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this payment failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this payment was returned." }, "claim": { "anyOf": [ { "type": "object", "properties": { "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient began claiming this payment, or null while unclaimed or unobserved." }, "claimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient claimed this payment, or null while unclaimed." }, "unboundAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when a claimed payment detached from its recipient, or null." } }, "required": [ "startedAt", "claimedAt", "unboundAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Claim lifecycle for payments sent to an off-platform recipient, or null when this payment is not claim-based." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was last updated, or null." } }, "required": [ "amount", "currency", "status", "description", "tags", "fee", "submittedAt", "terminalAt", "failure", "return", "claim", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "initiatorAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_019cd1798d77ef3e74d16143bd39940a", "attributes": { "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Q4 development work", "tags": { "order_id": "ord_123" }, "fee": null, "submittedAt": "2026-01-04T15:30:00.000Z", "terminalAt": null, "failure": null, "return": null, "claim": { "startedAt": null, "claimedAt": null, "unboundAt": null }, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "sender": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_019cd1798d6672a7b828eee780291b72" } }, "paymentRequest": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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" } } ] } } } } } }, "408": { "description": "408", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] }, "status": { "const": 408 }, "message": { "type": "string", "default": "The recipient wallet is ready, but the payment binding is not visible yet. Retry this action." }, "data": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] } }, "required": [ "reason" ], "additionalProperties": false, "title": "SandboxNotReadyErrorData" } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/payment-requests/{paymentRequestId}/fulfill": { "post": { "operationId": "simulations.fulfillPaymentRequest", "summary": "Fulfill payment request as test payer", "description": "Fulfill an open payment request addressed to your test payer", "tags": [ "Simulations" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$", "description": "Payment ID (pay_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "sender" ] }, "applied": { "description": "The fee is added to the sender's cost without reducing the principal amount.", "type": "string", "enum": [ "on_top" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "SenderOnTopFee" }, { "type": "null" } ], "description": "Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was submitted to money movement, or null while unsubmitted." }, "terminalAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment reached a terminal status, or null while in flight." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this payment failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code, when available." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason text, when available." } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this payment was returned." }, "claim": { "anyOf": [ { "type": "object", "properties": { "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient began claiming this payment, or null while unclaimed or unobserved." }, "claimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the recipient claimed this payment, or null while unclaimed." }, "unboundAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when a claimed payment detached from its recipient, or null." } }, "required": [ "startedAt", "claimedAt", "unboundAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Claim lifecycle for payments sent to an off-platform recipient, or null when this payment is not claim-based." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when this payment was created." }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment was last updated, or null." } }, "required": [ "amount", "currency", "status", "description", "tags", "fee", "submittedAt", "terminalAt", "failure", "return", "claim", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent, or null unless addressed by agent ID or agent handle." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `transaction`.", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "initiatorAgent", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_019cd1798d78f1129dd012ce651d1ff1", "attributes": { "amount": 2500, "currency": "USD", "status": "PROCESSING", "description": "Invoice 7", "tags": { "invoice_id": "inv_7" }, "fee": null, "submittedAt": "2026-04-15T00:00:00.000Z", "terminalAt": null, "failure": null, "return": null, "claim": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "initiatorAgent": { "data": null }, "sender": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "recipientAgent": { "data": null }, "transaction": { "data": null }, "paymentRequest": { "data": { "type": "paymentRequest", "id": "prq_019cd1798d7a68fe07c972bed48fb7fd" } } } } } } } } }, "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" } } ] } } } } } }, "408": { "description": "408", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] }, "status": { "const": 408 }, "message": { "type": "string", "default": "The deposit was accepted, but its Transfer is not visible yet. Retry with the same Idempotency-Key." }, "data": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] } }, "required": [ "reason" ], "additionalProperties": false, "title": "SandboxNotReadyErrorData" } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/payment-requests/{paymentRequestId}/decline": { "post": { "operationId": "simulations.declinePaymentRequest", "summary": "Decline payment request as test payer", "description": "Decline an open payment request addressed to your test payer", "tags": [ "Simulations" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique key for safely retrying a request without creating duplicates." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `paymentRequest`.", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Payment request ID (prq_*)." }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents." }, "currency": { "type": "string", "description": "Currency code." }, "fee": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Fee amount in cents." }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency of the fee." }, "payer": { "description": "Party role charged the fee.", "type": "string", "enum": [ "recipient" ] }, "applied": { "description": "The fee is subtracted from the principal amount before the recipient receives it.", "type": "string", "enum": [ "deducted" ] } }, "required": [ "amount", "currency", "payer", "applied" ], "additionalProperties": false, "title": "RecipientDeductedFee" }, { "type": "null" } ], "description": "Fee deducted from your proceeds as the recipient. Null when no fee applies, the fee was voided, or your party is not the fee payer." }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Payment request status." }, "payerCanPay": { "type": "boolean", "description": "Whether the payer can still fulfill this request: it is OPEN, unexpired, and has no payment attempt. Does not check the payer's authorization or funding." }, "payerCanDecline": { "type": "boolean", "description": "Whether the payer can still decline this request: it is OPEN. Does not check the payer's authorization." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 80 characters." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment." }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment." }, "requesterAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the party requesting payment, if one is set." }, "requesterHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The requesting party's composed public handle (@namespace), or null when it has none." }, "walletName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving wallet name, or null when unnamed or hidden from the caller." }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer." }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer, or null when none is known." }, "payerAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL for the payer party, if one is set." }, "payerHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less." }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payer phone number when addressed by phone." }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties." }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Identifier type used to address the payer." }, "payerIdentifier": { "type": "string", "description": "Identifier value used to address the payer." }, "initiatorParty": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*)." }, "name": { "type": "string", "description": "Party display name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle, such as @acme, or null when none is set." } }, "required": [ "id", "name", "handle" ], "additionalProperties": false }, { "type": "null" } ], "description": "The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party." }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment." }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transaction (txn_*) created by the most recent payment attempt, or null when none has been made." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when this payment request expires, or null when it does not expire." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the payment request was last updated." } }, "required": [ "amount", "currency", "fee", "status", "payerCanPay", "payerCanDecline", "description", "tags", "requesterName", "requesterEmail", "requesterAvatarUrl", "requesterHandle", "walletName", "payerName", "payerEmail", "payerAvatarUrl", "payerHandle", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "initiatorParty", "paymentLinkUrl", "transactionId", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes" }, "relationships": { "type": "object", "properties": { "initiatorAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent that initiated this resource, or null when no agent can be reliably attributed." }, "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party requesting the payment." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "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 that receives the funds." }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural." }, "payerAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payer agent, or null unless addressed by agent ID or agent handle." }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `payment`.", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "initiatorAgent", "requesterParty", "wallet", "payerParty", "payerAgent", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_019cd1798d7a68fe07c972bed48fb7fd", "attributes": { "amount": 2500, "currency": "USD", "fee": null, "status": "DECLINED", "payerCanPay": false, "payerCanDecline": false, "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "requesterAvatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp", "requesterHandle": "@acme", "walletName": "Operating", "description": "Invoice 7", "tags": { "invoice_id": "inv_7" }, "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png", "payerHandle": "@ada-lovelace", "payerPartyId": "pty_019cd1798d681091fcf1dc98afb72d01", "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "initiatorParty": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "name": "Acme Payments", "handle": "@acme" }, "paymentLinkUrl": "https://www.natural.com/pay/token_123", "transactionId": null, "expiresAt": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:05:00.000Z" }, "relationships": { "initiatorAgent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_019cd1798d714ce765e0486a417c23dc" } }, "payerParty": { "data": { "type": "party", "id": "pty_019cd1798d681091fcf1dc98afb72d01" } }, "payerAgent": { "data": null }, "payment": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/realtime/{realtimeId}/settle": { "post": { "operationId": "simulations.settleRealtime", "summary": "Sandbox: settle a realtime payment", "description": "Drive a sandbox realtime payment to settlement", "tags": [ "Simulations" ], "parameters": [ { "name": "realtimeId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rt_[0-9a-f]{32}$" } }, { "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": false, "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": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." } }, "additionalProperties": false, "title": "RealtimeSimulationRequestAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "RealtimeSimulationRequestData" } }, "required": [], "additionalProperties": false, "title": "RealtimeSimulationRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "customerPartyId": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "realtime-simulation" ] }, "id": { "type": "string", "pattern": "^rt_[0-9a-f]{32}$", "description": "The realtime payment the action was applied to." }, "attributes": { "type": "object", "properties": { "action": { "enum": [ "settle", "fail" ], "type": "string", "description": "Lifecycle action applied." }, "scenario": { "type": "string", "description": "Fixture scenario fired on the money-movement side." }, "fixturesFired": { "type": "integer", "description": "Number of webhook events emitted." } }, "required": [ "action", "scenario", "fixturesFired" ], "additionalProperties": false, "title": "RealtimeSimulationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "RealtimeSimulationResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "RealtimeSimulationResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "realtime-simulation", "id": "rt_019cd1798d855ae91a83bde5392f3664", "attributes": { "action": "settle", "scenario": "column_rtp_outgoing_success", "fixturesFired": 2 } } } } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/realtime/{realtimeId}/fail": { "post": { "operationId": "simulations.failRealtime", "summary": "Sandbox: fail a realtime payment", "description": "Drive a sandbox realtime payment to a terminal network rejection", "tags": [ "Simulations" ], "parameters": [ { "name": "realtimeId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rt_[0-9a-f]{32}$" } }, { "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": false, "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": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." } }, "additionalProperties": false, "title": "RealtimeSimulationRequestAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "RealtimeSimulationRequestData" } }, "required": [], "additionalProperties": false, "title": "RealtimeSimulationRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "customerPartyId": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "realtime-simulation" ] }, "id": { "type": "string", "pattern": "^rt_[0-9a-f]{32}$", "description": "The realtime payment the action was applied to." }, "attributes": { "type": "object", "properties": { "action": { "enum": [ "settle", "fail" ], "type": "string", "description": "Lifecycle action applied." }, "scenario": { "type": "string", "description": "Fixture scenario fired on the money-movement side." }, "fixturesFired": { "type": "integer", "description": "Number of webhook events emitted." } }, "required": [ "action", "scenario", "fixturesFired" ], "additionalProperties": false, "title": "RealtimeSimulationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "RealtimeSimulationResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "RealtimeSimulationResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "realtime-simulation", "id": "rt_019cd1798d855ae91a83bde5392f3664", "attributes": { "action": "fail", "scenario": "column_rtp_outgoing_rejected", "fixturesFired": 2 } } } } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/wire/{wireId}/settle": { "post": { "operationId": "simulations.settleWire", "summary": "Sandbox: settle a wire payment", "description": "Complete a test wire payment", "tags": [ "Simulations" ], "parameters": [ { "name": "wireId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wire_[0-9a-f]{32}$" } }, { "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": { "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." } }, "additionalProperties": false, "title": "WireSimulationRequestAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WireSimulationRequestData" } }, "required": [ "data" ], "additionalProperties": false, "title": "WireSimulationRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "customerPartyId": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wire-simulation" ] }, "id": { "type": "string", "pattern": "^wire_[0-9a-f]{32}$", "description": "The wire payment the action was applied to." }, "attributes": { "type": "object", "properties": { "action": { "enum": [ "settle", "fail" ], "type": "string", "description": "Lifecycle action applied." }, "scenario": { "type": "string", "description": "Fixture scenario fired on the money-movement side." }, "fixturesFired": { "type": "integer", "description": "Number of webhook events emitted." } }, "required": [ "action", "scenario", "fixturesFired" ], "additionalProperties": false, "title": "WireSimulationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "WireSimulationResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WireSimulationResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wire-simulation", "id": "wire_019cd1798d875d7c0a4165d10dc4db29", "attributes": { "action": "settle", "scenario": "column_wire_outgoing_success", "fixturesFired": 3 } } } } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/wire/{wireId}/fail": { "post": { "operationId": "simulations.failWire", "summary": "Sandbox: fail a wire payment", "description": "Reject a test wire payment", "tags": [ "Simulations" ], "parameters": [ { "name": "wireId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wire_[0-9a-f]{32}$" } }, { "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": { "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf." } }, "additionalProperties": false, "title": "WireSimulationRequestAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WireSimulationRequestData" } }, "required": [ "data" ], "additionalProperties": false, "title": "WireSimulationRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "customerPartyId": "pty_019cd1798d617f65a79cb965dda9eac3" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wire-simulation" ] }, "id": { "type": "string", "pattern": "^wire_[0-9a-f]{32}$", "description": "The wire payment the action was applied to." }, "attributes": { "type": "object", "properties": { "action": { "enum": [ "settle", "fail" ], "type": "string", "description": "Lifecycle action applied." }, "scenario": { "type": "string", "description": "Fixture scenario fired on the money-movement side." }, "fixturesFired": { "type": "integer", "description": "Number of webhook events emitted." } }, "required": [ "action", "scenario", "fixturesFired" ], "additionalProperties": false, "title": "WireSimulationAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "WireSimulationResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WireSimulationResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wire-simulation", "id": "wire_019cd1798d875d7c0a4165d10dc4db29", "attributes": { "action": "fail", "scenario": "column_wire_outgoing_rejected", "fixturesFired": 3 } } } } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/card-payments/{cardPaymentId}/settle": { "post": { "operationId": "simulations.settleCardPayment", "summary": "Sandbox: settle a card payment", "description": "Simulate settlement of a successful card payment into the receiving wallet. Sandbox only.", "tags": [ "Simulations" ], "parameters": [ { "name": "cardPaymentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cpy_[0-9a-f]{32}$", "description": "Card payment ID (cpy_*). The payment must have succeeded." } }, { "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": { "customerPartyId": { "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." } }, "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": {} } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CardPayment" } }, "required": [ "data" ], "additionalProperties": false, "title": "CardPaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "cpy_019d0a1b2c3d4e5f60718293a4b5c6d8", "type": "cardPayment", "attributes": { "amount": 3920, "currency": "USD", "status": "succeeded", "brand": "visa", "last4": "4242", "channel": "link", "receiptUrl": "https://checkout.natural.com/receipts#example", "failure": null, "fee": { "amount": 144, "currency": "USD", "payer": "recipient", "applied": "deducted" }, "refundedAmount": 0, "refundableAmount": 3920, "settledAt": null, "createdAt": "2026-09-17T18:02:39.000Z", "updatedAt": "2026-09-17T18:02:41.000Z" }, "relationships": { "paymentIntent": { "data": { "type": "paymentIntent", "id": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/customer-invitations/{invitationId}/accept": { "post": { "operationId": "simulations.acceptCustomerInvitation", "summary": "Accept customer invitation as test customer", "description": "Accept a pending customer invitation as the test customer it is addressed to", "tags": [ "Simulations" ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." } }, { "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": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*) of the test customer the invitation is addressed to." } }, "required": [ "partyId" ], "additionalProperties": false, "title": "SimulateCustomerInvitationActionAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "SimulateCustomerInvitationActionData" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "partyId": "pty_019cd1798d6a0cf1a6076c62addacb4d" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agentDelegationInvitation`.", "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name." }, "email": { "type": "string", "description": "Recipient email." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone." }, "url": { "type": "string", "format": "uri", "description": "Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations." }, "agentName": { "type": "string", "description": "Agent name." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits." }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status." }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Status after applying expiry: reads EXPIRED once `expiresAt` has passed even while `status` is still PENDING." }, "expiresAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation expires." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation was accepted, or null." }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation was declined, or null." }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED", "CONNECTION_ESTABLISHED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation." }, "redirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the customer is sent after accepting and finishing setup, or null." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation was last updated." } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "redirectUrl", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details." }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent." }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party that accepted the invitation, or null until acceptance." } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentDelegationInvitationResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentDelegationInvitation", "id": "adi_019cd1798d98577084df77e7ec734db5", "attributes": { "developerName": "Acme Payments", "email": "test+7f21c4@fixtures.sandbox.natural.test", "phone": null, "url": "https://www.natural.com/connect/adi_019cd1798d98577084df77e7ec734db5", "agentName": "Procurement Agent", "permissions": [ "wallets.create", "wallets.deposit", "wallets.withdraw", "wallets.transfer", "party.read" ], "limits": null, "status": "ACCEPTED", "effectiveStatus": "ACCEPTED", "expiresAt": "2026-02-03T15:30:00.000Z", "acceptedAt": "2026-01-04T15:35:00.000Z", "declinedAt": null, "cancelReason": null, "redirectUrl": null, "tags": {}, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:35:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "customerParty": { "data": { "type": "party", "id": "pty_019cd1798d6a0cf1a6076c62addacb4d" } } } } } } } } }, "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" } } ] } } } } } }, "408": { "description": "408", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] }, "status": { "const": 408 }, "message": { "type": "string", "default": "The sandbox fixture could not complete this action yet. Retry with the same Idempotency-Key." }, "data": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] } }, "required": [ "reason" ], "additionalProperties": false, "title": "SandboxNotReadyErrorData" } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/customer-invitations/{invitationId}/decline": { "post": { "operationId": "simulations.declineCustomerInvitation", "summary": "Decline customer invitation as test customer", "description": "Decline a pending customer invitation as the test customer it is addressed to", "tags": [ "Simulations" ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." } }, { "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": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_*) of the test customer the invitation is addressed to." } }, "required": [ "partyId" ], "additionalProperties": false, "title": "SimulateCustomerInvitationActionAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "SimulateCustomerInvitationActionData" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "partyId": "pty_019cd1798d6a0cf1a6076c62addacb4d" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agentDelegationInvitation`.", "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)." }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name." }, "email": { "type": "string", "description": "Recipient email." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone." }, "url": { "type": "string", "format": "uri", "description": "Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations." }, "agentName": { "type": "string", "description": "Agent name." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits." }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status." }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Status after applying expiry: reads EXPIRED once `expiresAt` has passed even while `status` is still PENDING." }, "expiresAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation expires." }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation was accepted, or null." }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the invitation was declined, or null." }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED", "CONNECTION_ESTABLISHED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation." }, "redirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the customer is sent after accepting and finishing setup, or null." }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Metadata visible to anyone who can read the resource." }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation was created." }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp when the invitation was last updated." } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "redirectUrl", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details." }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `agent`.", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent." }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type. Always `party`.", "type": "string", "enum": [ "party" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier." }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party that accepted the invitation, or null until acceptance." } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentDelegationInvitationResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentDelegationInvitation", "id": "adi_019cd1798d98577084df77e7ec734db5", "attributes": { "developerName": "Acme Payments", "email": "test+7f21c4@fixtures.sandbox.natural.test", "phone": null, "url": "https://www.natural.com/connect/adi_019cd1798d98577084df77e7ec734db5", "agentName": "Procurement Agent", "permissions": [ "wallets.create", "wallets.deposit", "wallets.withdraw", "wallets.transfer", "party.read" ], "limits": null, "status": "DECLINED", "effectiveStatus": "DECLINED", "expiresAt": "2026-02-03T15:30:00.000Z", "acceptedAt": null, "declinedAt": "2026-01-04T15:35:00.000Z", "cancelReason": null, "redirectUrl": null, "tags": {}, "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:35:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } }, "customerParty": { "data": null } } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets.", "schema": { "type": "integer" } } } }, "400": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable lower-snake-case public error code." }, "detail": { "type": "string", "description": "Safe user-facing error detail." }, "status": { "type": "string", "description": "HTTP status code as a string." }, "source": { "type": "object", "description": "Location of the invalid request value.", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid request value." }, "parameter": { "type": "string", "description": "Name of the invalid query parameter." }, "header": { "type": "string", "description": "Name of the invalid request header." } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Additional error context, including support and provider details when available.", "properties": { "supportId": { "type": "string", "description": "Request/support ID for troubleshooting." }, "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" } } ] } } } } } }, "408": { "description": "408", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] }, "status": { "const": 408 }, "message": { "type": "string", "default": "The sandbox fixture could not complete this action yet. Retry with the same Idempotency-Key." }, "data": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] } }, "required": [ "reason" ], "additionalProperties": false, "title": "SandboxNotReadyErrorData" } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/customers/{customerId}/agents/{agentId}/revoke": { "post": { "operationId": "simulations.revokeAgentConnection", "summary": "Revoke agent access as test customer", "description": "Remove an agent's access to a test customer, acting as the customer", "tags": [ "Simulations" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `customer`.", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the customer's party was created, or null when unknown." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Connection status: ACTIVE, SUSPENDED (paused by the customer), REVOKED, or EXPIRED." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted by the customer." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the customer connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when access was revoked, or null while active." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted to this agent." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." } }, "required": [ "data" ], "additionalProperties": false, "title": "CustomerResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `customer`.", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the customer's party was created, or null when unknown." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Connection status: ACTIVE, SUSPENDED (paused by the customer), REVOKED, or EXPIRED." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted by the customer." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the customer connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when access was revoked, or null while active." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted to this agent." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false } ], "title": "CustomerAgentRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "customer", "id": "pty_019cd1798d6a0cf1a6076c62addacb4d", "attributes": { "name": "Brightside Labs", "email": null, "avatarUrl": null, "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_019cd1798d95f0cc5678a9356b2148ea", "status": "ACTIVE", "permissions": [], "createdAt": "2026-01-04T15:35:00.000Z", "revokedAt": null }, "agents": [] } } } } } } }, "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" } } ] } } } } } }, "408": { "description": "408", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] }, "status": { "const": 408 }, "message": { "type": "string", "default": "The sandbox fixture could not complete this action yet. Retry with the same Idempotency-Key." }, "data": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] } }, "required": [ "reason" ], "additionalProperties": false, "title": "SandboxNotReadyErrorData" } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } }, "/simulations/customers/{customerId}/disconnect": { "post": { "operationId": "simulations.disconnectCustomer", "summary": "Disconnect test customer", "description": "End a test customer's connection and revoke all remaining agent access", "tags": [ "Simulations" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." } }, { "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." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type. Always `customer`.", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID (pty_*)." }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address." }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public avatar URL, or null when none is set." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when the customer's party was created, or null when unknown." }, "delegation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dlg_[0-9a-f]{32}$", "description": "Delegation ID (dlg_*)." }, "status": { "enum": [ "ACTIVE", "SUSPENDED", "REVOKED", "EXPIRED" ], "type": "string", "description": "Connection status: ACTIVE, SUSPENDED (paused by the customer), REVOKED, or EXPIRED." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted by the customer." }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the customer connected." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "RFC 3339 timestamp when access was revoked, or null while active." } }, "required": [ "id", "status", "permissions", "createdAt", "revokedAt" ], "additionalProperties": false, "title": "CustomerDelegation", "description": "Delegation details." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle, such as @acme-support, or null when none is set." }, "status": { "type": "string", "description": "Connection status." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted to this agent." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction spending limit in cents, or null for no limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily spending limit in cents, or null for no limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Monthly spending limit in cents, or null for no limit." } }, "additionalProperties": false, "title": "ConnectedAgentLimits" }, { "type": "null" } ], "description": "Spending limits in cents (per-transaction, daily, monthly) for this agent." } }, "required": [ "id", "name", "handle", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents." } }, "required": [ "name", "email", "avatarUrl", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "Customer connection, including revoked connections when requested." }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted." } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CustomerDisconnectResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "customer", "id": "pty_019cd1798d6a0cf1a6076c62addacb4d", "attributes": { "name": "Brightside Labs", "email": null, "avatarUrl": null, "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_019cd1798d95f0cc5678a9356b2148ea", "status": "REVOKED", "permissions": [], "createdAt": "2026-01-04T15:35:00.000Z", "revokedAt": "2026-08-07T12:00:00.000Z" }, "agents": [ { "id": "agt_019cd1798d637a4da75dce386343931d", "name": "Procurement Agent", "handle": "@acme-procurementagent", "status": "REVOKED", "permissions": [], "limits": null } ] } }, "meta": { "deleted": true } } } } } }, "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" } } ] } } } } } }, "408": { "description": "408", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] }, "status": { "const": 408 }, "message": { "type": "string", "default": "The sandbox fixture could not complete this action yet. Retry with the same Idempotency-Key." }, "data": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "SANDBOX_NOT_READY" ] } }, "required": [ "reason" ], "additionalProperties": false, "title": "SandboxNotReadyErrorData" } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "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": [] } ], "servers": [ { "url": "https://api.sandbox.natural.com", "description": "Sandbox" } ] } } }, "tags": [ { "name": "Agents", "description": "Agent management" }, { "name": "Customers", "description": "Customer management" }, { "name": "Invitation Links", "description": "Shareable links that offer your agents to customers" }, { "name": "Payments", "description": "Payment management" }, { "name": "Payment Intents", "description": "Accept card payments by link or voice" }, { "name": "Card Payments", "description": "Card payment attempts" }, { "name": "Voice", "description": "Collect a payment intent over a phone call" }, { "name": "Refunds", "description": "Return card payments to the payer" }, { "name": "Chargebacks", "description": "Respond to card payment chargebacks" }, { "name": "Transactions", "description": "Transaction activity and history" }, { "name": "Transfers", "description": "Deposits and withdrawals" }, { "name": "PaymentRequests", "description": "Payment request management" }, { "name": "Approvals", "description": "Approval review" }, { "name": "Invitations", "description": "Party invitation management" }, { "name": "Parties", "description": "Party and organization management" }, { "name": "Wallets", "description": "Wallet management" }, { "name": "External Accounts", "description": "Linked external bank accounts" }, { "name": "External Parties", "description": "Third parties with whom you transact over Direct" }, { "name": "External Party Accounts", "description": "Banking details belonging to external parties not on Natural" }, { "name": "ACH", "description": "Make ACH payments to external party accounts" }, { "name": "Realtime", "description": "Make realtime payments to external party accounts" }, { "name": "Wire", "description": "Send domestic wires to external party accounts" }, { "name": "API Keys", "description": "API key management" }, { "name": "Agent Keys", "description": "Agent key management" }, { "name": "Card Sessions", "description": "Let agents pay with a card without seeing the real card number" }, { "name": "Agent Tokens", "description": "Let agents spend from a mandate without seeing the real card number" }, { "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": "Webhooks", "description": "Webhook endpoint management" }, { "name": "Events", "description": "Webhook event log" }, { "name": "Simulations", "description": "Sandbox-only simulation controls" } ] }