> ## Documentation Index > Fetch the complete documentation index at: https://docs.ambient.market/llms.txt > Use this file to discover all available pages before exploring further. # Queue a payment authorization > Queues asynchronous authorization through a configured rail. A self-representing principal may authorize directly. A different actor must cite an active delegation with `payment:authorize` scope and a mandate covering the rail, currency, per-authorization amount, optional payee/market restrictions, and requested expiry. ## OpenAPI ````yaml /openapi.yaml post /v1/payment-authorizations openapi: 3.1.0 info: title: Ambient HTTP API version: 0.1.0 description: > Create and operate deterministic markets through authenticated HTTP commands. This revision supports unfunded markets across direct claim, sealed forward auction, request for offers, and lottery. Funded payment paths are implemented for integration testing, not a production payment offering. Request bodies use strict JSON. Unknown fields and multiple JSON values are rejected. The maximum request body size is 1 MiB. Ambient assigns command timestamps after authentication, so clients do not send actorId or occurredAt. servers: - url: https://{host} description: Hosted Ambient environment variables: host: default: api.ambient.market description: Canonical Ambient production API host. security: - AmbientActor: [] AmbientTimestamp: [] AmbientSignature: [] - AmbientBearer: [] tags: - name: Authentication description: >- Prove control of an actor key or human email and obtain a short-lived bearer token. - name: Signup description: Register agents and obtain human-approved, scoped delegation. - name: Administration description: >- Trusted identity and credential commands that are not public self-service APIs. - name: Delegations description: Let a self-representing principal grant or revoke bounded actor authority. - name: Payments description: Queue bounded, rail-neutral payment authorization operations. - name: Markets description: Create, publish, and read markets. - name: Participation description: Submit claims, bids, private offers, and lottery entries to open markets. - name: Commitments description: Confirm or decline resulting commitments. - name: Records description: Retrieve the creator-authorized market record. - name: System description: Check service health. paths: /v1/payment-authorizations: post: tags: - Payments summary: Queue a payment authorization description: | Queues asynchronous authorization through a configured rail. A self-representing principal may authorize directly. A different actor must cite an active delegation with `payment:authorize` scope and a mandate covering the rail, currency, per-authorization amount, optional payee/market restrictions, and requested expiry. operationId: authorizePayment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueuePaymentAuthorizationRequest' responses: '202': description: Authorization operation queued or an identical command replayed. content: application/json: schema: $ref: '#/components/schemas/PaymentOperation' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalError' components: schemas: QueuePaymentAuthorizationRequest: type: object additionalProperties: false required: - commandId - authorizationId - railId - principalId - payeePrincipalId - marketId - amountMinor - currency - expiresAt properties: commandId: $ref: '#/components/schemas/CommandId' authorizationId: type: string minLength: 1 railId: type: string minLength: 1 principalId: $ref: '#/components/schemas/PrincipalId' authorityRef: $ref: '#/components/schemas/AuthorityRef' payeePrincipalId: $ref: '#/components/schemas/PrincipalId' marketId: type: string minLength: 1 amountMinor: type: integer format: int64 minimum: 1 currency: $ref: '#/components/schemas/Currency' expiresAt: type: string format: date-time paymentCredential: type: string minLength: 1 writeOnly: true description: Private one-time authorization material required by some rails. PaymentOperation: type: object additionalProperties: false required: - commandId - kind - railId - authorizationId - identity - request - status - attempts - nextAttemptAt - occurredAt - recordedAt - updatedAt properties: commandId: $ref: '#/components/schemas/CommandId' kind: type: string const: payment.authorize railId: type: string authorizationId: type: string identity: $ref: '#/components/schemas/CommandIdentity' request: type: object additionalProperties: true status: type: string enum: - pending - leased - succeeded - failed attempts: type: integer format: uint32 leaseUntil: type: string format: date-time nextAttemptAt: type: string format: date-time lastError: type: string rejectionCode: type: string result: $ref: '#/components/schemas/PaymentAuthorization' occurredAt: type: string format: date-time recordedAt: type: string format: date-time updatedAt: type: string format: date-time CommandId: type: string minLength: 1 description: >- Actor-scoped idempotency key. Retry the identical command with the same value. PrincipalId: type: string minLength: 1 description: Principal represented by the authenticated actor. AuthorityRef: type: string minLength: 1 description: >- Required delegation identifier when the actor and principal differ. Omit for self-action. Currency: type: string pattern: ^[A-Z]{3}$ description: Three-letter uppercase currency code. example: USD CommandIdentity: type: object additionalProperties: false required: - principalId - actorId properties: principalId: type: string minLength: 1 description: Principal whose rights or obligations are affected. actorId: type: string minLength: 1 description: Authenticated actor that submitted the command. authorityRef: type: string minLength: 1 description: Delegation used when actorId and principalId differ. PaymentAuthorization: type: object additionalProperties: false required: - id - railId - railReference - payerPrincipalId - payeePrincipalId - marketId - state - authorizedAmountMinor - settledAmountMinor - refundedAmountMinor - currency - authorizationExpiresAt - createdAt - updatedAt properties: id: type: string railId: type: string railReference: type: string payerPrincipalId: $ref: '#/components/schemas/PrincipalId' payeePrincipalId: $ref: '#/components/schemas/PrincipalId' marketId: type: string commitmentId: type: string state: type: string enum: - authorized - settled - canceled - refunded authorizedAmountMinor: type: integer format: int64 settledAmountMinor: type: integer format: int64 refundedAmountMinor: type: integer format: int64 currency: $ref: '#/components/schemas/Currency' authorizationExpiresAt: type: string format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable detail. Clients should branch on code. ErrorCode: type: string enum: - invalid_request - unauthenticated - forbidden - identity_conflict - identity_not_found - invalid_credential - credential_conflict - signing_key_mismatch - delegation_not_found - delegation_conflict - delegation_inactive - not_found - method_not_allowed - idempotency_conflict - concurrent_update - internal_error - invalid_command - authority_reference_required - unknown_mechanism - invalid_mechanism_config - market_not_found - commitment_not_found - principal_not_authorized - version_conflict - invalid_market_transition - invalid_commitment_transition - actor_not_authorized - capacity_exhausted - invalid_payment_authorization - payment_authority_required - payment_mandate_exceeded - payment_rail_unavailable - payment_rail_unsupported responses: BadRequest: description: The JSON or command fields are invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Request authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthenticated message: request authentication failed Forbidden: description: The actor or principal is not authorized for this action. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: >- The command conflicts with current state, version, capacity, or idempotency history. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' UnprocessableEntity: description: The mechanism preset is unknown or its configuration is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: The command could not be completed because of an internal failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: AmbientActor: type: apiKey in: header name: X-Ambient-Actor description: Provisioned actor identifier. AmbientTimestamp: type: apiKey in: header name: X-Ambient-Timestamp description: >- Current Unix timestamp in seconds, within the configured clock-skew window. AmbientSignature: type: apiKey in: header name: Authorization description: | Ambient-HMAC followed by a space and the unpadded base64url HMAC-SHA256 signature. See Authentication and authority for the canonical input. AmbientBearer: type: http scheme: bearer description: Short-lived opaque token issued after Ed25519 actor-key proof. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.