Callbacks in Payment Page

Callback is a system message that the maxaa payment platform sends to the merchant's URL to pass some information, for example payment result.

What callbacks in maxaa look like

Callbacks are HTTP POST requests sent to the URL that you provide maxaa with when integrating.

The callback body contains a JSON string of parameters. You can configure what parameters are to be sent in the request body. To do so, contact the maxaa technical support.

Here is an example of a callback body of the typical structure. For demonstration purposes, the contents of the JSON string in the example are split into multiple lines.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "mobile",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d150e387a16a80e336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

The following is an example of the body of a customized callback.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "mobile",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "description": ""
    },
    "customer": {            // object with expanded customer data
        "id": "customer_123",
        "email": "johndoe@example.com",
        "phone": "491234567890",
        "first_name": "John",
        "last_name": "Doe"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d150e387a16a80e336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

The callbacks from maxaa always have a signature. For the information on how to verify the signature in a callback, see Signature generation and verification.

When maxaa sends callbacks

The maxaa payment platform sends you callbacks in the following cases:

• the status of the payment has been changed. It may be due to, for example, redirecting the customer, displaying them payment instructions, completing 3D-Secure authentication, asking the customer to provide data required for the payment, etc. To learn more about operation statuses at the maxaa payment platform, see Payment types, operations and payments.

  If you perform payments by using Payment Page, these callbacks are sent to you for informational purposes only. Your system just has to respond with the HTTP 200 OK status code to them, no other action is required. Also, you can choose not to receive such callbacks. To do so, contact the maxaa technical support.

• a card token has been generated, revoked or expired. See the example of such a callback in the Callback section.
• the operation has finished processing in the maxaa payment platform.

Callback delivery addresses

Callbacks are sent to the URL that you provide maxaa with when integrating. If you have several projects, you can provide maxaa with individual URLs for each project.

You can provide maxaa with individual URLs to receive callbacks with certain information about the payment, e.g. for the payment platform to send you callbacks for successfully performed payments to one URL and callbacks for the declined ones to the other. You can also use individual URLs to receive callbacks for the payments of a certain type or payments performed with a specific payment method.

You can specify individual URLs for receiving callbacks yourself by using Dashboard. To do so, go to Dashboard, select the Projects section, and then click the Callbacks tab. The tools in Dashboard allow you to specify in what cases and what URLs maxaa will send callbacks to. To learn more about specifying URLs in Dashboard, see Working with callback settings.

Please note that your system must accept callbacks only from the IP address you receive from maxaa when integrating. To double-check the IP address, contact the maxaa technical support.

Callback delivery addresses for a specific payment

You can also specify an individual URL for receiving callbacks for a specific payment. To do so, add the merchant_callback_url parameter to the request for opening the checkout page and set its value to the URL that maxaa should use to send callbacks to. After that the payment platform will send all the callbacks related to the payment (and only to this payment) to this URL ignoring the callback URLs configured in your project.

Also, you can specify the URLs the payment platform will use to send the final callback to with the information about the payment outcome. To do so, simply add one or both of the following parameters to your request:

• merchant_success_callback_url—the URL which the payment platform will send the final callback to if the payment is successfully completed
• merchant_decline_callback_url —the URL which the payment platform will send the final callback to if the payment is declined.

These parameters always override the merchant_callback_url parameter and the project settings. For example, if you specify both merchant_callback_url and merchant_success_callback_url parameters, the payment platform will use the URL specified in merchant_success_callback_url and ignore both merchant_callback_url and the default URL specified in your project at the payment platform. The same applies to merchant_decline_callback_url for the final decline callback URL.

EPayWidget.run(
    {
        project_id: 1234,
        payment_id: 'payment_47',
        customer_id: 'customer_123',
        customer_first_name: 'John',
        customer_last_name: 'Doe',
        customer_email: 'johndoe@example.com',
        merchant_callback_url: 'http://example.com/callback/default',
        merchant_success_callback_url: 'http://example.com/success',
        merchant_decline_callback_url: 'http://example.com/decline',
        payment_currency: 'USD',
        payment_amount: 10000,    
        signature: 'kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO\/RLUkDJrOcZzUCwX6R\/ekpZhkIQg=='
    }
)

How to respond to callbacks

Your system must respond to the callback with the HTTP 200 OK status code if it has successfully accepted it. Please note that your system shouldn't have any limitations on the time callbacks are received because callbacks from maxaa may be sent with delay.

If your system fails to accept and/or process a callback, it must respond to it with the relevant error message like 400 Bad Request status code (for example, if you were unable to convert a parameter string to an array) or 500 Internal Server Error status code (for example, if the callback was sent to the wrong URL). Even though your system wasn't able to accept and/or process a callback, it must be ready to accept further callbacks for this payment.

If your system hasn't responded with the HTTP 200 OK status code to the callback, maxaa will resend callbacks according to the following schedule:

• 6 attempts at 10-second intervals
• then 62 attempts within 4 hours with increasing intervals. The interval increases according to the formula: 70 + 10·1,12n-4, where n is the serial number of the attempt
• after that, the callbacks are sent every 4 hours until the maximum number of attempts is achieved.

In total, maxaa sends 120 callbacks within 11 days. The callback delivery schedule may insignificantly change depending on the system load.