Cube Pay Gateway (1.0.4)

You can easily and securely process payments from your customers using either the:

1. Payment API (This is a hosted checkout that will provide you will all payment options)
2. Direct Integration API (This is a hosted checkout where the user will be taken directly to the payin provider)

The Payments API helps you to process payments of your customers using a variety of payment methods and a single API Endpoint.

Merchants can also access your transaction analytics and manage accounts within the merchant portal.

All requests must use HTTPS. Authentication is achieved using an API Key, passed headers, namely X-Api-Key.

Get your API and Secret Keys

The API’s use a dedicated Merchant API key for all requests. You can create an API under the merchant portal.

The API’s can be generated under Settings - Credentials

We use HTTP statuses for our response as per the HTTP specification

If you receive a 4xx HTTP status response, it is safe to retry the request after fixing the root cause of the problem (either your request parameters or your account configuration).

If you receive a 5xx HTTP status response, please contact our support with the request information so we can investigate.

Gateway specific codes

For a 400 Bad Request we will provide specific codes and descriptions in the body of the response.

Test accounts allow you to test and process API transactions that mirror the production environment.

Payment transactions processed in the Test environment are executed on a simulator. To create a test payments call the URL does not change. You will just need to ensure you use a DEV API key which can be created under Settings – Credentials

When integrating with our system, you will receive webhooks every time the status of a transaction changes. These webhooks are a convenient way to stay up to date with the latest information about your transactions in real-time. If your webhook URL is temporarily inaccessible when we send notifications, our system will automatically retry every five minutes, up to a maximum of 15 attempts.

Below is an example of the payload you will receive in these webhooks:

  {
    "transaction_id": "bbds7128hdha",
    "user_id": "123",
    "tracking_id": "kshdhay6381623",
    "status": "successful",
    "currency": "EUR",
    "amount": "200.00",
    "transaction_type": "withdrawal"
    "provider": "simulator"
    "rejected_reason": "Insufficient funds"

  }

Webhook Payload Explanation

• transaction_id: The unique identifier for the transaction in our side.
• user_id: The user ID associated with the transaction.
• tracking_id: The unique identifier in your side, which was send when you made the request.
• status: The current status of the transaction, which can be:
  • expired
  • rejected
  • successful
  • pending
• currency: The currency in which the transaction is conducted (e.g. EUR).
• amount: The amount of the transaction (e.g., "200.00").
• transaction_type: Describes the type of transaction, such as "withdrawal" or "deposit".
• provider: The payment provider used for the transaction. You will receive this when available.
• rejected_reason: The reason why the transaction was rejected. You will receive this when the transaction is rejected and we have the reason available.

Webhook Signature

To ensure the integrity and authenticity of the data in these webhooks, it's crucial to verify the included signature. This guide explains how to verify the webhook signature generated by our system. When you receive a webhook, it will include an "x-signature" header in the HTTP request. To generate signature you must use the SHA-1 hashing algorithm. Update the hash with the payload, and then convert it to a hexadecimal representation in uppercase. The payload should be used exactly as we send it to you without any modifications.

Signature sample (NodeJs):

      const crypto = require("crypto");
      const data = /* Data object from the webhook payload */;
      const signaturePassword = /* Your secret signature password that can be find in BACK OFFICE under Credentials page */;
      const payloadForHash = JSON.stringify(data) + signaturePassword;
      const localSignature = crypto
        .createHash("sha1")
        .update(payloadForHash)
        .digest("hex")
        .toUpperCase();

Example:

  payload = 
    {
      "transaction_id":"r21nmrtpcmrcava",
      "user_id":"1111222",
      "tracking_id":"b8f04416-116a-11ed-861d-0242ac120002",
      "status":"rejected",
      "currency":"GBP",
      "amount":"200.00",
      "transaction_type":"withdrawal"
    }
  
  signature_password = spg_test_companyxxxxQyGAheyMqcHVmp8ZMQtkYcev27sCu7RF

Calculated Hash: "5FDDA8F46411C132DCFBEE53C39BA06298CB48BC"