Numipay Gateway (1.0.1)

The Payments API helps you to process payments of your customers using a variety of payment methods and a single API Endpoint. You can easily and securely process payments from your customers using either the:

1. Hosted Payment API: This hosted checkout solution offers a variety of payment options for your convenience through a single integration.

2. Direct Integration API: This hosted checkout allows users to be redirected directly to the payment provider for processing bypassing the cashier.

3. Server-to-Server API: This option enables you to use your own payment form to collect card information, which is then securely transmitted to us. Note: You must be PCI certified to use this integration.

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

# Before you begin All requests must be made using HTTPS. Authentication is handled via an API Key, which needs to be included in the headers as **X-Api-Key**.

Obtaining Your API and Secret Keys

The APIs require a dedicated Merchant API Key for all requests. You can generate this key within the merchant portal.

API keys can be created by navigating to Settings > Credentials.

# Error Handling

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

Status range	Description
2xx	indicates a successful request
4xx	indicates there is a problem with the client's request
5xx	indicates there is a problem with our servers/infrastructure. In this case it is our responsibility to fix the issue

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.

# Testing

Test accounts enable you to test and process API transactions in an environment that replicates the production system.

Payment transactions in the test environment can be executed using the simulator. To create test payments, use the same URL as in production but ensure you utilize a DEV API Key. This key can be created under Settings > Credentials.

# Webhook When integrating with our system, you will receive webhooks each time the status of a transaction changes. These webhooks provide a convenient way to keep up-to-date with real-time information about your transactions. If your webhook URL is temporarily inaccessible when notifications are sent, 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"
  }

Webhook Payload Explanation

• transaction_id: Our unique identifier for the particular transaction.
• user_id: The user ID associated with the transaction.
• tracking_id: Your unique identifier to track the request, this was sent 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 "deposit" or "withdrawal".

Webhook Signature

To ensure the integrity and authenticity of the data in these webhooks, it is essential 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 the signature, you must use the SHA-1 hashing algorithm. Update the hash with the payload, and then convert it to an uppercase hexadecimal representation.

**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"