# Servicio de pagos virtuales con wompi en Backend de suitme
Wompi es un proveedor de Bancolombia para poder hacer transferencias mediante metodos de pago como:

- Tarjetas de Crédito y/o Debito
- Botón de transferencia Bancolombia
- Nequi
- PSE
- Pago en efectivo en Corresponsales Bancarios

Estas transacciones cumplen con el objetivo de **Fondear cuenta** donde el usuario debe tener fondos en su cuenta de **Suite me** para realizar diferentes acciones dentro de la Wallet, tales como: _fondos de inversión, conversión a criptomoneda_

## Movimientos
Un movimiento es tendrá todas las entidades, ya que cualquier movimiento financiero y/o transacción, debe almacenarse dentro de esta entidad, para poder conocer el balance y las ganancias del usuario.

> para una mejor arquitectura y fluidez, manejaremos tablas de movimientos según el país de origen ejemplo:
> - Colombia (COP_Movements)
> - España (EUR_Movements)
> - Brasil (BRL_Movements)

Esta arquitectura nos permitirá tener distribuido de una manera mas sencilla la información y así no representara tanta carga para el Backend consultar dicha información. Dicho esto la tabla almacenara la siguiente información en formato JSON:
~~~typescript
// Movimientos
type X_Movements = {
id: number | string,
user_id: string | number,
current: string,
transaction_id: string,
reference_transaction_id: string,
status: enum Status { PENDING, APPROVED, DECLINED, VOIDED, ERROR },
payment_method: enum paymentMethod { CARD, NEQUI, PSE, BANCOLOMBIA_TRANSFER },
type_movement: string,
amount: number,
commission: number,
rate: number,
description: string,
created_at: Date,
updated_at: Date
}
// Metodos de pago del usuario
type userPaymentMethod = {
id: number | string,
source_payment_id: number,
type_payment_method: string,
status: enum Status { PENDING, AVAILABLE }
customer_email: string
user_id: number,
createAt: Date,
updateAt: Date
}

~~~

Estas tablas se alimentara de los servicios de ***pagos virtuales***.

## Wompi API (Servicio pagos virtuales)
Wompi nos va a proveer de 2 llaves muy importantes a la hora de interactuar con ella, estas son llamadas **Llave Publica** y **Llave Privada** estas llaves son las que identifica a _Suite me_ como Comercio, estas llaves son **REQUERIDAS** para autenticarnos, realizar transacciones, consultar estado de transacciones etc.
Para el desarrollo nos provee 2 endpoints:

- Sandbox: Este endpoint nos ayuda al desarrollo de la aplicación, para hacer pruebas, y manejar con dinero que no es real.
- Production: Por lo contrario este enpoint si es para despliegue, cuando ya se tenga todo el desarrollo listo, este va a manejar dinero que si es real.

Este endpoint será guardado en una variable de entorno (***URL_WOMPI***).

### Tokens de Aceptación
Para que el usuario pueda realizar una transacción es importante que acepte los terminos y condiciones de uso, Wompi ya nos provee esta funcionalidad en su endpoint `URL_WOMPI/merchants/:Llave Publica`, haciendo una petición **GET** obtenemos una respuesta con la data de nuestro comecio, en esta encontraremos una clave llamada **"*presigned_acceptance*"**, esta nos proveera un _JSON_ de esta forma:
~~~json
presigned_acceptance: {
acceptance_token: "eyJhbGciOiJIUzI1NiJ9.eyJjb250cmFjdF9pZCI6MSwicGVybWFsaW5rIjoiaHR0cHM6Ly93b21waS5jby93cC1jb250ZW50L3VwbG9hZHMvMjAxOS8wOS9URVJNSU5PUy1ZLUNPTkRJQ0lPTkVTLURFLVVTTy1VU1VBUklPUy1XT01QSS5wZGYiLCJmaWxlX2hhc2giOiIzZGNkMGM5OGU3NGFhYjk3OTdjZmY3ODExNzMxZjc3YiIsImppdCI6IjE2NzE5MDAzNzMtNDExOTMiLCJleHAiOjE2NzE5MDM5NzN9.H1Fxkq4ljksFHPcLRPuwTwxfDjrqhaz5Pepdv5EUFTQ",
permalink: "https://wompi.co/wp-content/uploads/2019/09/TERMINOS-Y-CONDICIONES-DE-USO-USUARIOS-WOMPI.pdf",
type: "END_USER_POLICY"
}
~~~
Donde el **"*acceptance_token*"** es el que va a avisar a Wompi que acepta los términos y condiciones estipulados, este valor es **REQUERIDO** para términos legales, el cual debemos mandar en el cuerpo de varios endpoints de transferencias.

