> ## Documentation Index > Fetch the complete documentation index at: https://docs.vantr.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update an order payment, adjust an authorization, or capture it > While a payment is an AUTHORIZED hold: PATCH amount_money to raise or lower the authorization (incremental/decremental auth), or PATCH status to COMPLETED — optionally with a lower amount_money — to capture the final total; the unused remainder is recorded as released, and capturing above the hold returns 409 (increase the authorization first). PATCH status to VOIDED or FAILED to release the hold. Otherwise updates are non-financial only: status within PENDING to COMPLETED, FAILED, or VOIDED (and COMPLETED to VOIDED), external_payment_id, and metadata. Outside an AUTHORIZED hold, amount, currency, and payment_type are immutable. ## OpenAPI ````yaml /openapi/v2.json patch /v2/orders/{orderId}/payments/{paymentId} openapi: 3.0.3 info: title: Vantr Developer API version: v2 description: >- OAuth 2.0 developer access for Vantr v2 APIs on api.vantr.ai. Developer API for v2 integrations with scoped access to supported resources. Vantr uses vantr.ai for marketing, app.vantr.ai for the web application, and api.vantr.ai for API traffic. The developer portal and public docs are first-class API-host experiences at api.vantr.ai/developer and api.vantr.ai/docs. The application and business API uses /v1 on api.vantr.ai. Third-party integrations use /v2 on api.vantr.ai. The current v2 API includes scoped access for products, product variations, product and variation tags, categories and subcategories, vendors, tenant locations, orders with order payments, and usage reporting. Bills are a planned public resource with constrained lifecycle rules. Server-side callers may use OAuth bearer tokens, direct confidential-client Basic authentication with client_id and client_secret, or the x-client-id/x-client-secret header pair (the legacy x-invoiceedge-client-id/x-invoiceedge-client-secret names remain accepted). Requests are rate limited per credential (240/min on /v2, 60/min on the OAuth token endpoints) with RateLimit-* response headers and 429 + Retry-After when exceeded. /v2 behavior is versioned by release date: send the X-API-Version header (YYYY-MM-DD) to pin a release, or omit it to use the latest. Unknown versions return 400 unsupported_api_version, and the resolved version is echoed in the X-API-Version response header. servers: - url: https://api.vantr.ai description: Vantr API - url: http://localhost:8080 description: Local development security: [] tags: - name: OAuth description: OAuth 2.0 token, revocation, and introspection endpoints. - name: Capabilities description: Discover v2 developer resource capabilities. - name: Products description: Product, variation, tag, and catalog metadata APIs. - name: Categories description: Category, subcategory, and classification metadata APIs. - name: Vendors description: Vendor profile APIs. - name: Locations description: Read-only tenant location APIs for public location_id discovery. - name: Orders description: Order and order-payment APIs with lifecycle-constrained writes. - name: Webhooks description: Register webhook endpoints and subscribe to event streams. - name: Usage description: Public API usage reporting. externalDocs: description: Vantr public API guide, route catalog, and SDK starters. url: https://api.vantr.ai/docs paths: /v2/orders/{orderId}/payments/{paymentId}: patch: tags: - Orders summary: Update an order payment, adjust an authorization, or capture it description: >- While a payment is an AUTHORIZED hold: PATCH amount_money to raise or lower the authorization (incremental/decremental auth), or PATCH status to COMPLETED — optionally with a lower amount_money — to capture the final total; the unused remainder is recorded as released, and capturing above the hold returns 409 (increase the authorization first). PATCH status to VOIDED or FAILED to release the hold. Otherwise updates are non-financial only: status within PENDING to COMPLETED, FAILED, or VOIDED (and COMPLETED to VOIDED), external_payment_id, and metadata. Outside an AUTHORIZED hold, amount, currency, and payment_type are immutable. operationId: updateOrderPayment parameters: - name: X-API-Version in: header required: false description: >- Pin a dated API release (YYYY-MM-DD). Omit for the latest (2026-06-09). Unknown values return 400 unsupported_api_version; the resolved version is echoed back in the X-API-Version response header. schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-06-09' - name: orderId in: path required: true schema: type: string format: uuid - name: paymentId in: path required: true schema: type: string format: uuid responses: '200': description: Payment updated. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '409': description: Payment status transition is not allowed. security: - OAuth2: - orders.write - BasicClientAuth: [] components: responses: BadRequest: description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' schemas: ErrorResponse: type: object properties: success: type: boolean example: false code: type: string message: type: string securitySchemes: OAuth2: type: oauth2 description: >- OAuth 2.0 with opaque bearer tokens. Authorization-code requests require PKCE S256. flows: authorizationCode: authorizationUrl: https://api.vantr.ai/oauth/authorize tokenUrl: https://api.vantr.ai/oauth/token refreshUrl: https://api.vantr.ai/oauth/token scopes: usage.read: Read API usage totals for the tenant. products.read: Read products, product variations, tags, and catalog metadata. products.write: Create, update, tag, and archive products and product variations. categories.read: Read product categories, subcategories, and category metadata. categories.write: Create, update, and archive product categories and subcategories. vendors.read: Read vendor profiles. vendors.write: Create, update, and deactivate vendor profiles. orders.read: >- Read orders, order items, reconciliation issues, and sales activity. orders.write: >- Create or update orders, reconciliation, refresh, and sync workflow records. locations.read: Read tenant locations for location_id discovery. webhooks.read: Read webhook endpoints, event subscriptions, and delivery state. webhooks.write: >- Create, update, rotate, or revoke webhook endpoints and event subscriptions. clientCredentials: tokenUrl: https://api.vantr.ai/oauth/token scopes: usage.read: Read API usage totals for the tenant. products.read: Read products, product variations, tags, and catalog metadata. products.write: Create, update, tag, and archive products and product variations. categories.read: Read product categories, subcategories, and category metadata. categories.write: Create, update, and archive product categories and subcategories. vendors.read: Read vendor profiles. vendors.write: Create, update, and deactivate vendor profiles. orders.read: >- Read orders, order items, reconciliation issues, and sales activity. orders.write: >- Create or update orders, reconciliation, refresh, and sync workflow records. locations.read: Read tenant locations for location_id discovery. webhooks.read: Read webhook endpoints, event subscriptions, and delivery state. webhooks.write: >- Create, update, rotate, or revoke webhook endpoints and event subscriptions. BasicClientAuth: type: http scheme: basic description: >- Use client_id as username and client_secret as password for confidential server-side calls. The application allowed_scopes still gate each /v2 endpoint; never use this secret in browsers, mobile apps, logs, or query strings. Server integrations may alternatively send x-client-id and x-client-secret headers (the legacy x-invoiceedge-* names remain accepted). ````