Version: current

Enrollment Notification

About this guide

This guide shows you how to work with enrollment notification. Due to the nature of some payment methods, a previous ennrollment is needed, specially for recurrent payments. We'll guide you through the steps to handle this type of calls.

How it works

  1. Verify the notification signature

    When an enrollment status is changed to accepted or revoked, EBANX sends a notification to the merchant system through the Notification URL that should be set in the Dashboard (It's the same URL for payments notification). For more details on setting your notification URL, you can refer to the Settings Tab on your EBANX Dashboard.

    The available certificates and their fingerprints are shown on the table below:

    FingerprintCertificate
    4ABAD89CF66B99998465470550EB15E3E271A246Download

    EBANX will send the following headers in the notification request:

    ParameterDescription
    X­-Signature­TypeThe signing algorithm. EBANX will always use RSA/SHA1.
    X­-Signature­FingerprintThe signature fingerprint. It indicates which certificate was used to sign the notification.
    X­-­Signature­ContentThe signed payload, encoded as a Base64 string.
    X­-Signature­Type: rsa,sha1
    X­-Signature­Fingerprint: 4ABAD89CF66B99998465470550EB15E3E271A246
    X-­Signature­Content: xh5hstzZt5Rf5ihNzbfFfkmN89askd...DrHJAnzHgaf2vzA==

    The signature can be validated in PHP as follows:

    Request Example

    $cert = file_get_contents('ebanx-notifications-public.pem');
    $data = file_get_contents("php://input");
    $signature = base64_decode($_SERVER['HTTP_X_SIGNATURE_CONTENT']);
    // http://php.net/manual/en/function.openssl-verify.php
    $result = openssl_verify($data, $signature, $cert);
    if ($result === 1)
    {
    echo "OK, signature is correct.";
    }
    else
    {
    echo "ERROR, the signature is incorrect.";
    }
  2. Get the enrollment code from the notification

    The notification will contain the following parameters:

    ParameterDescription
    operationThe value is always enrollment_status_change..
    notification_typeEvent that triggered the notification. For now the value is always update.
    merchant_enrollment_codeUnique identifier associated with the recurrency.

    Here's a sample of a notification:

    operation=enrollment_status_change&notification_type=update&merchant_enrollment_code=test-enrollment-123
  3. Send an Enrollment Query

    To check the latest status of an enrollment, you need to call the end-point /ws/userenrollments/query (from your server) using the merchant_enrollment_code received in the notification:

    EnvironmentMethodURL
    Productionhttps://ebanxpay.com/ws/userenrollments/query
    Sandboxhttps://sandbox.ebanxpay.com/ws/userenrollments/query

    Request

    Request Fields

    ParameterAccepted ValuesRequired
    integration_keyMerchant Integration Key (Ex: testabc123)Yes
    payment_type_codePayment method (Ex: mpconnect)Yes
    enrollment.merchant_enrollment_codeUnique identifier associated with the recurrency (Ex: test-enrollment-123)Yes
    enrollment.countryTwo Letters Country Code (Ex: ar for Argentina Country Code)Yes

    Request Example

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

    Response

    {
    "status": "SUCCESS",
    "enrollment": {
    "status": "revoked"
    }
  4. Let EBANX know you received our response

    Reply the notification with an HTTP 200 status. We suggest to print any message showing that you got the notification, indicating that the notification was successful.

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

  • If you‚Äôre not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
  • In case you‚Äôre already our partner please get in touch with our support team at integration@ebanx.com.
Last updated on by FlavioCostaeSilva