openapi: 3.1.0
info:
  title: Mercado Pago REST API
  description: |
    Mercado Pago REST API covering payments, Checkout Pro preferences,
    subscriptions (preapprovals), customers, cards, merchant orders, Orders
    API, refunds, chargebacks, claims, reports, Point (POS), QR, and OAuth.
    All requests authenticate with a Bearer access token in the
    `Authorization` header. Webhook deliveries are signed via the
    `x-signature` and `x-request-id` headers.
  version: "v1"
  contact:
    name: Mercado Pago Developers
    url: https://www.mercadopago.com.br/developers/en/reference
  license:
    name: Mercado Pago Terms of Service
    url: https://www.mercadopago.com.br/ayuda/terminos-y-politicas_299
servers:
  - url: https://api.mercadopago.com
    description: Mercado Pago Production API
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: OAuth 2.0 authorisation flows
  - name: Payments
    description: Create, capture, refund, and search payments
  - name: Preferences
    description: Checkout Pro preferences
  - name: Orders
    description: Unified Orders API (next-generation checkout)
  - name: Subscriptions
    description: Recurring preapproval subscriptions
  - name: Plans
    description: Subscription plans
  - name: Customers
    description: Stored customers and addresses
  - name: Cards
    description: Tokenised customer cards
  - name: Merchant Orders
    description: Aggregated preference + payments order resource
  - name: Payment Methods
    description: Discover available payment methods
  - name: Refunds
    description: Refund payments
  - name: Chargebacks
    description: Read chargebacks and disputes
  - name: Claims
    description: Buyer claims, mediations, and evidence
  - name: Reports
    description: Settlement and release reports
  - name: Point
    description: In-person POS (stores, terminals)
  - name: QR
    description: QR-code in-person collection