### Crea una transacción
Dado un objeto JSON con información con monto en **centavos**, **referencia**, **método de pago**, etc. se crea una transacción. En el caso de usar una _Fuentes de Pago_, se debe usar la _llave privada_, en vez de la pública en un ***Header: Bearer Token*** haciendo la petición tipo **POST**.
~~~json
{
// Estos campos son requeridos
acceptance_token: "eyJhbGciOiJIUzI1NiJ9.eyJjb250cmFjdF9pZCI6MSwicGVybWFsaW5rIjoiaHR0cHM6Ly93b21waS5jby93cC1jb250ZW50L3VwbG9hZHMvMjAxOS8wOS9URVJNSU5PUy1ZLUNPTkRJQ0lPTkVTLURFLVVTTy1VU1VBUklPUy1XT01QSS5wZGYiLCJmaWxlX2hhc2giOiIzZGNkMGM5OGU3NGFhYjk3OTdjZmY3ODExNzMxZjc3YiIsImppdCI6IjE1ODU4NDE2MTUtNDU2MTgiLCJleHAiOjE1ODU4NDUyMTV9.bwBa-RjN3euycqeXVroLWwUN1ZRY1X11I4zn1y5nMiY",
amount_in_cents: 3000000,
currency: "COP",
customer_email: "[e-mail]",
payment_method: {
type: "CARD",
token: "tok_prod_280_32326B334c47Ec49a516bf1785247ba2",
installments: 2
},
// Este campo es requerido en caso de que sea una fuente de pago, caso contrario no incluirlo.
payment_source_id: 1234,
reference: "TUPtdnVugyU40XlkhixhhGE6uYV2gh89",
// Campos opcionales pero importante poseerlos
redirect_url: "https://mitienda.com.co/pago/resultado",
customer_data: {
phone_number: "573307654321",
full_name: "Juan Alfonso Pérez Rodríguez",
legal_id: "1234567890",
legal_id_type: "CC"
},
// Campos opcionales, no necesitan ser incluidos
shipping_address: {
address_line_1: "Calle 34 # 56 - 78",
address_line_2: "Apartamento 502, Torre I",
country: "CO",
region: "Cundinamarca",
city: "Bogotá",
name: "Pepe Perez",
phone_number: "573109999999",
postal_code: "111111"
}
}
~~~
Al finalizar una transacción nos podemos encontrar con una respuesta en JSON con status 200 en caso de que todo haya salido bien.
~~~json
{
data: {
id: "124597-1671903208-15646",
created_at: "2022-12-24T17:33:29.196Z",
finalized_at: null,
amount_in_cents: 3000000,
reference: "testkdjvlknvdfkbndfdcd",
customer_email: "[e-mail]",
currency: "COP",
payment_method_type: "CARD",
payment_method: {
type: "CARD",
extra: {
bin: "424242",
name: "VISA-4242",
brand: "VISA",
exp_year: "29",
exp_month: "12",
last_four: "4242",
card_holder: "Pedro Pérez"
},
installments: 1
},
status: "PENDING",
status_message: null,
billing_data: null,
shipping_address: {
address_line_1: "Calle 34 # 56 - 78",
address_line_2: "Apartamento 502, Torre I",
country: "CO",
region: "Cundinamarca",
city: "Bogotá",
name: "Pepe Perez",
phone_number: "573109999999",
postal_code: "111111"
},
redirect_url: null,
payment_source_id: null,
payment_link_id: null,
customer_data: {
legal_id: "1234567890",
full_name: "Juan Alfonso Pérez Rodríguez",
phone_number: "573307654321",
legal_id_type: "CC"
},
bill_id: null,
taxes: []
},
meta: {}
}
~~~
> ¡No uses un token más de dos veces!

