dLocal

Adapter 0.1.0, documentation reviewed 2026-10-25. Overall status: limited.

Capabilities

Supported input

Notification delivery

• Repeated deliveries are recognized by none documented (notifications carry no event id, delivery id or event type); dLocal documents that notifications can be delivered more than once.
• Delivery order: not documented by the provider.
• dLocal retries Payins notifications until it gets a 2xx (hourly, then every 12 hours for 4 days) and says the same Payouts v3 notification may arrive several times. Each notification is a full snapshot of the payment, refund, chargeback or payout object without an event id, so compare the object's id, status and status_code (and last_updated for payouts) with what you stored, make the handler idempotent, and retrieve the object from dLocal before acting on a snapshot that looks older.

Known limitations

• Notifications carry no event id, delivery id or event type, so no delivery key is set and repeated deliveries are not reported as duplicates. Identical snapshots of one object are grouped by its id. The object kind (payment, refund, chargeback, payout) is inferred from its fields.
• status_code is decoded only together with the object type: payment (statuses, pending sub-codes, 39 rejection codes), refund, chargeback and Payouts v3 (statuses and 21 rejection codes) each have their own table. A bare number is never decoded on its own.
• An HTTP error body does not show whether it came from the Payins API (payments, refunds or saved cards) or from Payouts v3. A code listed by only one family or page is decoded with that meaning. Codes documented with different HTTP statuses (3001, 3003, 4001, 5009, 5010) are told apart when the HTTP status is supplied; the others with several documented meanings (for example 5007, 5008, 5011 to 5015, 5023, 5050) are shown with every meaning and lower confidence.
• Payins objects carry created_date and approved_date but no status change time. approved_date is used for approved statuses and created_date otherwise, so two snapshots of one payment can share a time and keep input order. Delivery order is not documented and retries can deliver an older snapshot late. Payouts v3 use last_updated.
• Cash vouchers, Pix and bank transfers stay PENDING until the payer pays; only the notification or a status query is final. An unpaid voucher ends as REJECTED 340.
• A capture is a new payment with its own id and the authorization_id of the authorization; both ids link the events. Refunds and chargebacks link through payment_id. Merchant references (order_id, order_refund_id, original_order_id, external_id) are shown but never used to link events.
• Chargeback reason codes depend on the card network, and the chargeback carries no card brand. Codes listed by several networks (for example Mexico and Elo 41, 74, 75, 80, 82, 85) are shown with every reading. chargeback_stage and processor_id values are not documented and are shown as supplied.
• Refund rejections have no documented sub-codes, and status_code is an integer in some refund and chargeback examples and a string in others; both are accepted.
• The raw network codes in the optional acquirer block (network_response_code) are not listed by dLocal and are shown as supplied. When a Mastercard merchant_advice_code is present, its retry advice takes precedence, as dLocal documents.
• Payouts v3 amounts are not read: the documented field list names amount_details.debit without its structure. The payout flow diagrams are images only, and the Payouts v3 notification signature and retry count are not documented.
• Not analyzed: the browser callback_url POST (dLocal says not to use its status as final), the legacy Payouts v2 form notification (no status field, status_reason values not documented) and dLocal for Platforms notifications are recognized only. Enrollment, dispute upload, account validation and sandbox tool responses are not recognized.
• Signatures (Authorization V2-HMAC-SHA256, callback signature, Payouts v2 control, Payload-Signature, bearer tokens) are sensitive and never verified; a pasted notification is not treated as authentic. Only the presence of a signature header is shown.
• Card data, payer and beneficiary names, local tax ids (CPF, CNPJ, CURP, RFC, DNI and others), bank accounts, Pix keys, 3D Secure values, ARNs, scheme references and notification URLs are never copied.
• Category and retry guidance per code are PandaPayLens suggestions; dLocal's own advice (5052 retry later, the Mastercard merchant advice codes) is reflected. A request timeout (HTTP 504, code 5010) is shown as a conditional retry because the original outcome is unknown.

Examples

• dLocal: one code, three meanings: The same status_code read for a payment, a chargeback and a payout.
• dLocal: cash voucher expired: An OXXO voucher that stays pending until it expires.

Provider documentation

• Payment status codes
• Create a payment
• Retrieve a payment
• HTTP errors: payments
• HTTP errors: refunds
• HTTP errors: saved cards
• Payins security, signature and idempotency
• Receive notifications
• Configure the callback URL
• Network response data
• 3D Secure
• Authorization and capture
• Cash payments
• Acquirer reference number notifications
• Refunds
• Refund status codes
• Chargebacks
• Chargeback status
• Chargeback notification
• Chargeback reason codes
• Payouts v3 statuses
• Payouts v3 error and rejection codes
• Payouts v3 notifications
• Country reference

PandaPayLens is not affiliated with dLocal. Pasted notifications are never treated as verified: PandaPayLens does not check webhook signatures.