paths:
  /oauth/token:
    post:
      tags: [Authentication]
      summary: Create Or Refresh An OAuth Token
      operationId: createOauthToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthTokenRequest'
      responses:
        "200":
          description: Access token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'

  /v1/payments:
    post:
      tags: [Payments]
      summary: Create A Payment
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCreateRequest'
      responses:
        "201":
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'

  /v1/payments/search:
    get:
      tags: [Payments]
      summary: Search Payments
      operationId: searchPayments
      parameters:
        - name: status
          in: query
          schema: { type: string }
        - name: external_reference
          in: query
          schema: { type: string }
        - name: range
          in: query
          schema: { type: string, enum: [date_created, date_approved, date_last_updated] }
        - name: begin_date
          in: query
          schema: { type: string, format: date-time }
        - name: end_date
          in: query
          schema: { type: string, format: date-time }
        - name: limit
          in: query
          schema: { type: integer, default: 30, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSearchResults'

  /v1/payments/{id}:
    parameters:
      - $ref: '#/components/parameters/PaymentId'
    get:
      tags: [Payments]
      summary: Get A Payment
      operationId: getPayment
      responses:
        "200":
          description: Payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
    put:
      tags: [Payments]
      summary: Update A Payment
      description: Capture, cancel, or update payment metadata.
      operationId: updatePayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentUpdateRequest'
      responses:
        "200":
          description: Updated payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'

  /v1/payments/{id}/cancel:
    parameters:
      - $ref: '#/components/parameters/PaymentId'
    put:
      tags: [Payments]
      summary: Cancel A Payment
      operationId: cancelPayment
      responses:
        "200":
          description: Cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'

  /v1/payments/{id}/refunds:
    parameters:
      - $ref: '#/components/parameters/PaymentId'
    post:
      tags: [Refunds]
      summary: Refund A Payment
      operationId: refundPayment
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
      responses:
        "201":
          description: Refund created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
    get:
      tags: [Refunds]
      summary: List Refunds For A Payment
      operationId: listRefunds
      responses:
        "200":
          description: Refunds list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Refund'

  /v1/payments/{id}/refunds/{refund_id}:
    parameters:
      - $ref: '#/components/parameters/PaymentId'
      - name: refund_id
        in: path
        required: true
        schema: { type: integer }
    get:
      tags: [Refunds]
      summary: Get A Refund
      operationId: getRefund
      responses:
        "200":
          description: Refund
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'

  /v1/payment_methods:
    get:
      tags: [Payment Methods]
      summary: List Payment Methods
      operationId: listPaymentMethods
      responses:
        "200":
          description: Payment methods
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentMethod'

  /v1/identification_types:
    get:
      tags: [Payment Methods]
      summary: List Identification Types
      operationId: listIdentificationTypes
      responses:
        "200":
          description: Identification types
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdentificationType'

  /checkout/preferences:
    post:
      tags: [Preferences]
      summary: Create A Checkout Preference
      operationId: createPreference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreferenceRequest'
      responses:
        "201":
          description: Preference created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preference'

  /checkout/preferences/search:
    get:
      tags: [Preferences]
      summary: Search Preferences
      operationId: searchPreferences
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                type: object

  /checkout/preferences/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Preferences]
      summary: Get A Preference
      operationId: getPreference
      responses:
        "200":
          description: Preference
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preference'
    put:
      tags: [Preferences]
      summary: Update A Preference
      operationId: updatePreference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreferenceRequest'
      responses:
        "200":
          description: Updated preference
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preference'

  /v1/orders:
    post:
      tags: [Orders]
      summary: Create An Order
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        "201":
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

  /v1/orders/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Orders]
      summary: Get An Order
      operationId: getOrder
      responses:
        "200":
          description: Order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

  /v1/orders/{id}/capture:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [Orders]
      summary: Capture An Order
      operationId: captureOrder
      responses:
        "200":
          description: Captured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

  /v1/orders/{id}/cancel:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [Orders]
      summary: Cancel An Order
      operationId: cancelOrder
      responses:
        "200":
          description: Cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

  /v1/orders/{id}/refund:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [Orders]
      summary: Refund An Order
      operationId: refundOrder
      responses:
        "200":
          description: Refunded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

  /v1/orders/{id}/transactions:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [Orders]
      summary: Add A Transaction To An Order
      operationId: addOrderTransaction
      responses:
        "201":
          description: Transaction added
          content:
            application/json:
              schema:
                type: object

  /preapproval:
    post:
      tags: [Subscriptions]
      summary: Create A Subscription
      operationId: createSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
      responses:
        "201":
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'

  /preapproval/search:
    get:
      tags: [Subscriptions]
      summary: Search Subscriptions
      operationId: searchSubscriptions
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                type: object

  /preapproval/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Subscriptions]
      summary: Get A Subscription
      operationId: getSubscription
      responses:
        "200":
          description: Subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
    put:
      tags: [Subscriptions]
      summary: Update A Subscription
      operationId: updateSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Updated subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'

  /preapproval_plan:
    post:
      tags: [Plans]
      summary: Create A Subscription Plan
      operationId: createPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Plan created

  /preapproval_plan/search:
    get:
      tags: [Plans]
      summary: Search Subscription Plans
      operationId: searchPlans
      responses:
        "200":
          description: Search results

  /preapproval_plan/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Plans]
      summary: Get A Subscription Plan
      operationId: getPlan
      responses:
        "200":
          description: Plan
    put:
      tags: [Plans]
      summary: Update A Subscription Plan
      operationId: updatePlan
      responses:
        "200":
          description: Updated plan

  /v1/customers:
    post:
      tags: [Customers]
      summary: Create A Customer
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        "201":
          description: Customer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'

  /v1/customers/search:
    get:
      tags: [Customers]
      summary: Search Customers
      operationId: searchCustomers
      responses:
        "200":
          description: Search results

  /v1/customers/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Customers]
      summary: Get A Customer
      operationId: getCustomer
      responses:
        "200":
          description: Customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
    put:
      tags: [Customers]
      summary: Update A Customer
      operationId: updateCustomer
      responses:
        "200":
          description: Updated customer

  /v1/customers/{customer_id}/cards:
    parameters:
      - name: customer_id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [Cards]
      summary: Save A Card For A Customer
      operationId: saveCustomerCard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
              required: [token]
      responses:
        "201":
          description: Card saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
    get:
      tags: [Cards]
      summary: List Customer Cards
      operationId: listCustomerCards
      responses:
        "200":
          description: Cards
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Card'

  /v1/customers/{customer_id}/cards/{card_id}:
    parameters:
      - name: customer_id
        in: path
        required: true
        schema: { type: string }
      - name: card_id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Cards]
      summary: Get A Customer Card
      operationId: getCustomerCard
      responses:
        "200":
          description: Card
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
    delete:
      tags: [Cards]
      summary: Delete A Customer Card
      operationId: deleteCustomerCard
      responses:
        "200":
          description: Deleted

  /merchant_orders:
    post:
      tags: [Merchant Orders]
      summary: Create A Merchant Order
      operationId: createMerchantOrder
      responses:
        "201":
          description: Merchant order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantOrder'

  /merchant_orders/search:
    get:
      tags: [Merchant Orders]
      summary: Search Merchant Orders
      operationId: searchMerchantOrders
      responses:
        "200":
          description: Search results

  /merchant_orders/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer }
    get:
      tags: [Merchant Orders]
      summary: Get A Merchant Order
      operationId: getMerchantOrder
      responses:
        "200":
          description: Merchant order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantOrder'
    put:
      tags: [Merchant Orders]
      summary: Update A Merchant Order
      operationId: updateMerchantOrder
      responses:
        "200":
          description: Updated merchant order

  /v1/chargebacks/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer }
    get:
      tags: [Chargebacks]
      summary: Get A Chargeback
      operationId: getChargeback
      responses:
        "200":
          description: Chargeback
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'

  /v1/claims/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer }
    get:
      tags: [Claims]
      summary: Get A Claim
      operationId: getClaim
      responses:
        "200":
          description: Claim
          content:
            application/json:
              schema:
                type: object

  /v1/claims/search:
    get:
      tags: [Claims]
      summary: Search Claims
      operationId: searchClaims
      responses:
        "200":
          description: Search results

  /v1/account/release:
    post:
      tags: [Reports]
      summary: Generate A Release Report
      operationId: createReleaseReport
      responses:
        "201":
          description: Report created
    get:
      tags: [Reports]
      summary: List Release Reports
      operationId: listReleaseReports
      responses:
        "200":
          description: Reports list

  /v1/account/release/{id}/download:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Reports]
      summary: Download A Release Report
      operationId: downloadReleaseReport
      responses:
        "200":
          description: Report file

  /v1/stores:
    post:
      tags: [Point]
      summary: Create A Store
      operationId: createStore
      responses:
        "201":
          description: Store created
    get:
      tags: [Point]
      summary: Search Stores
      operationId: searchStores
      responses:
        "200":
          description: Stores

  /v1/stores/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer }
    get:
      tags: [Point]
      summary: Get A Store
      operationId: getStore
      responses:
        "200":
          description: Store
    put:
      tags: [Point]
      summary: Update A Store
      operationId: updateStore
      responses:
        "200":
          description: Updated store
    delete:
      tags: [Point]
      summary: Delete A Store
      operationId: deleteStore
      responses:
        "200":
          description: Deleted

  /pos:
    post:
      tags: [Point]
      summary: Create A Point Of Sale
      operationId: createPos
      responses:
        "201":
          description: POS created
    get:
      tags: [Point]
      summary: Search Points Of Sale
      operationId: searchPos
      responses:
        "200":
          description: POS list

  /pos/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer }
    get:
      tags: [Point]
      summary: Get A Point Of Sale
      operationId: getPos
      responses:
        "200":
          description: POS
    put:
      tags: [Point]
      summary: Update A Point Of Sale
      operationId: updatePos
      responses:
        "200":
          description: Updated POS
    delete:
      tags: [Point]
      summary: Delete A Point Of Sale
      operationId: deletePos
      responses:
        "200":
          description: Deleted

  /point/integration-api/devices:
    get:
      tags: [Point]
      summary: List Point Terminals
      operationId: listTerminals
      responses:
        "200":
          description: Terminals

  /instore/qr/seller/collectors/{user_id}/pos/{external_pos_id}/orders:
    parameters:
      - name: user_id
        in: path
        required: true
        schema: { type: integer }
      - name: external_pos_id
        in: path
        required: true
        schema: { type: string }
    put:
      tags: [QR]
      summary: Create A QR Order
      description: Create or replace the QR order for an in-person point of sale.
      operationId: createQrOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "204":
          description: QR order created
    delete:
      tags: [QR]
      summary: Delete A QR Order
      operationId: deleteQrOrder
      responses:
        "204":
          description: QR order deleted

