sdk-node-payway
Version:
Modulo para conexión con gateway de pago DECIDIR2
1,292 lines (1,017 loc) • 91.2 kB
Markdown
Decidir SDK NODEJS
===============
Modulo para conexión con gateway de pago DECIDIR2
## Índice
- [Introducción](#introduccion)
- [Alcance](#Alcance)
- [Diagrama de secuencia](#diagrama-de-secuencia)
- [Instalación](#instalacion)
- [Versiones de NODEJS soportadas](#versiones)
- [Manual de Integración](#manualintegracion)
- [Ambiente](#ambiente)
- [Uso](#uso)
- [Inicializar la clase correspondiente al conector](#initconector)
- [Operatoria del Gateway](#operatoria)
- [Pagos Offline](#pagos-offline)
- [Cierre de lotes](#batchclosure)
- [Health Check](#healthcheck)
- [Ejecución del Pago](#ejecución-del-pago)
- [Pagos distribuidos](#pagos-distribuidos)
- [Operación en dos pasos](#twosteps)
- [Comercios agregadores](#comercios-agregadores)
- [Respuesta al pago](#respuesta-al-pago)
- [Ejemplo: transacción distribuida](#transaccion-distribuida)
- [Listado de Pagos](#getallpayments)
- [Información de un Pago](#getpaymentinfo)
- [Devoluciones de pagos](#refunds)
- [Anulación / Devolución Total de Pago](#refund)
- [Anulación de Devolución Total](#deleterefund)
- [Devolución Parcial de un Pago](#partialrefund)
- [Anulación de Devolución Parcial](#deletepartialrefund)
- [Tokenización de tarjetas de crédito](#tokenizaciontarjeta)
- [Listado de tarjetas tokenizadas](#listadotarjetastokenizadas)
- [Solicitud de token de pago](#solicitudpagotokenizado)
- [Ejecución de pago tokenizado](#pagotokenizado)
- [Solicitud de token de pago con tokenización interna](#solicitud-de-token-de-pago-con-tokenizacion-interna)
- [Ejecución de pago con tokenización interna](#ejecucion-de-pago-con-tokenizacion-interna)
- [Eliminación de tarjeta tokenizada](#eliminartarjetatokenizada)
- [Formulario de pago](#formpago)
- [Integración con Cybersource](#cybersource)
- [Parámetros Comunes](#parametros-comunes)
- [Retail](#retail)
- [Ticketing](#ticketing)
- [Digital Goods](#digital-goods)
- [Servicios](#services)
- [Travel](#travel)
- [Tablas de referencia](#tablasreferencia)
- [Códigos de Medios de Pago](#codigos-de-medios-de-pago)
- [Divisas Aceptadas](#divisasa)
- [Provincias](#provincias)
<a name="introduccion"></a>
- [CHANGELOG](#changelog)
## Introducción
### 🚀 Flujo de una Transacción con las SDKs
El flujo de una transacción a través de las **SDKs** consta de dos pasos clave:
1. **Generación de un Token de Pago** (por parte del cliente)
2. **Procesamiento del Pago** (por parte del comercio)
### 🌟 Funcionalidades Principales
Nuestras **SDKs** no solo facilitan la integración del proceso de pago, sino que también ofrecen un conjunto completo de herramientas para:
+ 🔗 **Crear links de pago** para ventas fáciles y rápidas.
+ 🔒 **Implementar 3D Secure (3DS)** para una autenticación más robusta.
+ 💳 **Realizar pagos con tarjetas tokenizadas** evitando almacenar datos sensibles.
+ 🔁 **Procesar devoluciones** de forma segura y eficiente.
+ 🛡️ **Aprovechar Cybersource** para garantizar la máxima seguridad en cada transacción.
### 📚 SDKs Disponibles
Ofrecemos SDKs específicas para diversos lenguajes de programación, permitiendo una integración sencilla y adaptable según tus necesidades.
---
+ [Sdk Java](https://github.com/decidir/SDK-JAVA.v2)
+ [Sdk PHP](https://github.com/decidir/SDK-PHP.v2)
+ [Sdk .Net](https://github.com/decidir/SDK-.NET.v2)
+ [Sdk Node](https://github.com/decidir/SDK-.NODE.v2)
---
### 🎯 Alcance
La **SDKs de Node** está diseñada para integrarse en aplicaciones móviles y web, permitiendo a los comercios:
+ ✅ **Realizar cobros** mediante múltiples métodos de pago, incluyendo tarjetas de crédito y débito, con soporte para transacciones en distintas monedas, como ARS y USD.
+ ✅ **Automatizar devoluciones** y cancelaciones de transacciones.
+ ✅ **Generar y gestionar links de pago** para ventas sin necesidad de integrar formularios complejos.
+ ✅ **Soportar autenticación reforzada** mediante 3D Secure (3DS).
+ ✅ **Implementar pagos con tarjetas tokenizadas**, protegiendo los datos sensibles de los clientes.
Este alcance cubre tanto soluciones para comercios que desean un proceso de pago simple como para aquellos que requieren flujos personalizados y mayor control sobre cada transacción.
[Volver al inicio](#alcance)
<a name="diagrama-secuencia"></a>
### 📈 Diagrama de Secuencia
El flujo de una transacción a través de las **SDKs** involucra dos pasos esenciales:
1. **Generar Token de Pago**: Se realiza una solicitud utilizando la **Llave de Acceso pública** (*public API Key*), enviando los datos sensibles de la tarjeta — como el PAN, mes y año de expiración, código de seguridad, titular, y tipo y número de documento —. A cambio, se recibe un **token de pago** que permitirá ejecutar la transacción.
2. **Pagar usando el Token de Pago**: Con la **Llave de Acceso privada** (*private API Key*), se procesa el pago enviando el **token generado** en el Paso 1, junto con el identificador de la transacción a nivel comercio, el monto total, la moneda y la cantidad de cuotas.
A continuación, se presenta un diagrama que ilustra el **Flujo de un Pago**.
</br>
[Volver al inicio](#diagramasecuencia)
<a name="instalacion"></a>
# Instalación del SDK
## Opción 1: Descarga directa
1. **Descargar la última versión del SDK**
Haz clic en el botón **Download ZIP** para obtener el SDK.
<br />
2. **Incluir en el proyecto**
Descomprime el archivo descargado e incluye la carpeta del SDK en tu proyecto.
## Opción 2: Instalación mediante npm (Recomendada)
La instalación a través de npm es el método que recomendamos y hemos testeado exhaustivamente, asegurando una integración rápida y segura:
```bash
npm install sdk-node-payway
```
Asegúrate de que las dependencias estén definidas en tu archivo package.json, utilizando la versión más actual disponible:
```javascript
"dependencies": {
"sdk-node-payway": "^1.0.7"
}
```
# ⚠️ **Requisitos del entorno**
> ⚠️ **El SDK solo es compatible con Node.js versión 18 o superior.** ⚠️
<br />
[Volver al inicio](#decidir-sdk-node)
<a name="versiones"></a>
## Versiones de NODEJS soportadas
> **La versión implementada del SDK está probada y es compatible con Node.js a partir de la versión 18.0.0 inclusive.**
[Volver al inicio](#versiones)
<a name="manualintegracion"></a>
## Manual de Integración
Se encuentra disponible la documentación **[Manual de Integración Decidir2](https://decidir.api-docs.io/1.0/guia-de-inicio/)** para su consulta online, en este detalla el proceso de integración. En el mismo se explican los servicios y operaciones disponibles, con ejemplos de requerimientos y respuestas, aquí sólo se ejemplificará la forma de llamar a los distintos servicios utilizando la presente SDK.
<a name="ambiente"></a>
## Ambientes
⚠️ El sdk NODEJS permite trabajar con los ambientes de Sandbox y Producción de Decidir. El ambiente se debe definir al instanciar el SDK.
```javascript
const ambient = "developer";//valores posibles: "developer" o "production";
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
```
[Volver al inicio](#ambiente)
<a name="uso"></a>
## Uso
<a name="initconector"></a>
### Inicializar la clase correspondiente al conector
El Sdk para NODEJS permite trabajar con los ambientes de desarrollo y de producción de Decidir.
El ambiente se debe instanciar como se indica a continuación.
Instanciación de la clase `sdk`
La misma recibe como parámetros la public key o private key provisto por Decidir para el comercio y el ambiente en que se trabajará.
```javascript
var publicKey = "b192e4cb99564b84bf5db5550112adea";
var privateKey = "566f2c897b5e4bfaa0ec2452f5d67f13";
var company = "Tienda-Margarita";
var user = "Cristian Arellano";
var ambient = "developer";//valores posibles: "developer" o "production";
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
<a name="operatoria"></a>
## Operatoria del Gateway
### Pagos Offline
Para el caso de la operatoria de pago offline, la operación requiere en un principio de la solicitud de un token a partir de datos del usuario.
Una vez generado y almacenado el token de Pago Offline, se deberá ejecutar la solicitud de pago utilizando el token previamente generado. Además del token de pago y los parámetros propios de la transacción, el comercio deberá identificar la compra con el site_transaction_id.
*Aclaracion*: amount es un campo double el cual debería tener solo dos dígitos decimales.
#### Pago Fácil
</br>
|Campo | Descripcion | Oblig | Restricciones |Ejemplo |
| ------------ | ------------ | ------------ | ------------ | ------------ |
|site_transaction_id |Identificador único para la operación | SI| 8 dígitos | site_transaction_id: "170518_35" |
|token |Token generado en el primer paso | SI| 36 dígitos,variable| token: "03508514-1578-4140-ba02-6bdd65e2af95" |
|payment_method_id | id del tipo de metodo de Pago Offline | SI| Dos dígitos | payment_method_id: 25|
|amount | Monto de la operación | SI| 12 dígitos,variable (10 números enteros y 2 decimales) | amount: 1100|
|currency | Son los días que existen entre el 1er y 2do vencimiento | SI| 3 letras | currency: "ARS"|
|payment_type | Tipo de pago | SI| Letras | payment_type: "single"|
|email | email del usuario que esta haciendo uso del sitio |Condicional |Sin validacion | email: "<user@mail.com>", |
|invoice_expiration | Fecha en que vence el cupón | SI| Formato AAMMDD | invoice_expiration: "191123"|
|cod_p3 | Son los dias que existen entre el 1º y 2º vencimiento de la factura. | SI| 2,fijo ("00" si la factura tiene no tiene 2° vencimientos)| invoice_expiration: "191123"|
|cod_p4 | Días después del 1º vencimiento y hasta que el cliente pueda abonar | SI| 3,fijo | cod_p4: "123"|
|client | Codigo Cliente | SI| 8,fijo | client: "12345678"|
|surcharge | Recargo por vencimiento del plazo | SI| 7,variable (5 digitos enteros y 2 decimales)| surcharge: 1001|
|payment_mode | Tipo de metodo de pago | SI| String "offline" | payment_mode: "offline"|
##### Ejemplo
```javascript
data = {
site_transaction_id : "230518_41",
token: '92a95793-3321-447c-8795-8aeb8a8ac067',
payment_method_id: 25,
amount: 1000,
currency: 'ARS',
payment_type: 'single',
email: 'user@mail.com',
invoice_expiration : 191123,
cod_p3: 12,
cod_p4: 134,
client: 12345678,
surcharge: 1001,
payment_mode: 'offline'
};
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
#### Rapipago
</br>
|Campo | Descripcion | Oblig | Restricciones |Ejemplo |
| ------------ | ------------ | ------------ | ------------ | ------------ |
|site_transaction_id |Identificador único para la operación | SI| 8 dígitos | site_transaction_id: "170518_35" |
|token |Token generado en el primer paso | SI| 36 dígitos,variable| token: "03508514-1578-4140-ba02-6bdd65e2af95" |
|payment_method_id | id del tipo de metodo de Pago Offline | SI| 2 dígitos | payment_method_id: 26|
|amount | Monto de la operación | SI| 12 dígitos,variable (10 números enteros y 2 decimales) | amount: 1100|
|currency | Son los días que existen entre el 1er y 2do vencimiento | SI| 3 letras | currency: "ARS" o "USD"|
|payment_type | Tipo de pago | SI| Letras | payment_type: "single"|
|email | email del usuario que esta haciendo uso del sitio |Condicional |Sin validacion | email: "<user@mail.com>", |
|invoice_expiration | Fecha en que vence el cupón | SI| Formato AAMMDD | invoice_expiration: "191123"|
|cod_p3 | Son los dias que existen entre el 1º y 2º vencimiento de la factura. | SI| 2,fijo ("00" si la factura tiene no tiene 2° vencimientos)| invoice_expiration: "191123"|
|cod_p4 | Días después del 1º vencimiento y hasta que el cliente pueda abonar | SI| 3,fijo | cod_p4: "123"|
|client | Codigo Cliente | SI| 8,fijo | client: "12345678"|
|surcharge | Recargo por vencimiento del plazo | SI| 7,variable (5 digitos enteros y 2 decimales)| surcharge: 1001|
|payment_mode | Tipo de metodo de pago | SI| String "offline" | payment_mode: "offline"|
##### Ejemplo
```javascript
const data = {
site_transaction_id: "230518_38",
token: "8e190c82-6a63-467e-8a09-9e8fa2ab6215",
payment_method_id: 26,
amount: 1000,
currency: "ARS",
payment_type: "single",
email: "user@mail.com",
invoice_expiration: "191123",
cod_p3: "12",
cod_p4: "134",
client: "12345678",
surcharge: 1001,
payment_mode: "offline"
};
```
#### Pago mis Cuentas
</br>
|Campo | Descripcion | Oblig | Restricciones |Ejemplo |
| ------------ | ------------ | ------------ | ------------ | ------------ |
|site_transaction_id |Identificador único para la operación | SI| 8 dígitos | site_transaction_id: "170518_35" |
|token |Token generado en el primer paso | SI| 36 dígitos,variable| token: "03508514-1578-4140-ba02-6bdd65e2af95" |
|payment_method_id | id del tipo de metodo de Pago Offline | SI| 2 dígitos | payment_method_id: 41|
|amount | Monto de la operación | SI| 12 dígitos,variable (10 números enteros y 2 decimales) | amount: 1100|
|currency | Son los días que existen entre el 1er y 2do vencimiento | SI| 3 letras | currency: "ARS" o "USD"|
|payment_type | Tipo de pago | SI| Letras | payment_type: "single"|
|email | email del usuario que esta haciendo uso del sitio |Condicional |Sin validacion | email: "<user@mail.com>", |
|invoice_expiration | Fecha en que vence el cupón | SI| Formato AAMMDD | invoice_expiration: "191123"|
|bank_id | Id de banco de la operacion | SI| String "offline" | bank_id: 1 |
##### Ejemplo
```javascript
const data = {
site_transaction_id : "220518_39",
token : "9ae1d130-8c89-4c3b-a267-0e97b88fedd0",
payment_method_id : 41,
amount : 1000,
currency : "ARS",
payment_type : "single",
email : "user@mail.com",
bank_id : 1,
sub_payments : 100,
invoice_expiration : "191123"
}
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
#### Cobro Express
|Campo | Descripcion | Oblig | Restricciones |Ejemplo |
| ------------ | ------------ | ------------ | ------------ | ------------ |
|site_transaction_id |Identificador único para la operación | SI| 8 dígitos | site_transaction_id: "170518_35" |
|token |Token generado en el primer paso | SI| 36 dígitos,variable| token: "03508514-1578-4140-ba02-6bdd65e2af95" |
|payment_method_id | id del tipo de metodo de Pago Offline | SI| Dos dígitos | payment_method_id: 51|
|amount | Monto de la operación | SI| 12 dígitos,variable (10 números enteros y 2 decimales) | amount: 1100|
|currency | Son los días que existen entre el 1er y 2do vencimiento | SI| 3 letras | currency: "ARS" o "USD"|
|payment_type | Tipo de pago | SI| Letras | payment_type: "single"|
|email | email del usuario que esta haciendo uso del sitio |Condicional |Sin validacion | email: "<user@mail.com>", |
|invoice_expiration | Fecha en que vence el cupón | SI| Formato AAMMDD | invoice_expiration: "191123"|
|second_invoice_expiration | Segunda fecha de vencimiento del cupón | SI| Formato AAMMDD | second_invoice_expiration: "191123"|
|cod_p3 | Son los dias que existen entre el 1º y 2º vencimiento de la factura. | SI| 2,fijo ("00" si la factura tiene no tiene 2° vencimientos)| invoice_expiration: "191123"|
|client | Codigo Cliente | SI| 8,fijo | client: "12345678"|
|surcharge | Recargo por vencimiento del plazo | SI| 7,variable (5 digitos enteros y 2 decimales)| surcharge: 1001|
|payment_mode | Tipo de metodo de pago | SI| String "offline" | payment_mode: "offline"|
##### Ejemplo
```javascript 1.8
const data = {
site_transaction_id : "160518_42",
token : "3df26771-67ab-4a8e-91e2-f1e0b0c559f7",
payment_method_id : 51,
amount : 1000,
currency : "ARS",
payment_type : "single",
email : "user@mail.com",
invoice_expiration : "191123",
second_invoice_expiration : "191123",
cod_p3 : "1",
cod_p4 : "134",
client : "12345678",
surcharge : 1001,
payment_mode : "offline"
};
```
[<sub>Volver a inicio</sub>](#decidir-sdk-php)
#### Cobro Express
|Campo | Descripcion | Oblig | Restricciones |Ejemplo |
| ------------ | ------------ | ------------ | ------------ | ------------ |
|site_transaction_id |Identificador único para la operación | SI| 8 dígitos | site_transaction_id: "170518_35" |
|token |Token generado en el primer paso | SI| 36 dígitos,variable| token: "03508514-1578-4140-ba02-6bdd65e2af95" |
|payment_method_id | id del tipo de metodo de Pago Offline | SI| Dos dígitos | payment_method_id: 51|
|amount | Monto de la operación | SI| 12 dígitos,variable (10 números enteros y 2 decimales) | amount: 1100|
|currency | Son los días que existen entre el 1er y 2do vencimiento | SI| 3 letras | currency: "ARS" o "USD"|
|payment_type | Tipo de pago | SI| Letras | payment_type: "single"|
|email | email del usuario que esta haciendo uso del sitio |Condicional |Sin validacion | email: "<user@mail.com>", |
|invoice_expiration | Fecha en que vence el cupón | SI| Formato AAMMDD | invoice_expiration: "191123"|
|second_invoice_expiration | Segunda fecha de vencimiento del cupón | SI| Formato AAMMDD | second_invoice_expiration: "191123"|
|cod_p3 | Son los dias que existen entre el 1º y 2º vencimiento de la factura. | SI| 2,fijo ("00" si la factura tiene no tiene 2° vencimientos)| invoice_expiration: "191123"|
|cod_p4 | Días después del 1º vencimiento y hasta que el cliente pueda abonar | SI| 3,fijo | cod_p4: "123"|
|client | Codigo Cliente | SI| 8,fijo | client: "12345678"|
|surcharge | Recargo por vencimiento del plazo | SI| 7,variable (5 digitos enteros y 2 decimales)| surcharge: 1001|
|payment_mode | Tipo de metodo de pago | SI| Strin "offline" | payment_mode: "offline"|
##### Ejemplo
```javascript
const data = {
site_transaction_id: "160518_42",
token: "3df26771-67ab-4a8e-91e2-f1e0b0c559f7",
payment_method_id: 51,
amount: 1000,
currency: "ARS",
payment_type: "single",
email: "user@mail.com",
invoice_expiration: "191123",
second_invoice_expiration: "191123",
cod_p3: "1",
cod_p4: "134",
client: "12345678",
surcharge: 1001,
payment_mode: "offline"
}
```
<a name="batchclosure"></a>
### Cierre de lote
Permite realizar el cierre de lote, indicando nombre de usuario, id de site y el id de metodo de pago
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
const args = {
"username": username,
"site_id": site_id,
"payment_method_id": payment_method_id,
};
sdk.batchclosure(args, function(result, err) {
console.log("-----------------------------------------");
console.log("batchclosure result:");
console.log(result);
console.log("-----------------------------------------");
console.log("batchclosure error:");
console.log(err);
console.log("-------------------***-------------------");
});
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
<a name="healthcheck"></a>
### Health Check
Este recurso permite conocer el estado actual de la API RESTful de DECIDIR.
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
sdk.healthcheck(function(result, err) {
console.log("-----------------------------------------");
console.log("healthcheck result:");
console.log(result);
console.log("-----------------------------------------");
console.log("healthcheck error:");
console.log(err);
console.log("-------------------***-------------------");
});
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
### Ejecución del Pago
Una vez generado y almacenado el token de pago, se deberá ejecutar la solicitud de pago más el token previamente generado.
Además del token de pago y los parámetros propios de la transacción, el comercio deberá identificar la compra con el site_transaction_id.
*Aclaración* : amount es un número entero en centavos (tipo long).
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
args = {
site_transaction_id: "id_" + date,
token: token,
user_id: 'juanpepito',
payment_method_id: 1,
bin: "450799",
amount: 2550,
currency: "ARS",
installments: 1,
description: "Description of product",
payment_type: "single",
sub_payments: [],
apiKey: "566f2c897b5e4bfaa0ec2452f5d67f13",
'Content-Type': "application/json"
};
sdk.payment(args, function(result, err) {
resolve(result);
console.log("")
console.log("Se realiza una petición de pago enviando el payload y el token de pago ")
console.log("generado anteriormente")
console.log(" PAYMENT REQUEST ");
console.log("sendPaymentRequest result:");
console.log(result);
console.log("sendPaymentRequest error:");
console.log(err);
});
```
<a name="twosteps"></a>
### Operación en dos pasos
Una vez generado y almacenado el token de pago, se deberá ejecutar la solicitud de pago más el token previamente generado.
Si el pago es preaprobado `Status.PRE_APPROVED`, se procederá a realizar la confirmación del pago enviando **ID de pago, monto y usuario aprobador**.
A continuación se muestra un ejemplo con una transacción simple sin Cybersource.
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
args = {
amount: 2550,
};
sdk.confirmPayment(args, function(result, err) {
resolve(result);
console.log("")
console.log("Se realiza una petición de confirmación de pago enviando el payload y el token de pago ")
console.log("generado anteriormente")
console.log(" CONFIRM PAYMENT REQUEST ");
console.log("sendPaymentRequest result:");
console.log(result);
console.log("sendPaymentRequest error:");
console.log(err);
});
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
### Comercios agregadores
#### Campos agregador para American Express
El set de datos a enviar a la sdk son otros:
```javascript
let args = {
customer: {
id: "{{user}}",
email: "{{email}}",
ip_address: "{{ip_address}}"
},
site_transaction_id: "AGREGADOR_{{$timestamp}}",
token: "{{token}}",
payment_method_id: 65,
bin: "{{bin}}",
amount: 2000,
currency: "ARS",
installments: 1,
description: "",
payment_type: "single",
sub_payments: [],
aggregate_data: {
product: "producto_x",
origin_country: "032",
merchant_id: "decidir_Agregador",
seller_id: "seller_123",
merchant_url: "http://merchant-url",
aggregator_name: "payfact",
gateway_id: "payway",
indicator: "1",
identification_number: "30598910045",
bill_to_pay: "Decidir_Test",
bill_to_refund: "Decidir_Test",
merchant_name: "DECIDIR",
street: "Lavarden",
number: "247",
postal_code: "C1437FBE",
category: "05044",
channel: "005",
geographic_code: "C1437",
city: "Ciudad de Buenos Aires",
province: "Buenos Aires",
country: "Argentina",
merchant_email: "merchant@mail.com",
merchant_phone: "+541135211111"
}
};
```
### Campos de `aggregate_data` (Comercios Agregadores)
El objeto `aggregate_data` se utiliza para informar los datos del sub-comercio dentro de una operación realizada por un **comercio agregador**.
| Campo | Tipo | Obligatorio | Descripción | Observaciones |
|-------------------------|---------|-------------|------------------------------------------------------------------------------|---------------|
| product | string | Condicional | Producto asociado a la transacción | — |
| origin_country | string | Condicional | País de origen del comercio (código numérico) | Ej: `"032"` |
| merchant_id | string | Condicional | Identificador del comercio | — |
| merchant_url | string | Condicional | URL del comercio | — |
| aggregator_name | string | Condicional | Nombre del agregador | Ej: `"payfact"` |
| gateway_id | string | Condicional | Identificador del gateway asociado | Ej: `"payway"` |
| indicator | string | Condicional | Indicador del tipo de operación | — |
| identification_number | string | Condicional | Número de identificación fiscal del comercio | Cuit / RUT |
| bill_to_pay | string | Condicional | Referencia de la factura a pagar | — |
| bill_to_refund | string | Condicional | Referencia de la factura a devolver | — |
| merchant_name | string | Condicional | Nombre comercial del sub-comercio | — |
| street | string | Condicional | Calle del comercio | — |
| number | string | Condicional | Número de dirección | — |
| postal_code | string | Condicional | Código postal | — |
| category | string | Condicional | Categoría del comercio | Código MCC |
| channel | string | Condicional | Canal de venta | Ej: `"005"` ecommerce |
| geographic_code | string | Condicional | Código geográfico | — |
| city | string | Condicional | Ciudad | — |
| province | string | Condicional | Provincia | — |
| country | string | Condicional | País | Ej: `"Argentina"` |
| merchant_email | string | Condicional | Email del comercio | — |
| merchant_phone | string | Condicional | Teléfono del comercio | — |
| seller_id | string | **Solo Amex** | **Identificador del vendedor asignado por American Express** | **Se envía únicamente cuando `payment_method_id` es Amex** |
### Respuesta al pago
La respuesta de ante cualquier pago exitoso es:
```JSON
{
"id": 971344,
"site_transaction_id": "AGREGADOR_1527712473",
"payment_method_id": 65,
"card_brand": "Amex MT",
"amount": 2000,
"currency": "ars",
"status": "approved",
"status_details": {
"ticket": "4",
"card_authorization_code": "203430",
"address_validation_code": "VTE0011",
"error": null
},
"date": "2018-05-30T17:34Z",
"customer": {
"id": "juan",
"email": "jmejia@prismamp.com",
"ip_address": "192.168.0.1"
},
"bin": "373953",
"installments": 1,
"first_installment_expiration_date": null,
"payment_type": "single",
"sub_payments": [],
"site_id": "00020220",
"fraud_detection": {
"status": null
},
"aggregate_data": {
"enabled": true,
"product": "producto_x",
"origin_country": "032",
"merchant_id": "decidir_Agregador",
"seller_id": "seller_123",
"merchant_url": "http://merchant-url",
"aggregator_name": "payfact",
"gateway_id": "payway",
"indicator": "1",
"identification_number": "30598910045",
"bill_to_pay": "Decidir_Test",
"bill_to_refund": "Decidir_Test",
"merchant_name": "DECIDIR",
"street": "Lavarden",
"number": "247",
"postal_code": "C1437FBE",
"category": "05044",
"channel": "005",
"geographic_code": "C1437",
"city": "Ciudad de Buenos Aires",
"province": "Buenos Aires",
"country": "Argentina",
"merchant_email": "merchant@mail.com",
"merchant_phone": "+541135211111"
},
"establishment_name": null,
"spv": null,
"confirmed": null,
"pan": null,
"customer_token": "13e550af28e73b3b00af465d5d64c15ee1f34826744a4ddf68dc6b469dc604f5",
"card_data": "/tokens/971344",
"tid": "364656548412345"
}
```
<a id="transaccion-distribuida"></a>
## Pagos distribuidos
Existen transacciones distribuidas definidas por monto o por porcentaje.
- Por monto: se debe enviar el arreglo `sub_payments` con cada sub-sitio a acreditar.
- Por porcentaje: no debe completarse `sub_payments` (la distribución estática se configura en el SAC).
**Aclaración:** `amount` es un número entero en centavos (tipo long).
**Nota técnica:** Usar `payment_type: "distributed"`.
En transacciones distribuidas por monto, la sumatoria de los `sub_payments[].amount` debe ser exactamente igual al `amount` total de la operación padre.
En distribuidas por porcentaje, no se completa `sub_payments`.
### Ejemplo — Distribuida por monto (Node.js)
```js
// SDK instanciado previamente
// const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
const installments = 2;
// MONTOS EN CENTAVOS
const amount1 = 10000; // $100,00
const amount2 = 25990; // $259,90
const totalAmount = amount1 + amount2; // $359,90 => 35990
const subPayments = [
{ site_id: "00111115", amount: amount1, installments },
{ site_id: "00111116", amount: amount2, installments }
];
// Validación opcional
const sumSub = subPayments.reduce((acc, sp) => acc + Number(sp.amount), 0);
if (sumSub !== totalAmount) {
throw new Error(`La suma de sub_payments (${sumSub}) debe ser igual al amount total (${totalAmount}).`);
}
const args = {
site_transaction_id: "TX0000000001",
token: "a6f05789-10df-4464-a318-887a1520204b",
customer: {
id: "test",
email: "test@payway.com"
},
payment_method_id: 1,
bin: "450979",
amount: totalAmount,
currency: "ARS",
installments,
payment_type: "distributed",
sub_payments: subPayments
};
sdk.payment(args, (result, err) => {
if (err) {
console.error("Error en pago distribuido:", err);
return;
}
console.log("Pago distribuido OK:", result);
});
```
<a id="ejemplo-transaccion-distribuida"></a>
### Ejemplo respuesta: transacción distribuida
En pagos **distributed**, se devuelve un `tid` **por cada elemento de `sub_payments`**, el cual debe utilizarse para la conciliación por subcomercio.
El `tid` a **nivel raíz** solo se devuelve en el caso de **pagos simples (no distributed)**.
```json
{
"id": 971255,
"site_transaction_id": "DISTRIBUTED_1527712473",
"payment_method_id": 65,
"card_brand": "Amex",
"amount": 2000,
"currency": "ars",
"status": "approved",
"status_details": {
"ticket": "4",
"card_authorization_code": "203430",
"address_validation_code": "VTE0011",
"error": null
},
"aggregate_data": {
"enabled": true,
"seller_id": "123456",
"product": "producto_x",
"origin_country": "032",
"merchant_id": "decidir_Agregador",
"merchant_url": "http://merchant-url",
"aggregator_name": "payfact",
"gateway_id": "payway",
"indicator": "1",
"identification_number": "30598910045",
"bill_to_pay": "Decidir_Test",
"bill_to_refund": "Decidir_Test",
"merchant_name": "DECIDIR",
"street": "Lavarden",
"number": "247",
"postal_code": "C1437FBE",
"category": "05044",
"channel": "005",
"geographic_code": "C1437",
"city": "Ciudad de Buenos Aires",
"province": "Buenos Aires",
"country": "Argentina",
"merchant_email": "merchant@mail.com",
"merchant_phone": "+541135211111",
},
"date": "2025-03-30T00:00Z",
"customer": {
"id": "juan",
"email": "jmejia@prismamp.com",
"ip_address": "192.168.0.1"
},
"bin": "373953",
"installments": 1,
"first_installment_expiration_date": null,
"payment_type": "distributed",
"sub_payments": [
{
"site_id": "04052023",
"installments": 1,
"amount": 1000,
"ticket": "211",
"card_authorization_code": "058205",
"subpayment_id": 1265395,
"tid": "234567891234567"
},
{
"site_id": "00009007",
"installments": 1,
"amount": 1000,
"ticket": "626",
"card_authorization_code": "048246",
"subpayment_id": 1265394,
"tid": "345678912345678"
}
],
"site_id": "00020220",
"fraud_detection": {
"status": null
},
"establishment_name": null,
"spv": null,
"confirmed": null,
"pan": null,
"customer_token": "23e560a3b3c001f465d5d55ee1f3542c468712744a4ddf68dc6b469dc604f5",
"card_data": "/tokens/971255"
}
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
<a name="getallpayments"></a>
### Listado de Pagos
Mediante este recurso, se genera una solicitud de listado de pagos.
Este recurso admite la posibilidad de agregar los filtros adicionales:
+ (opcional) offset: desplazamiento en los resultados devueltos. Valor por defecto = 0.
+ (opcional) pageSize: cantidad máxima de resultados retornados. Valor por defecto = 50.
+ (opcional) siteOperationId: ID único de la transacción a nivel comercio (equivalente al site_transaction_id).
+ (opcional) merchantId: ID Site del comercio.
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
var args = {
data: {
},
headers: {
"apikey": "566f2c897b5e4bfaa0ec2452f5d67f13",
"Content-Type": "application/json",
"Cache-Control": "no-cache"
}
};
offset = '10';
pageSize = '20';
siteOperationId = '450799';
merchantId = 'Id001';
sdk.getAllPayments(offset, pageSize, siteOperationId, merchantId, function(result, err) {
console.log("infoPayments:");
console.log(result);
console.log("infoPayments error:");
console.log(err);
});
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
<a name="getpaymentinfo"></a>
### Información de un Pago
Mediante este recurso, se genera una solicitud de información de un pago previamente realizado, pasando como parámetro el id del pago.
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
id = result.id;
const args = {
data: {
},
headers: {
"apikey": "566f2c897b5e4bfaa0ec2452f5d67f13",
"Content-Type": "application/json",
"Cache-Control": "no-cache"
}
};
sdk.paymentInfo(paymentId, function(result, err) {
console.log("");
console.log("información de pago previamente realizado");
console.log("");
console.log(result);
console.log("-----------------------------------------");
console.log("error:");
console.log(err);
});
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
<a name="refund"></a>
### Anulación / Devolución Total de Pago
Mediante este recurso, se genera una solicitud de anulación / devolución total de un pago puntual, pasando como parámetro el id del pago.
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
id = result.id;
const args = {
data: {
},
headers: {
"apikey": "566f2c897b5e4bfaa0ec2452f5d67f13",
"Content-Type": "application/json",
"Cache-Control": ""
}
};
sdk.refund(id, function(result, err) {
console.log("Reintegro monto total de la transacción")
console.log(" REFUND ");
console.log("refund result:");
console.log(result);
console.log("refund error:");
console.log(err);
});
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
<a name="deleterefund"></a>
### Anulación de Devolución Total
Mediante este recurso, se genera una solicitud de anulación de devolución total de un pago puntual, pasando como parámetro el id del pago y el id de la devolución.
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
paymentId = result.id;
const args = {
data: {
},
headers: {
"apikey": "566f2c897b5e4bfaa0ec2452f5d67f13",
"Content-Type": "application/json",
"Cache-Control": ""
}
};
sdk.deleteRefund(args, paymentId, refundId, function(result, err) {
console.log("")
console.log("Reintegro monto total de la transacción")
console.log(" REFUND ");
console.log(result);
console.log("refund error:");
console.log(err);
});
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
<a name="partialrefund"></a>
### Devolución Parcial de un Pago
Mediante este recurso, se genera una solicitud de devolución parcial de un pago puntual, pasando como parámetro el id del pago y el monto de la devolución.
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
paymentId = result.id;
amount = 1050;
const args = {
data: {
"amount": amount
},
headers: {
"apikey": "566f2c897b5e4bfaa0ec2452f5d67f13",
"Content-Type": "application/json",
"Cache-Control": ""
}
};
sdk.partialRefund(args, paymentId, function(result, err) {
console.log("")
console.log("Reintegro monto parcial de la transacción ")
console.log("")
console.log(" PARTIAL REFUND ");
console.log("partial refund result:");
console.log(result);
console.log("partial refund error:");
console.log(err);
});
```
[<sub>Volver a inicio</sub>](#decidir-sdk-nodejs)
<a name="deletepartialrefund"></a>
### Anulación de Devolución Parcial
Mediante este recurso, se genera una solicitud de anulación de devolución parcial de un pago puntual, pasando como parámetro el id del pago y el id de la devolución.
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
paymentId = result.id;
amount = 1050;
const args = {
data: {
"amount": amount
},
headers: {
"apikey": "566f2c897b5e4bfaa0ec2452f5d67f13",
"Content-Type": "application/json",
"Cache-Control": ""
}
};
sdk.deletePartialRefund(args, paymentId, function(result, err) {
console.log("")
console.log("Reintegro monto parcial de la transacción ")
console.log("")
console.log(" PARTIAL REFUND ");
console.log("partial refund result:");
console.log(result);
console.log("partial refund error:");
console.log(err);
});
```
<a name="formpago"></a>
### Formulario de pago
Este servicio permite integrar un formulario de pago en el comercio. Primero, utiliza el recurso **checkoutHash** para generar un hash basado en los datos de la operación. Luego, este hash se emplea al invocar el recurso payments/link, el cual devuelve un enlace personalizado para el formulario de pago del comercio, listo para ser utilizado y completar el flujo de pago.
## Aclaraciones
> ⚠️ Los siguientes campos aplican **exclusivamente para comercios del rubro RETAIL**. ⚠️
| Campo | Descripción | Obligatorio | Restricciones | Ejemplo |
|-----------------------|----------------------------------------------------------------------------------------------|-------------------|---------------------------------------------------------|----------------------------------|
| origin_platform | Plataforma de origen desde la cual se realiza la operación | Sí | Alfanumérico | "SDK-Node" |
| payment_description | Descripción del pago | No | Alfanumérico | "TEST" |
| currency | Tipo de moneda | Sí | Letras | "ARS" / "USD" |
| products | Detalle de los productos incluidos en la operación | No | Array de objetos con `id`, `value`, `description`, `quantity` | [{"id": 4444, "value": 19.99, "description": "Remera", "quantity": 2}] |
| total_price | Precio total de la operación | Sí | Numérico | 39.98 |
| site | Identificador único del comercio | Sí | Numérico | "00097002" |
| success_url | URL a la que se redirige cuando se completa la operación con éxito. Es requerida si **no** se envía `redirect_url` | Sí | URL válida | "https://www.lanacion.com/" |
| redirect_url | URL a la que se redirige con los datos de la operación finalizada. Es requerida si **no** se envía `success_url` | No | URL válida | "https://www.infobae.com/" |
| cancel_url | URL a la que se redirige si el cliente cancela el formulario | Sí | URL válida | "https://www.clarin.com/" |
| notifications_url | URL donde se enviarán notificaciones relacionadas con la operación | Sí | URL válida | "https://www.mitienda.com/notificaciones" |
| template_id | Identificador de la plantilla del formulario de pago | Sí | Numérico (**1 = sin Cybersource**, **2 = con Cybersource**) | 1 |
| installments | Cantidad de cuotas posibles | Sí | Array de números | [1] |
| id_payment_method | Identificador del método de pago a utilizar (opcional; por defecto incluye todos los métodos) | No | Numérico | 31 |
| plan_gobierno | Indica si se utiliza un plan de financiamiento de cuotas (por ejemplo: Plan Ahora, MiPyME, etc.) | Sí | Valores posibles: `true`, `false` | false |
| public_apikey | Clave pública de autenticación | Sí | Alfanumérico | "YKcWXjI2aoSnp60urwLd6TbLYNuybcWC" |
| auth_3ds | Indica si se requiere autenticación 3DS | Sí | Valores posibles: `true`, `false` | false |
|
### CONSIDERACIONES:
> ⚠️ **IMPORTANTE – `template_id` y uso de Cybersource**
> - `template_id = 1` → Checkout estándar **sin Cybersource** (transacción sin control de fraude Cybersource).
> - `template_id = 2` → Checkout **con Cybersource habilitado** (misma operatoria, pero con evaluación antifraude).
>
> Asegúrate de seleccionar el `template_id` correcto según el flujo configurado para tu comercio.
#### Ejemplo
Los campos payment_description y products son mutuamente excluyentes. No deben enviarse juntos en la misma request. Si ambos son enviados, la solicitud será rechazada.
```javascript
args = {
"origin_platform": "SDK-Node",
"payment_description": "Compra de productos electrónicos",
"currency": "ARS",
"products": [
{
"id": 1001,
"value": 1500.50,
"description": "Auriculares Bluetooth",
"quantity": 1
},
{
"id": 1002,
"value": 999.99,
"description": "Teclado Mecánico",
"quantity": 1
}
],
"total_price": 2500.49,
"site": "12345678",
"success_url": "https://www.mitienda.com/compra-exitosa",
"redirect_url": "https://www.mitienda.com/datos-operacion",
"cancel_url": "https://www.mitienda.com/cancelacion",
"notifications_url": "https://www.mitienda.com/notificaciones",
"template_id": 1,
"installments": [3],
"id_payment_method": 1,
"plan_gobierno": false,
"installment_type": "3 Cuotas",
"public_apikey": "abcd1234efgh5678ijkl9012mnop3456",
"auth_3ds": true
};
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
var checkout = new sdk.checkoutHash(sdk, args).then(function(result) {
console.log("-----------------------------------------")
console.log("Link Hash")
console.log("-------------------***-------------------");
})
})
```
<a name="tokenizaciontarjeta"></a>
## Tokenizacion de tarjetas de crédito
Esta funcionalidad permite que luego de realizar una compra con una tarjeta, se genere un token alfanumerico unico en el backend de Decidir, esto permite que a la hora de comprar nuevamente con esta tarjeta solo requerira el codigo de seguridad.
Como primer paso se debe realizar una un pago normal, el token generado estara en el campo "token" de la respuesta.
<a name="listadotarjetastokenizadas"></a>
### Listado de tarjetas tokenizadas
Este metodo permite conocer el listado de tarjetas tokenizadas que posee un usuario determinado. Para esto es necesario el nombre de usuario a la instancia de token
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
user_id = result.user_id;
const args = {
data: {
},
headers: {
"apikey": "566f2c897b5e4bfaa0ec2452f5d67f13",
"Content-Type": "application/json",
"Cache-Control": "no-cache"
}
};
setTimeout(function() {
sdk.cardTokens(user_id, function(result, err) {
resolve(result);
console.log("");
console.log("");
console.log("Luego de realizar un primer pago se genera automaticamente un token único");
console.log("para la tarjeta");
console.log("");
console.log("cardTokens result:");
console.log(result);
console.log("cardTokens error:");
console.log(err);
})
}
```
[<sub>Volver a inicio</sub>](#listadotarjetastokenizadas)
<a name="solicitudpagotokenizado"></a>
### Solicitud de token de pago
Al cargar el formulario de pago este mostrara las tarjetas tokenizadas que posee el usuario.
[<sub>Volver a inicio</sub>](#solicitudpagotokenizado)
<a name="pagotokenizado"></a>
### Ejecucion de pago tokenizado
Una vez que se obtiene el token a partir de la tarjeta tokenizada, se deberá ejecutar la solicitud de pago. Además del token de pago y los parámetros propios de la transacción, el comercio deberá identificar la compra con el "site_transaction_id" y "user_id".
```javascript
const sdk = new sdkModulo.sdk(ambient, publicKey, privateKey, company, user);
args = {
site_transaction_id: "id_" + date,
token: token,
user_id: 'juanpepito',
payment_method_id: 1,
bin: "450799",
amount: 2000,
currency: "ARS",
installments: 1,
description: "Description of product",
payment_type: "single",
sub_payments: [],
apiKey: "566f2c897b5e4bfaa0ec2452f5d67f13",
'Content-Type': "application/json"
};
sdk.payment(args, function(result, err) {
resolve(result.user_id);
console.log("")
console.log("")
console.log("Se realiza una petición de pago enviando el payload y el token de pago ")
console.log("de la tarjeta tokenizada")
console.log("")
console.log("")
console.log(" PAYMENT REQUEST ");
console.log("-----------------------------------------");
console.log("sendPaymentRequest result:");
console.log(result);
console.log("-----------------------------------------");
console.log("sendPaymentRequest error:");
console.log(err);
console.log("-------------------***-------------------");
});
```
[<sub>Volver a inicio</sub>](#solicitudpagotokenizado)
## Solicitud de token de pago con tokenización interna
<br>
### Estructura de solicitud de token
La estructura TokenRequest representa una solicitud para generar un token asociado a una transacción con tarjeta. Contiene los siguientes campos:
card_data (obligatorio): un objeto que contiene la información de la tarjeta.
card_number (obligatorio): una cadena que representa el número de tarjeta.
Longitud máxima: 19
Longitud mínima: 15
Patrón: el número de tarjeta no debe comenzar con un 0 y debe constar únicamente de dígitos num