Verification flows

The KYC Verifications API helps you validate identities, verify documents, and manage compliance processes. It supports multiple verification flows, each with its own data requirements.

The API also includes a notification system that keeps merchants informed of status changes throughout the verification process.

Payout on Hold

This verification type is created by dLocal when a payout is placed on hold due to fraud compliance concerns. Additional information is required from the merchant to release the funds.

API Endpoints

Method	Endpoint	Description
GET	`/verifications/{verification-id}`	Retrieve a verification created by dLocal for a Payout on Hold due to fraud compliance. Verifications will only be created by dLocal when specific information is required to release the funds.
GET	`/verifications/{verification-id}/documents`	Retrieve the required documentation that needs to be sent for a given verification. These documents must be sent and validated by dLocal for the verification to be approved, and the payouts will be set on hold due to fraud compliance related to the verification release.
PATCH	`/verifications/{verification-id}/documents/{document-id}`	Update a specific document associated with a given verification using a multipart/form-data request.

When a payout is placed on hold, dLocal automatically creates a verification and sends a notification to the merchant.

The merchant must then retrieve the verification details, check which documents are required, and submit the necessary information to complete the verification process.

Example verification response

{
  "type": "PAYOUT_ON_HOLD",
  "id": "KV-371ea706-0be6-4088-9693-11f6be6b3240",
  "notification_url": "https://marketplace.com/notifications",
  "created_date": "2025-05-06T16:24:57.36526",
  "expiration_date": "2025-05-08T00:00:00",
  "status": "PENDING",
  "status_detail": "PENDING_DOCUMENTATION",
  "status_code": 300,
  "attributes": {
    "external_reference": "BLC-T-SETTLEMENT-PAYOUT-MC-2224",
    "client": {
      "id": "VC-371ea706-0be6-4088-9693-11f6be6b3240",
      "type": "BENEFICIARY",
      "document_type": "RUT",
      "document_number": "211003420017"
    }
  }
}

Remittances

This verification type is used for creating Remitter and Beneficiary verifications required for remittance payments.

The required fields depend on the client type (remitter or beneficiary), country, and industry. The verification ID returned by this process will be used in subsequent Payins and Payouts API calls.

API Endpoints

Method	Endpoint	Description
POST	`/verifications`	Create a new Remitter and Beneficiary verification required for the remittance flow. The service will return a verification ID, which will be used in the Payins and Payouts API’s services.
GET	`/verifications/{verification-id}?include=client_data`	Retrieve verification details with extended client information. Include the query parameter `client_data` to access detailed client information.
GET	`/verifications/{verification-id}/documents`	Retrieved documents required for a given verification. These documents must be completed and validated for the verification to be approved.
PATCH	`/verifications/{verification-id}/documents/{document-id}`	Update a specific document associated with a given verification using a multipart/form-data request.

Client types

The requirements for client information and the verification process will depend on the type of verification, the client information needed, and the triggered flows.

For remittances, two types of verifications can be created:

Remitter verification: Contains information about the sender of the funds
Beneficiary verification: Contains information about the recipient of the funds

Example verification request

{
  "type": "REMITTANCE",
  "notification_url": "https://marketplace.com/notifications", 
  "attributes": {
    "external_reference": "2352362346",
    "client": {
      "type": "REMITTER",
      "last_name": "Doe",
      "first_name": "John",
      "document_type": "TAX_ID",
      "document_number": "27327331566",
      "document_country": "AR",
      "date_of_birth": "2012-06-28",
      "place_of_birth": "AR",
      "gender": "Male",
      "nationality": "AR",
      "marital_status": "Married",
      "is_pep": false,
      "pep_condition": "President of Uruguay",
      "is_so": false,
      "profession": "STUDENT",
      "source_of_funds": "SAVINGS",
      "consent": {
        "type": "TERMS_AND_CONDITIONS",
        "accepted": true
      },
      "address": {
        "country": "UY",
        "city": "Montevideo",
        "zip_code": "11300",
        "state": "Montevideo",
        "street_name": "Dr. Luis Bonavita",
        "street_number": "1234"
      }
    }
  }
}

{
  "type": "REMITTANCE",
  "notification_url": "https://marketplace.com/notifications",
  "attributes": {
    "external_reference": "2352362346",
    "client": {
      "type": "BENEFICIARY",
      "last_name": "Doe",
      "first_name": "John",
      "nationality": "AR",
      "document_type": "TAX_ID",
      "document_number": "27327331566",
      "document_country": "AR",
      "date_of_birth": "2012-06-28",
      "place_of_birth": "AR",
      "bank": {
        "account_number": "96323056678"
      },
      "address": {
        "country": "UY",
        "city": "Montevideo",
        "state": "Montevideo",
        "zip_code": "11300",
        "street_name": "Dr. Luis Bonavita",
        "street_number": "1234"
      }
    }
  }
}

Both remitter and beneficiary verifications may require additional documentation. After creating the verification, you can:

Retrieve the list of required documents using the GET documents endpoint
Submit the required documents using the PATCH document endpoint

Notifications

Both verification types use a notification system to inform merchants about status changes. Notifications are sent to the URL specified in the notification_url field of the verification request.

Common verification statuses include:

CREATING - Verification is being created
PENDING - Verification is pending additional information
APPROVED - Verification has been approved
REJECTED - Verification has been rejected

📘
Contact your Technical Account Manager to set up your notification URL.