Prerequisites

Initial Setup

Request Format

Headers

To authenticate your requests to the payment gateway, include your API KEY in the header section of every request.

The header should be structured as follows:

Key	Value
X-API-Key	YOUR_API_KEY

Note that any request sent to the API without this key will not be recognized, and an error message will be returned in response.

Security

We prioritize the security of our payment gateway and employ secure communication methods between you and the gateway.

Encryption Algorithm

We utilize aes-256-gcm for data encryption. You can decrypt the response using the secret key provided during registration. Keep your secret key confidential to ensure the security of your transactions.

All HTTP responses with status codes 203 and 495 are encrypted:

JSON

{
    "body": {
        "cipher": "mxNRNrDCtspjBdyNv/E1JHMh629xOpo87dpKLJh2UI8W7VNtOQt2zK7lqwCfPZvv71/NEM47iVODxkJvKzaw8UohWGQ1ubs8MD2XatwOO/i9NFTFXVKZPw1OyGgEFZ2eKWAaHbjzSS0tYNoJS61WHyuy5IbObh+kmQ==",
        "iv": "OD4rGatpEqX4snQI",
        "tag": "quo+cB0arhwcPGk07mRcKQ=="
    }
}
 

Other HTTP response codes will return a simple message:

JSON

{  
    "message": "We failed to process the response for you. We are working tirelessly to resolve the issue."  
}

Decrypting the Payload

Responses with status codes 203 and 495 are always encrypted. You will need your secret key to decrypt the message. The algorithm used is aes-256-gcm. Additionally,

🚧

the tag field sent with the payload is base64 encoded and must be decoded before attempting to decrypt the message.

Here's an example decryption method in PHP:

PHP

public function decrypt($payload): bool|string  
{  
    $secret_key = env(secret);  
    return openssl_decrypt(  
        $payload['cipher'],  
        'aes-256-gcm',  
        $secret_key,  
        0,  
        $payload['iv'],  
        base64_decode($payload['tag']),  
    );  
}

And here's a similar decryption method in Python:

Python

from Crypto.Cipher import AES  
from Crypto.Util.Padding import unpad  
from Crypto.Random import get_random_bytes  
import base64  
import os  

def decrypt(payload):  
    secret_key = os.environ.get('SECRET_KEY')  
    cipher_text = base64.b64decode(payload['cipher'])  
    iv = payload['iv']  
    tag = base64.b64decode(payload['tag'])  
    cipher = AES.new(secret_key.encode('utf-8'), AES.MODE_GCM, nonce=iv.encode('utf-8'))  
    decrypted_data = cipher.decrypt_and_verify(cipher_text, tag)  
    return decrypted_data.decode('utf-8')

Please refer to the documentation for your preferred programming language for further guidance on decrypting AES-256-GCM payloads.

👍

Cancel and Success URLs

If the merchant gives these urls in th e initial request, we shall ping these urls according to the status of the transaction

Eg if the url is www.yoursite.com/success
then the we shall ping the url in the form of

www.yoursite.com/success?status=success&order_id=(base64EncodedStringOfTheOriginalMerchantOrderId)

Same Format will be used for Cancel Url

👍

Web-hook URL

This is a server to server communication, and it must be provided during the initial Checkout Request otherwise the request wont go through, This is true for both Mobile Payments and Card Payments.

Final Notes.

Once a request is made to the gateway, there is a designated waiting period for payment to complete:

• Mobile Transactions: 10 minutes
• Card Transactions: 15 minutes

If the transaction is not completed within these time frames, the order will automatically be marked as Cancelled. Any orders marked as Cancelled will only be reconsidered if evidence is provided showing that payment was made within the designated window and it got ACCEPTED. Beyond this, it’s recommended to create a new request.

Please note: Cancelled orders will be automatically deleted from our servers after 60 days from their creation date. For cases involving disputes, we advise that you record the transaction details and promptly reach out to our support team to prevent the record from being purged.

Trawx is not responsible for any issues resulting from merchant negligence.