Prophius Payment Checkout SDK Integration

Introduction

The Payment Gateway SDK enables developers to integrate seamless payment functionalities into their web applications. This document provides a detailed guide on integrating the SDK, configuring environment variables, handling transactions, and processing responses.

---

Installation

Include the SDK by adding the following <script> tag to your HTML file. Note that the CDN link is environment-specific:

• Test Environment: <script src="https://payment-gateway-sdk-k8.dev.prophius-api.com/cdn-v1.js"></script>

• Live Environment: <script src="https://payment-gateway-sdk-k8.dev.prophius-api.com/cdn-v1.js"></script>

---

Initialization

The Paycontactless class is used to initialize the payment gateway. Developers must provide their API Key, API Password, and Merchant Code, which are specific to the environment (test or live) and should be securely stored in environment variables or a configuration file.

---

Constructor Parameters

Parameter	Type	Description
apiKey	string	Your API key for authenticating requests (specific to test or live).
apiPassword	string	Your API password for authenticating requests.
merchantCode	string	Your merchant identification code.

---

Example Usage

const paycontactless = new Paycontactless({ apiPassword: process.env.API_PASSWORD, // Fetch from environment variable apiKey: process.env.API_KEY, // Fetch from environment variable merchantCode: process.env.MERCHANT_CODE, // Fetch from environment variable });

---

Initiating a Transaction

Use the initTransaction method to start a payment process. It accepts an object with the following parameters:

---

Parameters

Parameter	Type	Required	Description
amount	string	Yes	The transaction amount in the specified currency.
currency	string	Yes	The currency code (e.g., NGN, USD).
callbackUrl	string	Yes	The URL to redirect to on a successful transaction.
redirectUrl	string	Yes	The URL to redirect to after completing the process.
transactionRef	string	No	Custom reference for the transaction (auto-generated if not provided).
onSuccess	function	No	Callback function executed on success.
onError	function	No	Callback function executed on error or failure.

---

Example

await paycontactless.initTransaction({ amount: "1000", currency: "NGN", callbackUrl: "https://yourwebsite.com/callback", redirectUrl: "https://yourwebsite.com/redirect", onSuccess: (data) => { console.log("Transaction Successful", data); }, onError: (error) => { console.error("Transaction Failed", error); }, });

---

Responses

---

Success Response

The onSuccess callback is executed on a successful transaction and returns the following structure:

{ "event": "event:success", "data": { "referenceNumber": "REF123456789", "transactionRef": "ref_123456789_random", "amount": "1000", "currency": "NGN", "status": "success" } }

Field Descriptions

• referenceNumber: Unique identifier for the transaction.

• transactionRef: The custom or auto-generated reference number.

• amount: The transaction amount.

• currency: The transaction currency.

• status: The status of the transaction (e.g., "success").

---

Error Responses

Validation Error

{ "event": "event:error" "message": "Invalid input. Supported values are: NGN, USD, GBP." }

Payment Failure

{ "event": "event:failed", "data": { "respDesc": "Insufficient funds", "transactionRef": "ref_123456789_random", "status": "failed" } }

Cancellation Event

{ "event": "event:cancelled", "data": { "transactionRef": "ref_123456789_random", "status": "cancelled" } }

---

Error Handling Best Practices

1. Ensure that apiKey, apiPassword, and merchantCode are securely stored in environment variables or configuration files.

2. Validate input values for amount and currency before calling initTransaction.

3. Use the onError callback to handle any errors gracefully.

---

Environment-Specific Details

1. Keys:

   • Test Environment Keys: For testing purposes, use the test keys.

   • Live Environment Keys: For production, use the live keys provided for your payment gateway account.

2. Testing: You can test your integration on the Test Environment using the URL: https://payment-gateway-sdk-k8.dev.prophius-api.com/test

---

Support

If you encounter any issues or need further assistance, please contact our support team: 📧 Email: [e-mail]