# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.prophius.com/developer-console/untitled/prophius-payment-checkout-sdk-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.