> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mag3nt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settle a pay link with a closed AP2 Payment Mandate

> Settles a mag3nt pay link by consuming a closed AP2 Payment Mandate (`mandate.payment.1`). The mandate is verified for signature, expiry, and payee scoping against the link; if an open mandate is supplied, the open→closed chain is re-verified. The payer card named by the mandate is authenticated via its card token, then the payer card is debited and the link credited atomically. Idempotent on the mandate `jti` (replay-safe).




## OpenAPI

````yaml /openapi.yaml post /api/ap2/settle
openapi: 3.1.0
info:
  title: mag3nt API
  version: '2026-06-04'
  description: >
    Payment infrastructure for AI agents. Issue virtual cards, pay for API
    access via x402/AP2/MPP protocols, and settle in USDC on Base.
  contact:
    name: mag3nt
    url: https://mag3nt.com
  license:
    name: Proprietary
    url: https://github.com/mag3nt-com/mag3nt-node/blob/main/LICENSE
servers:
  - url: https://mag3nt.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Payments
    description: Universal outbound protocol payments
  - name: Cards
    description: Virtual payment card lifecycle
  - name: Keys
    description: Developer API key management
  - name: Funding
    description: Treasury deposits and balances
  - name: x402
    description: HTTP 402 payment protocol
  - name: AP2
    description: Agent-to-Agent Payment Protocol
  - name: MPP
    description: Micropayment Protocol with streaming
  - name: Pay Links
    description: Shareable payment URLs
  - name: Withdrawals
    description: Withdraw unspent funds back to wallet
  - name: Settlement
    description: On-chain settlement status
  - name: Webhooks
    description: Signed payment.settled notifications for sellers
  - name: Status
    description: System health and configuration
externalDocs:
  description: mag3nt documentation
  url: https://docs.mag3nt.com
paths:
  /api/ap2/settle:
    post:
      tags:
        - AP2
      summary: Settle a pay link with a closed AP2 Payment Mandate
      description: >
        Settles a mag3nt pay link by consuming a closed AP2 Payment Mandate
        (`mandate.payment.1`). The mandate is verified for signature, expiry,
        and payee scoping against the link; if an open mandate is supplied, the
        open→closed chain is re-verified. The payer card named by the mandate is
        authenticated via its card token, then the payer card is debited and the
        link credited atomically. Idempotent on the mandate `jti` (replay-safe).
      operationId: ap2Settle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pay_link_code
                - closed_mandate
                - card_token
              properties:
                pay_link_code:
                  type: string
                  description: Code of the pay link being settled.
                  example: pl_a1b2c3d4
                closed_mandate:
                  type: string
                  description: Closed AP2 Payment Mandate (mandate.payment.1) as an SD-JWT.
                open_mandate:
                  type: string
                  description: >-
                    Optional open AP2 mandate; when present the open→closed
                    chain is re-verified.
                card_token:
                  type: string
                  description: >-
                    Token of the payer card named by the mandate (authorizes the
                    debit).
      responses:
        '200':
          description: Mandate already settled (idempotent replay)
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ALREADY_SETTLED
        '201':
          description: Settlement complete
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: SETTLED, or ALREADY_SETTLED on idempotent replay.
                    example: SETTLED
                  protocol:
                    type: string
                    example: ap2
                  settlement_id:
                    type: string
                  mandate_id:
                    type: string
                    description: The mandate jti the settlement is keyed on.
                  pay_link_code:
                    type: string
                  amount:
                    type:
                      - number
                      - string
                  fee:
                    type:
                      - number
                      - string
                  net_amount:
                    type:
                      - number
                      - string
                  tx_hash:
                    type:
                      - string
                      - 'null'
                  payee:
                    type: string
        '400':
          description: Missing required fields, or the link does not accept AP2
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid card token for the mandate payer card
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Pay link or payer card not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid or out-of-scope mandate, or settlement rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Card not found
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key prefixed with 'Bearer sx_live_...'

````