Callbacks in Gate

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

What callbacks in Rocketpay look like

Callbacks are HTTP POST requests sent to the URL that you provide Rocketpay 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 Rocketpay 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 Rocketpay always have a signature. For the information on how to verify the signature in a callback, see Signature generation and verification.

When Rocketpay sends callbacks

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

• your system has to perform certain actions for the payment. For more information about this kind of callbacks, see the information below.
• a card token has been generated, revoked or expired. For more information about callbacks with token information, see Token-related callback parameters.
• the operation has finished processing in the Rocketpay payment platform. The callback will have the status of the operation.

When there are some actions to perform the payment required from your system, the Rocketpay payment platform assigns a certain status to the payment and sends you a respective callback. To learn more about operation statuses at the Rocketpay payment platform, see Payment types, operations and payments.

Listed below are some of the actions that may be required from your system to perform a payment:

• Your system has to send Rocketpay the data required for purchase performing. In this case, Rocketpay will send you a callback where the necessary data is indicated. Learn more about such cases at Submission of additional payment information.

  Figure: Example of a callback fragment where the data required to perform the purchase is indicated

  "clarification_fields": {
              "account": {
                  "type": "object",
                  "description": "Object contains the account details of bank",
                  "properties": {
                      "number": {
                          "type": "string",
                          "maxLength": 100,
                          "minLength": 1,
                          "description": "Customer account number"
                      }
                  },
                  "required": [
                      "number"
                  ],
                  "errors": [
                      {
                          "property": "account.number",
                          "message": "The property number is required",
                          "constraint": "required"
                      }
                  ]
              }
          },

• Your system has to send Rocketpay the data that your customer received from the payment system when making a payment. It may be, for example, a transaction ID or a payment verification code. In this case, Rocketpay will send you a callback where the data required for the payment to proceed is indicated.

  If the payment system sends the customer some data that you then should pass to the payment platform, it will be mentioned in the section of the payment method the payment was initiated with. See Payment methods for the list of payment methods supported in Rocketpay.

  Figure: Example of a callback fragment where the data required for the payment to proceed is indicated

  {
      "clarification_fields": [
          "approval_code"
      ]
  }

• Your system has to perform some actions for the customer to complete 3-D Secure authentication. To learn more about this procedure, see the Customer authentication by using the 3‑D Secure 1 and Authentication by using 3‑D Secure 2 sections or reach out to your key account manager at Rocketpay.
• Your system has to redirect the customer so that they could complete the purchase on the provider's side. In this case, Rocketpay will send you a callback with the data to redirect the customer.

  Figure: Example of a callback fragment with customer redirection data

  "redirect_data": {
      "method": "GET",
      "body": [],
      "encrypted": [],
      "url": "https://example.com/redirect"
  }

• Your system has to display some information to the customer (for example, payment instructions or a QR code) so that they could make a purchase. In this case, Rocketpay will send you a callback with the data to display to the customer.

  Figure: Example of a callback fragment with the data to display to the customer

  "display_data": [
              {
                  "type": "qr_data",
                  "title": "QR code",
                  "data": "00020101com.359a71a-0cad-4cb2-a9503***63042BBF"
              }
          ],

Callback delivery addresses

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

You can provide Rocketpay 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 payment 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 where Rocketpay 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 Rocketpay when integrating. To double-check the IP address, contact the Rocketpay 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 initial payment request and set its value to the URL that Rocketpay 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 any 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.

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "merchant_callback_url": "http://example.com/callback/default",
        "merchant_success_callback_url": "http://example.com/success",
        "merchant_decline_callback_url": "http://example.com/decline",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "payment": {
        "amount": 10000,
        "currency": "USD"
    }
}

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 Rocketpay 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, Rocketpay 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, Rocketpay sends 120 callbacks within 11 days. The callback delivery schedule may insignificantly change depending on the system load.

You can delay callback delivery for a specific payment. To do so, add the delay parameter in the callback object to your request and set the value of this parameter to the number of seconds the callback is to be delayed for. Callback delivery can be delayed for 600 seconds maximum.

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "payment": {
        "amount": 10000,
        "currency": "USD"
    },
    "callback": {
            "delay": 30                // delivery time delay in seconds
    }
}