# 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." }`

&#x20;

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

&#x20;

***

**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.&#x20;
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**: <support@prophius.com>

<br>