components:
  parameters:
    PaymentId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64
        example: 1234567890

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: access_token
      description: |
        Mercado Pago access token. Send as `Authorization: Bearer {ACCESS_TOKEN}`.
        HTTPS is required. Idempotency is supported via the `X-Idempotency-Key`
        header on POST/PUT operations.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.mercadopago.com/authorization
          tokenUrl: https://api.mercadopago.com/oauth/token
          scopes:
            offline_access: Persistent refresh token
            read: Read merchant data
            write: Write merchant data

  schemas:
    OAuthTokenRequest:
      type: object
      required: [grant_type, client_id, client_secret]
      properties:
        grant_type:
          type: string
          enum: [authorization_code, refresh_token, client_credentials]
        client_id: { type: string }
        client_secret: { type: string }
        code: { type: string }
        refresh_token: { type: string }
        redirect_uri: { type: string, format: uri }

    OAuthTokenResponse:
      type: object
      properties:
        access_token: { type: string }
        token_type: { type: string, example: bearer }
        expires_in: { type: integer }
        scope: { type: string }
        user_id: { type: integer }
        refresh_token: { type: string }
        public_key: { type: string }
        live_mode: { type: boolean }

    Payment:
      type: object
      properties:
        id: { type: integer, format: int64 }
        date_created: { type: string, format: date-time }
        date_approved: { type: string, format: date-time, nullable: true }
        date_last_updated: { type: string, format: date-time }
        money_release_date: { type: string, format: date-time, nullable: true }
        status:
          type: string
          enum: [pending, approved, authorized, in_process, in_mediation, rejected, cancelled, refunded, charged_back]
        status_detail: { type: string }
        currency_id: { type: string, example: BRL }
        description: { type: string }
        transaction_amount: { type: number, format: double }
        transaction_amount_refunded: { type: number, format: double }
        payment_method_id: { type: string, example: pix }
        payment_type_id:
          type: string
          enum: [credit_card, debit_card, ticket, bank_transfer, atm, account_money, digital_currency, digital_wallet, prepaid_card]
        installments: { type: integer }
        external_reference: { type: string }
        payer:
          $ref: '#/components/schemas/Payer'
        metadata:
          type: object
          additionalProperties: true

    PaymentCreateRequest:
      type: object
      required: [transaction_amount, payment_method_id, payer]
      properties:
        transaction_amount: { type: number, format: double }
        token: { type: string }
        description: { type: string }
        installments: { type: integer, minimum: 1, default: 1 }
        payment_method_id: { type: string, example: visa }
        issuer_id: { type: string }
        external_reference: { type: string }
        statement_descriptor: { type: string }
        notification_url: { type: string, format: uri }
        capture: { type: boolean, default: true }
        binary_mode: { type: boolean, default: false }
        payer:
          $ref: '#/components/schemas/Payer'
        metadata:
          type: object
          additionalProperties: true

    PaymentUpdateRequest:
      type: object
      properties:
        status:
          type: string
          enum: [cancelled]
        capture: { type: boolean }
        transaction_amount: { type: number, format: double }

    PaymentSearchResults:
      type: object
      properties:
        paging:
          type: object
          properties:
            total: { type: integer }
            limit: { type: integer }
            offset: { type: integer }
        results:
          type: array
          items:
            $ref: '#/components/schemas/Payment'

    Payer:
      type: object
      properties:
        id: { type: string }
        type: { type: string, enum: [customer, guest, registered] }
        email: { type: string, format: email }
        first_name: { type: string }
        last_name: { type: string }
        identification:
          type: object
          properties:
            type: { type: string, example: CPF }
            number: { type: string }

    Refund:
      type: object
      properties:
        id: { type: integer, format: int64 }
        payment_id: { type: integer, format: int64 }
        amount: { type: number, format: double }
        source:
          type: object
          properties:
            id: { type: string }
            name: { type: string }
            type: { type: string }
        date_created: { type: string, format: date-time }
        status: { type: string, enum: [approved, rejected, in_process] }
        unique_sequence_number: { type: string, nullable: true }

    RefundRequest:
      type: object
      properties:
        amount:
          type: number
          format: double
          description: Optional partial refund amount. Omit for a full refund.

    PaymentMethod:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        payment_type_id: { type: string }
        status: { type: string }
        secure_thumbnail: { type: string, format: uri }
        thumbnail: { type: string, format: uri }
        deferred_capture: { type: string }
        settings:
          type: array
          items:
            type: object

    IdentificationType:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        type: { type: string }
        min_length: { type: integer }
        max_length: { type: integer }

    Preference:
      type: object
      properties:
        id: { type: string }
        client_id: { type: string }
        collector_id: { type: integer }
        date_created: { type: string, format: date-time }
        external_reference: { type: string }
        init_point: { type: string, format: uri }
        sandbox_init_point: { type: string, format: uri }
        items:
          type: array
          items:
            $ref: '#/components/schemas/PreferenceItem'
        payer:
          $ref: '#/components/schemas/Payer'
        back_urls:
          type: object
          properties:
            success: { type: string, format: uri }
            pending: { type: string, format: uri }
            failure: { type: string, format: uri }
        auto_return: { type: string, enum: [approved, all] }
        notification_url: { type: string, format: uri }

    PreferenceRequest:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PreferenceItem'
        payer:
          $ref: '#/components/schemas/Payer'
        back_urls:
          type: object
          properties:
            success: { type: string, format: uri }
            pending: { type: string, format: uri }
            failure: { type: string, format: uri }
        auto_return: { type: string, enum: [approved, all] }
        notification_url: { type: string, format: uri }
        external_reference: { type: string }
        expires: { type: boolean }
        expiration_date_from: { type: string, format: date-time }
        expiration_date_to: { type: string, format: date-time }

    PreferenceItem:
      type: object
      required: [title, quantity, unit_price]
      properties:
        id: { type: string }
        title: { type: string }
        description: { type: string }
        picture_url: { type: string, format: uri }
        category_id: { type: string }
        quantity: { type: integer, minimum: 1 }
        currency_id: { type: string, example: BRL }
        unit_price: { type: number, format: double }

    Order:
      type: object
      properties:
        id: { type: string }
        type: { type: string, enum: [online, point] }
        external_reference: { type: string }
        total_amount: { type: string }
        status:
          type: string
          enum: [created, processed, partially_processed, action_required, cancelled, refunded]
        status_detail: { type: string }
        capture_mode: { type: string, enum: [automatic, manual] }
        transactions:
          type: object
          properties:
            payments:
              type: array
              items:
                type: object

    OrderRequest:
      type: object
      required: [type, total_amount, external_reference]
      properties:
        type: { type: string, enum: [online, point] }
        external_reference: { type: string }
        total_amount: { type: string }
        capture_mode: { type: string, enum: [automatic, manual], default: automatic }
        processing_mode: { type: string, enum: [automatic, manual], default: automatic }
        payer:
          $ref: '#/components/schemas/Payer'
        transactions:
          type: object
          additionalProperties: true

    Subscription:
      type: object
      properties:
        id: { type: string }
        payer_id: { type: integer }
        payer_email: { type: string, format: email }
        back_url: { type: string, format: uri }
        reason: { type: string }
        external_reference: { type: string }
        status:
          type: string
          enum: [pending, authorized, paused, cancelled, finished]
        date_created: { type: string, format: date-time }
        last_modified: { type: string, format: date-time }
        next_payment_date: { type: string, format: date-time }
        auto_recurring:
          $ref: '#/components/schemas/AutoRecurring'

    SubscriptionRequest:
      type: object
      required: [reason, auto_recurring, payer_email]
      properties:
        preapproval_plan_id: { type: string }
        reason: { type: string }
        external_reference: { type: string }
        payer_email: { type: string, format: email }
        card_token_id: { type: string }
        back_url: { type: string, format: uri }
        status: { type: string, enum: [authorized, pending] }
        auto_recurring:
          $ref: '#/components/schemas/AutoRecurring'

    AutoRecurring:
      type: object
      properties:
        frequency: { type: integer }
        frequency_type: { type: string, enum: [days, months] }
        start_date: { type: string, format: date-time }
        end_date: { type: string, format: date-time }
        transaction_amount: { type: number, format: double }
        currency_id: { type: string, example: BRL }
        free_trial:
          type: object
          properties:
            frequency: { type: integer }
            frequency_type: { type: string }

    Customer:
      type: object
      properties:
        id: { type: string }
        email: { type: string, format: email }
        first_name: { type: string }
        last_name: { type: string }
        identification:
          type: object
          properties:
            type: { type: string }
            number: { type: string }
        phone:
          type: object
          properties:
            area_code: { type: string }
            number: { type: string }
        date_registered: { type: string, format: date-time }
        date_last_updated: { type: string, format: date-time }
        live_mode: { type: boolean }

    CustomerRequest:
      type: object
      required: [email]
      properties:
        email: { type: string, format: email }
        first_name: { type: string }
        last_name: { type: string }
        phone:
          type: object
          properties:
            area_code: { type: string }
            number: { type: string }
        identification:
          type: object
          properties:
            type: { type: string }
            number: { type: string }
        description: { type: string }

    Card:
      type: object
      properties:
        id: { type: string }
        customer_id: { type: string }
        expiration_month: { type: integer }
        expiration_year: { type: integer }
        first_six_digits: { type: string }
        last_four_digits: { type: string }
        payment_method:
          type: object
          properties:
            id: { type: string }
            name: { type: string }
        security_code:
          type: object
          properties:
            length: { type: integer }
            card_location: { type: string }
        issuer:
          type: object
          properties:
            id: { type: integer }
            name: { type: string }
        cardholder:
          type: object
          properties:
            name: { type: string }
            identification:
              type: object
              properties:
                type: { type: string }
                number: { type: string }
        date_created: { type: string, format: date-time }
        date_last_updated: { type: string, format: date-time }

    MerchantOrder:
      type: object
      properties:
        id: { type: integer, format: int64 }
        preference_id: { type: string }
        external_reference: { type: string }
        site_id: { type: string }
        status: { type: string, enum: [opened, closed, expired] }
        order_status:
          type: string
          enum: [payment_required, payment_in_process, paid, partially_paid, partially_refunded, refunded, expired]
        total_amount: { type: number, format: double }
        paid_amount: { type: number, format: double }
        items:
          type: array
          items:
            $ref: '#/components/schemas/PreferenceItem'
        payments:
          type: array
          items:
            type: object

    Chargeback:
      type: object
      properties:
        id: { type: integer, format: int64 }
        payments: { type: array, items: { type: integer } }
        date_created: { type: string, format: date-time }
        date_last_updated: { type: string, format: date-time }
        currency_id: { type: string }
        amount: { type: number, format: double }
        status:
          type: string
          enum: [pending, in_mediation, won, lost, refunded, expired]
        reason: { type: string }
        liable_party:
          type: string
          enum: [collector, mercadopago, insurance]