Recurring Payment Retries

Overview

In the event of a failed payment attempt, for reasons such as Insufficient Funds, by the customer's bank, EBANX will send a notification and allowing for up to 3 retries, in a 7 day window. This guide will walk you through a basic API integration that accepts Pix Automático Payment Retries.

By following this basic integration guide, you will understand how you can retry failed recurring payments.

Availability

Pix Automático integration through Direct API will available in Brazil only.

What you will need

A Sandbox Account

As with any secure payment integration, you will first need to set up authorization. The EBANX sandbox allows you to set up a test environment to run transactions using test credit card numbers and explore our payment solutions.

Sign up for an Sandbox Account at our EBANX Business Page, select your business model and answer a few questions. We'll get in touch with you shortly after!

Sign up for an EBANX Sandbox Account here

How it works

To complete an Pix Automático retry, please follow the steps below.

  1. EBANX notifies payment failure and retry availability

    Your title

    Once the customer's bank notifies EBANX that the payment has failed, EBANX adds the available_retries field to the payment, specifying how many retry attempts there are left and sends a notification.

    {
    "operation":"payment_status_change",
    "notification_type":"update",
    "merchant_payment_code":"{{unique_payment_code}}"
    }

    Using the ID provided in merchant_payment_code, call the ws/query endpoint to get the latest status of the payment.

    Check the example:

    {
    "integration_key": "{{integration_key}}",
    "merchant_payment_code": "{{unique_payment_code}}",
    }

    A successful request will return a JSON response like the one below, with a status of PE for the retriable recurring payment, along with the remaining retry attempts in available_retries.

    {
    "payment": {
    "hash": "{{unique_payment_hash}}",
    "country": "br",
    "merchant_payment_code": "{{unique_payment_code}}",
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "status": "PE",
    "available_retries": 3,
    "status_date": "2024-01-17 03:00:00",
    "open_date": "2024-01-10 13:00:00",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "19.90",
    "amount_ext": "19.90",
    "amount_iof": "0.00",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2024-01-17",
    "payment_type_code": "pix-automatico",
    "pre_approved": false
    },
    "status": "SUCCESS"
    }

  2. Call the /ws/retry API to schedule the Pix Automático payment retry

    Very Important!

    Payments can be retried once a day, up to 3 times, in a 7 day period after notification. After 3 unsuccessful retry attempts or 7 days past with no confirmation, the payment will be automatically canceled

    Your title

    Using the ID provided in merchant_payment_code, from the previous step, use the ws/retry endpoint to schedule.

    Check the example:

    curl POST 'https://sandbox.ebanxpay.com/retry' \
    --header 'Content-Type: application/json' \
    --data '{
    "integration_key": "{{integration_key}}",
    "merchant_payment_code": "{{unique_payment_code}}"
    }'

    A successful request will return a JSON response like the one below. The Pix Automático payment will still have a pending (PE) status and the available retries will decrease.

    {
    "payment": {
    "hash": "{{unique_payment_hash}}",
    "country": "br",
    "merchant_payment_code": "{{unique_payment_code}}",
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "status": "PE",
    "available_retries": 2,
    "status_date": "2024-01-17 03:00:00",
    "open_date": "2024-01-10 13:00:00",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "19.90",
    "amount_ext": "19.90",
    "amount_iof": "0.00",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2024-01-17",
    "payment_type_code": "pix-automatico",
    "pre_approved": false
    },
    "status": "SUCCESS"
    }

  3. Confirming the Payment after a Retry

    Your title

    As soon as the payment retry is confirmed by the customer's bank, the payment status is modified from PE to CO and a Status Update notification is sent.

    {
    "operation":"payment_status_change",
    "notification_type":"update",
    "merchant_payment_code":"{{unique_payment_code}}"
    }

    Using the ID provided in merchant_payment_code, use the ws/query endpoint to get the latest status of the payment.

    Check the example:

    curl POST 'https://sandbox.ebanxpay.com/query' \
    --header 'Content-Type: application/json' \
    --data '{
    "integration_key": "{{integration_key}}",
    "merchant_payment_code": "{{unique_payment_code}}"
    }'

    A successful request will return a JSON response like the one below, with a status of CO for the successful recurring payment.

    {
    "payment": {
    "hash": "{{unique_payment_hash}}",
    "country": "br",
    "merchant_payment_code": "{{unique_payment_code}}",
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "status": "CO",
    "status_date": "2024-01-17 03:00:00",
    "open_date": "2024-01-10 13:00:00",
    "confirm_date": "2024-01-17 03:00:00",
    "transfer_date": null,
    "amount_br": "19.90",
    "amount_ext": "19.90",
    "amount_iof": "0.00",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2024-01-17",
    "payment_type_code": "pix-automatico",
    "pre_approved": false
    },
    "status": "SUCCESS"
    }
note

Pix Automático goes live on June 16th 2025. Stay tuned for Sandbox Environment availability on December 1st 2024!

Still need help?

Help Image

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

Edit this page
Last updated on by Alex Nunes Gonzaga
On This Page