# Enrollment

The ***enrollment*** is the process in which the user is onboarded to the recurrence, and agrees to be automatically charged for the defined amount and frequency.

When the users scan the Pix QR code, the banking application will prompt all the recurrency details for the user to accept.

### <i class="fa-pencil">:pencil:</i> Create an enrollment

#### Example request

{% tabs %}
{% tab title="QR Code Authorization" %}

<pre class="language-sh"><code class="lang-sh">curl -L \
--request POST \
<strong>--url 'https://api-stg.onekeypayments.com/v1/enrollments' \
</strong>--header 'Content-Type: application/json' \
--header 'X-Date: 2025-11-14T08:00:46.101Z' \
--header 'X-Login: text' \
--header 'Authorization: text' \
--data '{
    "invoice_id": "invoiceid10000",
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "document": "01234567890",
        "document_type": "CPF",
        "email": "ricardo.carlos@example.com",
        "phone": "+5511999999999"
        },
    "start_date": "2025-10-22",
    "frequency": "MONTHLY",
    "amount": 1,
    "amount_type": "FIXED",
<strong>    "include_first_payment": false,
</strong>    "success_url": "https://merchant.com/payment/success",
    "notification_url": "https://merchant.com/payment/notification"
}'
</code></pre>

{% endtab %}

{% tab title="QR Code Authorization + First Payment" %}

<pre class="language-sh"><code class="lang-sh">curl -L \
--request POST \
<strong>--url 'https://api-stg.onekeypayments.com/v1/enrollments' \
</strong>--header 'Content-Type: application/json' \
--header 'X-Date: 2025-11-14T08:00:46.101Z' \
--header 'X-Login: text' \
--header 'Authorization: text' \
--data '{
    "invoice_id": "invoiceid10000",
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "document": "01234567890",
        "document_type": "CPF",
        "email": "ricardo.carlos@example.com",
        "phone": "+5511999999999"
        },
    "start_date": "2025-10-22",
    "frequency": "MONTHLY",
    "amount": 1,
    "amount_type": "FIXED",
<strong>    "include_first_payment": true,
</strong>    "success_url": "https://merchant.com/payment/success",
    "notification_url": "https://merchant.com/payment/notification"
}'
</code></pre>

{% endtab %}

{% tab title="Response" %}
{% code overflow="wrap" %}

```json
{
  "enrollment_id": 36,
  "invoice_id": "invoiceid10000",
  "currency": "BRL",
  "country": "BR",
  "amount": 1,
  "status": "PENDING",
  "redirect_url": "https://link.depositcheckout.com/enrollment/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiIzNiIsImlhdCI6MTc2MTMyNDk4NCwiZXhwIjoxNzYyNjIwOTg0LCJsYW5ndWFnZSI6InB0In0.odWD9R6Mh9br53fynu3n2vVBIXCvkOTk74-V4gAaNhurk217WaWUHOrK4CWobz1a",
  "metadata": {
    "qr_code": "data:image/png;base64,iVBORw0KGgo...",
    "digitable_line": "00020101021226990014br.gov.bcb.pix2577pix..."
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

> For more information about this endpoint, please visit the API Reference.
>
> <a href="https://app.gitbook.com/s/0lbPmhFPUb55BAkK3G6F/deposits-api/automatic-pix/create-enrollment" class="button primary" data-icon="pencil">Create enrollment</a>

***

### &#x20;<i class="fa-message-plus">:message-plus:</i> Enrollment notifications

Whenever there are updates regarding an enrollment, merchants will receive a webhook notification to the defined `notification_url` containing the Enrollment ID in order to retrieve the status.

```json
{
    "enrollment_id": 3000000001
}
```

***

### <i class="fa-magnifying-glass">:magnifying-glass:</i>  Retrieve the Enrollment details

Merchants can easily retrieve the details within an enrollment by requesting the endpoint described below.

Useful information such as status and deposit IDs associated the enrollment can be obtained

{% tabs %}
{% tab title="Request" %}

```sh
curl -L \
  --url 'https://api-stg.onekeypayments.com/v1/enrollments/{enrollment_id}' \
  --header 'X-Date: 2025-10-22T10:30:00-03:00' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --header 'Accept: */*'
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "enrollment_id": 30,
  "amount": 1,
  "country": "BR",
  "currency": "BRL",
  "invoice_id": "invoiceid10000",
  "amount_type": "FIXED",
  "status": "ACTIVE",
  "frequency": "MONTHLY",
  "start_date": "2025-10-22",
  "payer": {
    "id": "404606303",
    "email": "ricardo.carlos@example.com",
    "first_name": "Ricardo",
    "last_name": "Carlos",
    "phone": "+5511999999999",
    "full_name": "Ricardo Carlos"
  },
  "deposits": [
    1398852515
  ]
}
```

{% endtab %}
{% endtabs %}

> For more information about this endpoint, please visit the API Reference

***

### <i class="fa-delete-left">:delete-left:</i> Cancel an Enrollment

Merchants can manage the Enrollment lifecycle with ease. In case of willing to cancel an ongoing enrollment, merchants have to request the Enrollment Cancellation Endpoint

{% tabs %}
{% tab title="Request" %}

```shellscript
curl -L \
  --request DELETE \
  --url 'https://api-stg.onekeypayments.com/v3/enrollments/{enrollment_id}/' \
  --header 'X-Login: text' \
  --header 'X-Date: text' \
  --header 'Authorization: text' \
  --header 'X-Idempotency-Key: text' \
  --header 'Content-Type: text' \
  --header 'Accept: */*'
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "enrollment_id": 36,
  "status": "CANCELLED"
}
```

{% endtab %}
{% endtabs %}