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