# POST `/merchant/v1/access`

[Documentation page](/api-reference/payments/payments.access)

## Summary

Authorize resource access

## 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.

## Security requirements

```json
[
  {
    "OrganizationApiKeyAuth": []
  }
]
```

## Operation parameters

### header `PAYMENT-SIGNATURE`

```json
{
  "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"
  }
}
```

## Request body

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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"
}
```

## First-party examples

### cURL

```json
{
  "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"
}
```

```shell
curl --request POST \
  --url "$RECUUT_API_URL/merchant/v1/access" \
  --header "Authorization: Bearer $RECUUT_API_KEY" \
  --header 'Content-Type: application/json' \
  --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"}'

```

## Canonical operation

```json
{
  "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"
    }
  ]
}
```