Preparativos para tu integración

Para iniciar la integración completa, primero debemos configurar tus llaves pública y privada, para ello debes dar click en el botón Generar un par de claves.

generate-keys-01

Esta acción te abrirá una modal en donde debes elegir cómo quieres generar tus llaves.

generate-keys-02

Ayúdame a crear un par de llaves para mí

Al seleccionar esta opción, sólo debes guardar las llaves que generamos para ti.

generate-keys-03

Al darle click en el botón Continuar, debes asegurarte que has guardado al menos tu llave privada, ya que esta será de vital importancia que la almacenes en un lugar seguro en tu servidor.

generate-keys-05

Me gustaría generar y subir mis propias llaves

Al seleccionar esta opción, debes generar por tu propia cuenta tus llaves pública y privada, para ello puedes seguir nuestra guía aquí. Te recomendamos que no generes estas llaves en ningún sitio web, ya que podría comprometerse tu llave privada.

Ya que hayas generado tus llaves, basta con compartirnos únicamente tu llave pública.

generate-keys-04

Integración con tu servidor

Por cuestiones de seguridad e integridad de la información, debes firmar con tu llave privada RSA SHA256 el detalle de la compra a pagar, la cual debe ser una instancia de PurchaseData como objeto JSON, recomendamos generar tu instancia desde tu servidor por cuestiones de seguridad e integridad; a continuación se muestra un ejemplo:

 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


{
  "country": "US",
  "shopperCartId": "l6l6jpce28ugg",
  "merchantOrderId": "l6l6jpce2f649",
  "shopperEmail": "hello@zenki.fi",
  "purchaseSummary": {
    "currency": "USD",
    "totalItemsAmount": "0.5",
    "shipmentAmount": "0.25",
    "subtotalAmount": "0.75",
    "taxesAmount": "0.125",
    "localTaxesAmount": "0.125",
    "importCosts": "0.125",
    "discountAmount": "0.25",
    "additionalCharges": {
      "donation": "0.125"
    },
    "grandTotalAmount": "1"
  },
  "items": [
    {
      "itemId": "l6l6jpce3gzis",
      "price": "0.5",
      "quantity": "1",
      "productName": "Javascript",
      "thumbnailUrl": "https://cdn.tshirts.boutique/wp-content/uploads/2022/07/12213723/12100-105.jpg",
      "metadata": {
        "size": "L"
      }
    }
  ],
  "metadata": {
    "anotherId": "l6l6jpce1jrdw"
  }
}

Importante: Asegúrate de que la suma de los campos de purchaseSummary corresponda con grandTotalAmount, ya que de lo contrario no se podrá efectuar el pago. Si alguno de los campos de purchaseSummary no aplica para tu orden de pago, puedes asignarle un 0 como valor.

Ya que tengas tu instancia de PurchaseData, procedemos a transformarla a cadena de texto; como ejemplo, en Javascript puedes usar el método JSON.stringify(purchaseData), pero dependerá de la tecnología que uses en tu servidor, a continuación se muestra un ejemplo de tu instancia transformada a cadena de texto:

1

'{"country":"US","shopperCartId":"l6l6jpce28ugg","merchantOrderId":"l6l6jpce2f649","shopperEmail":"hello@zenki.fi","purchaseSummary":{"currency":"USD","totalItemsAmount":"0.5","shipmentAmount":"0.25","subtotalAmount":"0.75","taxesAmount":"0.125","localTaxesAmount":"0.125","importCosts":"0.125","discountAmount":"0.25","additionalCharges":{"donation":"0.125"},"grandTotalAmount":"1"},"items":[{"itemId":"l6l6jpce3gzis","price":"0.5","quantity":"1","productName":"Javascript","thumbnailUrl":"https://cdn.tshirts.boutique/wp-content/uploads/2022/07/12213723/12100-105.jpg","metadata":{"size":"L"}}],"metadata":{"anotherId":"l6l6jpce1jrdw"}}'

Continuamos firmando tu cadena de texto con tu llave privada RSA SHA256, ya que, por cuestiones de seguridad e integridad de la información, debes firmar con tu llave privada RSA SHA256 en formato base64, puedes seguir las instrucciones que tenemos aquí. Dicha firma la nombraremos purchaseSignature.

Este es un ejemplo de tu purchaseSignature:

1

THeBWuVviGSUUFKiac/BP79tQGjR3kk9YpEkWF/WXbwAKFaKZ0qpPfHCm4X6x/87f5APyCtKTCo94ukwKiDMHbiTM3X+5IFcgzxfiDsoeKiP3A5dLS9gOA77nlLaSkKDSwOs7doyhlKSgPcZPDN7y/JEBovJVZFb+09pO8WTptGXGSOxzzfhs0KAOTLX+EdK9EzEC85CSrhFn8dcEFdrCsU6r+Y9/SB7BixEPVd2C2bfrbFersaMIsR2ZMYsQl60XzVe8Rf+wvjKNeDykFLOpXAZi2svBbp7Zs/1rMnTBrwwbHG/6+fijHLJtsdaUKRauYyOK5FTgFyACOhXrn07v0cFUGxmB48Ah5a9giHWcNJAUZUNJPL4DSzwjKaE7eUejMRZH2/mAijEpvdmuxW4W00s+05eb1U1bPaYLfAwLG9yk+37iiTNpWgJ623qleEdS7Jh4eIEOPwMm+Umt3GQXH5sSUaj1j25e1NqWwtH/DeSHVPJeTUMIxrXxJJClzuMmOL5tYPLZN+QkxHJJYk4/lYXcqAY3BA5WZ+7dZhhWiWs3V3PU/7911izzX/k/n5QuSCn7LUfLvaNz4R0g9vWwmB89xwcyCSDLqjAGS6nDRqBQEZ5IFCbHfJ3jdcDRirkUFqGJ/lL7I9kRZnO+yyrP1fDbc78vcBWES2AgerIOVk=

Ya teniendo tu cadena de texto de tu PurchaseData y tu purchaseSignature, podemos continuar con la integración seleccionando una de las siguientes opciones:

Definición de entidades

Nota: Las propiedades de cada entidad que tienen como sufijo un ? son opcionales, mientras que aquellas que tienen un ! son requeridas; para el caso de los parámetros aplica la misma regla del sufijo ? como opcionales.

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;
}