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.

Create an enrollment

Example request

QR Code Authorization

curl -L \
--request POST \
--url 'https://api-stg.onekeypayments.com/v1/enrollments' \
--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": "[email protected]",
        "phone": "[phone]"
        },
    "start_date": "2025-10-22",
    "frequency": "MONTHLY",
    "amount": 1,
    "amount_type": "FIXED",
    "include_first_payment": false,
    "success_url": "https://merchant.com/payment/success",
    "notification_url": "https://merchant.com/payment/notification"
}'

QR Code Authorization + First Payment

Response

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

Create enrollment

---

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.

{
    "enrollment_id": 3000000001
}

---

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

Request

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: */*'

Response

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

---

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

Request

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: */*'

Response