> For the complete documentation index, see [llms.txt](https://apidocs.onekeypayments.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.onekeypayments.com/api-documentation/automatic-pix-api/enrollment-creation-endpoint.md).
# 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 |