dLocal Payments API

openapi: 3.0.3
info:
  title: dLocal Cards Accounts Payments 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: Payments
  description: Create and manage payments using local payment methods.
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'
  /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:
  schemas:
    Address:
      type: object
      properties:
        street:
          type: string
        number:
          type: string
        city:
          type: string
        state:
          type: string
        zip_code:
          type: string
        country:
          type: string
    PaymentStatus:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        status_code:
          type: string
        status_detail:
          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
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        param:
          type: string
  responses:
    Unauthorized:
      description: Invalid credentials or signature
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    PaymentId:
      name: payment_id
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    dLocalSignature:
      type: apiKey
      in: header
      name: Authorization