---
updatedAt: 2026-11-02T18:06:15.000Z
agentTools:
  projectIndex: https://docs.dlocal.com/llms.txt
---

# One-time user enrollment

Learn how to enroll users for Pix with Biometrics payments.

The one-time biometric enrollment requires merchants to create an enrollment request via dLocal's API, establishing the user's biometric authentication profile for future payments.

# Flow launch options

The enrollment flow can be adapted to match the merchant's preferred user experience. It is possible to either **redirect users to dLocal's standardized interface** for a pre-built biometric authentication journey or use the **embedded SDK** to integrate the biometric flow directly into a native mobile app (iOS / Android) while maintaining your brand experience.

* **Redirect approach**: Users are directed to dLocal's secure interface, where they authorize their bank account and register their biometric data (face or fingerprint verification).
* **Embedded SDK**: The same enrollment process occurs within your application, providing a seamless branded experience.

Once enrollment is completed successfully, dLocal provides an enrollment ID via API that uniquely identifies the approved biometric profile, enabling future payments without requiring additional biometric registration.

> 👍
>
> **Exploring embedded SDK integration?** Our team can grant access to the native experience integration toolkit. Contact your designated Technical Account Manager or email us at <integrations@dlocal.com>.

# Overall flow

![](https://files.readme.io/05234715563134dfb52c520fd0b92bdd9b6f4226e4b6fd22e586d759d84402a0-pix_with_biometrics_-_one_time_user_enrollment.png)

# Biometric enrollment process

This process performs a **one-time biometric enrollment that enables future biometric-authenticated payments**.

## User flow

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/3bfaa254b8de0998388af8bdb3ec285e5161c6ff14bb7d7e93e74a57b465dc18-Pix_por_Biometria_-_Enrollment_flow.png",
        "",
        "The screenshots illustrate an example of the Pix with Biometrics user enrollment flow"
      ],
      "align": "center",
      "caption": "The screenshots illustrate an example of the Pix with Biometrics user enrollment flow"
    }
  ]
}
[/block]

## Example request

<EndpointSelector
  method="POST"
  productionUrl="https://api.dlocal.com/enrollments"
  sandboxUrl="https://sandbox.dlocal.com/enrollments"
  defaultEnvironment="production"
/>

```json Enrollment request
curl -X POST \
   -H 'X-Date: {X-Date}' \
   -H 'X-Login: {X-Login}' \
   -H 'X-Trans-Key: {X-Trans-Key}' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: {Signature}' \
   -d '{body}'
   https://api.dlocal.com/enrollments

{
  "currency": "BRL",
  "country": "BR",
  "type": "ON_DEMAND",
  "payment_method_id": "XV",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Thiago Gabriel",
    "document": "53033315550",
    "email": "user@mail.com",
    "device_id": "123456789"
  },
  "external_id": "31231jj223",
  "description": "PIX Biometrics enrollment",
  "notification_url": "http://merchantsite.com/notifications",
  "callback_url": "http://merchantsite.com/callback"
}
```
```json Synchronous response
{
  "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
  "external_id": "31231jj223",
  "currency": "BRL",
  "country": "BR",
  "type": "ON_DEMAND",
  "payment_method_id": "XV",
  "payment_method_flow": "REDIRECT",
  "payment_method_type": "TICKET",
  "created_date": "2025-12-26T20:37:20.000+0000",
  "status": "PENDING",
  "status_detail": "The enrollment is pending.",
  "status_code": "100",
  "redirect_url": "https://pay.dlocal.com/gmf-apm/payments/E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
  "notification_url": "http://merchantsite.com/notifications"
}
```
```json Asynchronous response
{
  "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
  "external_id": "31231jj223",
  "currency": "BRL",
  "country": "BR",
  "type": "ON_DEMAND",
  "payment_method_id": "XV",
  "payment_method_flow": "REDIRECT",
  "payment_method_type": "TICKET",
  "created_date": "2025-12-26T20:37:20.000+0000",
  "status": "ACTIVE",
  "status_detail": "The enrollment is active.",
  "status_code": "200",
  "notification_url": "http://merchantsite.com/notifications"
}
```

## Request params

[block:parameters]
{
  "data": {
    "h-0": "Field",
    "h-1": "Type",
    "h-2": "Description",
    "h-3": "Required",
    "0-0": "`currency`",
    "0-1": "String",
    "0-2": "`BRL` or `USD`<br><br>Transaction currency in [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217).",
    "0-3": "Yes",
    "1-0": "`country`",
    "1-1": "ISO 3166-1 alpha-2 code",
    "1-2": "`BR`<br><br>Transaction country in [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).",
    "1-3": "Yes",
    "2-0": "`type`",
    "2-1": "String",
    "2-2": "Type of enrollment. Always send `ON_DEMAND` for Pix with Biometrics.",
    "2-3": "Yes",
    "3-0": "`payment_method_id`",
    "3-1": "String",
    "3-2": "`XV`<br><br>ID of the selected payment method.",
    "3-3": "Yes",
    "4-0": "`payment_method_flow`",
    "4-1": "String",
    "4-2": "`REDIRECT`",
    "4-3": "Yes",
    "5-0": "**Payer Object**",
    "5-1": "",
    "5-2": "",
    "5-3": "",
    "6-0": "`payer.name`",
    "6-1": "String (max. 100)",
    "6-2": "Name of the payer.",
    "6-3": "Yes",
    "7-0": "`payer.document`",
    "7-1": "11–14 digits<br/>Full CPF validation",
    "7-2": "Document of the payer (CPF or CNPJ).",
    "7-3": "Yes",
    "8-0": "`payer.email`",
    "8-1": "String (max. 100)",
    "8-2": "Email of the payer.",
    "8-3": "Yes",
    "9-0": "`external_id`",
    "9-1": "String",
    "9-2": "An identifier used by the merchant to identify the enrollment in their system.",
    "9-3": "Yes",
    "10-0": "`description`",
    "10-1": "String",
    "10-2": "Enrollment description.",
    "10-3": "No",
    "11-0": "`notification_url`",
    "11-1": "String (max. 200)",
    "11-2": "Notifications will be sent on every change of status to the `notification_url` specified by the merchant.",
    "11-3": "No",
    "12-0": "`callback_url`",
    "12-1": "String",
    "12-2": "URL where the user will be redirected after approval of the transaction.",
    "12-3": "Yes"
  },
  "cols": 4,
  "rows": 13,
  "align": [
    null,
    null,
    null,
    null
  ]
}
[/block]

## Response params

| Field | Type   | Description                                                                         |
| :---- | :----- | :---------------------------------------------------------------------------------- |
| `id`  | String | Enrollment ID provided by dLocal, which must be used for future biometric payments. |