{ "x-generated-comment": "Generated API definition.", "components": { "schemas": { "AccessDecision": { "additionalProperties": false, "description": "Successful access check; HTTP 200 means your app may return the resource.", "properties": { "transaction_id": { "anyOf": [ { "examples": [ "txn_00000000000070008000000000000000" ], "pattern": "^txn_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "type": "string", "x-recuut-public-id-prefix": "txn" }, { "type": "null" } ], "description": "Payment transaction ID, or null when access is free.", "examples": [ "txn_00000000000070008000000000000000", null ], "title": "Transaction Id" } }, "required": [ "transaction_id" ], "title": "AccessDecision", "type": "object" }, "AccessRequest": { "additionalProperties": false, "description": "Resource details and reporting rules for one access check.", "properties": { "resource": { "$ref": "#/components/schemas/AccessResource", "description": "Details of the resource your app plans to return after access is allowed." }, "revision_id": { "description": "ID of the published reporting rules for this resource. A published revision cannot change.", "examples": [ "acr_00000000000070008000000000000000" ], "pattern": "^acr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Revision Id", "type": "string", "x-recuut-public-id-prefix": "acr" }, "settlement_asset": { "$ref": "#/components/schemas/SettlementAsset", "description": "Settlement token selected by the published revision's Price." } }, "required": [ "revision_id", "resource", "settlement_asset" ], "title": "AccessRequest", "type": "object" }, "AccessResource": { "additionalProperties": false, "description": "Details of the resource your app returns after access is allowed.", "examples": [ { "description": "Generate a paid quarterly research report.", "mime_type": "application/json", "url": "https://merchant.example/reports/quarterly" } ], "properties": { "description": { "default": "", "description": "Optional description of what the payer receives.", "examples": [ "Generate a paid quarterly research report." ], "maxLength": 500, "title": "Description", "type": "string" }, "mime_type": { "description": "Content type returned by the resource, such as `application/json`. Use lowercase `type/subtype` text without a charset or other parameters.", "examples": [ "application/json" ], "maxLength": 255, "minLength": 3, "pattern": "^(?:application|audio|font|image|message|model|multipart|text|video|x-[a-z0-9][a-z0-9!#$&^_.+-]*)/[a-z0-9][a-z0-9!#$&^_.+-]*$", "title": "Mime Type", "type": "string" }, "url": { "description": "Full HTTP or HTTPS URL of the resource. Do not include a username, password, query string, or `#` fragment.", "examples": [ "https://merchant.example/reports/quarterly" ], "format": "uri", "maxLength": 2048, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url", "mime_type" ], "title": "AccessResource", "type": "object" }, "ApiErrorCode": { "enum": [ "forbidden", "internal_error", "invalid_request", "unauthenticated" ], "title": "ApiErrorCode", "type": "string" }, "ApiErrorSchema": { "additionalProperties": false, "description": "Stable error response for API requests.", "properties": { "code": { "$ref": "#/components/schemas/ApiErrorCode", "description": "Machine-readable error code." }, "message": { "description": "Human-readable explanation of the error.", "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "ApiErrorSchema", "type": "object" }, "AtomicAmount": { "description": "Non-negative amount in the payment asset's smallest unit.", "examples": [ "1000000" ], "pattern": "^(?:0|[1-9][0-9]{0,29})$", "type": "string" }, "CompleteRequest": { "description": "Report whether your app finished the protected work or failed.", "discriminator": { "mapping": { "failed": "#/components/schemas/FailedCompleteRequest", "succeeded": "#/components/schemas/SucceededCompleteRequest" }, "propertyName": "outcome" }, "oneOf": [ { "$ref": "#/components/schemas/SucceededCompleteRequest" }, { "$ref": "#/components/schemas/FailedCompleteRequest" } ], "title": "CompleteRequest" }, "CompletionResult": { "additionalProperties": false, "description": "Result of finishing work and attempting its payment.", "properties": { "payment_response": { "anyOf": [ { "$ref": "#/components/schemas/PaymentResponse" }, { "type": "null" } ], "description": "Base64 JSON proof for a successful payment. It is null until payment succeeds. The decoded receipt is also available in `receipt`. [See the decoded fields.](/guides/concepts/x402-payment-retry/#what-the-encoded-headers-contain)" }, "receipt": { "anyOf": [ { "$ref": "#/components/schemas/ReceiptDocument" }, { "type": "null" } ], "description": "Checked receipt for a successful payment, or null until payment succeeds." }, "status": { "description": "Current result: `succeeded` means payment finished; `failed` means the app's work failed; `settling` or `reconciling` means payment is still being checked.", "enum": [ "settling", "reconciling", "failed", "succeeded" ], "examples": [ "succeeded" ], "title": "Status", "type": "string" }, "transaction_hash": { "anyOf": [ { "$ref": "#/components/schemas/TransactionHash" }, { "type": "null" } ], "description": "Transaction hash from the payment network, or null until payment succeeds." }, "transaction_id": { "description": "ID of the transaction that Recuut tried to finish.", "examples": [ "txn_00000000000070008000000000000000" ], "pattern": "^txn_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Transaction Id", "type": "string", "x-recuut-public-id-prefix": "txn" } }, "required": [ "transaction_id", "status", "payment_response", "transaction_hash", "receipt" ], "title": "CompletionResult", "type": "object" }, "ContractComponentsSchema": { "additionalProperties": false, "description": "Reusable contract schemas and their authentication scheme.", "properties": { "schemas": { "additionalProperties": { "$ref": "#/components/schemas/ContractRevisionSchema" }, "description": "Active contract revisions keyed by their exact x-recuut-revision-id value.", "propertyNames": { "examples": [ "acr_00000000000070008000000000000000" ], "pattern": "^acr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "x-recuut-public-id-prefix": "acr" }, "title": "Schemas", "type": "object" }, "securitySchemes": { "additionalProperties": { "$ref": "#/components/schemas/MerchantApiSecuritySchemeSchema" }, "description": "Authentication schemes for contracts.", "propertyNames": { "const": "merchantApiKey" }, "title": "Securityschemes", "type": "object" } }, "required": [ "securitySchemes", "schemas" ], "title": "ContractComponentsSchema", "type": "object" }, "ContractInfoSchema": { "additionalProperties": false, "description": "Metadata for the generated runtime contract document.", "properties": { "title": { "description": "Contract document title.", "title": "Title", "type": "string" }, "version": { "description": "Contract document version.", "pattern": "^\\d+(?:\\.\\d+){0,2}$", "title": "Version", "type": "string" } }, "required": [ "title", "version" ], "title": "ContractInfoSchema", "type": "object" }, "ContractListFilters": { "additionalProperties": false, "properties": { "include_integration_key": { "default": false, "description": "Include cross-environment Resource and revision correlation keys. Generated SDKs request this metadata explicitly.", "title": "Include Integration Key", "type": "boolean" } }, "title": "ContractListFilters", "type": "object" }, "ContractPathItemSchema": { "additionalProperties": false, "description": "Empty path entry. This document contains reporting rules, not API routes.", "properties": {}, "title": "ContractPathItemSchema", "type": "object" }, "ContractRevisionSchema": { "additionalProperties": false, "description": "Fixed reporting rules for one published resource version.", "properties": { "additionalProperties": { "const": false, "description": "Do not accept values that these reporting rules do not name.", "title": "Additionalproperties", "type": "boolean" }, "properties": { "additionalProperties": { "$ref": "#/components/schemas/ContractValueSchema" }, "description": "Values your app may report for this published version.", "propertyNames": { "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]+(?:[-_][a-z0-9]+)*$" }, "title": "Properties", "type": "object" }, "required": { "description": "Names of every value your app must report.", "items": { "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]+(?:[-_][a-z0-9]+)*$", "type": "string" }, "title": "Required", "type": "array" }, "title": { "description": "Contract revision display title.", "title": "Title", "type": "string" }, "type": { "const": "object", "description": "JSON Schema root type.", "title": "Type", "type": "string" }, "x-recuut-resource-description": { "description": "Protected resource description.", "title": "X-Recuut-Resource-Description", "type": "string" }, "x-recuut-resource-id": { "description": "Protected resource identifier.", "examples": [ "res_00000000000070008000000000000000" ], "pattern": "^res_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "X-Recuut-Resource-Id", "type": "string", "x-recuut-public-id-prefix": "res" }, "x-recuut-resource-integration-key": { "anyOf": [ { "maxLength": 100, "minLength": 1, "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$", "type": "string" }, { "type": "null" } ], "description": "Environment-local integration key shared by related Resources. Returned when include_integration_key is requested.", "title": "X-Recuut-Resource-Integration-Key" }, "x-recuut-resource-name": { "description": "Protected resource display name.", "title": "X-Recuut-Resource-Name", "type": "string" }, "x-recuut-revision-id": { "description": "Stable revision identifier.", "examples": [ "acr_00000000000070008000000000000000" ], "pattern": "^acr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "X-Recuut-Revision-Id", "type": "string", "x-recuut-public-id-prefix": "acr" }, "x-recuut-revision-key": { "anyOf": [ { "examples": [ "rvk_00000000000070008000000000000000" ], "pattern": "^rvk_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "type": "string", "x-recuut-public-id-prefix": "rvk" }, { "type": "null" } ], "description": "Cross-environment revision correlation key. Returned when include_integration_key is requested.", "title": "X-Recuut-Revision-Key" }, "x-recuut-revision-name": { "description": "Revision display name.", "title": "X-Recuut-Revision-Name", "type": "string" }, "x-recuut-revision-number": { "description": "Monotonic revision number.", "minimum": 1, "title": "X-Recuut-Revision-Number", "type": "integer" }, "x-recuut-settlement-asset": { "$ref": "#/components/schemas/ContractSettlementAsset", "description": "Settlement token selected by this revision's published Price." } }, "required": [ "title", "type", "additionalProperties", "properties", "required", "x-recuut-settlement-asset", "x-recuut-revision-id", "x-recuut-revision-number", "x-recuut-revision-name", "x-recuut-resource-id", "x-recuut-resource-name", "x-recuut-resource-description" ], "title": "ContractRevisionSchema", "type": "object" }, "ContractSettlementAsset": { "enum": [ "EURC", "USDC" ], "type": "string" }, "ContractValueSchema": { "additionalProperties": false, "description": "One value your app must report after it runs, such as tokens used.", "properties": { "description": { "description": "Meaning of the reported value.", "title": "Description", "type": "string" }, "format": { "const": "decimal", "description": "Recuut decimal string format.", "title": "Format", "type": "string" }, "pattern": { "const": "^(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{1,12})?$", "description": "Pattern for a positive decimal value or zero.", "title": "Pattern", "type": "string" }, "type": { "const": "string", "description": "JSON value type.", "title": "Type", "type": "string" }, "x-recuut-decimal-places": { "const": 12, "description": "Required generated-model scale: exactly 12 decimal places.", "title": "X-Recuut-Decimal-Places", "type": "integer" }, "x-recuut-label": { "description": "Merchant-facing value label.", "title": "X-Recuut-Label", "type": "string" }, "x-recuut-max-digits": { "const": 30, "description": "Required generated-model precision: exactly 30 total digits.", "title": "X-Recuut-Max-Digits", "type": "integer" }, "x-recuut-position": { "description": "Stable display order.", "exclusiveMaximum": 100, "minimum": 0, "title": "X-Recuut-Position", "type": "integer" }, "x-recuut-unit": { "description": "Unit attached to the reported quantity.", "title": "X-Recuut-Unit", "type": "string" } }, "required": [ "type", "format", "pattern", "description", "x-recuut-label", "x-recuut-unit", "x-recuut-position", "x-recuut-max-digits", "x-recuut-decimal-places" ], "title": "ContractValueSchema", "type": "object" }, "ContractsDocumentSchema": { "additionalProperties": false, "description": "OpenAPI document containing active resource reporting rules.", "properties": { "components": { "$ref": "#/components/schemas/ContractComponentsSchema", "description": "Contract schemas and security scheme." }, "info": { "$ref": "#/components/schemas/ContractInfoSchema", "description": "Contract document metadata." }, "openapi": { "const": "3.1.0", "description": "OpenAPI document version.", "title": "Openapi", "type": "string" }, "paths": { "additionalProperties": { "$ref": "#/components/schemas/ContractPathItemSchema" }, "description": "Reserved path map; contract discovery exposes schemas only.", "propertyNames": { "minLength": 1, "pattern": "^/" }, "title": "Paths", "type": "object" }, "security": { "description": "Authentication required to use protected resources.", "items": { "$ref": "#/components/schemas/MerchantApiSecurityRequirementSchema" }, "title": "Security", "type": "array" } }, "required": [ "openapi", "info", "paths", "components", "security" ], "title": "ContractsDocumentSchema", "type": "object" }, "Currency": { "enum": [ "EUR", "USD" ], "title": "Currency", "type": "string" }, "EvmAddress": { "pattern": "^0x[0-9a-fA-F]{40}$", "type": "string" }, "FailedCompleteRequest": { "additionalProperties": false, "description": "Tell Recuut that your app could not finish the work.", "properties": { "failure_code": { "description": "Short reason code chosen by your app, such as `upstream_timeout`. Do not include secrets or a message for an end user.", "pattern": "^[A-Za-z0-9._:-]{1,100}$", "title": "Failure Code", "type": "string" }, "outcome": { "const": "failed", "description": "Use `failed` when your app could not finish the work.", "title": "Outcome", "type": "string" }, "resource_execution": { "anyOf": [ { "$ref": "#/components/schemas/ResourceExecutionMetadata" }, { "type": "null" } ], "description": "Safe response metadata collected by your app. Response headers and body content are not accepted." }, "revision_id": { "description": "ID of the published reporting rules used for this work.", "examples": [ "acr_00000000000070008000000000000000" ], "pattern": "^acr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Revision Id", "type": "string", "x-recuut-public-id-prefix": "acr" } }, "required": [ "revision_id", "outcome", "failure_code" ], "title": "FailedCompleteRequest", "type": "object" }, "ListOrder": { "description": "Show records from newest to oldest, or oldest to newest.", "enum": [ "newest", "oldest" ], "title": "ListOrder", "type": "string" }, "MerchantApiSecurityRequirementSchema": { "additionalProperties": false, "description": "Security requirement applied to runtime contracts.", "properties": { "merchantApiKey": { "description": "Required Merchant API key scopes.", "items": { "minLength": 1, "type": "string" }, "title": "Merchantapikey", "type": "array" } }, "required": [ "merchantApiKey" ], "title": "MerchantApiSecurityRequirementSchema", "type": "object" }, "MerchantApiSecuritySchemeSchema": { "additionalProperties": false, "description": "Bearer API-key scheme used by generated contract documents.", "properties": { "scheme": { "const": "bearer", "description": "HTTP bearer authentication scheme.", "title": "Scheme", "type": "string" }, "type": { "const": "http", "description": "OpenAPI security scheme type.", "title": "Type", "type": "string" } }, "required": [ "type", "scheme" ], "title": "MerchantApiSecuritySchemeSchema", "type": "object" }, "NetworkIdentifier": { "maxLength": 100, "pattern": "^[a-z0-9]+:[A-Za-z0-9_-]+$", "type": "string" }, "NextPageUrl": { "description": "URL for the next page. Follow it unchanged because it already includes the same time marker and filters.", "examples": [ "/merchant/v1/transactions?as_of=2026-08-12T09%3A30%3A00Z&page=2&page_size=50" ], "format": "uri-reference", "minLength": 1, "pattern": "^/", "type": "string" }, "PageNumber": { "description": "Page number to return. The first page is 1.", "minimum": 1, "type": "integer" }, "PageSize": { "description": "Number of items to return on each page. Use 1 through 100.", "maximum": 100, "minimum": 1, "type": "integer" }, "PagedPayerSchema": { "additionalProperties": false, "properties": { "as_of": { "$ref": "#/components/schemas/SnapshotTimestamp" }, "count": { "description": "Total number of records in this unchanged list.", "minimum": 0, "title": "Count", "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/PayerSchema" }, "title": "Items", "type": "array" }, "next": { "anyOf": [ { "$ref": "#/components/schemas/NextPageUrl" }, { "type": "null" } ], "description": "URL for the next page, or null after the final page." } }, "required": [ "items", "count", "as_of", "next" ], "title": "PagedPayerSchema", "type": "object" }, "PagedResourceSchema": { "additionalProperties": false, "properties": { "as_of": { "$ref": "#/components/schemas/SnapshotTimestamp" }, "count": { "description": "Total number of records in this unchanged list.", "minimum": 0, "title": "Count", "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/ResourceSchema" }, "title": "Items", "type": "array" }, "next": { "anyOf": [ { "$ref": "#/components/schemas/NextPageUrl" }, { "type": "null" } ], "description": "URL for the next page, or null after the final page." } }, "required": [ "items", "count", "as_of", "next" ], "title": "PagedResourceSchema", "type": "object" }, "PagedTransactionSchema": { "additionalProperties": false, "properties": { "as_of": { "$ref": "#/components/schemas/SnapshotTimestamp" }, "count": { "description": "Total number of records in this unchanged list.", "minimum": 0, "title": "Count", "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/TransactionSchema" }, "title": "Items", "type": "array" }, "next": { "anyOf": [ { "$ref": "#/components/schemas/NextPageUrl" }, { "type": "null" } ], "description": "URL for the next page, or null after the final page." } }, "required": [ "items", "count", "as_of", "next" ], "title": "PagedTransactionSchema", "type": "object" }, "PayerAddress": { "description": "Blockchain address of the payer.", "examples": [ "0x1111111111111111111111111111111111111111" ], "pattern": "^0x[0-9a-fA-F]{40}$", "type": "string" }, "PayerIdentifier": { "maxLength": 255, "minLength": 1, "type": "string" }, "PayerListFilters": { "additionalProperties": false, "properties": { "as_of": { "description": "Stable snapshot timestamp for this page sequence. Include a timezone; future timestamps are rejected.", "format": "date-time", "title": "As Of", "type": "string" } }, "title": "PayerListFilters", "type": "object" }, "PayerSchema": { "additionalProperties": false, "description": "Payer activity in this account's test or live data.", "properties": { "created_at": { "description": "When this payer was first observed.", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Recuut ID for this payer.", "examples": [ "pyr_00000000000070008000000000000000" ], "pattern": "^pyr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Id", "type": "string", "x-recuut-public-id-prefix": "pyr" }, "identifier": { "$ref": "#/components/schemas/PayerIdentifier", "description": "Payer address or identifier, stored in a consistent form." }, "last_transaction_at": { "description": "Time of the payer's most recent transaction.", "format": "date-time", "title": "Last Transaction At", "type": "string" } }, "required": [ "id", "identifier", "last_transaction_at", "created_at" ], "title": "PayerSchema", "type": "object" }, "PaymentApiErrorSchema": { "additionalProperties": false, "description": "Stable payment API error response.", "properties": { "code": { "anyOf": [ { "$ref": "#/components/schemas/PaymentErrorCode" }, { "$ref": "#/components/schemas/ApiErrorCode" } ], "description": "Machine-readable error code.", "title": "Code" }, "message": { "description": "Human-readable explanation of the error.", "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "PaymentApiErrorSchema", "type": "object" }, "PaymentErrorCode": { "enum": [ "payments_not_configured", "live_payments_not_enabled", "payment_rate_limited", "payment_required", "facilitator_unavailable", "invalid_authorization", "invalid_payment_signature", "payment_signature_required", "payment_signature_mismatch", "payment_request_failed", "payment_request_missing", "payment_request_not_found", "payment_request_mismatch", "payment_request_expired", "payment_request_succeeded", "payment_requirements_mismatch", "payment_request_in_progress", "payment_attempt_conflict", "transaction_not_found", "transaction_state_conflict", "resource_execution_not_found", "resource_execution_conflict", "revision_not_found", "revision_unavailable", "revision_mismatch", "completion_conflict", "invalid_values", "contract_values_mismatch", "maximum_exceeded", "price_not_found", "price_not_supported", "currency_conversion_disabled" ], "title": "PaymentErrorCode", "type": "string" }, "PaymentResponse": { "contentEncoding": "base64", "contentMediaType": "application/json", "description": "Base64 JSON proof returned after a successful x402 payment. [See the decoded fields.](/guides/concepts/x402-payment-retry/#what-the-encoded-headers-contain)", "examples": [ "eyJhbW91bnQiOiIxMDAwMDAwIiwiZXJyb3JSZWFzb24iOm51bGwsImV4dGVuc2lvbnMiOnsicmVjdXV0LXJlY2VpcHQiOnsiZW52aXJvbm1lbnQiOiJ0ZXN0IiwiZW52aXJvbm1lbnRfa2V5IjoidGVzdCIsImlkIjoicmN0XzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwiaXNzdWVkX2F0IjoiMjAyNi0wOC0xMlQwOTozMDowMC4wMDBaIiwicGF5bWVudCI6eyJhc3NldCI6IlVTREMiLCJhc3NldF9pZCI6IjB4MzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMyIsImF1dGhvcml6ZWRfYXRvbWljIjoiMTAwMDAwMCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwYXllciI6IjB4MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMSIsInJlY2lwaWVudCI6IjB4MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMiIsInNjaGVtZSI6ImV4YWN0Iiwic2V0dGxlZF9hdG9taWMiOiIxMDAwMDAwIiwidHJhbnNhY3Rpb25faGFzaCI6IjB4YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYSJ9LCJwcmljZSI6eyJjYWxjdWxhdGlvbl9tb2RlIjoiZml4ZWQiLCJjdXJyZW5jeSI6IlVTRCIsImlkIjoicHJjXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwibGFiZWwiOiJRdWFydGVybHkgcmVwb3J0IGFjY2VzcyJ9LCJyZXNvdXJjZSI6eyJpZCI6InJlc18wMDAwMDAwMDAwMDA3MDAwODAwMDAwMDAwMDAwMDAwMCIsIm5hbWUiOiJRdWFydGVybHkgcmVwb3J0IiwidXJsIjoiaHR0cHM6Ly9tZXJjaGFudC5leGFtcGxlL3JlcG9ydHMvcXVhcnRlcmx5In0sInNjaGVtYV92ZXJzaW9uIjoyLCJzZWxsZXIiOnsiaWQiOiJvcmdfMDAwMDAwMDAwMDAwNzAwMDgwMDAwMDAwMDAwMDAwMDAiLCJuYW1lIjoiQWNtZSBSZXNlYXJjaCJ9LCJ0cmFuc2FjdGlvbl9pZCI6InR4bl8wMDAwMDAwMDAwMDA3MDAwODAwMDAwMDAwMDAwMDAwMCJ9fSwibmV0d29yayI6ImVpcDE1NTo4NDUzMiIsInBheWVyIjoiMHgxMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExIiwic3VjY2VzcyI6dHJ1ZSwidHJhbnNhY3Rpb24iOiIweGFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWEifQ==" ], "minLength": 4, "type": "string" }, "PaymentScheme": { "enum": [ "exact", "upto" ], "type": "string" }, "PaymentSignature": { "contentEncoding": "base64", "contentMediaType": "application/json", "description": "Payment proof created by the payer. Forward this base64 text unchanged. [See the decoded fields](/guides/concepts/x402-payment-retry/#what-the-encoded-headers-contain).", "examples": [ "eyJhY2NlcHRlZCI6eyJhbW91bnQiOiIxMDAwIiwiYXNzZXQiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJleHRyYSI6eyJuYW1lIjoiVVNEQyIsInZlcnNpb24iOiIyIn0sIm1heFRpbWVvdXRTZWNvbmRzIjozMDAsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwYXlUbyI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInNjaGVtZSI6ImV4YWN0In0sImV4dGVuc2lvbnMiOnsicmVjdXV0LXBheW1lbnQtcmVxdWVzdCI6eyJpbmZvIjp7ImlkIjoicHJxXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIn0sInNjaGVtYSI6eyJyZXF1aXJlZCI6WyJpZCJdLCJ0eXBlIjoib2JqZWN0In19fSwicGF5bG9hZCI6eyJhdXRob3JpemF0aW9uIjp7ImZyb20iOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJub25jZSI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInRvIjoiMHgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIiwidmFsaWRBZnRlciI6IjAiLCJ2YWxpZEJlZm9yZSI6IjQxMDI0NDQ4MDAiLCJ2YWx1ZSI6IjEwMDAifX0sInJlc291cmNlIjp7ImRlc2NyaXB0aW9uIjoiR2VuZXJhdGUgcGFpZCB0ZXh0LiIsIm1pbWVUeXBlIjoiYXBwbGljYXRpb24vanNvbiIsInVybCI6Imh0dHBzOi8vbWVyY2hhbnQuZXhhbXBsZS9nZW5lcmF0ZSJ9LCJ4NDAyVmVyc2lvbiI6Mn0=" ], "minLength": 4, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$", "title": "PaymentSignature", "type": "string" }, "ReceiptDocument": { "additionalProperties": false, "description": "Permanent record of one successful payment.", "properties": { "environment": { "description": "Test or live payment environment.", "enum": [ "test", "live" ], "title": "Environment", "type": "string" }, "environment_key": { "anyOf": [ { "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "type": "string" }, { "type": "null" } ], "description": "Immutable organization environment key for version 2 receipts.", "title": "Environment Key" }, "id": { "description": "Stable receipt identifier.", "examples": [ "rct_00000000000070008000000000000000" ], "pattern": "^rct_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Id", "type": "string", "x-recuut-public-id-prefix": "rct" }, "issued_at": { "description": "UTC settlement time represented by this receipt.", "format": "date-time", "title": "Issued At", "type": "string" }, "payment": { "$ref": "#/components/schemas/ReceiptPayment", "description": "Payment network and amount details." }, "price": { "$ref": "#/components/schemas/ReceiptPrice", "description": "Price facts at settlement time." }, "resource": { "$ref": "#/components/schemas/ReceiptResource", "description": "Resource facts at settlement time." }, "schema_version": { "anyOf": [ { "const": 1, "type": "integer" }, { "const": 2, "type": "integer" } ], "description": "Receipt contract version.", "title": "Schema Version" }, "seller": { "$ref": "#/components/schemas/ReceiptSeller", "description": "Seller facts at settlement time." }, "transaction_id": { "description": "Transaction represented by this receipt.", "examples": [ "txn_00000000000070008000000000000000" ], "pattern": "^txn_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Transaction Id", "type": "string", "x-recuut-public-id-prefix": "txn" } }, "required": [ "schema_version", "id", "issued_at", "transaction_id", "environment", "seller", "resource", "price", "payment" ], "title": "ReceiptDocument", "type": "object" }, "ReceiptPayment": { "additionalProperties": false, "description": "Settlement-rail evidence fixed at settlement time.", "properties": { "asset": { "$ref": "#/components/schemas/SettlementAssetSymbol", "description": "Settlement asset symbol." }, "asset_id": { "$ref": "#/components/schemas/EvmAddress", "description": "Settlement asset contract address." }, "authorized_atomic": { "$ref": "#/components/schemas/AtomicAmount", "description": "Authorized amount in the payment asset's smallest unit." }, "network": { "$ref": "#/components/schemas/NetworkIdentifier", "description": "Settlement network identifier." }, "payer": { "$ref": "#/components/schemas/PayerAddress", "description": "Payer address." }, "recipient": { "$ref": "#/components/schemas/RecipientAddress", "description": "Settlement recipient address." }, "scheme": { "$ref": "#/components/schemas/PaymentScheme", "description": "Payment protocol scheme." }, "settled_atomic": { "$ref": "#/components/schemas/AtomicAmount", "description": "Paid amount in the payment asset's smallest unit." }, "transaction_hash": { "$ref": "#/components/schemas/TransactionHash", "description": "Settlement transaction hash." } }, "required": [ "scheme", "network", "asset", "asset_id", "authorized_atomic", "settled_atomic", "payer", "recipient", "transaction_hash" ], "title": "ReceiptPayment", "type": "object" }, "ReceiptPrice": { "additionalProperties": false, "description": "Price identity and calculation policy fixed at settlement time.", "properties": { "calculation_mode": { "description": "How the settled amount was calculated.", "enum": [ "fixed", "output_based" ], "title": "Calculation Mode", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currency", "description": "Three-letter settlement currency." }, "id": { "description": "Price identifier.", "examples": [ "prc_00000000000070008000000000000000" ], "pattern": "^prc_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Id", "type": "string", "x-recuut-public-id-prefix": "prc" }, "label": { "description": "Price display label.", "maxLength": 255, "minLength": 1, "title": "Label", "type": "string" } }, "required": [ "id", "label", "currency", "calculation_mode" ], "title": "ReceiptPrice", "type": "object" }, "ReceiptResource": { "additionalProperties": false, "description": "Protected resource identity fixed at settlement time.", "properties": { "id": { "description": "Protected resource identifier.", "examples": [ "res_00000000000070008000000000000000" ], "pattern": "^res_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Id", "type": "string", "x-recuut-public-id-prefix": "res" }, "name": { "description": "Protected resource name.", "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "url": { "description": "Protected resource URL.", "format": "uri", "maxLength": 2048, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "id", "name", "url" ], "title": "ReceiptResource", "type": "object" }, "ReceiptSeller": { "additionalProperties": false, "description": "Seller identity fixed at settlement time.", "properties": { "id": { "description": "Seller organization identifier.", "examples": [ "org_00000000000070008000000000000000" ], "pattern": "^org_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Id", "type": "string", "x-recuut-public-id-prefix": "org" }, "name": { "description": "Seller display name.", "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "id", "name" ], "title": "ReceiptSeller", "type": "object" }, "RecipientAddress": { "description": "Blockchain address that receives the payment.", "examples": [ "0x2222222222222222222222222222222222222222" ], "pattern": "^0x[0-9a-fA-F]{40}$", "type": "string" }, "ResourceExecutionCompleteRequest": { "additionalProperties": false, "description": "Attach safe response metadata to one free protected-resource execution.", "properties": { "resource_execution": { "$ref": "#/components/schemas/ResourceExecutionMetadata", "description": "Safe response metadata collected by your app. Response headers and body content are not accepted." }, "revision_id": { "description": "ID of the published reporting rules used for this work.", "examples": [ "acr_00000000000070008000000000000000" ], "pattern": "^acr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Revision Id", "type": "string", "x-recuut-public-id-prefix": "acr" } }, "required": [ "revision_id", "resource_execution" ], "title": "ResourceExecutionCompleteRequest", "type": "object" }, "ResourceExecutionCompleteResult": { "additionalProperties": false, "description": "The free resource execution that accepted this completion.", "properties": { "resource_execution_id": { "description": "Resource execution whose response metadata is retained.", "examples": [ "rex_00000000000070008000000000000000" ], "pattern": "^rex_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Resource Execution Id", "type": "string", "x-recuut-public-id-prefix": "rex" } }, "required": [ "resource_execution_id" ], "title": "ResourceExecutionCompleteResult", "type": "object" }, "ResourceExecutionMetadata": { "additionalProperties": false, "description": "Allowlisted facts about one protected resource response.", "properties": { "duration_ms": { "maximum": 2147483647, "minimum": 0, "title": "Duration Ms", "type": "integer" }, "response_content_type": { "anyOf": [ { "maxLength": 255, "minLength": 3, "pattern": "^(?:application|audio|font|image|message|model|multipart|text|video|x-[a-z0-9][a-z0-9!#$&^_.+-]*)/[a-z0-9][a-z0-9!#$&^_.+-]*$", "type": "string" }, { "type": "null" } ], "title": "Response Content Type" }, "response_size_bytes": { "anyOf": [ { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, { "type": "null" } ], "title": "Response Size Bytes" }, "response_status": { "maximum": 599, "minimum": 100, "title": "Response Status", "type": "integer" } }, "required": [ "response_status", "duration_ms" ], "title": "ResourceExecutionMetadata", "type": "object" }, "ResourceListFilters": { "additionalProperties": false, "properties": { "archived": { "default": false, "description": "Return archived resources instead of active resources.", "title": "Archived", "type": "boolean" }, "as_of": { "description": "Stable snapshot timestamp for this page sequence. Include a timezone; future timestamps are rejected.", "format": "date-time", "title": "As Of", "type": "string" } }, "title": "ResourceListFilters", "type": "object" }, "ResourceSchema": { "additionalProperties": false, "description": "Resource in this Recuut account.", "properties": { "created_at": { "description": "When the resource was created.", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "description": "Merchant-facing resource description.", "title": "Description", "type": "string" }, "id": { "description": "Stable protected-resource identifier.", "examples": [ "res_00000000000070008000000000000000" ], "pattern": "^res_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Id", "type": "string", "x-recuut-public-id-prefix": "res" }, "image_url": { "anyOf": [ { "type": "string" }, { "const": "", "type": "string" } ], "description": "Optional HTTP(S) display image URL. An empty string means this resource has no image.", "examples": [ "https://merchant.example/images/quarterly-report.png", "" ], "title": "Image Url" }, "name": { "description": "Merchant-facing resource name.", "title": "Name", "type": "string" }, "updated_at": { "description": "When the resource was last updated.", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "name", "description", "image_url", "created_at", "updated_at" ], "title": "ResourceSchema", "type": "object" }, "SettlementAsset": { "enum": [ "USDC", "EURC" ], "title": "SettlementAsset", "type": "string" }, "SettlementAssetSymbol": { "enum": [ "USDC", "EURC" ], "type": "string" }, "SnapshotTimestamp": { "description": "Time marker that keeps list pages unchanged. Omit it on the first request. Reuse the returned value on later pages.", "examples": [ "2026-08-12T09:30:00Z" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$", "type": "string" }, "SucceededCompleteRequest": { "additionalProperties": false, "description": "Tell Recuut that your app finished the work successfully.", "properties": { "outcome": { "const": "succeeded", "description": "Use `succeeded` when your app finished the work.", "title": "Outcome", "type": "string" }, "resource_execution": { "anyOf": [ { "$ref": "#/components/schemas/ResourceExecutionMetadata" }, { "type": "null" } ], "description": "Safe response metadata collected by your app. Response headers and body content are not accepted." }, "revision_id": { "description": "ID of the published reporting rules used for this work.", "examples": [ "acr_00000000000070008000000000000000" ], "pattern": "^acr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Revision Id", "type": "string", "x-recuut-public-id-prefix": "acr" }, "values": { "additionalProperties": { "pattern": "^(?:0|[1-9]\\d{0,17})(?:\\.\\d{1,12})?$", "type": "string" }, "description": "Values measured by your app. Include every value named by the published revision, and do not add other values.", "propertyNames": { "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]+(?:[-_][a-z0-9]+)*$" }, "title": "Values", "type": "object" } }, "required": [ "revision_id", "outcome", "values" ], "title": "SucceededCompleteRequest", "type": "object" }, "Timestamp": { "description": "UTC date and time in RFC 3339 format.", "examples": [ "2026-08-12T09:30:00Z" ], "format": "date-time", "type": "string" }, "TransactionDetailSchema": { "additionalProperties": false, "description": "Transaction details, with a receipt after successful payment.", "properties": { "authorized_at": { "anyOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ], "description": "When payment authorization completed, when applicable." }, "authorized_atomic": { "anyOf": [ { "$ref": "#/components/schemas/AtomicAmount" }, { "type": "null" } ], "description": "Authorized amount in the payment asset's smallest unit." }, "created_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the transaction was created." }, "id": { "description": "ID of this transaction.", "examples": [ "txn_00000000000070008000000000000000" ], "pattern": "^txn_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Id", "type": "string", "x-recuut-public-id-prefix": "txn" }, "payer": { "anyOf": [ { "$ref": "#/components/schemas/PayerAddress" }, { "type": "null" } ], "description": "Payer address, when known." }, "payment_request_id": { "description": "ID of the payment request that created this transaction.", "examples": [ "prq_00000000000070008000000000000000" ], "pattern": "^prq_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Payment Request Id", "type": "string", "x-recuut-public-id-prefix": "prq" }, "receipt": { "anyOf": [ { "$ref": "#/components/schemas/ReceiptDocument" }, { "type": "null" } ], "description": "Receipt for a payment that finished successfully." }, "settled_at": { "anyOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ], "description": "When settlement completed, when applicable." }, "settled_atomic": { "anyOf": [ { "$ref": "#/components/schemas/AtomicAmount" }, { "type": "null" } ], "description": "Paid amount in the payment asset's smallest unit." }, "status": { "$ref": "#/components/schemas/TransactionStatus", "description": "Current payment status." }, "transaction_hash": { "anyOf": [ { "$ref": "#/components/schemas/TransactionHash" }, { "type": "null" } ], "description": "Transaction hash from the payment network, when available." } }, "required": [ "id", "payment_request_id", "status", "payer", "transaction_hash", "authorized_atomic", "settled_atomic", "created_at", "authorized_at", "settled_at", "receipt" ], "title": "TransactionDetailSchema", "type": "object" }, "TransactionHash": { "description": "Transaction hash issued by the payment network.", "examples": [ "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ], "pattern": "^0x[0-9a-fA-F]{64}$", "type": "string" }, "TransactionListFilters": { "additionalProperties": false, "properties": { "as_of": { "description": "Stable snapshot timestamp for this page sequence. Include a timezone; future timestamps are rejected.", "format": "date-time", "title": "As Of", "type": "string" }, "payer_id": { "anyOf": [ { "examples": [ "pyr_00000000000070008000000000000000" ], "pattern": "^pyr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "type": "string", "x-recuut-public-id-prefix": "pyr" }, { "type": "null" } ], "description": "Filter by server-issued payer identifier.", "title": "Payer Id" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/TransactionStatus" }, { "type": "null" } ], "description": "Filter by transaction lifecycle status." } }, "title": "TransactionListFilters", "type": "object" }, "TransactionSchema": { "additionalProperties": false, "description": "Summary of one payment transaction.", "properties": { "authorized_at": { "anyOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ], "description": "When payment authorization completed, when applicable." }, "authorized_atomic": { "anyOf": [ { "$ref": "#/components/schemas/AtomicAmount" }, { "type": "null" } ], "description": "Authorized amount in the payment asset's smallest unit." }, "created_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the transaction was created." }, "id": { "description": "ID of this transaction.", "examples": [ "txn_00000000000070008000000000000000" ], "pattern": "^txn_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Id", "type": "string", "x-recuut-public-id-prefix": "txn" }, "payer": { "anyOf": [ { "$ref": "#/components/schemas/PayerAddress" }, { "type": "null" } ], "description": "Payer address, when known." }, "payment_request_id": { "description": "ID of the payment request that created this transaction.", "examples": [ "prq_00000000000070008000000000000000" ], "pattern": "^prq_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Payment Request Id", "type": "string", "x-recuut-public-id-prefix": "prq" }, "settled_at": { "anyOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ], "description": "When settlement completed, when applicable." }, "settled_atomic": { "anyOf": [ { "$ref": "#/components/schemas/AtomicAmount" }, { "type": "null" } ], "description": "Paid amount in the payment asset's smallest unit." }, "status": { "$ref": "#/components/schemas/TransactionStatus", "description": "Current payment status." }, "transaction_hash": { "anyOf": [ { "$ref": "#/components/schemas/TransactionHash" }, { "type": "null" } ], "description": "Transaction hash from the payment network, when available." } }, "required": [ "id", "payment_request_id", "status", "payer", "transaction_hash", "authorized_atomic", "settled_atomic", "created_at", "authorized_at", "settled_at" ], "title": "TransactionSchema", "type": "object" }, "TransactionStatus": { "enum": [ "pending", "authorized", "settling", "reconciling", "succeeded", "failed" ], "title": "TransactionStatus", "type": "string" } }, "securitySchemes": { "OrganizationApiKeyAuth": { "bearerFormat": "Recuut API key", "description": "Private API key for your Recuut account. A `recuut_test_` key uses test payers and transactions. A `recuut_live_` key uses live data. Send this key only from your server.", "scheme": "bearer", "type": "http", "x-recuut-example": "recuut_test_key_00000000000070008000000000000000_0000000000000000000000000000000000000000000", "x-recuut-token-pattern": "^recuut_(?:test|live)_key_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}_[A-Za-z0-9_-]{43}$" } } }, "info": { "description": "Use this API to check payment before returning a protected resource, finish payments, and read resources, payers, and transactions. Send a private Recuut API key with every request. The key selects your account and either test or live data.", "title": "Recuut Merchant API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/merchant/v1/access": { "post": { "description": "Ask Recuut whether a client may receive a resource, such as an API response or digital item you sell. If payment is needed, Recuut returns HTTP 402 with instructions for the payer to retry.", "operationId": "payments.access", "parameters": [ { "description": "Payment proof created by the payer. Forward this base64 text unchanged. Leave it out on the first request. Include the payer's exact value when it retries after HTTP 402. [See the decoded fields](/guides/concepts/x402-payment-retry/#what-the-encoded-headers-contain).", "in": "header", "name": "PAYMENT-SIGNATURE", "required": false, "schema": { "$ref": "#/components/schemas/PaymentSignature" } } ], "requestBody": { "content": { "application/json": { "examples": { "authorize_resource": { "summary": "Authorize a published resource revision", "value": { "resource": { "description": "Generate a paid quarterly research report.", "mime_type": "application/json", "url": "https://merchant.example/reports/quarterly" }, "revision_id": "acr_00000000000070008000000000000000", "settlement_asset": "USDC" } } }, "schema": { "$ref": "#/components/schemas/AccessRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "free_access_allowed": { "description": "HTTP 200 means the merchant may serve the resource without payment.", "summary": "Free access allowed", "value": { "transaction_id": null } }, "paid_access_allowed": { "description": "HTTP 200 means the merchant may serve the resource after payment was authorized.", "summary": "Paid access allowed", "value": { "transaction_id": "txn_00000000000070008000000000000000" } } }, "schema": { "$ref": "#/components/schemas/AccessDecision" } } }, "description": "Access allowed.", "headers": { "RECUUT-RESOURCE-EXECUTION-ID": { "description": "Identifier for this allowed resource execution. New SDKs use it to report safe response metadata.", "required": true, "schema": { "examples": [ "rex_00000000000070008000000000000000" ], "pattern": "^rex_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "type": "string" } } } }, "400": { "content": { "application/json": { "examples": { "invalid_payment_signature": { "summary": "Malformed payment signature", "value": { "code": "invalid_payment_signature", "message": "PAYMENT-SIGNATURE is not valid base64-encoded JSON." } }, "payment_request_missing": { "summary": "Payment request missing", "value": { "code": "payment_request_missing", "message": "The payment request extension is missing." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "invalid_payment_signature", "payment_request_missing" ], "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "unauthenticated": { "summary": "API key required", "value": { "code": "unauthenticated", "message": "A valid Recuut API key is required." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "unauthenticated", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "examples": { "invalid_authorization": { "summary": "Authorization rejected", "value": { "code": "invalid_authorization", "message": "The payment authorization is invalid." } }, "payment_required": { "summary": "Payment required", "value": { "code": "payment_required", "message": "Payment authorization is required." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "invalid_authorization", "payment_required" ], "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Payment is required. Copy this JSON body and the PAYMENT-REQUIRED header unchanged to the payer.", "headers": { "PAYMENT-REQUIRED": { "description": "Payment instructions for the payer. Forward this base64 text unchanged after HTTP 402. [See the decoded fields](/guides/concepts/x402-payment-retry/#what-the-encoded-headers-contain).", "required": false, "schema": { "contentEncoding": "base64", "contentMediaType": "application/json", "examples": [ "eyJhY2NlcHRzIjpbeyJhbW91bnQiOiIxMDAwMCIsImFzc2V0IjoiMHgwMzZDYkQ1Mzg0MmM1NDI2NjM0ZTc5Mjk1NDFlQzIzMThmM2RDRjdlIiwiZXh0cmEiOnsibmFtZSI6IlVTREMiLCJ2ZXJzaW9uIjoiMiJ9LCJtYXhUaW1lb3V0U2Vjb25kcyI6MzAwLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMyIiwicGF5VG8iOiIweDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIiLCJzY2hlbWUiOiJleGFjdCJ9XSwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIiwiZXh0ZW5zaW9ucyI6eyJyZWN1dXQtcGF5bWVudC1yZXF1ZXN0Ijp7ImluZm8iOnsiaWQiOiJwcnFfMDAwMDAwMDAwMDAwNzAwMDgwMDAwMDAwMDAwMDAwMDAifSwic2NoZW1hIjp7InJlcXVpcmVkIjpbImlkIl0sInR5cGUiOiJvYmplY3QifX19LCJyZXNvdXJjZSI6eyJkZXNjcmlwdGlvbiI6IkdlbmVyYXRlIHBhaWQgdGV4dC4iLCJtaW1lVHlwZSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ1cmwiOiJodHRwczovL21lcmNoYW50LmV4YW1wbGUvZ2VuZXJhdGUifSwieDQwMlZlcnNpb24iOjJ9" ], "minLength": 1, "type": "string" } } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "Capability denied", "value": { "code": "forbidden", "message": "This API key does not allow this operation." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "forbidden", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "payment_request_not_found": { "summary": "Payment request not found", "value": { "code": "payment_request_not_found", "message": "The payment request is unknown." } }, "revision_not_found": { "summary": "Revision not found", "value": { "code": "revision_not_found", "message": "Published API revision not found." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "payment_request_not_found", "revision_not_found" ], "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "currency_conversion_disabled": { "summary": "Currency conversion unavailable", "value": { "code": "currency_conversion_disabled", "message": "Settlement in test USDC requires currency conversion, which this Price does not allow." } }, "payment_attempt_conflict": { "summary": "Payment attempt conflict", "value": { "code": "payment_attempt_conflict", "message": "This payment request was already consumed by another signed payload." } }, "payment_request_in_progress": { "summary": "Authorization in progress", "value": { "code": "payment_request_in_progress", "message": "Payment authorization is still being verified." } }, "payment_request_mismatch": { "summary": "Payment request mismatch", "value": { "code": "payment_request_mismatch", "message": "The payment request does not match this revision and API key." } }, "payment_request_succeeded": { "summary": "Payment request already succeeded", "value": { "code": "payment_request_succeeded", "message": "The payment request has already succeeded." } }, "payment_requirements_mismatch": { "summary": "Payment requirements mismatch", "value": { "code": "payment_requirements_mismatch", "message": "The signed payment requirements do not match the issued challenge." } }, "price_not_found": { "summary": "Price not found", "value": { "code": "price_not_found", "message": "The paid revision has no active Price." } }, "price_not_supported": { "summary": "Price not supported", "value": { "code": "price_not_supported", "message": "This Price is not supported for x402 payments." } }, "transaction_state_conflict": { "summary": "Transaction state conflict", "value": { "code": "transaction_state_conflict", "message": "The Transaction is no longer pending." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "currency_conversion_disabled", "payment_attempt_conflict", "payment_request_in_progress", "payment_request_mismatch", "payment_request_succeeded", "payment_requirements_mismatch", "price_not_found", "price_not_supported", "transaction_state_conflict" ], "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Conflict" }, "410": { "content": { "application/json": { "examples": { "payment_request_expired": { "summary": "Payment request expired", "value": { "code": "payment_request_expired", "message": "The payment request has expired." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "payment_request_expired", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Gone" }, "422": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Invalid request", "value": { "code": "invalid_request", "message": "The request is invalid." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "invalid_request", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unprocessable Content" }, "429": { "content": { "application/json": { "examples": { "payment_rate_limited": { "summary": "Payment rate limit exceeded", "value": { "code": "payment_rate_limited", "message": "The payment request rate limit was exceeded." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "payment_rate_limited", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before trying again.", "required": true, "schema": { "examples": [ 60 ], "maximum": 60, "minimum": 1, "type": "integer" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Internal error", "value": { "code": "internal_error", "message": "The request could not be completed." } }, "payment_request_failed": { "summary": "Challenge persistence failed", "value": { "code": "payment_request_failed", "message": "The payment challenge could not be recorded." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "internal_error", "payment_request_failed" ], "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "examples": { "facilitator_unavailable": { "summary": "Facilitator unavailable", "value": { "code": "facilitator_unavailable", "message": "A payment challenge could not be prepared." } }, "payment_request_failed": { "summary": "Invalid facilitator response", "value": { "code": "payment_request_failed", "message": "The facilitator returned invalid payment requirements." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "facilitator_unavailable", "payment_request_failed" ], "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "examples": { "live_payments_not_enabled": { "summary": "Live payments unavailable", "value": { "code": "live_payments_not_enabled", "message": "Paid live transactions are not enabled yet." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "live_payments_not_enabled", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [ { "OrganizationApiKeyAuth": [] } ], "summary": "Authorize resource access", "tags": [ "payments" ], "x-codeSamples": [ { "label": "cURL", "lang": "shell", "source": "curl --request POST \\\n --url \"$RECUUT_API_URL/merchant/v1/access\" \\\n --header \"Authorization: Bearer $RECUUT_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\"resource\":{\"description\":\"Generate a paid quarterly research report.\",\"mime_type\":\"application/json\",\"url\":\"https://merchant.example/reports/quarterly\"},\"revision_id\":\"acr_00000000000070008000000000000000\",\"settlement_asset\":\"USDC\"}'\n", "x-recuut-request-example": "authorize_resource" } ] } }, "/merchant/v1/contracts": { "get": { "description": "Returns each published revision, its settlement asset, and the usage values your app must report, in OpenAPI format. SDKs and tools use this response. The API key selects one environment; equivalent Resources may share the published integration key across environments.", "operationId": "resources.contracts.list", "parameters": [ { "description": "Include cross-environment Resource and revision correlation keys. Generated SDKs request this metadata explicitly.", "in": "query", "name": "include_integration_key", "required": false, "schema": { "default": false, "description": "Include cross-environment Resource and revision correlation keys. Generated SDKs request this metadata explicitly.", "title": "Include Integration Key", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "published_contracts": { "description": "One published revision keyed by the same revision ID used in the completion example.", "summary": "Published contracts", "value": { "components": { "schemas": { "acr_00000000000070008000000000000000": { "additionalProperties": false, "properties": { "input_tokens": { "description": "Number of input tokens consumed by the report.", "format": "decimal", "pattern": "^(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{1,12})?$", "type": "string", "x-recuut-decimal-places": 12, "x-recuut-label": "Input tokens", "x-recuut-max-digits": 30, "x-recuut-position": 0, "x-recuut-unit": "token" } }, "required": [ "input_tokens" ], "title": "Quarterly report usage", "type": "object", "x-recuut-resource-description": "Generate a paid quarterly research report.", "x-recuut-resource-id": "res_00000000000070008000000000000000", "x-recuut-resource-integration-key": "quarterly_report", "x-recuut-resource-name": "Quarterly report", "x-recuut-revision-id": "acr_00000000000070008000000000000000", "x-recuut-revision-key": "rvk_00000000000070008000000000000000", "x-recuut-revision-name": "Usage v1", "x-recuut-revision-number": 1, "x-recuut-settlement-asset": "USDC" } }, "securitySchemes": { "merchantApiKey": { "scheme": "bearer", "type": "http" } } }, "info": { "title": "Recuut resource contracts", "version": "1" }, "openapi": "3.1.0", "paths": {}, "security": [ { "merchantApiKey": [] } ] } } }, "schema": { "$ref": "#/components/schemas/ContractsDocumentSchema" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "unauthenticated": { "summary": "API key required", "value": { "code": "unauthenticated", "message": "A valid Recuut API key is required." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "unauthenticated", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "Capability denied", "value": { "code": "forbidden", "message": "This API key does not allow this operation." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "forbidden", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Forbidden" } }, "security": [ { "OrganizationApiKeyAuth": [] } ], "summary": "List access contracts", "tags": [ "contracts" ], "x-codeSamples": [ { "label": "cURL", "lang": "shell", "source": "curl --request GET \\\n --url \"$RECUUT_API_URL/merchant/v1/contracts\" \\\n --header \"Authorization: Bearer $RECUUT_API_KEY\"\n" } ] } }, "/merchant/v1/payers": { "get": { "description": "Returns the payers that used this Recuut account in test or live data. The `as_of` time keeps the list unchanged while you read later pages.", "operationId": "payments.payers.list", "parameters": [ { "description": "Stable snapshot timestamp for this page sequence. Include a timezone; future timestamps are rejected.", "in": "query", "name": "as_of", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotTimestamp" } }, { "description": "Show the newest or oldest records first.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder", "default": "newest" } }, { "description": "Page number to return. The first page is 1.", "in": "query", "name": "page", "required": false, "schema": { "$ref": "#/components/schemas/PageNumber", "default": 1 } }, { "description": "Number of items to return on each page. Use 1 through 100.", "in": "query", "name": "page_size", "required": false, "schema": { "$ref": "#/components/schemas/PageSize", "default": 50 } } ], "responses": { "200": { "content": { "application/json": { "examples": { "payer_page": { "summary": "Payer page", "value": { "as_of": "2026-08-12T09:30:00Z", "count": 1, "items": [ { "created_at": "2026-08-01T08:00:00Z", "id": "pyr_00000000000070008000000000000000", "identifier": "0x1111111111111111111111111111111111111111", "last_transaction_at": "2026-08-12T09:30:00Z" } ], "next": null } } }, "schema": { "$ref": "#/components/schemas/PagedPayerSchema" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "unauthenticated": { "summary": "API key required", "value": { "code": "unauthenticated", "message": "A valid Recuut API key is required." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "unauthenticated", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "Capability denied", "value": { "code": "forbidden", "message": "This API key does not allow this operation." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "forbidden", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Invalid request", "value": { "code": "invalid_request", "message": "The request is invalid." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "invalid_request", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unprocessable Content" } }, "security": [ { "OrganizationApiKeyAuth": [] } ], "summary": "List payers", "tags": [ "payers" ], "x-codeSamples": [ { "label": "cURL", "lang": "shell", "source": "curl --request GET \\\n --url \"$RECUUT_API_URL/merchant/v1/payers\" \\\n --header \"Authorization: Bearer $RECUUT_API_KEY\"\n" } ], "x-recuut-pagination": { "requestPage": "page", "requestSnapshot": "as_of", "responseCount": "count", "responseItems": "items", "responseNext": "next", "responseSnapshot": "as_of" } } }, "/merchant/v1/resource-executions/{resource_execution_id}/complete": { "post": { "description": "Retain safe response metadata for allowed work that did not create a payment transaction.", "operationId": "resources.complete_execution", "parameters": [ { "description": "Server-issued resource execution identifier.", "example": "rex_00000000000070008000000000000000", "in": "path", "name": "resource_execution_id", "required": true, "schema": { "description": "Server-issued resource execution identifier.", "examples": [ "rex_00000000000070008000000000000000" ], "pattern": "^rex_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Resource Execution Id", "type": "string", "x-recuut-public-id-prefix": "rex" } } ], "requestBody": { "content": { "application/json": { "examples": { "complete": { "summary": "Retain a free resource response", "value": { "resource_execution": { "duration_ms": 84, "response_content_type": "application/json", "response_size_bytes": 312, "response_status": 200 }, "revision_id": "acr_00000000000070008000000000000000" } } }, "schema": { "$ref": "#/components/schemas/ResourceExecutionCompleteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "completed": { "summary": "Resource execution completed", "value": { "resource_execution_id": "rex_00000000000070008000000000000000" } } }, "schema": { "$ref": "#/components/schemas/ResourceExecutionCompleteResult" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Invalid request", "value": { "code": "invalid_request", "message": "The request is invalid." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "invalid_request", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "unauthenticated": { "summary": "API key required", "value": { "code": "unauthenticated", "message": "A valid Recuut API key is required." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "unauthenticated", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "Capability denied", "value": { "code": "forbidden", "message": "This API key does not allow this operation." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "forbidden", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "resource_execution_not_found": { "summary": "Resource execution not found", "value": { "code": "resource_execution_not_found", "message": "Resource execution not found." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "resource_execution_not_found", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "resource_execution_conflict": { "summary": "Resource execution conflict", "value": { "code": "resource_execution_conflict", "message": "Resource response metadata conflicts with the accepted response." } }, "revision_mismatch": { "summary": "Revision mismatch", "value": { "code": "revision_mismatch", "message": "The completion revision does not match the resource execution." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "resource_execution_conflict", "revision_mismatch" ], "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Invalid request", "value": { "code": "invalid_request", "message": "The request is invalid." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "invalid_request", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Internal error", "value": { "code": "internal_error", "message": "The request could not be completed." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "internal_error", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Internal Server Error" } }, "security": [ { "OrganizationApiKeyAuth": [] } ], "summary": "Complete a free resource execution", "tags": [ "resources" ], "x-codeSamples": [ { "label": "cURL", "lang": "shell", "source": "curl --request POST \\\n --url \"$RECUUT_API_URL/merchant/v1/resource-executions/rex_00000000000070008000000000000000/complete\" \\\n --header \"Authorization: Bearer $RECUUT_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\"resource_execution\":{\"duration_ms\":84,\"response_content_type\":\"application/json\",\"response_size_bytes\":312,\"response_status\":200},\"revision_id\":\"acr_00000000000070008000000000000000\"}'\n", "x-recuut-request-example": "complete" } ] } }, "/merchant/v1/resources": { "get": { "description": "Returns the Resources in the environment selected by this API key. Equivalent Resources in another environment may use the same integration key while keeping distinct Resource and revision IDs.", "operationId": "resources.list", "parameters": [ { "description": "Return archived resources instead of active resources.", "in": "query", "name": "archived", "required": false, "schema": { "default": false, "description": "Return archived resources instead of active resources.", "title": "Archived", "type": "boolean" } }, { "description": "Stable snapshot timestamp for this page sequence. Include a timezone; future timestamps are rejected.", "in": "query", "name": "as_of", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotTimestamp" } }, { "description": "Show the newest or oldest records first.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder", "default": "newest" } }, { "description": "Page number to return. The first page is 1.", "in": "query", "name": "page", "required": false, "schema": { "$ref": "#/components/schemas/PageNumber", "default": 1 } }, { "description": "Number of items to return on each page. Use 1 through 100.", "in": "query", "name": "page_size", "required": false, "schema": { "$ref": "#/components/schemas/PageSize", "default": 50 } } ], "responses": { "200": { "content": { "application/json": { "examples": { "resource_page": { "summary": "Resource page", "value": { "as_of": "2026-08-12T09:30:00Z", "count": 1, "items": [ { "created_at": "2026-08-01T08:00:00Z", "description": "Generate a paid quarterly research report.", "id": "res_00000000000070008000000000000000", "image_url": "https://merchant.example/report.png", "name": "Quarterly report", "updated_at": "2026-08-12T09:30:00Z" } ], "next": null } } }, "schema": { "$ref": "#/components/schemas/PagedResourceSchema" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "unauthenticated": { "summary": "API key required", "value": { "code": "unauthenticated", "message": "A valid Recuut API key is required." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "unauthenticated", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "Capability denied", "value": { "code": "forbidden", "message": "This API key does not allow this operation." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "forbidden", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Invalid request", "value": { "code": "invalid_request", "message": "The request is invalid." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "invalid_request", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unprocessable Content" } }, "security": [ { "OrganizationApiKeyAuth": [] } ], "summary": "List resources", "tags": [ "resources" ], "x-codeSamples": [ { "label": "cURL", "lang": "shell", "source": "curl --request GET \\\n --url \"$RECUUT_API_URL/merchant/v1/resources\" \\\n --header \"Authorization: Bearer $RECUUT_API_KEY\"\n" } ], "x-recuut-filter": { "className": "ResourceFilter", "parameters": [ "archived" ] }, "x-recuut-pagination": { "requestPage": "page", "requestSnapshot": "as_of", "responseCount": "count", "responseItems": "items", "responseNext": "next", "responseSnapshot": "as_of" } } }, "/merchant/v1/transactions": { "get": { "description": "Returns payment records for this Recuut account and its test or live data. The page controls keep the list unchanged while you read later pages.", "operationId": "payments.transactions.list", "parameters": [ { "description": "Stable snapshot timestamp for this page sequence. Include a timezone; future timestamps are rejected.", "in": "query", "name": "as_of", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotTimestamp" } }, { "description": "Filter by transaction lifecycle status.", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransactionStatus" }, { "type": "null" } ], "description": "Filter by transaction lifecycle status." } }, { "description": "Filter by server-issued payer identifier.", "example": "pyr_00000000000070008000000000000000", "in": "query", "name": "payer_id", "required": false, "schema": { "anyOf": [ { "examples": [ "pyr_00000000000070008000000000000000" ], "pattern": "^pyr_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "type": "string", "x-recuut-public-id-prefix": "pyr" }, { "type": "null" } ], "description": "Filter by server-issued payer identifier.", "title": "Payer Id" } }, { "description": "Show the newest or oldest records first.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder", "default": "newest" } }, { "description": "Page number to return. The first page is 1.", "in": "query", "name": "page", "required": false, "schema": { "$ref": "#/components/schemas/PageNumber", "default": 1 } }, { "description": "Number of items to return on each page. Use 1 through 100.", "in": "query", "name": "page_size", "required": false, "schema": { "$ref": "#/components/schemas/PageSize", "default": 50 } } ], "responses": { "200": { "content": { "application/json": { "examples": { "transaction_page": { "summary": "Transaction page", "value": { "as_of": "2026-08-12T09:30:00Z", "count": 1, "items": [ { "authorized_at": "2026-08-12T09:29:57Z", "authorized_atomic": "1000000", "created_at": "2026-08-12T09:29:55Z", "id": "txn_00000000000070008000000000000000", "payer": "0x1111111111111111111111111111111111111111", "payment_request_id": "prq_00000000000070008000000000000000", "settled_at": "2026-08-12T09:30:00Z", "settled_atomic": "1000000", "status": "succeeded", "transaction_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ], "next": null } } }, "schema": { "$ref": "#/components/schemas/PagedTransactionSchema" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "unauthenticated": { "summary": "API key required", "value": { "code": "unauthenticated", "message": "A valid Recuut API key is required." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "unauthenticated", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "Capability denied", "value": { "code": "forbidden", "message": "This API key does not allow this operation." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "forbidden", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Invalid request", "value": { "code": "invalid_request", "message": "The request is invalid." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "invalid_request", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unprocessable Content" } }, "security": [ { "OrganizationApiKeyAuth": [] } ], "summary": "List transactions", "tags": [ "transactions" ], "x-codeSamples": [ { "label": "cURL", "lang": "shell", "source": "curl --request GET \\\n --url \"$RECUUT_API_URL/merchant/v1/transactions?payer_id=pyr_00000000000070008000000000000000\" \\\n --header \"Authorization: Bearer $RECUUT_API_KEY\"\n" } ], "x-recuut-filter": { "className": "TransactionFilter", "parameters": [ "status", "payer_id" ] }, "x-recuut-pagination": { "requestPage": "page", "requestSnapshot": "as_of", "responseCount": "count", "responseItems": "items", "responseNext": "next", "responseSnapshot": "as_of" } } }, "/merchant/v1/transactions/{transaction_id}": { "get": { "description": "Returns one transaction. It includes a receipt only after payment has finished successfully.", "operationId": "payments.transactions.get", "parameters": [ { "description": "Server-issued transaction identifier.", "example": "txn_00000000000070008000000000000000", "in": "path", "name": "transaction_id", "required": true, "schema": { "description": "Server-issued transaction identifier.", "examples": [ "txn_00000000000070008000000000000000" ], "pattern": "^txn_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Transaction Id", "type": "string", "x-recuut-public-id-prefix": "txn" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "succeeded_transaction": { "summary": "Succeeded transaction with receipt", "value": { "authorized_at": "2026-08-12T09:29:57Z", "authorized_atomic": "1000000", "created_at": "2026-08-12T09:29:55Z", "id": "txn_00000000000070008000000000000000", "payer": "0x1111111111111111111111111111111111111111", "payment_request_id": "prq_00000000000070008000000000000000", "receipt": { "environment": "test", "environment_key": "test", "id": "rct_00000000000070008000000000000000", "issued_at": "2026-08-12T09:30:00.000Z", "payment": { "asset": "USDC", "asset_id": "0x3333333333333333333333333333333333333333", "authorized_atomic": "1000000", "network": "eip155:84532", "payer": "0x1111111111111111111111111111111111111111", "recipient": "0x2222222222222222222222222222222222222222", "scheme": "exact", "settled_atomic": "1000000", "transaction_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "price": { "calculation_mode": "fixed", "currency": "USD", "id": "prc_00000000000070008000000000000000", "label": "Quarterly report access" }, "resource": { "id": "res_00000000000070008000000000000000", "name": "Quarterly report", "url": "https://merchant.example/reports/quarterly" }, "schema_version": 2, "seller": { "id": "org_00000000000070008000000000000000", "name": "Acme Research" }, "transaction_id": "txn_00000000000070008000000000000000" }, "settled_at": "2026-08-12T09:30:00Z", "settled_atomic": "1000000", "status": "succeeded", "transaction_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } }, "schema": { "$ref": "#/components/schemas/TransactionDetailSchema" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "unauthenticated": { "summary": "API key required", "value": { "code": "unauthenticated", "message": "A valid Recuut API key is required." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "unauthenticated", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "Capability denied", "value": { "code": "forbidden", "message": "This API key does not allow this operation." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "forbidden", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "transaction_not_found": { "summary": "Transaction not found", "value": { "code": "transaction_not_found", "message": "Transaction not found." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "transaction_not_found", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Not Found" } }, "security": [ { "OrganizationApiKeyAuth": [] } ], "summary": "Get a transaction", "tags": [ "transactions" ], "x-codeSamples": [ { "label": "cURL", "lang": "shell", "source": "curl --request GET \\\n --url \"$RECUUT_API_URL/merchant/v1/transactions/txn_00000000000070008000000000000000\" \\\n --header \"Authorization: Bearer $RECUUT_API_KEY\"\n" } ] } }, "/merchant/v1/transactions/{transaction_id}/complete": { "post": { "description": "Tell Recuut whether your work succeeded or failed. Recuut then finishes the payment. A finished successful payment includes a receipt.", "operationId": "payments.transactions.complete", "parameters": [ { "description": "Server-issued transaction identifier.", "example": "txn_00000000000070008000000000000000", "in": "path", "name": "transaction_id", "required": true, "schema": { "description": "Server-issued transaction identifier.", "examples": [ "txn_00000000000070008000000000000000" ], "pattern": "^txn_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Transaction Id", "type": "string", "x-recuut-public-id-prefix": "txn" } }, { "description": "Payment proof created by the payer. Forward this base64 text unchanged. It is required to finish this payment. [See the decoded fields](/guides/concepts/x402-payment-retry/#what-the-encoded-headers-contain).", "example": "$PAYMENT_SIGNATURE", "in": "header", "name": "PAYMENT-SIGNATURE", "required": true, "schema": { "$ref": "#/components/schemas/PaymentSignature" } } ], "requestBody": { "content": { "application/json": { "examples": { "complete_succeeded": { "summary": "Complete a successful transaction", "value": { "outcome": "succeeded", "resource_execution": { "duration_ms": 84, "response_content_type": "application/json", "response_size_bytes": 312, "response_status": 200 }, "revision_id": "acr_00000000000070008000000000000000", "values": { "input_tokens": "1000" } } }, "failed": { "summary": "Report a failed merchant operation", "value": { "failure_code": "merchant_operation_failed", "outcome": "failed", "resource_execution": { "duration_ms": 148, "response_content_type": "application/json", "response_size_bytes": 96, "response_status": 500 }, "revision_id": "acr_00000000000070008000000000000000" } } }, "schema": { "$ref": "#/components/schemas/CompleteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "merchant_operation_failed": { "description": "The work failed, so no payment receipt is returned.", "summary": "Merchant operation failed", "value": { "payment_response": null, "receipt": null, "status": "failed", "transaction_hash": null, "transaction_id": "txn_00000000000070008000000000000000" } }, "settlement_succeeded": { "description": "Payment succeeded. The response includes the payment receipt.", "summary": "Settlement succeeded", "value": { "payment_response": "eyJhbW91bnQiOiIxMDAwMDAwIiwiZXJyb3JSZWFzb24iOm51bGwsImV4dGVuc2lvbnMiOnsicmVjdXV0LXJlY2VpcHQiOnsiZW52aXJvbm1lbnQiOiJ0ZXN0IiwiZW52aXJvbm1lbnRfa2V5IjoidGVzdCIsImlkIjoicmN0XzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwiaXNzdWVkX2F0IjoiMjAyNi0wOC0xMlQwOTozMDowMC4wMDBaIiwicGF5bWVudCI6eyJhc3NldCI6IlVTREMiLCJhc3NldF9pZCI6IjB4MzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMyIsImF1dGhvcml6ZWRfYXRvbWljIjoiMTAwMDAwMCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwYXllciI6IjB4MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMSIsInJlY2lwaWVudCI6IjB4MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMiIsInNjaGVtZSI6ImV4YWN0Iiwic2V0dGxlZF9hdG9taWMiOiIxMDAwMDAwIiwidHJhbnNhY3Rpb25faGFzaCI6IjB4YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYSJ9LCJwcmljZSI6eyJjYWxjdWxhdGlvbl9tb2RlIjoiZml4ZWQiLCJjdXJyZW5jeSI6IlVTRCIsImlkIjoicHJjXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwibGFiZWwiOiJRdWFydGVybHkgcmVwb3J0IGFjY2VzcyJ9LCJyZXNvdXJjZSI6eyJpZCI6InJlc18wMDAwMDAwMDAwMDA3MDAwODAwMDAwMDAwMDAwMDAwMCIsIm5hbWUiOiJRdWFydGVybHkgcmVwb3J0IiwidXJsIjoiaHR0cHM6Ly9tZXJjaGFudC5leGFtcGxlL3JlcG9ydHMvcXVhcnRlcmx5In0sInNjaGVtYV92ZXJzaW9uIjoyLCJzZWxsZXIiOnsiaWQiOiJvcmdfMDAwMDAwMDAwMDAwNzAwMDgwMDAwMDAwMDAwMDAwMDAiLCJuYW1lIjoiQWNtZSBSZXNlYXJjaCJ9LCJ0cmFuc2FjdGlvbl9pZCI6InR4bl8wMDAwMDAwMDAwMDA3MDAwODAwMDAwMDAwMDAwMDAwMCJ9fSwibmV0d29yayI6ImVpcDE1NTo4NDUzMiIsInBheWVyIjoiMHgxMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExIiwic3VjY2VzcyI6dHJ1ZSwidHJhbnNhY3Rpb24iOiIweGFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWEifQ==", "receipt": { "environment": "test", "environment_key": "test", "id": "rct_00000000000070008000000000000000", "issued_at": "2026-08-12T09:30:00.000Z", "payment": { "asset": "USDC", "asset_id": "0x3333333333333333333333333333333333333333", "authorized_atomic": "1000000", "network": "eip155:84532", "payer": "0x1111111111111111111111111111111111111111", "recipient": "0x2222222222222222222222222222222222222222", "scheme": "exact", "settled_atomic": "1000000", "transaction_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "price": { "calculation_mode": "fixed", "currency": "USD", "id": "prc_00000000000070008000000000000000", "label": "Quarterly report access" }, "resource": { "id": "res_00000000000070008000000000000000", "name": "Quarterly report", "url": "https://merchant.example/reports/quarterly" }, "schema_version": 2, "seller": { "id": "org_00000000000070008000000000000000", "name": "Acme Research" }, "transaction_id": "txn_00000000000070008000000000000000" }, "status": "succeeded", "transaction_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "transaction_id": "txn_00000000000070008000000000000000" } } }, "schema": { "$ref": "#/components/schemas/CompletionResult" } } }, "description": "OK", "headers": { "PAYMENT-RESPONSE": { "description": "Proof that payment succeeded. Return this base64 text unchanged. [See the decoded fields](/guides/concepts/x402-payment-retry/#what-the-encoded-headers-contain).", "required": false, "schema": { "contentEncoding": "base64", "contentMediaType": "application/json", "examples": [ "eyJhbW91bnQiOiIxMDAwMDAwIiwiZXJyb3JSZWFzb24iOm51bGwsImV4dGVuc2lvbnMiOnsicmVjdXV0LXJlY2VpcHQiOnsiZW52aXJvbm1lbnQiOiJ0ZXN0IiwiZW52aXJvbm1lbnRfa2V5IjoidGVzdCIsImlkIjoicmN0XzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwiaXNzdWVkX2F0IjoiMjAyNi0wOC0xMlQwOTozMDowMC4wMDBaIiwicGF5bWVudCI6eyJhc3NldCI6IlVTREMiLCJhc3NldF9pZCI6IjB4MzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMyIsImF1dGhvcml6ZWRfYXRvbWljIjoiMTAwMDAwMCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwYXllciI6IjB4MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMSIsInJlY2lwaWVudCI6IjB4MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMiIsInNjaGVtZSI6ImV4YWN0Iiwic2V0dGxlZF9hdG9taWMiOiIxMDAwMDAwIiwidHJhbnNhY3Rpb25faGFzaCI6IjB4YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYSJ9LCJwcmljZSI6eyJjYWxjdWxhdGlvbl9tb2RlIjoiZml4ZWQiLCJjdXJyZW5jeSI6IlVTRCIsImlkIjoicHJjXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwibGFiZWwiOiJRdWFydGVybHkgcmVwb3J0IGFjY2VzcyJ9LCJyZXNvdXJjZSI6eyJpZCI6InJlc18wMDAwMDAwMDAwMDA3MDAwODAwMDAwMDAwMDAwMDAwMCIsIm5hbWUiOiJRdWFydGVybHkgcmVwb3J0IiwidXJsIjoiaHR0cHM6Ly9tZXJjaGFudC5leGFtcGxlL3JlcG9ydHMvcXVhcnRlcmx5In0sInNjaGVtYV92ZXJzaW9uIjoyLCJzZWxsZXIiOnsiaWQiOiJvcmdfMDAwMDAwMDAwMDAwNzAwMDgwMDAwMDAwMDAwMDAwMDAiLCJuYW1lIjoiQWNtZSBSZXNlYXJjaCJ9LCJ0cmFuc2FjdGlvbl9pZCI6InR4bl8wMDAwMDAwMDAwMDA3MDAwODAwMDAwMDAwMDAwMDAwMCJ9fSwibmV0d29yayI6ImVpcDE1NTo4NDUzMiIsInBheWVyIjoiMHgxMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExIiwic3VjY2VzcyI6dHJ1ZSwidHJhbnNhY3Rpb24iOiIweGFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWEifQ==" ], "minLength": 1, "type": "string" } } } }, "202": { "content": { "application/json": { "examples": { "settlement_pending": { "description": "Payment is still in progress, so no payment receipt is returned yet.", "summary": "Settlement pending", "value": { "payment_response": null, "receipt": null, "status": "settling", "transaction_hash": null, "transaction_id": "txn_00000000000070008000000000000000" } }, "settlement_reconciling": { "description": "Recuut is checking the payment, so no payment receipt is returned yet.", "summary": "Settlement reconciling", "value": { "payment_response": null, "receipt": null, "status": "reconciling", "transaction_hash": null, "transaction_id": "txn_00000000000070008000000000000000" } } }, "schema": { "$ref": "#/components/schemas/CompletionResult" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "examples": { "invalid_payment_signature": { "summary": "Malformed payment signature", "value": { "code": "invalid_payment_signature", "message": "PAYMENT-SIGNATURE is not valid base64-encoded JSON." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "invalid_payment_signature", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "unauthenticated": { "summary": "API key required", "value": { "code": "unauthenticated", "message": "A valid Recuut API key is required." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "unauthenticated", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "Capability denied", "value": { "code": "forbidden", "message": "This API key does not allow this operation." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "forbidden", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "transaction_not_found": { "summary": "Transaction not found", "value": { "code": "transaction_not_found", "message": "Transaction not found." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "transaction_not_found", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "completion_conflict": { "summary": "Completion conflict", "value": { "code": "completion_conflict", "message": "This Transaction was already completed with different input." } }, "payment_signature_mismatch": { "summary": "Signature mismatch", "value": { "code": "payment_signature_mismatch", "message": "The completion signature does not match the authorized payment." } }, "price_not_found": { "summary": "Historical price unavailable", "value": { "code": "price_not_found", "message": "The historical payment Price is unavailable." } }, "revision_mismatch": { "summary": "Revision mismatch", "value": { "code": "revision_mismatch", "message": "The completion revision does not match the authorized Price." } }, "transaction_state_conflict": { "summary": "Transaction state conflict", "value": { "code": "transaction_state_conflict", "message": "Only an authorized Transaction can be completed." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "completion_conflict", "payment_signature_mismatch", "price_not_found", "revision_mismatch", "transaction_state_conflict" ], "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "examples": { "contract_values_mismatch": { "summary": "Contract values mismatch", "value": { "code": "contract_values_mismatch", "message": "Reported values must exactly match the revision contract." } }, "invalid_request": { "summary": "Invalid request", "value": { "code": "invalid_request", "message": "The request is invalid." } }, "invalid_values": { "summary": "Invalid completion values", "value": { "code": "invalid_values", "message": "Successful completion requires values and no failure code." } }, "maximum_exceeded": { "summary": "Authorized maximum exceeded", "value": { "code": "maximum_exceeded", "message": "The calculated charge exceeds the authorized maximum." } }, "payment_signature_required": { "summary": "Payment signature required", "value": { "code": "payment_signature_required", "message": "PAYMENT-SIGNATURE is required for completion." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "contract_values_mismatch", "invalid_request", "invalid_values", "maximum_exceeded", "payment_signature_required" ], "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Internal error", "value": { "code": "internal_error", "message": "The request could not be completed." } }, "payment_request_failed": { "summary": "Stored requirements invalid", "value": { "code": "payment_request_failed", "message": "The stored payment requirements are invalid." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "internal_error", "payment_request_failed" ], "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "examples": { "live_payments_not_enabled": { "summary": "Live payments unavailable", "value": { "code": "live_payments_not_enabled", "message": "Paid live transactions are not enabled yet." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "const": "live_payments_not_enabled", "description": "Stable error code your app can check.", "type": "string" }, "message": { "description": "Short explanation of what went wrong.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [ { "OrganizationApiKeyAuth": [] } ], "summary": "Complete a transaction", "tags": [ "transactions" ], "x-codeSamples": [ { "label": "Report a failed merchant operation \u2014 cURL", "lang": "shell", "source": "curl --request POST \\\n --url \"$RECUUT_API_URL/merchant/v1/transactions/txn_00000000000070008000000000000000/complete\" \\\n --header \"Authorization: Bearer $RECUUT_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --header \"PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE\" \\\n --data '{\"failure_code\":\"merchant_operation_failed\",\"outcome\":\"failed\",\"resource_execution\":{\"duration_ms\":148,\"response_content_type\":\"application/json\",\"response_size_bytes\":96,\"response_status\":500},\"revision_id\":\"acr_00000000000070008000000000000000\"}'\n", "x-recuut-request-example": "failed" }, { "label": "Complete a successful transaction \u2014 cURL", "lang": "shell", "source": "curl --request POST \\\n --url \"$RECUUT_API_URL/merchant/v1/transactions/txn_00000000000070008000000000000000/complete\" \\\n --header \"Authorization: Bearer $RECUUT_API_KEY\" \\\n --header 'Content-Type: application/json' \\\n --header \"PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE\" \\\n --data '{\"outcome\":\"succeeded\",\"resource_execution\":{\"duration_ms\":84,\"response_content_type\":\"application/json\",\"response_size_bytes\":312,\"response_status\":200},\"revision_id\":\"acr_00000000000070008000000000000000\",\"values\":{\"input_tokens\":\"1000\"}}'\n", "x-recuut-request-example": "complete_succeeded" } ] } } }, "servers": [], "tags": [ { "description": "List, inspect, and complete payment transactions.", "name": "transactions" }, { "description": "List payers for test or live Merchant API data.", "name": "payers" }, { "description": "List the resources this Recuut account sells.", "name": "resources" }, { "description": "Read the published reporting contracts used to generate typed resource bindings.", "name": "contracts" }, { "description": "Check payment before returning a protected resource.", "name": "payments" } ] }