Si se necesita hacer múltiples cobros a una misma tarjeta, se debe utilizar una **Fuente de Pago**

> ¡Tampoco guardes nunca la información de una tarjeta!
> **Wompi Desaconseja completamente que guardemos información sensible de tarjetas**. No sólo pones en riesgo la información de tus usuarios sino que puedes enfrentar sanciones económicas y problemas legales. Wompi cuenta con una certificación PCI DSS para al manejo, transmisión y procesamiento seguro de datos de tarjeta, de manera que ningún comercio deba guardar estos datos, usando únicamente los tokens seguros generados.

### Tokenizar Tarjeta
Actualmente Wompi solo permite Tokenizar estos dos métodos de pago ( **Tarjetas, Nequi** ), dado el siguiente objeto JSON haciendo una petición tipo **POST** al endpoint `URL_WOMPI/tokens/cards` con la **Llave Publica** en el **Header: Bearer Token** esto es con la intención de no utilizar información sensible y Wompi se encargue de la seguridad.

~~~json
{
number: "4242424242424242", // Número de la tarjeta
cvc: "123", // Código de seguridad de la tarjeta (3 o 4 dígitos según corresponda)
exp_month: "08", // Mes de expiración (string de 2 dígitos)
exp_year: "28", // Año expresado en 2 dígitos
card_holder: "José Pérez" // Nombre del tarjetahabiente
}
~~~

Al finalizar la petición generamos un token, de los datos de la tarjeta y nos podemos encontrar con la siguiente respuesta en JSON con status 200 en caso de que todo haya salido bien.
~~~json
{
status: "CREATED",
data: {
id: "tok_test_24597_3F5ec26245E5D8f953A8A9a39be7F262",
created_at: "2022-12-24T18:17:56.111+00:00",
brand: "VISA",
name: "VISA-4242",
last_four: "4242",
bin: "424242",
exp_year: "29",
exp_month: "12",
card_holder: "Pedro Pérez",
created_with_cvc: true,
expires_at: "2023-06-22T18:17:55.000Z",
validity_ends_at: "2022-12-26T18:17:56.111+00:00"
}
}
~~~
Donde el `data.id` es el dato que insertaremos en los métodos de pagos de una transacción en este caso es tipo **"CARD"**.

### Tokenizar Nequi
La Tokenización de una cuenta de Nequi la utilizamos mas que todo para crear **fuentes de pago**, ya que para realizar una transacción con Nequi tenemos que obligatoriamente ***pasarle el numero de teléfono del usuario***.

Para tokenizar una cuenta de Nequi podemos realizar hace petición tipo **POST** con un **Header: Bearer Token** con la **Llave Publica**, dado el siguiente objeto JSON:
~~~json
{
phone_number: "3991111111"
}
~~~
Tras haber hecho la petición con exito recibiremos un status 200 con la siguiente respuesta se recibira como respuesta en la propiedad `data.id` el token con el que podrás registrar la fuente de pago. Sin embargo, el cliente tendrá que haber aceptado primero la suscripción en su celular de modo que el estado pase de `"PENDING"` a `"APPROVED"`.
~~~json
{
data: {
id: "nequi_test_t5NfZV0SypJ5wNTMeMEIOVQGlSMMrXPH",
status: "PENDING",
phone: "3991111111",
phone_number: "3991111111"
},
meta: {}
}
~~~

### Fuentes de pago

Las fuentes de pago se usan para hacer cargos a los usuarios sin necesidad de que ellos intervengan directamente en cada ocasión. Así podrás por ejemplo cobrar mensualmente una suscripción a un servicio, realizar cobros por servicios _on-demand_ (como ventas a domicilio o servicios de transporte), cobrar por el uso de tu plataforma, etc. Para la creación de **transacciones** y **fuentes de pago**, pensando en la privacidad y el correcto manejo de los datos personales de los usuarios, es **obligatorio** el uso de **Tokens de Aceptación** a la hora de crear cualquiera de estos dos recursos a través de Wompi.

