openapi: 3.0.3
info:
  title: dLocal Payins Accounts Payouts API
  description: 'Accept payments from customers in emerging markets using 1,000+ local payment methods including cards, bank transfers, cash, mobile money, eWallets, and Pix. Supports 3D Secure, installments, recurring payments, merchant-initiated transactions, and authorization/capture flows.

    '
  version: '2.1'
  contact:
    name: dLocal Developer Support
    url: https://docs.dlocal.com/
  termsOfService: https://www.dlocal.com/terms-of-service/
servers:
- url: https://api.dlocal.com
  description: Production
- url: https://sandbox.dlocal.com
  description: Sandbox
security:
- HmacAuth: []
tags:
- name: Payouts
  description: Submit and manage disbursements
paths:
  /payouts:
    post:
      summary: Submit a Payout
      description: 'Submit a payout to a recipient in an emerging market country. Supports bank transfers, mobile money, and other local disbursement methods.

        '
      operationId: createPayout
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutRequest'
            example:
              login: merchant_login
              trans_key: merchant_trans_key
              request_id: REQ-001
              currency: USD
              amount: 250.0
              country: BR
              beneficiary:
                name: Maria Silva
                lastname: Silva
                document: '12345678901'
                email: maria@example.com
                bank_account:
                  type: C
                  number: 12345-6
                  agency: '0001'
                  bank_code: '341'
              payment_method_id: BT
              notification_url: https://webhook.site/payout-notify
      responses:
        '200':
          description: Payout submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /payouts/{payout_id}:
    get:
      summary: Retrieve a Payout
      description: Get status and details of a specific payout.
      operationId: getPayout
      tags:
      - Payouts
      parameters:
      - name: payout_id
        in: path
        required: true
        schema:
          type: string
          example: PO-123456789
      responses:
        '200':
          description: Payout retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '404':
          description: Payout not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /payouts/merchant_request_id/{request_id}:
    get:
      summary: Retrieve a Payout by Request ID
      description: Retrieve payout details using the merchant's own request identifier.
      operationId: getPayoutByRequestId
      tags:
      - Payouts
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Payout retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
  /payouts/{payout_id}/cancel:
    post:
      summary: Cancel a Payout
      description: Cancel a pending payout that has not yet been processed.
      operationId: cancelPayout
      tags:
      - Payouts
      parameters:
      - name: payout_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Payout cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
  /payouts/{payout_id}/release:
    post:
      summary: Release a Payout
      description: Release a payout that was held for compliance review.
      operationId: releasePayout
      tags:
      - Payouts
      parameters:
      - name: payout_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Payout released
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
components:
  schemas:
    MobileWallet:
      type: object
      properties:
        phone:
          type: string
        provider:
          type: string
    CreatePayoutRequest:
      type: object
      required:
      - request_id
      - currency
      - amount
      - country
      - beneficiary
      - payment_method_id
      properties:
        login:
          type: string
          description: Merchant login (may be in header instead)
        trans_key:
          type: string
          description: Transaction key (may be in header instead)
        request_id:
          type: string
          description: Unique merchant-assigned identifier for this payout
          example: REQ-001
        currency:
          type: string
          description: ISO 4217 currency code
          example: USD
        amount:
          type: number
          format: float
          description: Payout amount
          example: 250.0
        amount_in_usd:
          type: number
          format: float
          description: Amount in USD equivalent
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: BR
        payment_method_id:
          type: string
          description: 'Payment method code (e.g. BT for bank transfer, MM for mobile money)

            '
          example: BT
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        comment:
          type: string
          description: Internal comment for the payout
        notification_url:
          type: string
          format: uri
          description: Webhook URL for payout status notifications
        purpose:
          type: string
          description: Purpose of the payout for compliance
        fx_quote_id:
          type: string
          description: FX quote ID to lock in exchange rate
    BankAccount:
      type: object
      properties:
        type:
          type: string
          enum:
          - C
          - S
          description: Account type - C for Checking, S for Savings
        number:
          type: string
        agency:
          type: string
        bank_code:
          type: string
        clabe:
          type: string
          description: CLABE number for Mexico
        iban:
          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
    Beneficiary:
      type: object
      required:
      - name
      - document
      properties:
        name:
          type: string
          example: Maria Silva
        lastname:
          type: string
        document:
          type: string
          description: National ID or tax document
          example: '12345678901'
        document_type:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        bank_account:
          $ref: '#/components/schemas/BankAccount'
        mobile_wallet:
          $ref: '#/components/schemas/MobileWallet'
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        param:
          type: string
    Payout:
      type: object
      properties:
        id:
          type: string
          description: dLocal payout identifier
          example: PO-123456789
        request_id:
          type: string
        amount:
          type: number
          format: float
        currency:
          type: string
        country:
          type: string
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        payment_method_id:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - PROCESSING
          - PAID
          - REJECTED
          - CANCELLED
          - HELD
          description: Current payout status
        status_code:
          type: string
        status_detail:
          type: string
        created_date:
          type: string
          format: date-time
        updated_date:
          type: string
          format: date-time
        transaction_id:
          type: string
  securitySchemes:
    HmacAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'HMAC-SHA256 signature. Format: "V2-HMAC-SHA256, Signature: {hmac_value}" Signature = HMAC-SHA256(X-Login + X-Date + RequestBody, SecretKey)

        '