Integración con nuestra librería de React

Al darle click al botón Continuar, se mostrará tu zenkipayKey y un snippet de código que debes copiar y/o adaptar en tu sitio web, dicho snippet trae un ejemplo de la información requerida para poder realizar un pago.

react

En tu proyecto React, instala @zenkipay-pkg/react, para ello puedes revisar la lista de versiones aquí.

Ejecutamos en una terminal en el directorio root de nuestro proyecto:

1

npm i @zenkipay-pkg/react

Tienes a tu disposición nuestro componente ZenkipayButton que inserta el botón de pago de Zenkipay y nuestros hooks personalizados que te permiten consultar si tu comerciante tiene habilitado el descuento crypto love y su porcentage, o no; también te permite abrir la modal de pago. Dicho componente y hooks personalizados serán descritos a continuación:

Componente ZenkipayButton

Este componente cuenta con las siguientes propiedades y eventos:

Propiedad	Tipo	Descripción
zenkipayKey	cadena de texto	Requerido, cada comercio tiene sus propios `zenkipayKey`, hay una para la integración de pruebas y otra para la integración productiva.
purchaseData	cadena de texto	Requerido, es una instancia de PurchaseData transformado en cadena de texto.
purchaseSignature	cadena de texto	Requerido, esta firma debe ser proporcionada por tu servidor.
style	Style	Opcional, éste modifica el estilo visual del botón.

Evento	Tipo	Descripción
zenkiPayment	ZenkiPayment	Emite cada actualización de eventos de la modal de pago.
error	Error	Emite un evento cuando ocurre un error, así como su detalle.

Hook personalizado useGetDiscountPercentage

Puedes verificar si tu comerciante tiene un descuento habilitado usando este hook personalizado:

1

function useGetDiscountPercentage(): GetDiscountPercentageFn | null;

Cuando las dependencias de Zenkipay son importadas, éste returna una función de tipo GetDiscountPercentageFn, puedes usar ésta para verificar si tu comerciante tiene habilitado un porcentaje, en caso afirmativo retorna el porcentaje de dicho descuento, encaso contrario returna null.

Hook personalizado useOpenModal

Para abrir la modal de pago, puedes usar el siguiente hook:

1

function useOpenModal(): OpenModalFn | null;

Cuando las dependencias de Zenkipay son importadas, éste returna una función de tipo OpenModalFn, puedes usar ésta para abrir la modal de pago.

Pago de pruebas

Ya que tengas preparada tu integración, procedemos a realizar un pago de pruebas desde tu sitio, para ello le damos click en el botón Haz un pago de prueba con datos firmados, lo que te mostrará una modal como la siguiente:

common-test-01

Para realizar tu pago puedes seguir nuestra guía de pagos aquí.

Realiza tu primer pago

Ya que hayas realizado correctamente tu pago de pruebas, se te mostrará un mensaje de que hemos confirmado tu primer pago de integración.

common-test-02

Prueba rápida

Si aún no hayas generado tus llaves pública y privada, puedes continuar con la selección de tus criptomonedas aquí.

Si ya generaste tus llaves pública y privada, y firmaste tu Purchase Data, debes continuar con tu configuración de KYC.

Integración completa

Ya que hayas realizado tu prueba con tus datos firmados con tus llaves, podemos continuar con tu selección de criptomonedas.

Definición de entidades

Styles

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


class Style {
  theme?: Theme;
  shape?: Shape;
  size?: Size;
  expand?: Expand;
}

type Theme = "default" | "dark" | "light";

type Shape = "default" | "pill" | "square";

type Size = "default" | "sm" | "lg";

type Expand = "default" | "block";

Options

1
2
3
4
5
6
7
8


class Options {
  purchaseData!: string;
  purchaseSignature!: string;
  zenkipayKey?: string;
  style?: Style;
  zenkiPayment?: (zenkiPayment: ZenkiPayment) => void | Promise<void>;
  error?: (error: Error) => void | Promise<void>;
}

PurchaseData

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


class PurchaseData {
  country?: string;
  shopperCartId?: number | string;
  merchantOrderId?: number | string;
  shopperEmail?: string;
  purchaseSummary!: PurchaseSummary;
  items!: PurchaseItem[];
  metadata?: Metadata;
}

class PurchaseSummary {
  currency!: string;
  totalItemsAmount!: number | string;
  shipmentAmount!: number | string;
  subtotalAmount!: number | string;
  taxesAmount!: number | string;
  localTaxesAmount!: number | string;
  importCosts!: number | string;
  discountAmount!: number | string;
  additionalCharges?: AdditionalCharges;
  grandTotalAmount!: number | string;
}