Para crear una fuente de pago podemos hacerlo mediante la petición **POST** al endpoint `URL_WOMPI/payment_sources` donde en el **Header: Bearer token** tendremos que insertar la **Llave Privada** donde le enviaremos el siguiente objeto JSON:
~~~json
{
type: "CARD", //para indicar el medio de pago correspondiente al token, que puede ser "NEQUI" o "CARD"
token: "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301",// el token de Nequi o Tarjeta
customer_email: "[e-mail]", // que es el email del pagador
acceptance_token: "eyJhbGciOiJIUzI1NiJ9.eyJjb250cmFjdF9pZCI6MSwicGVybWFsaW5rIjoiaHR0cHM6Ly93b21waS5jby93cC1jb250ZW50L3VwbG9hZHMvMjAxOS8wOS9URVJNSU5PUy1ZLUNPTkRJQ0lPTkVTLURFLVVTTy1VU1VBUklPUy1XT01QSS5wZGYiLCJmaWxlX2hhc2giOiIzZGNkMGM5OGU3NGFhYjk3OTdjZmY3ODExNzMxZjc3YiIsImppdCI6IjE1ODEwOTIzNjItMzk1NDkiLCJleHAiOjE1ODEwOTU5NjJ9.JwGfnfXsP9fbyOiQXFtQ_7T4r-tjvQrkFx0NyfIED5s" // Token de aceptación
}
~~~
Obtendremos una respuesta con una estructura como la siguiente indicándonos que fue creada exitosamente:
~~~json
// Tarjeta
{
data: {
id: 3891,
public_data: {
bin: "424242",
last_four: "4242",
exp_month: "12",
exp_year: "29",
card_holder: "Pedro Pérez",
validity_ends_at: "2025-06-14T09:42:11.293+00:00",
type: "CARD"
},
token: "tok_test_24597_5488f3dd638C114B2B13191Ce2cf1Ae0",
type: "CARD",
status: "AVAILABLE"
customer_email: "[e-mail]"
},
meta: {}
}
// Nequi
{
data: {
id: 3891,
public_data: {
type: "NEQUI",
phone_number: "3105671703",
phone: "3991111111"
},
token: "tok_test_24597_5488f3dd638C114B2B13191Ce2cf1Ae0",
type: "NEQUI",
status: "AVAILABLE"
customer_email: "[e-mail]"
},
meta: {}
}
~~~
Teniendo disponible **`data.id` de una fuente de pago** esta información la podemos almacenar en la base de datos, lo cual para hacer una transacción ahora ahora lo haremos con la **Llave Privada** en el **Header: Bearer token**, dado el objeto JSON:
~~~json
// Tarjeta
{
amount_in_cents: 3000000,
currency: "COP",
customer_email: "[e-mail]",
payment_method: {
installments: 1
},
payment_source_id: 45420,
redirect_url: "https://mitienda.com.co/pago/resultado",
reference: "test111322",
// Esta información es opcional, pero se sugiere tenerla
customer_data: {
phone_number: "573307654321",
full_name: "Juan Alfonso Pérez Rodríguez",
legal_id: "1234567890",
legal_id_type: "CC"
},
// Información Opcional
shipping_address: {
address_line_1: "Calle 34 # 56 - 78",
address_line_2: "Apartamento 502, Torre I",
country: "CO",
region: "Cundinamarca",
city: "Bogotá",
name: "Pepe Perez",
phone_number: "573109999999",
postal_code: "111111"
}
}
// Nequi
{
amount_in_cents: 3000000,
currency: "COP",
customer_email: "[e-mail]",
payment_source_id: 45420,
redirect_url: "https://mitienda.com.co/pago/resultado",
reference: "test111322",
// Esta información es opcional, pero se sugiere tenerla
customer_data: {
phone_number: "573307654321",
full_name: "Juan Alfonso Pérez Rodríguez",
legal_id: "1234567890",
legal_id_type: "CC"
},
// Información Opcional
shipping_address: {
address_line_1: "Calle 34 # 56 - 78",
address_line_2: "Apartamento 502, Torre I",
country: "CO",
region: "Cundinamarca",
city: "Bogotá",
name: "Pepe Perez",
phone_number: "573109999999",
postal_code: "111111"
}
}
~~~
### Obtener información de una fuente de pago
Para obtener información de una fuente de pago, podemos ayudarnos del endpoint que nos ofrece Wompi `URL_WOMPI/payment_sources/:id_fuente_de_pago` haciendo una petición tipo **GET** donde en el **Header: Bearer token** le enviaremos la **Llave Privada**, obtendremos una respuesta de esta forma.
~~~json
// Tarjeta
{
data: {
id: 3891,
public_data: {
bin: "424242",
last_four: "4242",
exp_month: "12",
exp_year: "29",
card_holder: "Pedro Pérez",
validity_ends_at: "2025-06-14T09:42:11.293+00:00",
type: "CARD"
},
token: "tok_test_24597_5488f3dd638C114B2B13191Ce2cf1Ae0",
type: "CARD",
status: "AVAILABLE"
customer_email: "[e-mail]"
},
meta: {}
}
// Nequi
{
data: {
id: 3891,
public_data: {
type: "NEQUI",
phone_number: "3105671703",
phone: "3991111111"
},
token: "tok_test_24597_5488f3dd638C114B2B13191Ce2cf1Ae0",
type: "NEQUI",
status: "AVAILABLE"
customer_email: "[e-mail]"
},
meta: {}
}
~~~

