🚀 Cards H2H Library

A powerful library for partners to seamlessly integrate a payment form on their website, allowing customers to complete transactions without leaving the site. All payments are processed securely by Pay Retailers.

Installation

First, install the package via NPM:

npm install @payretailers1/h2h-widget

Usage

Import and Setup To use the SDK, import the PrCards class from the package:

import { PrCards } from "@payretailers1/h2h-widget";

Class Initialization

Create an instance of PrCards and use the init method to initialize the payment form.

Basic JavaScript Example

const prCards = new PrCards();

prCards.init({
    transactionId: "123456", // Generado previamente por tu backend
    containerId: "payment-container", // ID del div donde se inyectará el iframe
    styles: {
        width: "100%",
        height: "500px",
        border: "none",
    },
    callbacks: {
        onLoad: () => {
            console.log("Formulario cargado");
        },
        onSuccess: (response) => {
            console.log("Pago exitoso:", response);
        },
        onError: (error) => {
            console.error("Error:", error);
        },
    },
});

Usage with React

import React, { useEffect } from "react";
import { PrCards } from "@payretailers1/h2h-widget";

const PaymentComponent = () => {
    useEffect(() => {
        const prCards = new PrCards();

        prCards.init({
            transactionId: "123456", // Generado previamente
            containerId: "payment-container",
            styles: {
                width: "100%",
                height: "500px",
                border: "none",
            },
            callbacks: {
                onLoad: () => {
                    console.log("Formulario cargado");
                },
                onSuccess: (response) => {
                    console.log("Pago exitoso:", response);
                },
                onError: (error) => {
                    console.error("Error:", error);
                },
            },
        });

        return () => {
            prCards.destroy(); // Limpia el formulario al desmontar el componente
        };
    }, []);

    return <div id="payment-container"></div>;
};

export default PaymentComponent;

Usage in Vue with Nuxt

<template>
    <div id="payment-component"></div>
</template>

<script>
import { PrCards } from '@payretailers1/h2h-widget';


export default {
    name: 'PaymentForm',
    data() {
        return {
            showPaymentComponent: false,
            depositAmount: 0,
            amounts: [20, 50, 100, 200],
            prCards: new PrCards()
        };
    },
    methods: {
        loadWidget() {
            this.prCards.destroy();
            this.prCards.init({
                transactionId: '22aa2247-4b37-4bbc-9718-270179c2780e',
                containerId: 'payment-component',
                styles: {
                    'height': '100%',
                    'width': '100%',
                    'border': 'none',
                    'position': 'absolute',
                    'top': '0',
                    'left': '0',
                    'bottom': '0',
                    'right': '0',
                    'padding-top': '5%',
                    'borderColor': '#ffdjcj',
                    'backgroundColor': '#fffccff',
                    'loadAnimation': '../images/loader.gif'
                },
                callbacks: {
                    onLoad: () => console.log('Form loaded'),
                    onSuccess: (response) => {
                        console.log('Success handeled');
                        this.prCards.destroy();
                    },
                    onError: () => console.log('Error'),
                }
            });
            
        },

    }
};
</script>

Parameters for the init Method

The init method accepts an object of type PrCardsOptions:

export type PrCardsOptions = {
    transactionId: string;       // transaction ID (required)
    containerId: string;         // Div ID where the iframe will be injected (required)
    styles: { [key: string]: string }; // CSS styles for the iframe (optional)
    callbacks: Callbacks;        // Callback functions to handle events (required)
};

Callbacks The callbacks parameter should include the following methods:

• onLoad: Executes when the iframe finishes loading.
• onSuccess: Executes when a payment is successfully completed.
• onError: Executes when an error occurs.

RespuestaEvent Response

The SDK uses the following response types and event codes:

Response Types

type ResponseType = "ValidationError" | "PaymentError" | "PaymentSuccess";

Event Codes

export enum EventCodes {
    VALIDATION_ERROR = "VALIDATION_ERROR",
    PAYMENT_ERROR = "PAYMENT_ERROR",
    PAYMENT_SUCCESS = "PAYMENT_SUCCESS",
    NOT_FOUND = "NOT_FOUND",
    UNEXPECTED_EXCEPTION = "UNEXPECTED_EXCEPTION"
}

Errors and Exceptions

Missing Parameters

If any required parameter in the PrCardsOptions object (other than callbacks) is missing, a ValidationError will be logged to console.error:

export declare class ValidationError extends Response {
    constructor(message: string, details?: string | null);
}

Missing Callbacks

If any required callback is not defined, a CallbackError will be returned:

export declare class CallbackError extends ValidationError {
    constructor(message: string, details?: string | null);
}

Invalid Transaction

If the form does not find a transaction in a PENDING state, a PaymentError will be thrown:

export declare class PaymentError extends Response {
    readonly transactionId: string;
    constructor(transactionId: string, message: string, details?: string | null);
}

Successful Response

If the payment is successfully processed, the onSuccess callback will receive a PaymentSuccess object:

export declare class PaymentSuccess extends Response {
    readonly transactionId: string;
    constructor(transactionId: string, details?: string | null);
}

destroy Method

To clear the iframe from the container:

prCards.destroy();

This removes the form and stops any associated processes.