class AdditionalCharges {
  [key: string]: number | string;
}

class PurchaseItem {
  itemId?: number | string;
  quantity!: number | string;
  price!: number | string;
  productName!: string;
  productDescription?: string;
  thumbnailUrl?: string;
  metadata?: Metadata;
}

class Metadata {
  [key: string]: number | string;
}

ZenkiPayment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


class ZenkiPayment {
  status!: POST_MSG_TYPE;
  isCompleted!: boolean;
  data?: DoneMsg | null;
}

enum POST_MSG_TYPE {
  ERROR = "error",
  CANCEL = "cancel",
  CLOSE = "close",
  DONE = "done",
}

class DoneMsg {
  orderId!: string;
}

FnCallback

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


type FnCallback = (
  error: Error | null,
  data: DoneMsg | null,
  details: MsgDetails
) => void;

class MsgDetails {
  postMsgType!: POST_MSG_TYPE;
  isCompleted!: boolean;
}

GetDiscountPercentageFn

1

type GetDiscountPercentageFn = (options: Options) => Promise<number | null>;

OpenModalFn

1

type OpenModalFn = (options: Options, callback?: FnCallback) => Promise<void>;

Ejemplos

A continuación se muestra un ejemplo de cómo puedes usar nuestro componente y nuestros hooks personalizados:

Usando el componente ZenkipayButton

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


import React, { useEffect, useState } from "react";
import { Style, ZenkiPayment, ZenkipayButton } from "@zenkipay-pkg/react";

import { getPurchaseData } from "./api/your-purchase-data.api";

export function App(): JSX.Element {
  const [zenkipayKey] = useState<string>(
    "e77e5b6662532432e9179ff4d33fe364ec88aacf9240e5e7673e474255e4a90c"
  );
  const [purchaseData, setPurchaseData] = useState<string>("");
  const [purchaseSignature, setPurchaseSignature] = useState<string>("");
  const [style] = useState<Style>({ size: "lg", shape: "pill" });

  useEffect((): void => {
    getPurchaseData().then(({ purchaseData, purchaseSignature }): void => {
      setPurchaseData(purchaseData);
      setPurchaseSignature(purchaseSignature);
    });
  }, []);

  return (
    <ZenkipayButton
      zenkipayKey={zenkipayKey}
      purchaseData={purchaseData}
      purchaseSignature={purchaseSignature}
      style={style}
      zenkiPayment={zenkiPayment}
      error={handleError}
    />
  );

  function zenkiPayment({ status, isCompleted, data }: ZenkiPayment): void {
    console.log({ status, isCompleted, data });
  }

  function handleError(error: Error): void {
    console.error(error);
  }
}

Usando hooks personalizados

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61


import React, { useState, useEffect } from "react";
import {
  DoneMsg,
  MsgDetails,
  Options,
  useGetDiscountPercentage,
  useOpenModal,
} from "@zenkipay-pkg/react";

import { getPurchaseData } from "./api/your-purchase-data.api";

export function App(): JSX.Element {
  const getDiscountPercentage = useGetDiscountPercentage();
  const openModal = useOpenModal();

  const [zenkipayKey] = useState<string>(
    "e77e5b6662532432e9179ff4d33fe364ec88aacf9240e5e7673e474255e4a90c"
  );
  const [options, setOptions] = useState<Options | null>(null);
  const [discount, setDiscount] = useState<number>(0);

  useEffect((): void => {
    getPurchaseData().then(({ purchaseData, purchaseSignature }): void => {
      setOptions({
        zenkipayKey,
        purchaseData,
        purchaseSignature,
      });
    });
  }, []);

  useEffect((): void => {
    if (getDiscountPercentage && options) {
      getDiscountPercentage(options).then((discount: number | null): void => {
        if (discount) setDiscount(discount);
      });
    }
  }, [getDiscountPercentage, options]);

  return (
    <button onClick={openPaymentModal}>
      Zenkipay {discount && <span>{discount}% Off</span>}
    </button>
  );

  async function openPaymentModal(): Promise<void> {
    if (openModal && options) {
      await openModal(
        options,
        (
          error: Error | null,
          data: DoneMsg | null,
          details: MsgDetails
        ): void => {
          if (error) console.error({ ...details, error });
          else console.log({ ...details, data });
        }
      );
    }
  }
}