### Metodos de pago
Para usar un método de pago al hacer **POST** en el endpoint de `URL_WOMPI/transactions/:id_transacción` se debe:

- Especificar el campo **payment_method** con un objeto JSON que contiene detalles específicos de cada método de pago.

Al finalizar el proceso de pago de cualquiera de los métodos disponibles, se debe siempre verificar periódicamente con la ayuda de un (_long polling_) el estado de una transacción, esperando un **status** final (aprobada, rechazada o error), usando el **id** de transacción y el endpoint, ya que **ninguno de los métodos de pago otorga un resultado síncrono (inmediato)**. Una transacción recién creada siempre tiene un status: **"PENDING"**.

1. **Tarjetas de Crédito o Débito**
Teniendo estos detalles, y habiéndole preguntado al usuario final el número de cuotas (`"installments"`) en los que desea pagar, los campos de método de pago de una nueva transacción con tarjeta de crédito o débito deben ser similares a los siguientes:
~~~json
{
payment_method: {
type: "CARD",
installments: 2, // Número de cuotas
token: "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301" // Token de la tarjeta de crédito
} // Otros campos de la transacción a crear...
}
~~~
2. **Botón de Transferencia Bancolombia**
En Wompi, tus clientes pueden completar el pago de una transacción usando su cuenta de ahorros o corriente Bancolombia. El nombre del método de pago que debes usar al crear la transacción es **BANCOLOMBIA_TRANSFER**.

Al usar el tipo de método de pago **BANCOLOMBIA_TRANSFER** debes tener en cuenta lo siguiente:

1. Tu cliente debe escoger qué **tipo de persona** es en el campo ***user_type***. Por el momento únicamente está disponible Persona Natural, como **"PERSON"**
2. Debes especificar un nombre de lo que se está pagando en el campo **payment_description**. Máximo 64 caracteres. No puedes incluir comillas simples en este dato (`'`).
3. Si tu transacción es en el ambiente Sandbox, debes enviar el campo **sandbox_status** que especificará qué status final quieres simular. Puede ser uno de los siguientes valores: `APPROVED`, `DECLINED` o `ERROR`.

