openapi: 3.0.1
info:
  title: Pagar.me Core Anticipations Orders API
  description: The Pagar.me Core API (v5) is a REST API for online payments in Brazil. It processes orders and charges via credit card, PIX, and boleto; manages customers, addresses, cards, and tokens; supports recurring billing through plans, subscriptions, and invoices; and provides marketplace capabilities via recipients, split, transfers, and anticipations, with webhook event notifications. Authentication uses HTTP Basic auth with the account secret key as the username and an empty password.
  termsOfService: https://pagar.me/termos-de-uso/
  contact:
    name: Pagar.me Support
    url: https://docs.pagar.me
  version: '5'
servers:
- url: https://api.pagar.me/core/v5
  description: Pagar.me Core API v5 production
security:
- basicAuth: []
tags:
- name: Orders
  description: Top-level checkout objects bundling customer, items, and payments.
paths:
  /orders:
    post:
      operationId: createOrder
      tags:
      - Orders
      summary: Create order
      description: Creates an order, bundling customer, items, and payments. Generates one or more charges.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    get:
      operationId: listOrders
      tags:
      - Orders
      summary: List orders
      description: Returns a paginated list of orders.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: A list of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
  /orders/{order_id}:
    get:
      operationId: getOrder
      tags:
      - Orders
      summary: Get order
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{order_id}/closed:
    patch:
      operationId: closeOrder
      tags:
      - Orders
      summary: Close or reopen an order
      parameters:
      - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - open
                  - closed
      responses:
        '200':
          description: The updated order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    Address:
      type: object
      properties:
        line_1:
          type: string
        line_2:
          type: string
        zip_code:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
    OrderItem:
      type: object
      properties:
        amount:
          type: integer
          description: Unit amount in cents.
        description:
          type: string
        quantity:
          type: integer
        code:
          type: string
    Customer:
      allOf:
      - $ref: '#/components/schemas/CreateCustomerRequest'
      - type: object
        properties:
          id:
            type: string
          created_at:
            type: string
            format: date-time
    BoletoPayment:
      type: object
      properties:
        instructions:
          type: string
        due_at:
          type: string
          format: date-time
    Payment:
      type: object
      properties:
        payment_method:
          type: string
          enum:
          - credit_card
          - debit_card
          - boleto
          - pix
        amount:
          type: integer
        credit_card:
          $ref: '#/components/schemas/CreditCardPayment'
        boleto:
          $ref: '#/components/schemas/BoletoPayment'
        pix:
          $ref: '#/components/schemas/PixPayment'
        split:
          type: array
          items:
            $ref: '#/components/schemas/Split'
    Split:
      type: object
      properties:
        amount:
          type: integer
        recipient_id:
          type: string
        type:
          type: string
          enum:
          - flat
          - percentage
        options:
          type: object
          properties:
            charge_processing_fee:
              type: boolean
            liable:
              type: boolean
    CardInput:
      type: object
      properties:
        number:
          type: string
        holder_name:
          type: string
        exp_month:
          type: integer
        exp_year:
          type: integer
        cvv:
          type: string
        billing_address:
          $ref: '#/components/schemas/Address'
    CreateOrderRequest:
      type: object
      required:
      - items
      - payments
      properties:
        code:
          type: string
          description: Merchant order identifier.
        customer_id:
          type: string
        customer:
          $ref: '#/components/schemas/CreateCustomerRequest'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        shipping:
          $ref: '#/components/schemas/Shipping'
        closed:
          type: boolean
        metadata:
          type: object
          additionalProperties:
            type: string
    Shipping:
      type: object
      properties:
        amount:
          type: integer
        description:
          type: string
        recipient_name:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    CreditCardPayment:
      type: object
      properties:
        installments:
          type: integer
        statement_descriptor:
          type: string
        card_id:
          type: string
        card_token:
          type: string
        card:
          $ref: '#/components/schemas/CardInput'
    PixPayment:
      type: object
      properties:
        expires_in:
          type: integer
          description: Expiration in seconds.
        additional_information:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
    OrderList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        paging:
          $ref: '#/components/schemas/Paging'
    Charge:
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        amount:
          type: integer
        paid_amount:
          type: integer
        status:
          type: string
          enum:
          - pending
          - paid
          - canceled
          - processing
          - failed
          - overpaid
          - underpaid
        currency:
          type: string
        payment_method:
          type: string
        order_id:
          type: string
        customer:
          $ref: '#/components/schemas/Customer'
        last_transaction:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    CreateCustomerRequest:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        document:
          type: string
          description: CPF or CNPJ.
        document_type:
          type: string
          enum:
          - CPF
          - CNPJ
          - PASSPORT
        type:
          type: string
          enum:
          - individual
          - company
        phones:
          type: object
          properties:
            home_phone:
              $ref: '#/components/schemas/Phone'
            mobile_phone:
              $ref: '#/components/schemas/Phone'
        address:
          $ref: '#/components/schemas/Address'
    Order:
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        amount:
          type: integer
        currency:
          type: string
        status:
          type: string
        customer:
          $ref: '#/components/schemas/Customer'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        charges:
          type: array
          items:
            $ref: '#/components/schemas/Charge'
        created_at:
          type: string
          format: date-time
    Phone:
      type: object
      properties:
        country_code:
          type: string
        area_code:
          type: string
        number:
          type: string
    Paging:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        size:
          type: integer
  parameters:
    OrderId:
      name: order_id
      in: path
      required: true
      schema:
        type: string
    Size:
      name: size
      in: query
      schema:
        type: integer
        default: 10
    Page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth with the account secret key as the username and an empty password.