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: []