openapi: 3.0.3
info:
  title: dLocal Payments API
  version: '2.1'
  description: |
    The dLocal Payments API (Payins) lets you create, retrieve, cancel, and
    authorize payments using over 1,000 local payment methods across 60+
    emerging-market countries in Latin America, Africa, and Asia. Supports
    card payments, Pix, UPI, M-Pesa, bank transfers, cash vouchers, digital
    wallets, BNPL, and QR codes. All requests are authenticated with the
    `V2-HMAC-SHA256` signature scheme using `X-Login`, `X-Trans-Key`, and
    `X-Date` headers.
  contact:
    name: dLocal Support
    url: https://docs.dlocal.com/
  license:
    name: Proprietary
    url: https://dlocal.com/terms-and-conditions/
servers:
  - url: https://api.dlocal.com
    description: Production
  - url: https://sandbox.dlocal.com
    description: Sandbox
tags:
  - name: Payments
    description: Create and manage payments using local payment methods.
  - name: Authorizations
    description: Authorize a card transaction and capture or cancel later.
paths:
  /payments:
    post:
      tags: [Payments]
      operationId: createPayment
      summary: Create A Payment
      description: Create a new payment using a local payment method in the target country.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /payments/{payment_id}:
    get:
      tags: [Payments]
      operationId: retrievePayment
      summary: Retrieve A Payment
      description: Retrieve full payment details. Payments older than 12 months may return 404.
      parameters:
        - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: Payment found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '404':
          $ref: '#/components/responses/NotFound'
  /payments/{payment_id}/status:
    get:
      tags: [Payments]
      operationId: retrievePaymentStatus
      summary: Retrieve A Payment Status
      description: Retrieve a lightweight status snapshot of a payment.
      parameters:
        - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: Status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatus'
  /payments/{payment_id}/cancel:
    post:
      tags: [Payments]
      operationId: cancelAlternativePayment
      summary: Cancel An Alternative Payment
      description: Cancel a pending alternative (non-card) payment such as a cash ticket or bank transfer.
      parameters:
        - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: Payment cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
  /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
  /payment-methods:
    get:
      tags: [Payments]
      operationId: searchPaymentMethods
      summary: Search Payment Methods
      description: List supported payment methods for a country and currency.
      parameters:
        - name: country
          in: query
          required: true
          schema: { type: string, example: BR }
      responses:
        '200':
          description: Payment methods returned
components:
  parameters:
    PaymentId:
      name: payment_id
      in: path
      required: true
      schema: { type: string }
  schemas:
    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
    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 }
    Address:
      type: object
      properties:
        street: { type: string }
        number: { type: string }
        city: { type: string }
        state: { type: string }
        zip_code: { type: string }
        country: { type: string }
    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 }
    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 }
    PaymentStatus:
      type: object
      properties:
        id: { type: string }
        status: { type: string }
        status_code: { type: string }
        status_detail: { type: string }
    Error:
      type: object
      properties:
        code: { type: integer }
        message: { type: string }
        param: { type: string }
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Invalid credentials or signature
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  securitySchemes:
    dLocalSignature:
      type: apiKey
      in: header
      name: Authorization
      description: |
        `V2-HMAC-SHA256, Signature: <hmac(secret_key, X-Login+X-Date+RequestBody)>`
        accompanied by `X-Login`, `X-Trans-Key`, `X-Date`, and `X-Version: 2.1` headers.
security:
  - dLocalSignature: []