Initialize Payment

The initialize payment endpoint allows you to create a payment request and get a payment URL that customers can use to complete their payment.

Endpoint

POST https://api.resolutpay.com/transaction/initialize

Request Parameters

Parameter	Type	Required	Description
amount	integer	Yes	Amount in pesewas (smallest currency unit)
email	string	Yes	Customer's email address
reference	string	Yes	Unique reference for the transaction
callback_url	string	Yes	URL to redirect customer after payment
currency	string	No	Currency code (default: GHS)
metadata	object	No	Additional data to store with transaction
channels	array	No	Payment channels to enable
split_code	string	No	Split payment code
subaccount	string	No	Subaccount code
transaction_charge	integer	No	Transaction charge in pesewas
bearer	string	No	Who bears the transaction charge

Example Request

const axios = require("axios");

const initializePayment = async () => {
  try {
    const response = await axios.post(
      "https://api.resolutpay.com/transaction/initialize",
      {
        amount: 5000, // 50 GHS in pesewas
        email: "customer@example.com",
        reference: "REF_" + Date.now(),
        callback_url: "https://yourwebsite.com/verify",
        currency: "GHS",
        metadata: {
          custom_fields: [
            {
              display_name: "Invoice ID",
              variable_name: "invoice_id",
              value: "INV-001",
            },
          ],
        },
        channels: [
          "card",
          "bank",
          "ussd",
          "qr",
          "mobile_money",
          "bank_transfer",
        ],
      },
      {
        headers: {
          Authorization: "Bearer YOUR_SECRET_KEY",
          "Content-Type": "application/json",
        },
      }
    );

    console.log("Payment URL:", response.data.data.authorization_url);
    return response.data;
  } catch (error) {
    console.error("Error:", error.response.data);
    throw error;
  }
};

Example Response

{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.resolutpay.com/0/peJh7nXxKz",
    "access_code": "0/peJh7nXxKz",
    "reference": "REF_1234567890"
  }
}

Payment Channels

You can specify which payment methods to enable:

Channel	Description
card	Credit and debit cards
bank	Bank transfers
ussd	USSD payments
qr	QR code payments
mobile_money	Mobile money
bank_transfer	Direct bank transfers

Metadata

Use the metadata field to store additional information with your transaction:

metadata: {
  custom_fields: [
    {
      display_name: 'Customer Name',
      variable_name: 'customer_name',
      value: 'John Doe'
    },
    {
      display_name: 'Order ID',
      variable_name: 'order_id',
      value: 'ORD-123'
    }
  ],
  referrer: 'website',
  cancel_action: 'https://yourwebsite.com/cancel'
}

Split Payments

For split payments, include the split_code parameter:

{
  amount: 5000,
  email: 'customer@example.com',
  reference: 'REF_' + Date.now(),
  callback_url: 'https://yourwebsite.com/verify',
  split_code: 'SPL_xxxxxxxxxx'
}

Subaccounts

To process payments for a subaccount:

{
  amount: 5000,
  email: 'customer@example.com',
  reference: 'REF_' + Date.now(),
  callback_url: 'https://yourwebsite.com/verify',
  subaccount: 'ACCT_xxxxxxxxxx'
}

Transaction Charges

Specify who bears the transaction charge:

{
  amount: 5000,
  email: 'customer@example.com',
  reference: 'REF_' + Date.now(),
  callback_url: 'https://yourwebsite.com/verify',
  transaction_charge: 100, // 1 GHS in pesewas
  bearer: 'account' // 'account', 'subaccount', or 'customer'
}

Error Responses

Common error responses:

{
  "status": false,
  "message": "Invalid amount",
  "data": null
}

Error	Description
Invalid amount	Amount is less than minimum or invalid
Invalid email	Email format is invalid
Invalid reference	Reference already exists
Invalid callback_url	Callback URL is invalid

Complete Example

Here's a complete example with error handling:

const express = require("express");
const axios = require("axios");
const app = express();

app.use(express.json());

app.post("/initialize-payment", async (req, res) => {
  try {
    const { amount, email, reference } = req.body;

    // Validate required fields
    if (!amount || !email || !reference) {
      return res.status(400).json({
        success: false,
        message: "Amount, email, and reference are required",
      });
    }

    // Validate amount (minimum 100 pesewas = 1 GHS)
    if (amount < 100) {
      return res.status(400).json({
        success: false,
        message: "Amount must be at least 100 pesewas (1 GHS)",
      });
    }

    const response = await axios.post(
      "https://api.resolutpay.com/transaction/initialize",
      {
        amount: amount,
        email: email,
        reference: reference,
        callback_url: "https://yourwebsite.com/verify",
        currency: "GHS",
        channels: ["card", "bank", "ussd", "mobile_money"],
        metadata: {
          custom_fields: [
            {
              display_name: "Customer Name",
              variable_name: "customer_name",
              value: req.body.customer_name || "Anonymous",
            },
          ],
        },
      },
      {
        headers: {
          Authorization: `Bearer ${process.env.RESOLUTPAY_SECRET_KEY}`,
          "Content-Type": "application/json",
        },
      }
    );

    res.json({
      success: true,
      data: response.data.data,
    });
  } catch (error) {
    console.error(
      "Payment initialization error:",
      error.response?.data || error.message
    );

    res.status(500).json({
      success: false,
      message: error.response?.data?.message || "Failed to initialize payment",
    });
  }
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

Next Steps

• Verify Payment - Learn how to verify payment status
• Charge Card - Process card payments directly
• Webhooks - Set up real-time payment notifications