Así, los campos de método de pago una nueva transacción con **BANCOLOMBIA_TRANSFER** deben ser similares a los siguientes:
~~~json
{
payment_method: {
type: "BANCOLOMBIA_TRANSFER", user_type: "PERSON", // Tipo de persona
payment_description: "Pago a Tienda Wompi", // Nombre de lo que se está pagando. Máximo 64 caracteres
// El siguiente dato SOLO aplica si estás haciendo transacciones en Sandbox
sandbox_status: "APPROVED", // Status final deseado en el Sandbox. Uno de los siguientes: APPROVED, DECLINED o ERROR
ecommerce_url: "https://comercio.co/thankyou_page" // Permite al cliente omitir la pantalla resumen de la transacción de wompi, y redireccionar a un resumen personalizado en el comercio
} // Otros campos de la transacción a crear...
}
~~~
Al crear la transacción, se debe consultar con un _long polling_ hasta que ésta contenga un campo llamado **async_payment_url** dentro de un objeto *¨*extra**, que estará dentro de la propiedad **payment_method**. Una vez se obtenga, se debe redireccionar al cliente a esta URL para que complete el pago en la respectiva institución financiera (banco). El campo que debes esperar de la transacción se vería como el siguiente:
~~~json
{
payment_method: {
type: "BANCOLOMBIA_TRANSFER", // Otros campos del payment_method
extra: {
async_payment_url: "https://..." // URL para redireccionar al cliente
}
} // Otros campos de la transacción...
}
~~~
Al finalizarse el proceso de pago a través de Bancolombia, éste redireccionará a la **redirect_url** que se especificado originalmente en la transacción.

3. **Nequi**
El cliente que debe contar con la app de Nequi instalada en su celular para poder completar el pago usando este método.
~~~json
{
payment_method: {
type: "NEQUI"
phone_number: "3107654321" // Número celular de la cuenta Nequi
} // Otros campos de la transacción a crear...
}
~~~
Al crear la transacción, se le indica al usuario que recibirá una notificación ***push*** de parte de Nequi en su celular, en la cual deberán ***aceptar*** o ***rechazar*** dicha transacción. Este resultado se verá reflejado en Wompi en cuestión de segundos, luego de que el usuario haya tomado acción.

4. **PSE**
En Wompi, los usuarios pueden completar el pago de una transacción usando la cuenta de ahorros o corriente de cualquier banco colombiano, a través de PSE.

Al usar el tipo de método de pago **PSE** se debe tener en cuenta lo siguiente:

1. Se debe obtener la lista de **instituciones financieras** usando el endpoint **GET** `URL_WOMPI/pse/financial_institutions` Requiere **Llave Publica**
2. El usuario debe escoger en qué institución (banco) quiere realizar el pago.
3. El Usuario debe especificar el **tipo de persona** que es: natural (`0`) o jurídica (`1`).
4. Especifica su **tipo y número de documento**
5. Especificar un nombre de lo que se está pagando, máximo 64 caracteres

Luego de que tu cliente haya escogido una institución financiera, usa su código (`code`) como el identificador que vas a enviar al crear la transacción. Así, los campos de método de pago una nueva transacción con **PSE** deben ser similares a los siguientes:
~~~json
{
payment_method: {
type: "PSE",
user_type: 0, // Tipo de persona, natural (0) o jurídica (1)
user_legal_id_type: "CC", // Tipo de documento, CC o NIT
user_legal_id: "1099888777", // Número de documento
financial_institution_code: "1", // Código (`code`) de la institución financiera
payment_description: "Pago a Tienda Wompi, ref: JD38USJW2XPLQA", // Nombre de lo que se está pagando. Máximo 30 caracteres
} // Otros campos de la transacción a crear...
}
~~~
Al crear la transacción, debes consultarla continuamente (_long polling_) hasta que ésta contenga un campo llamado **async_payment_url** dentro de un objeto **extra**, que estará dentro de la propiedad **payment_method**. Una vez la obtengas, debes redireccionar a tu cliente a esta URL para que complete el pago en la respectiva institución financiera (banco). El campo que debes esperar de la transacción se vería como el siguiente:
~~~json
{
payment_method: { // Otros campos del payment_method
extra: {
async_payment_url: "https://..." // URL para redireccionar al cliente
}
} // Otros campos de la transacción...
}
~~~
Al finalizarse el proceso de pago a través de PSE, éste redireccionará a la **redirect_url** que hayas especificado originalmente en la transacción, para que puedas verificar el resultado de la transacción, nuevamente con un _long polling_ hasta obtener un ***status*** final.