Enrollment with First Payment

Use Enrollment with First Payment when the customer needs to authorize recurring charges and make an initial payment at sign-up or checkout. Send the enrollment and the first payment in a single /ws/direct request. To obtain authorization without initiating a payment, see Single Enrollment. For a comparison, see Ways to create an enrollment.

Requirements

• API authentication - All API requests must be authenticated using JWS (JSON Web Signature). The legacy integration_key is being deprecated — if you still use it, follow the Migration Guide to transition to JWS. If you don't have credentials yet, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - See the Direct API reference for details.
• Notification URL - Configure your Notification URL in the Merchant Area to receive payment and enrollment notifications. See Notifications.
• Recurring payment method enabled - The payment method must be enabled for your account. Contact your EBANX Integration Specialist.

How it works

1. You send one request - Call /ws/direct with the payment data and an enrollment object that contains a new merchant_enrollment_code.
2. EBANX creates the enrollment and the payment - The enrollment starts as pending. The payment is created in the same request.
3. The customer approves - Depending on the payment method, the customer approves the enrollment in the provider's app or on a redirect page returned in the response.
4. The first payment is processed - With a Single provider operation, the customer authorizes the enrollment and the first payment in the same approval flow (for example, one Pix QR code). With Charge after approval, EBANX charges the first payment only after the enrollment is accepted. See Execution models.
5. You receive notifications - EBANX sends an enrollment notification when the enrollment status changes and a payment notification when the payment status changes.
6. You charge later payments - Send new /ws/direct requests that reference the same merchant_enrollment_code. Each charge uses the existing authorization.

New code, new enrollment

Enrollment with First Payment applies only when the merchant_enrollment_code is new. A request that references an existing enrollment is a regular recurring charge. Use a unique merchant_enrollment_code for each enrollment.

Request and response

The request is a regular /ws/direct payment request with an enrollment object inside payment. The payment fields and the method-specific enrollment fields are described in the guide of each method.

Parameter	Requirement	Description
payment.payment_type_code	Required	The recurring payment method.
payment.amount_total	Required	Amount of the first payment.
payment.merchant_payment_code	Required	Your unique code for the first payment.
payment.enrollment.merchant_enrollment_code	Required	A new, unique code for the enrollment. Reuse it in later charges.
payment.enrollment.*	Depends on the method	Method-specific enrollment fields, such as subscription or back_urls. See the table below.

The response returns status: SUCCESS and the payment with status PE. Depending on the payment method, it can also include:

• redirect_url - Redirect the customer to this URL to approve the enrollment.
• payment.enrollment - The enrollment status (pending) and its merchant_enrollment_code.

Payment method	Method-specific enrollment fields	Customer approval	Enrollment in response
Capitec Pay Recurring	subscription (frequency, amount limits, and dates)	Capitec Bank app	Yes
Card Recurring	subscription, back_urls (card data goes in payment.card)	3-D Secure authentication, using threeds_redirect_url	No
Maya Recurring	subscription, back_urls	redirect_url	No
Nequi Recurring	email, phone_number	Push notification in the Nequi app	Yes
OPay Recurring	subscription, back_urls	redirect_url	Yes
Pix Automático	Customer data and subscription	Pix QR code	Yes
UPI AutoPay	subscription, back_urls	UPI app link or QR code	No
Yape Recurring	subscription	Yape app, using the redirect_url	Yes

To compare the requests of each method side by side, see Compare requests by payment method.

Execution models

The provider behind each payment method defines how the first payment is executed. Your integration sends the same single request in both models.

Model	What happens	What you see
Single provider operation	The provider creates the enrollment and charges the first payment in the same operation.	The payment follows the regular payment flow of the method.
Charge after approval	The provider has no single operation for both steps. EBANX creates the enrollment and holds the first payment. After the customer approves the enrollment, EBANX requests the first charge automatically.	The payment remains PE (pending) while the enrollment awaits approval. After approval, EBANX submits the charge. You do not send a second request.

Status outcomes

With Charge after approval, the first payment depends on the enrollment status while the payment is PE. With a Single provider operation, the first payment follows the regular payment flow of the method.

Enrollment status	First payment (Charge after approval)
pending	Stays PE (pending).
accepted	Sent to the provider. It moves to CO (confirmed) if the charge is paid, or to CA (canceled) if it is not.
not_accepted	Canceled (CA). No charge is sent to the provider.
cancelled	Canceled (CA). No charge is sent to the provider.
expired	Canceled (CA). No charge is sent to the provider.
revoked	Canceled (CA). No charge is sent to the provider.

A later change to the enrollment, such as revoked or cancelled after the first payment is processed, does not change the first payment.

Payment method support

Payment method	Country	Execution model	Guide
Capitec Pay Recurring	South Africa	Charge after approval	Capitec Pay Recurring
Card Recurring	India	Follows the card flow, with 3-D Secure authentication	Card Recurring
Maya Recurring	Philippines	Charge after approval	Maya Recurring
Nequi Recurring	Colombia	Charge after approval	Nequi Recurring
OPay Recurring	Nigeria	Single provider operation	OPay Recurring
Pix Automático (with an instant payment)	Brazil	Single provider operation	Pix Automático
UPI AutoPay (Intent or QR code)	India	Single provider operation	UPI AutoPay
Yape Recurring	Peru	Charge after approval	Yape Recurring

The guide of each payment method is the reference for its request fields, limits, and customer experience.

Compare requests by payment method

Select two payment methods to see their requests and responses side by side. The lines that differ are highlighted.

Select an API Payload

Select a reference payment type

A code example for this payment method will be available soon.

Select a payment type to compare

A code example for this payment method will be available soon.

Notifications

Use the payment notification to update the order and the enrollment notification to update the subscription. You can also query both statuses with /ws/userenrollments/query and /ws/query. Do not charge later payments until the enrollment is accepted.

For more information, refer to the

Payment Notificationschevron_right

For more information, refer to the

Enrollment Notificationschevron_right

Testing in sandbox

In the sandbox, payment methods with the Charge after approval model return a redirect_url in the /ws/direct response. Open it to simulate the customer's decision and check the resulting enrollment and payment statuses. See Sandbox Simulator.

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.