# Enrollment Creation Endpoint
## Enrollment creation
`POST` `https://api-stg.onekeypayments.com/v3/enrollments`
This endpoint will allow you to start an enrollment.
#### Headers
| Name | Type | Description |
| ----------------- | ------ | ------------------------------------------------------------------------------ |
| Content-Type | string | `application/json` |
| X-Date | string | ISO8601 Datetime with Timezone:
yyyy-MM-dd'T'HH:mm:ssZ
|
| X-Login | string | Merchant X-Login API Key |
| Authorization | string | Authorization control hash |
| X-Idempotency-Key | string | Unique idempotency key |
**This API utilizes the same security rules & technical aspects as our deposits API, which can be found** [**here.**](/api-documentation/deposits-api/technical-and-security-aspects.md)
#### Request Body
| Name | Type | Description |
| --------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| country | string | Country of the deposit |
| amount | number | Amount of the deposit |
| invoice\_id | string | Unique deposit ID on your side |
| currency | string | Currency of the deposit |
| request\_payer\_data\_on\_validation\_failure | boolean | Flag specifying if you want to ignore errors because of invalid phone, zip\_code and/or city's state |
| payer | object | Object containing details about the customer. See "Payer object" section for details |
| payment\_method | string | Payment method code |
| payment\_types | array | Array of payment methods' types to show the customer on our Hosted Checkout |
| bank\_accounts | object | Object containing details about the customer's bank account. Used to enforce a close-loop policy |
| bonus\_amount | number | Used to show the customer a bonus amount (Pay 100, receive 120) |
| bonus\_relative | boolean | Used to define if the bonus\_amount was specified as an absolute value or as a percentage |
| strikethrough\_price | number | Used to show the customer a strikethrough amount |
| description | string | Description of the deposit |
| client\_ip | string | Valid IPv4/v6 Address of the customer |
| device\_id | string | Unique customer's device ID created using our JS library |
| language | string | Language of the view page |
| back\_url | string | HTTPS URL used to redirect the customer in case of cancelling the deposit |
| success\_url | string | HTTPS URL used to redirect the customer in case of success |
| error\_url | string | HTTPS URL used to redirect the customer in case of error while generating the payment |
| notification\_url | string | HTTPS URL used to send the notifications about deposit's change of status |
| logo | string | HTTPS URL used as the Merchant logo on our cashier |
| test | boolean | Used to mark a deposit as test. If true, the deposit will not affect the merchant's balance |
| mobile | boolean | Used to specify if the redirection will be made on a mobile device |
| early\_release | boolean | Used to specify if the deposit should be released earlier |
| fee\_on\_payer | boolean | Used to specify if you want to let the customer assume the deposit fee |
#### Enrollment Specific Fields
| Name | Type | Description |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------- |
| start\_date | date | Date that the enrollment starts. Format `YYYY-MM-DD` |
| frequency | string | `DAILY`, `WEEKLY`, `MONTHLY` or `ANNUALLY` |
| amount\_type | string | `FIXED` |
| include\_first\_payment | boolean | `true` or `false,` indicates if a payment will be done as soon as the enrollment is created |
| first\_payment\_amount | number | Only used if include\_first\_payment is true. |
| automatic\_billing | boolean | `true` or `false,`Indicates if recurring transactions will be generated automatically or not. |
{% hint style="warning" %}
All of these fields are mandatory in order to create a new enrollment.
{% endhint %}
#### Example Request
```json
{
"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",
"include_first_payment": true,
"first_payment_amount":"50",
"success_url": "https://merchant.com/payment/success",
"notification_url": "https://merchant.com/payment/notification"
}
```
{% hint style="success" %}
With the provided request above, this would create a payment of 1 BRL, which needs to be paid once per month.
{% endhint %}
### Successful response example
```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,iVBORw0KGgoAANNNSUhEUgAAAH0AAAB9AQAAAACn+1GIAAACbElEQVR4XmP4jwp+MIwKjAqgCTCu9+JUi09hhwvUsnClXdih+h0u4HpeoPSVvqs4QkCbffPldaFIAs/3BJTP70UI1KpFqxfU30WYwRgKAiEIW/5/lGSPCcoHsSACLFW3ElxeBa2HC7yKb5H8J57bj1DhdPFfRzIzwtDusHaZz3Wy5XCBmO5pzxPOJVxHqLi4xsus31IeLsDAvqjo5Fv253CBQ48vVmQzvXgPF1h5fN4zo50l2+ECn7pOi5Rdy0AYKqD6+uAEW9bjcIEmu17N9V5c9XCBvyuYdot0iEyHCzxbvYfD3E9DHy4g+X/5hwu72RG2iJ9/FnMneI86XKD3kHay2P5AJFt07giVib1BBJDv1pfTZ+RNRjjsF/Nvj/1GvghbCqImLXA+ZRAOF2j37QjXkv8eDxe4Gpz3NX5TKyJezA09nms7Pa+HC1xg6nogeDMBYeiiy95y3y8jBfJHJWffAE0GRJi+d/SreJfwaz9coOeL0APzTndEeNyf/1Pq27Q1CO+bvL2wTtDiwHK4QLWinOM79xBEeKheu/Xi2Tt1hLVN3a3i6W4FiJiL+T81QeKxACJ9qH1PZNnxPD0dLnDhgvia5T9UzOECTqong1YdVp0PFzhaO0U3cG0rwox084Zlq1guI0KdZ+6cl4IzdcThAtw93WKbjqshIurg17PpEgtVEQJiWr0xr07vRriUp4vtgfhKBX+4wP/oveJlYcsRDmO03FRauD0UKVeeyWCXNXVHhIdr2aoHTq+QzHA1vMtZ1vYQEciuSrk8Aqs5EH6ptbvbZDrdECHAqDJ959FXnohQRwKjAqMCyAIAB4fJmMX3JNsAAAAASUVORK5CYII=",
"digitable_line": "00020101021226990014br.gov.bcb.pix2577pix.onekeypayments.com/qrs1/v2/01zVHEoEXMAE9s5IICqar4t2ly1vHNPURJbZRqPXlz6TFt52040000530398654041.005802*80980014br.gov.bcb.pix2576pix.onekeypayments.com/public/v1/rec/1ZEpF4g8eOa9s6Lc9g1LzCklGR4fVe9OaxDf2W2630425BF"
}
}
```
### Response fields
| Name | Type | Description |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `enrollment_id` | number | Indicates the ID of the enrollment. This is important to create reucrring payments. |
| `invoice_id` | string | ID of the deposit on the merchant end. |
| `country` | string | `BR` |
| `currency` | string | `BRL` |
| `amount` | string | Amount of the enrollment created. |
| `status` | string | Status of the enrollment |
| `redirect_url` | URL | URL used to redirect the customer where they can see the details to pay |
| `qr_code` | string | PNG image encoded in base64 of the QR code used to display the Pix QR natively on your site |
| `digitable_line` | string | Plain text string line the user can use to manually pay for the PIX instead of scanning the QR |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://apidocs.onekeypayments.com/api-documentation/automatic-pix-api/enrollment-creation-endpoint.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.