openapi: 3.0.3
info:
  title: dLocal Cards Accounts Authorizations API
  version: '2.1'
  description: 'Securely store cards for repeat usage. Create returns a `card_id` token

    that can be used in subsequent Payments and Authorizations.

    '
servers:
- url: https://api.dlocal.com
  description: Production
- url: https://sandbox.dlocal.com
  description: Sandbox
security:
- dLocalSignature: []
tags:
- name: Authorizations
  description: Authorize a card transaction and capture or cancel later.
paths:
  /secure_payments:
    post:
      tags:
      - Authorizations
      operationId: createAuthorization
      summary: Create An Authorization
      description: Authorize a card transaction without capturing funds. Set capture=false on the card object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Authorization created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
  /payments/{authorization_id}/captures:
    post:
      tags:
      - Authorizations
      operationId: captureAuthorization
      summary: Capture An Authorization
      description: Capture funds previously authorized.
      parameters:
      - name: authorization_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                currency:
                  type: string
      responses:
        '200':
          description: Capture successful
  /payments/{authorization_id}/cancel:
    post:
      tags:
      - Authorizations
      operationId: cancelAuthorization
      summary: Cancel An Authorization
      description: Release a previously authorized payment.
      parameters:
      - name: authorization_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Authorization cancelled
components:
  schemas:
    Address:
      type: object
      properties:
        street:
          type: string
        number:
          type: string
        city:
          type: string
        state:
          type: string
        zip_code:
          type: string
        country:
          type: string
    Payer:
      type: object
      required:
      - name
      - email
      - document
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        document:
          type: string
        phone:
          type: string
        birth_date:
          type: string
          format: date
        address:
          $ref: '#/components/schemas/Address'
        ip:
          type: string
        device_id:
          type: string
    PaymentRequest:
      type: object
      required:
      - amount
      - currency
      - country
      - payment_method_flow
      - payer
      - order_id
      properties:
        amount:
          type: number
          description: Transaction amount in the specified currency.
        currency:
          type: string
          description: ISO-4217 three-letter currency code.
          example: BRL
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: BR
        payment_method_id:
          type: string
          description: Local payment method code (e.g. CARD, VI, MC, PIX).
        payment_method_flow:
          type: string
          enum:
          - DIRECT
          - REDIRECT
        payer:
          $ref: '#/components/schemas/Payer'
        card:
          $ref: '#/components/schemas/Card'
        order_id:
          type: string
          description: Merchant-provided order identifier.
        description:
          type: string
        notification_url:
          type: string
          format: uri
        callback_url:
          type: string
          format: uri
    Payment:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
        currency:
          type: string
        country:
          type: string
        payment_method_id:
          type: string
        payment_method_type:
          type: string
        payment_method_flow:
          type: string
        card:
          $ref: '#/components/schemas/Card'
        created_date:
          type: string
          format: date-time
        approved_date:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - PAID
          - PENDING
          - REJECTED
          - CANCELLED
          - AUTHORIZED
          - EXPIRED
          - VERIFIED
          - REFUNDED
        status_code:
          type: string
        status_detail:
          type: string
        order_id:
          type: string
        notification_url:
          type: string
        redirect_url:
          type: string
        refunds:
          type: array
          items:
            type: object
    Card:
      type: object
      properties:
        holder_name:
          type: string
        expiration_month:
          type: integer
          minimum: 1
          maximum: 12
        expiration_year:
          type: integer
        number:
          type: string
        cvv:
          type: string
        brand:
          type: string
        last4:
          type: string
        capture:
          type: boolean
          default: true
        installments:
          type: integer
          default: 1
        token:
          type: string
        encrypted_data:
          type: string
  securitySchemes:
    dLocalSignature:
      type: apiKey
      in: header
      name: Authorization