OpenAPI schema
Read, copy, or download the exact API definition used by recuut tools and SDKs.
This page provides the exact JSON API definition for tools and SDKs. Most people can use the guides or API reference instead. Tools should fetch /openapi.json directly.
OpenAPI is a standard file that describes an API for tools and SDKs. This copy is generated from the Merchant API contract during every docs build, so the download, API Reference, and SDK-generation input stay aligned.
{ "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": "Environment-scoped revision details for one access check.", "properties": { "inputs": { "additionalProperties": { "pattern": "^(?:0|[1-9][0-9]{0,17})$", "type": "string" }, "description": "Values available before execution. Include a value for every input variable of the published revision and none for output variables.", "propertyNames": { "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]+(?:[-_][a-z0-9]+)*$" }, "title": "Inputs", "type": "object" }, "resource": { "$ref": "#/components/schemas/AccessResource", "description": "Details of the resource your app plans to return after access is allowed." }, "revision_key": { "description": "Stable revision key. Recuut resolves the published revision in the API key's environment.", "examples": [ "rvk_00000000000070008000000000000000" ], "pattern": "^rvk_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "Revision Key", "type": "string", "x-recuut-public-id-prefix": "rvk" } }, "required": [ "inputs", "resource", "revision_key" ], "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-key value.", "propertyNames": { "examples": [ "rvk_00000000000070008000000000000000" ], "pattern": "^rvk_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "x-recuut-public-id-prefix": "rvk" }, "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_resource_key": { "default": false, "description": "Include the cross-environment Resource key. Generated SDKs request this metadata explicitly.", "title": "Include Resource 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/VariableSchema" }, "description": "Variables declared by this published version.", "propertyNames": { "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]+(?:[-_][a-z0-9]+)*$" }, "title": "Properties", "type": "object" }, "required": { "description": "Keys of every variable your app must supply a value for.", "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-key": { "anyOf": [ { "maxLength": 100, "minLength": 1, "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$", "type": "string" }, { "type": "null" } ], "description": "Environment-local resource key shared by related Resources. Returned when include_resource_key is requested.", "title": "X-Recuut-Resource-Key" }, "x-recuut-resource-name": { "description": "Protected resource display name.", "title": "X-Recuut-Resource-Name", "type": "string" }, "x-recuut-revision-key": { "description": "Stable revision key resolved in the API key's environment.", "examples": [ "rvk_00000000000070008000000000000000" ], "pattern": "^rvk_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$", "title": "X-Recuut-Revision-Key", "type": "string", "x-recuut-public-id-prefix": "rvk" }, "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-key", "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": { "const": "USDC", "type": "string" }, "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" }, "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." } }, "required": [ "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", "variables_mismatch", "maximum_exceeded", "price_not_found", "price_not_supported" ], "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": [ "eyJhbW91bnQiOiIxMDAwMDAwIiwiZXJyb3JSZWFzb24iOm51bGwsImV4dGVuc2lvbnMiOnsicmVjdXV0LXJlY2VpcHQiOnsiZW52aXJvbm1lbnQiOiJ0ZXN0IiwiZW52aXJvbm1lbnRfa2V5IjoidGVzdCIsImlkIjoicmN0XzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwiaXNzdWVkX2F0IjoiMjAyNi0wOC0xMlQwOTozMDowMC4wMDBaIiwicGF5bWVudCI6eyJhc3NldCI6IlVTREMiLCJhc3NldF9pZCI6IjB4MzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMyIsImF1dGhvcml6ZWRfYXRvbWljIjoiMTAwMDAwMCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwYXllciI6IjB4MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMSIsInJlY2lwaWVudCI6IjB4MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMiIsInNjaGVtZSI6ImV4YWN0Iiwic2V0dGxlZF9hdG9taWMiOiIxMDAwMDAwIiwidHJhbnNhY3Rpb25faGFzaCI6IjB4YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYSJ9LCJwcmljZSI6eyJjYWxjdWxhdGlvbl9tb2RlIjoiZml4ZWQiLCJjdXJyZW5jeSI6IlVTRCIsImlkIjoicHJjXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIn0sInJlc291cmNlIjp7ImlkIjoicmVzXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwibmFtZSI6IlF1YXJ0ZXJseSByZXBvcnQiLCJ1cmwiOiJodHRwczovL21lcmNoYW50LmV4YW1wbGUvcmVwb3J0cy9xdWFydGVybHkifSwic2NoZW1hX3ZlcnNpb24iOjMsInNlbGxlciI6eyJpZCI6Im9yZ18wMDAwMDAwMDAwMDA3MDAwODAwMDAwMDAwMDAwMDAwMCIsIm5hbWUiOiJBY21lIFJlc2VhcmNoIn0sInRyYW5zYWN0aW9uX2lkIjoidHhuXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIn19LCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMyIiwicGF5ZXIiOiIweDExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTEiLCJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYSJ9" ], "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": { "description": "Immutable organization environment key.", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "title": "Environment Key", "type": "string" }, "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": { "const": 3, "description": "Receipt contract version.", "title": "Schema Version", "type": "integer" }, "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", "environment_key", "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", "usage_based" ], "title": "Calculation Mode", "type": "string" }, "currency": { "const": "USD", "description": "USD denomination of the published Price.", "title": "Currency", "type": "string" }, "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" } }, "required": [ "id", "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." } }, "required": [ "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" }, "SettlementAssetSymbol": { "const": "USDC", "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." }, "values": { "additionalProperties": { "pattern": "^(?:0|[1-9][0-9]{0,17})$", "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": [ "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" }, "VariableSchema": { "additionalProperties": false, "description": "One variable whose value is read from input or returned by the handler.", "properties": { "description": { "description": "Meaning of the variable.", "title": "Description", "type": "string" }, "format": { "const": "integer", "description": "Canonical non-negative integer string format.", "title": "Format", "type": "string" }, "pattern": { "const": "^(?:0|[1-9][0-9]{0,17})$", "description": "Pattern for a non-negative integer with at most 18 digits.", "title": "Pattern", "type": "string" }, "type": { "const": "string", "description": "JSON value type.", "title": "Type", "type": "string" }, "x-recuut-decimal-places": { "const": 0, "description": "Required generated-model scale: zero decimal places.", "title": "X-Recuut-Decimal-Places", "type": "integer" }, "x-recuut-label": { "description": "Merchant-facing variable label.", "title": "X-Recuut-Label", "type": "string" }, "x-recuut-max-digits": { "const": 18, "description": "Required generated-model precision: at most 18 integer 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-source": { "$ref": "#/components/schemas/VariableSource", "description": "Whether the framework reads this value from input or the handler returns it." }, "x-recuut-unit": { "description": "Unit attached to the supplied quantity.", "title": "X-Recuut-Unit", "type": "string" } }, "required": [ "type", "format", "pattern", "description", "x-recuut-label", "x-recuut-unit", "x-recuut-position", "x-recuut-source", "x-recuut-max-digits", "x-recuut-decimal-places" ], "title": "VariableSchema", "type": "object" }, "VariableSource": { "description": "Where a protected handler obtains one variable's value.", "enum": [ "input", "reported" ], "title": "VariableSource", "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": { "inputs": {}, "resource": { "description": "Generate a paid quarterly research report.", "mime_type": "application/json", "url": "https://merchant.example/reports/quarterly" }, "revision_key": "rvk_00000000000070008000000000000000" } } }, "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": { "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": [ "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." } }, "maximum_exceeded": { "summary": "Input charge exceeds the maximum", "value": { "code": "maximum_exceeded", "message": "The calculated charge exceeds the authorized maximum." } }, "variables_mismatch": { "summary": "Input values do not match", "value": { "code": "variables_mismatch", "message": "Reported values must exactly match the revision contract." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "invalid_request", "maximum_exceeded", "variables_mismatch" ], "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 '{\"inputs\":{},\"resource\":{\"description\":\"Generate a paid quarterly research report.\",\"mime_type\":\"application/json\",\"url\":\"https://merchant.example/reports/quarterly\"},\"revision_key\":\"rvk_00000000000070008000000000000000\"}'\n", "x-recuut-request-example": "authorize_resource" } ] } }, "/merchant/v1/contracts": { "get": { "description": "Returns each published revision, its settlement asset, and its input and output variables, in OpenAPI format. SDKs and tools use this response. The API key selects one environment; equivalent Resources may share the published resource key across environments.", "operationId": "resources.contracts.list", "parameters": [ { "description": "Include the cross-environment Resource key. Generated SDKs request this metadata explicitly.", "in": "query", "name": "include_resource_key", "required": false, "schema": { "default": false, "description": "Include the cross-environment Resource key. Generated SDKs request this metadata explicitly.", "title": "Include Resource Key", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "published_contracts": { "description": "One published revision keyed by the revision key used in the access example.", "summary": "Published contracts", "value": { "components": { "schemas": { "rvk_00000000000070008000000000000000": { "additionalProperties": false, "properties": { "input_tokens": { "description": "Number of input tokens consumed by the report.", "format": "integer", "pattern": "^(?:0|[1-9][0-9]{0,17})$", "type": "string", "x-recuut-decimal-places": 0, "x-recuut-label": "Input tokens", "x-recuut-max-digits": 18, "x-recuut-position": 0, "x-recuut-source": "reported", "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-key": "quarterly_report", "x-recuut-resource-name": "Quarterly report", "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 } } } }, "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}}'\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 resource key while keeping distinct Resource 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" }, "resource": { "id": "res_00000000000070008000000000000000", "name": "Quarterly report", "url": "https://merchant.example/reports/quarterly" }, "schema_version": 3, "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 }, "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 } } } }, "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": "eyJhbW91bnQiOiIxMDAwMDAwIiwiZXJyb3JSZWFzb24iOm51bGwsImV4dGVuc2lvbnMiOnsicmVjdXV0LXJlY2VpcHQiOnsiZW52aXJvbm1lbnQiOiJ0ZXN0IiwiZW52aXJvbm1lbnRfa2V5IjoidGVzdCIsImlkIjoicmN0XzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwiaXNzdWVkX2F0IjoiMjAyNi0wOC0xMlQwOTozMDowMC4wMDBaIiwicGF5bWVudCI6eyJhc3NldCI6IlVTREMiLCJhc3NldF9pZCI6IjB4MzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMyIsImF1dGhvcml6ZWRfYXRvbWljIjoiMTAwMDAwMCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwYXllciI6IjB4MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMSIsInJlY2lwaWVudCI6IjB4MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMiIsInNjaGVtZSI6ImV4YWN0Iiwic2V0dGxlZF9hdG9taWMiOiIxMDAwMDAwIiwidHJhbnNhY3Rpb25faGFzaCI6IjB4YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYSJ9LCJwcmljZSI6eyJjYWxjdWxhdGlvbl9tb2RlIjoiZml4ZWQiLCJjdXJyZW5jeSI6IlVTRCIsImlkIjoicHJjXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIn0sInJlc291cmNlIjp7ImlkIjoicmVzXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwibmFtZSI6IlF1YXJ0ZXJseSByZXBvcnQiLCJ1cmwiOiJodHRwczovL21lcmNoYW50LmV4YW1wbGUvcmVwb3J0cy9xdWFydGVybHkifSwic2NoZW1hX3ZlcnNpb24iOjMsInNlbGxlciI6eyJpZCI6Im9yZ18wMDAwMDAwMDAwMDA3MDAwODAwMDAwMDAwMDAwMDAwMCIsIm5hbWUiOiJBY21lIFJlc2VhcmNoIn0sInRyYW5zYWN0aW9uX2lkIjoidHhuXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIn19LCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMyIiwicGF5ZXIiOiIweDExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTEiLCJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYSJ9", "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" }, "resource": { "id": "res_00000000000070008000000000000000", "name": "Quarterly report", "url": "https://merchant.example/reports/quarterly" }, "schema_version": 3, "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": [ "eyJhbW91bnQiOiIxMDAwMDAwIiwiZXJyb3JSZWFzb24iOm51bGwsImV4dGVuc2lvbnMiOnsicmVjdXV0LXJlY2VpcHQiOnsiZW52aXJvbm1lbnQiOiJ0ZXN0IiwiZW52aXJvbm1lbnRfa2V5IjoidGVzdCIsImlkIjoicmN0XzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwiaXNzdWVkX2F0IjoiMjAyNi0wOC0xMlQwOTozMDowMC4wMDBaIiwicGF5bWVudCI6eyJhc3NldCI6IlVTREMiLCJhc3NldF9pZCI6IjB4MzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMyIsImF1dGhvcml6ZWRfYXRvbWljIjoiMTAwMDAwMCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MzIiLCJwYXllciI6IjB4MTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMSIsInJlY2lwaWVudCI6IjB4MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMiIsInNjaGVtZSI6ImV4YWN0Iiwic2V0dGxlZF9hdG9taWMiOiIxMDAwMDAwIiwidHJhbnNhY3Rpb25faGFzaCI6IjB4YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYSJ9LCJwcmljZSI6eyJjYWxjdWxhdGlvbl9tb2RlIjoiZml4ZWQiLCJjdXJyZW5jeSI6IlVTRCIsImlkIjoicHJjXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIn0sInJlc291cmNlIjp7ImlkIjoicmVzXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIiwibmFtZSI6IlF1YXJ0ZXJseSByZXBvcnQiLCJ1cmwiOiJodHRwczovL21lcmNoYW50LmV4YW1wbGUvcmVwb3J0cy9xdWFydGVybHkifSwic2NoZW1hX3ZlcnNpb24iOjMsInNlbGxlciI6eyJpZCI6Im9yZ18wMDAwMDAwMDAwMDA3MDAwODAwMDAwMDAwMDAwMDAwMCIsIm5hbWUiOiJBY21lIFJlc2VhcmNoIn0sInRyYW5zYWN0aW9uX2lkIjoidHhuXzAwMDAwMDAwMDAwMDcwMDA4MDAwMDAwMDAwMDAwMDAwIn19LCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMyIiwicGF5ZXIiOiIweDExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTEiLCJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYSJ9" ], "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": { "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." } }, "variables_mismatch": { "summary": "Variables mismatch", "value": { "code": "variables_mismatch", "message": "Completion values must use keys declared by the revision contract." } } }, "schema": { "additionalProperties": false, "description": "Error returned for this endpoint and HTTP status.", "properties": { "code": { "description": "Stable error code your app can check.", "enum": [ "invalid_request", "invalid_values", "maximum_exceeded", "payment_signature_required", "variables_mismatch" ], "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}}'\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},\"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" } ]}