QUICK START GUIDE

This guide will walk you through the basics of setting up your integration with Transactpay, from generating API keys to making your first API call.

Step 1: Get Your API Keys

When you sign up for a Transactpay account, you're provided with two sets of API keys for both Test and Live environments:

Key Types

Public Key

Used in public or client-side applications (e.g., JavaScript or mobile apps). It can initiate transactions but cannot access sensitive data or make administrative changes.
Secret Key

Your most powerful credential. It has full access to your account and should only be used in secure, server-side environments.
Encryption Key

Required only for specific operations like direct card charges. See the Encryption Guide for how to use it.

⚠️
Security Warning:

Never expose your Secret Key in frontend code (JavaScript, HTML, etc.).

Do not commit it to version control or include it in public repositories.

Always store it in a secure environment variable on your backend.

If your key is exposed or compromised, regenerate it immediately from your dashboard.

You can find or regenerate your API keys by:

Logging in to your Transactpay Dashboard.
Navigating to Settings.
Clicking on API Keys & Webhooks.

Step 2: Authenticate API Requests

All Transactpay API requests require authentication. Any request made without a valid Secret Key will fail with a 401 Unauthorized response.

Include your Secret Key as a Bearer token in the Authorization header like so:

--header 'api-key: YOUR_PUBLIC_KEY'

⚠️
Warning:
Do not hardcode your secret key directly into your codebase. Use environment variables to manage secrets securely.

Step 3: Make Your First API Request

To start a transaction, send a POST request to the Create Order endpoint.

Here’s an example using Axios in Node.js:

const axios = require('axios');

const data = JSON.stringify({
  customer: {
    firstname: "transact",
    lastname: "pay",
    mobile: "+2348134543421",
    country: "NG",
    email: "[email protected]"
  },
  order: {
    amount: 100,
    reference: "",
    description: "Pay",
    currency: "NGN"
  },
  payment: {
    RedirectUrl: "https://www.hi.com"
  }
});

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://payment-api-service.transactpay.ai/payment/order/create',
  headers: {
    'api-key': 'PGW-PUBLICKEY-TEST-26795CB9393A4AF8BA931E8DA967FF3E',
    'Content-Type': 'application/json'
  },
  data: data
};

axios.request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.error(error);
  });

Expected Response

A payment link for customer redirection.
Order details.
Transaction status.

{
    "data": {
        "order": {
            "reference": "541368781",
            "processorReference": "TRNPAY-45E9614E-70A6-405E-8565-5FD433679D92",
            "orderPaymentReference": null,
            "amount": 100.0000,
            "fee": 0.0000,
            "feeRate": 0.0000,
            "statusId": 1,
            "status": "Initiated",
            "currency": "NGN",
            "narration": "Pay",
            "recurringPaymentId": null
        },
        "subsidiary": {
            "id": 125,
            "name": "Transactpay",
            "country": "NG",
            "supportEmail": "[email protected]",
            "customization": []
        },
        "customer": {
            "email": "[email protected]",
            "firstName": "transact",
            "lastName": "pay",
            "mobile": "+2348134543421",
            "country": "NG"
        },
        "payment": {
            "code": null,
            "source": "Selected by Customer",
            "selectedOption": null,
            "accountNumber": null,
            "bankProviderName": null
        },
        "otherPaymentOptions": [
            {
                "code": "C",
                "name": "Card Payment",
                "currency": "NGN"
            },
            {
                "code": "BANK-TRANSFER",
                "name": "Pay With Bank Transfer",
                "currency": "NGN"
            },
            {
                "code": "Opay",
                "name": "Pay With Opay",
                "currency": "NGN"
            }
        ],
        "savedCards": [],
        "subsidiaryOrderSummary": {
            "orderName": "Transactpay Order 541368781",
            "totalAmount": 100.0,
            "reference": "541368781",
            "currency": "NGN",
            "recurringPaymentId": null,
            "orderItems": [
                {
                    "name": "Summary",
                    "amount": 100.0
                }
            ]
        },
        "isDiscounted": false,
        "oldAmount": null,
        "newAmount": null,
        "discountAmount": null,
        "mandateCode": null
    },
    "status": "success",
    "statusCode": "01",
    "message": "Created order successfully"
}

Additional Security Best Practices

Never expose your secret key in any public code.
Validate and sanitize user inputs before making API requests.
Use HTTPS for all communications to secure sensitive data.
Keep your dependencies updated to avoid known vulnerabilities.

API Key Management Best Practices

Store your secret keys in secure vaults or server-side environment variables.
Rotate your keys regularly or after a suspected breach.
Audit access logs and monitor for unusual activity.
Use Test keys in development and Live keys only in production.

⚠️
Warning:
Do not share screenshots, logs, or documentation that include your secret key. Avoid transmitting keys via unencrypted channels.

Next Steps

Now that you've successfully made your first API call, explore what else you can build:

Charge a card directly
Handle webhooks
Manage refunds and settlements

👉 Dive deeper with our Full API Reference.

If you need help managing your API keys or believe a key has been compromised, contact Transactpay support immediately.