Enrollment Creation Endpoint

Enrollment creation

POST https://api-stg.onekeypayments.com/v1/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.

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

All of these fields are mandatory in order to create a new enrollment.

Example Request

{
"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": true,
"success_url": "https://merchant.com/payment/success",
"notification_url": "https://merchant.com/payment/notification"
}

With the provided request above, this would create a payment of 1 BRL, which needs to be paid once per month.

Successful response example

{
    "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