Enrollment Notification

Enrollment at EBANX refers to the process of registering a customer’s payment information for recurring transactions or subscriptions. It involves securely saving the customer’s payment details, such as credit or debit card information, for future use. EBANX’s Enrollment Notification system enhances recurring payments by informing your system whenever a customer’s enrollment status changes. When a customer initiates or modifies a recurring payment, EBANX sends a notification to your system through a pre-configured Notification URL. This notification includes details about the enrollment status, such as whether it has been accepted or revoked. To ensure the authenticity of these notifications, EBANX signs each request using a private certificate. Your system can verify the legitimacy of the notification by validating this digital signature with EBANX’s public certificate. This process ensures that only trusted notifications are processed, maintaining the integrity of your payment system.

How it works

1. Customer initiates enrollment - Your customer provides payment details to begin the recurring payment process.
2. Verification - EBANX verifies the payment details and processes the enrollment.
3. Status updates - Notifications are sent to your system when the enrollment status changes (accepted or revoked).
4. Future transactions - After successful enrollment, future transactions can be made without customer input.

Requirements

• Dashboard credentials

  • Ensure you have your EBANX dashboard credentials.
  • If not, Contact our support team at sales.engineering@ebanx.com for assistance.

• Notification URL

  • Allows EBANX to send real-time updates directly to your system, ensuring seamless communication.
  • Configure your Notification URL in the EBANX dashboard under Account Settings in the Integrations tab.

• EBANX public certificate

  • Click to Download Certificate

Instructions

Follow the steps below.

1. Validate incoming notification

   When an enrollment status changes to accepted or revoked, EBANX sends a notification to your system's Notification URL, configured in your Dashboard. This URL ensures timely updates for enrollment management. It is crucial to validate the notification's digital signature to ensure the authenticity and integrity of the incoming data before processing.

   For detailed instructions, see the

   Payment Notification Guidechevron_right

2. Get enrollment code from notification

   // Sample Notification
   operation=enrollment_status_change&notification_type=update&merchant_enrollment_code=test-enrollment-123

   Notifications include these parameters:

   Parameter	Description
   operation	The value is always set to enrollment_status_change.
   notification_type	Event that triggered the notification. The value is always set to update for enrollment notifications.
   merchant_enrollment_code	Unique ID linked to the recurring transaction.

3. Define you parameters

   To retrieve the latest enrollment status, call the /ws/userenrollments/query endpoint using the details provided in the notification.

   Request Parameters

   Parameter	Accepted Values	Required
   integration_key	Your EBANX integration key	Yes
   operation	Set to enrollment	Yes
   payment_type_code	Payment method (eg: mpconnect)	Yes
   enrollment.merchant_enrollment_code	Unique ID linked to the recurring transaction.	Yes
   enrollment.country	Two letter country code	Yes

   
   

4. Example request

   Use the following example to initiate a request.

   {
       "integration_key": "testabc123",
       "operation": "enrollment",
       "payment_type_code": "mpconnect",
       "enrollment": {
           "merchant_enrollment_code": "test-enrollment-123",
           "country": "br"
       }
   }

5. Example response

   A successful request returns a response like the example below

   {
       "status": "SUCCESS",
       "enrollment": {
           "status": "revoked"
       }
   }

6. Acknowledge the response

   Acknowledge the response by sending an HTTP 200 status back to EBANX. We recommend logging a confirmation message to indicate that the notification was successfully received.

   • If EBANX does not receive an HTTP 200 response, it may assume the notification failed and will attempt to resend it. This can lead to duplicate notifications and potentially duplicate processing.

7. Congratulations!

   You have succesfully implemented Enrollment Notification.

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.