Deberás implementar y exponer en tu backend los endpoints de “Autorización” y “Ajustes” para que podamos comunicarnos.
Cada vez que un usuario utiliza su tarjeta en cualquier tienda o comercio electrónico.
Cuando la red (Mastercard, Visa, etc) solicita la conciliación de todos los pagos que presentan los comerciantes.
Si hubiera una diferencia en la conciliación, solicitaremos una corrección a tu API. Necesitaremos que tus endpoints respondan lo más rápido posible para garantizar una buena experiencia de usuario. Si la respuesta se demora, rechazaremos la transacción.
Como una solicitud HTTP puede dar timeout, tenemos que asegurarnos de que al reintentar se procese una única vez. Para eso, en cada solicitud, te enviaremos un header x-idempotency-key
con ID único que deberás procesar con un caché en memoria (por ejemplo: redis).
Al comienzo de cada transacción, deberás verificar si la clave de idempotencia que te enviamos ya está en la caché en memoria y dependiendo de si está o no, deberás realizar lo siguiente:
Deberás almacenar en la caché en memoria la relación clave de idempotencia → pedido con un estado en tránsito con un TTL de 3 minutos.
Cuando apruebes o rechaces la transacción, deberás almacenar el resultado en la caché y actualizar el estado de la clave de idempotencia a terminado
.
En caso de una solicitud duplicada, deberás verificar el estado de la transacción en la caché.
terminado
deberás responder con un código HTTP 200 con el body esperado para el endpoint y completarlo con el resultado de la caché.en tránsito
deberás responder con un código HTTP 425 (Too Early: RFC 8470) con el body esperado para el endpoint. Nosotros volveremos a buscar la respuesta de esta solicitud unos milisegundos más tarde.La comunicación entre nuestros backends debe ser estrictamente segura ya que los endpoints permitirán cargar y deducir fondos.
Para eso, requerimos que implementes tres medidas:
Toda comunicación con nosotros debe ser vía HTTPS, sin importar quien emite el certificado.
Te acercamos algunos de los proveedores más reconocidos
Siempre nos comunicaremos con tu backend desde IPs específicas. Recomendamos que solo aceptes request de las siguientes IPs y que rechaces cualquier otra:
IPS de Pomelo:
34.226.254.178
44.198.3.59
34.223.185.46
100.20.205.117
34.206.159.176
52.0.20.124
35.84.78.117
52.43.46.111
Para asegurarnos de que los únicos participantes en la comunicación sean nuestros backends (Pomelo y el Cliente), en el momento del onboarding le proporcionaremos una api-key
y api-secret
para firmar digitalmente el contenido de la comunicación.
El proceso será algo así:
api-key
y api-secret
.Al momento de una autorización de pago, nosotros firmamos con hmac-sha256 cada pedido de autorización con el api-secret
.
api-key
del request.api-secret
.Durante el proceso de onboarding, crearemos una api-key
y api-secret
específicas para ti.
También es posible usar gpg o algún plugin de correo electrónico (como por ejemplo https://flowcrypt.com/).
Veamos un ejemplo usando openssl en la línea de comandos.
$ echo -e 'api-key=$(openssl rand -base64 32)\napi-secret=$(openssl rand -base64 32)' > api-credentials.txt
$ cat api-credentials.txt
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=
$ openssl genrsa -out private.pem 2048
$ openssl rsa -in private.pem -pubout -out public.pem
public.pem
por email o Slack.$ openssl rsautl -encrypt -in api-credentials.txt -out api-credentials.txt.enc -inkey public.pem -pubin
api-credentials.txt.enc
por email o Slackapi-credentials.txt.enc
con tu clave privada private.pem
:$ openssl rsautl -decrypt -in api-credentials.txt.enc -inkey private.pem
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=
api-secret
en un lugar seguro y que sea accesible únicamente por la aplicación de “Autorizar pagos”, asociada al api-key
.Junto con el pedido de autorización o ajuste te enviaremos headers HTTP con la firma, el timestamp de la firma y la api-key
para que verifiques que la firma sea correcta.
Los headers HTTP que enviamos son:
x-api-key
: este header te permitirá identificar qué api-secret
tenés que usar en el caso que se hayan configurado múltiples pares de api-key
y api-secret
.
x-signature
: este header contiene la firma digital (body + timestamp + endpoint) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.
x-timestamp
: este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.
x-endpoint
: el endpoint al que se realiza el pedido y que se uso para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.
Importante: además de chequear la firma que te enviamos, al generar la respuesta deberás firmar tu body junto con el timestamp y el endpoint de respuesta con tu api-secret
luego de impactar la operación. Ten en cuenta que validaremos la firma y rechazaremos la transacción si la firma no coincide o expiró.
Puedes testear la implementación de tu backend con algunas operaciones típicas que enviaremos con una colección de Postman incluida en nuestro repositorio de ejemplos públicos. Podrás importar la colección a una instancia de Postman y así simular pedidos reales hacia tu backend, incluido el algoritmo de generación y chequeo de firma.
En el repositorio también encontrarás ejemplos de implementación del algoritmo de generación y validación de firma en varios lenguajes.
Este es un proceso opcional, pero recomendamos ejecutarlo a diario.
En el servidor SFTP que te disponibilizaremos encontrarás estos archivos:
Contiene el detalle de cada transacción que te generamos el día anterior.
El nombre del archivo tiene el siguiente formato: transaction_yyyy-mm-dd_<nombre cliente>_<pais>.csv
{Atributo} | Descripción | Valores permitidos |
---|---|---|
TRANSACTION_ID | El id que permite identificar la transacción como única. | |
LOCAL_TRANSACTION_DATE_TIME | ||
TRANSACTION_TYPE | Indica el tipo de transacción. | PURCHASE WITHDRAWAL EXTRACASH BALANCE_INQUIRY REFUND PAYMENT REVERSAL_PURCHASE REVERSAL_WITHDRAWAL REVERSAL_EXTRACASH REVERSAL_REFUND REVERSAL_PAYMENT |
PRODUCT_TYPE | Es el tipo de producto | PREPAID CREDIT DEBIT |
PROVIDER | Es la marca de la tarjeta emitida. | VISA MASTERCARD |
AFFINITY_GROUP_ID | ||
USER_ID | El id del usuario de Pomelo titular de la tarjeta. | |
CARD_ID | ||
BIN | Los primeros seis u ocho dígitos del PAN. | |
LAST_FOUR | Los últimos cuatro dígitos del PAN. | |
ORIGIN | DOMESTIC: la transacción ocurrió en el país del emisor. INTERNATIONAL: la transacción no se realizó en el país del emisor. | |
MERCHANT_ID | ||
MERCHANT_MCC | El código de categoría de comerciante según se define en el ISO-18245. | |
MERCHANT_NAME | ||
LOCAL_AMOUNT | Es el monto total de la transacción que debe ser deducido del balance del usuario, con impuestos y tasas agregadas (cuando aplica). Siempre se convierte a la moneda local de la tarjeta. | |
LOCAL_CURRENCY | El código de la moneda de LOCAL_TOTAL en ISO_4217 formato ALPHA-3. | |
TRANSACTION_AMOUNT | El monto de la transacción sin impuestos y en la moneda original enviada por el comerciante. | |
TRANSACTION_CURRENCY | El código de la moneda de TRANSACTION_TOTAL en ISO_4217 formato ALPHA-3. | |
SETTLEMENT_AMOUNT | El monto de la transacción según lo enviado por la red. Para Argentina siempre lo mostraremos en USD, mientras que para el resto de los países, en la moneda local. | |
SETTLEMENT_CURRENCY | El código de la moneda de SETTLEMENT_TOTAL en ISO_4217 formato ALPHA-3. Para Argentina siempre lo mostraremos en USD, mientras que para el resto de los países, en la moneda local. | |
ENTRY_MODE | El modo en que se usó la tarjeta en el punto de venta del comerciante. | UNKNOWN MANUAL CHIP CONTACTLESS CREDENTIAL_ON_FILE MAG_STRIPE OTHERS |
STATUS | El estado de la transacción. | APPROVED REJECTED HELD |
STATUS_DETAIL | Razón adicional por la que la transacción se aprueba o rechaza. | Ver tabla a continuación |
SOURCE | Indica qué flujo / proceso desencadenó la transacción, visto desde Pomelo. | ONLINE: Se origina durante el flujo transaccional a partir de transacciones en tiempo real enviadas por la red CLEARING: Se origina durante el proceso de acuerdo entre Pomelo y la red al gestionar el archivo de liquidación PURGE: transacciones que no se presentaron en el archivo de liquidación de la red. |
ORIGINAL_TRANSACTION_ID | Este valor podría estar vacío si la transacción no está relacionada con otra. | |
COUNTRY_CODE | Este es el código de país en formato ISO-3166. | |
POINT_TYPE | POS ECOMMERCE ATM MOTO | |
CLIENT_NAME | El nombre del cliente que aprueba o rechaza la transacción, dado que el reporte se segmenta por cliente, va a tener el mismo valor para todas las filas | |
CLIENT_COUNTRY_CODE | El coódigo de país del cliente en formato ISO-3166 | |
AMOUNT_DETAILS | El detalle de la composición del monto local, en el mismo formato que es enviado de forma ONLINE. Codificado en base64 | |
INSTALLMENTS_GRACE_PERIOD | [OPCIONAL*] El período de gracia refiere a la cantidad de meses previo a que comiencen los pagos en cuotas. Puede ir de 0 a 99. | |
INSTALLMENTS_QUANTITY | [OPCIONAL*] La cantidad de cuotas | |
INSTALLMENTS_CREDIT_TYPE | [OPCIONAL*] El tipo de crédito otorgado | NO_PROMOTION WITHOUT_INTEREST WITH_INTEREST BUY_TODAY_PAY_LATER |
*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.
Status detail | Descripción |
---|---|
CARD_BLOCKED | El estado de la tarjeta es BLOCKED. |
CARD_DISABLED | El estado de la tarjeta es DISABLED |
CARD_NOT_ACTIVE | El estado de la tarjeta es EMBOSSED o CREATED |
CARD_NOT_CONFIGURED | A la tarjeta le faltan configuraciones. |
CARD_NOT_FOUND | No podemos encontrar el PAN de la tarjeta. |
CLIENT_TIMEOUT | El cliente demora en responder. |
CLIENT_UNAVAILABLE | No podemos conectar con el cliente o recibimos un 5XX. |
CLIENT_SIGNATURE_ERROR | Cuando hay una falla en la firma del cliente. |
CRYPTO_ERROR | Hay un error en los criptogramas (EMV). |
DUPLICATE_TRANSMISSION_DETECTED | Recibimos una transacción repetida por parte de la network. |
EXPIRED_CARD | El estado de la tarjeta es EXPIRED. |
EXTRA_FIELDS | La mensajería de parte de la network viene con campos no esperados. |
INSUFFICIENT_FUNDS | El cliente nos responda que la cuenta no tiene fondos. |
INTERNAL_ERROR | Fallo imprevisto en el sistema de Pomelo. |
INVALID_AMOUNT | Se superan los límites del grupo de afinidad. |
INVALID_CVV | El CVV no coincide. |
INVALID_EXPIRATION_DATE | La fecha de expiración recibida no coincide con la tarjeta. |
INVALID_MERCHANT | El cliente rechaza al merchant por algún motivo específico. |
INVALID_PIN | El PIN es incorrecto |
PIN_TRY_LIMIT_EXCEED | Se ha ingresado incorrectamente el PIN y se excedio el limite de intentos. |
INVALID_TRANSACTION | La transacción es inválida. |
LOST_CARD | El estado de la tarjeta es LOST. |
MISSING_FIELDS | La mensajería de parte de la network viene sin campos obligatorios. |
NOT_DECLINED | Una transacción viene con monto en 0 para validar si la cuenta está activa. |
ORIGINAL_NOT_FOUND | Se intenta hacer una reversal de una transacción que no encontramos. |
OTHER | No reconocemos el caso. |
RESTRICTED_USER | El estado del usuario no es ACTIVE. |
SECURITY_VIOLATION | Supera un umbral de fraude. |
SERVICE_UNAVAILABLE | El cliente o un servicio de Pomelo están caídos. |
STOLEN_CARD | El estado de la tarjeta es STOLEN. |
SYSTEM_ERROR | El cliente nos indica que tuvo un error inesperado. |
APPROVED | El cliente aprueba una transacción. |
TRANSACTION_NOT_PERMITTED | El tipo de transacción no está permitido en el grupo de afinidad. |
REJECTED_FRAUD | La transacción fue rechazada por el motor de fraude. |
¿Está en Pomelo? | ¿Está en el cliente? | ¿Tiene el mismo estado? | Action |
---|---|---|---|
Y | Y | Y | No hacer nada / Marcar como coincidente |
Y | Y | N | 1) Registrar un ajuste que debite / acredite al usuario final si corresponde. 2) Marcar como coincidente. |
Y | N | N | 1) IF STATUS == APPROVED: Registrar un ajuste que debite / acredite al usuario final si corresponde. 2) Marcar como coincidente. |
N | Y | N | No es un caso de uso posible. |
En caso de que esté intentando ajustar un crédito a un usuario final que no tenga fondos suficientes en la cuenta, debe seguir intentando obtener los fondos de ese usuario.
Se convierte en una deuda entre el cliente y el usuario final.
Contiene el detalle de cada transacción que presentan los comerciantes el día anterior.
El nombre del archivo tiene el siguiente formato: presentment_yyyy-mm-dd_<nombre cliente>_<pais>.csv
Atributo | Descripción | Valores permitidos |
---|---|---|
PRESENTMENT_ID | ||
TRANSACTION_ID | El id de la transacción original que generó la presentación. | |
LOCAL_TRANSACTION_DATE_TIME | ||
TRANSACTION_TYPE | Indica el tipo de transacción. | PURCHASE WITHDRAWAL EXTRACASH REFUND PAYMENT |
PRODUCT_TYPE | Es el tipo de producto. | PREPAID CREDIT DEBIT |
PROVIDER | Es la marca de la tarjeta emitida. | VISA MASTERCARD |
AFFINITY_GROUP_ID | ||
USER_ID | El id del usuario de Pomelo titular de la tarjeta | |
CARD_ID | ||
BIN | Los primeros seis u ocho dígitos del PAN. | |
LAST_FOUR | Los últimos cuatro dígitos del PAN. | |
ORIGIN | DOMESTIC: la transacción ocurrió en el país del emisor. INTERNATIONAL: la transacción no se realizó en el país del emisor. | |
MERCHANT_ID | ||
MERCHANT_MCC | El código de categoría de comerciante según se define en el ISO-18245. | |
MERCHANT_NAME | ||
TRANSACTION_AMOUNT | El monto de la transacción sin impuestos y en la moneda original enviada por el comerciante. | |
TRANSACTION_CURRENCY | El código de la moneda de TRANSACTION_TOTAL en ISO_4217 formato ALPHA-3. | |
SETTLEMENT_AMOUNT | El monto de la transacción presentado por la marca. | |
SETTLEMENT_CURRENCY | El código de la moneda de SETTLEMENT_AMOUNT en ISO_4217 formato ALPHA-3. Para Argentina siempre lo mostraremos en USD, mientras que para el resto de los países, en la moneda local. | |
DEBT_AMOUNT | El monto de la transacción en la moneda a pagar a Pomelo. Si el monto se debe pagar a Pomelo siempre es un valor positivo, de lo contrario será un valor negativo. | |
DEBT_CURRENCY | El código de la moneda de DEBT_AMOUNT en ISO_4217 formato ALPHA-3, si es una transacción doméstica deberá pagarse en moneda local, de lo contrario en USD. | |
RECONCILIATION_DATE | ||
INTERCHANGE_FEE | Comisión por una transacción aplicada al intercambio de la misma. | |
INTERCHANGE_RATE | Valor alfanumérico que identifica la tasa de intercambio de la transacción presentada por el adquirente. | |
TAX | Este es el impuesto asociado a la tasa de intercambio, debido a la regulación local, esos montos deben tener un IVA calculado. | |
FUNCTION_CODE | Este es el tipo de presentación. | FIRST_PRESENTMENT SECOND_PRESENTMENT_FULL SECOND_PRESENTMENT_PARTIAL |
REVERSE_PRESENTMENT | Significa que la presentación fue revertida desde la red. | TRUE FALSE |
REASON_CODE | Razón de la segunda presentación. | |
ICA_ACQUIRER | ||
TAX_ID | ID asociado a los impuestos de la transacción | |
INSTALLMENTS_GRACE_PERIOD | [OPCIONAL*] El período de gracia refiere a la cantidad de meses previo a que comiencen los pagos en cuotas. Puede ir de 0 a 99. | |
INSTALLMENTS_QUANTITY | [OPCIONAL*] La cantidad de cuotas | |
CURRENT_INSTALLMENT | [OPCIONAL*] Indica qué número de cuota está pagando el cliente. | |
INSTALLMENTS_CREDIT_TYPE | [OPCIONAL*] El tipo de crédito otorgado | NO_PROMOTION WITHOUT_INTEREST WITH_INTEREST BUY_TODAY_PAY_LATER |
USD_EXCHANGE_RATE | El cual indicará el tipo de cambio del Banco Nación al cierre del día anterior | |
DEBT_AMOUNT_ARS | Este campo es el monto de la deuda expresada en ARS, usando el tipo de cambio por el monto del debt amount. En caso de que el Debt Amount ya este en ARS, no se realiza la multiplicación |
*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.
Nuestro equipo de finanzas enviará diariamente un detalle con la deuda a pagar. Ese detalle tendrá todas las presentaciones que recibimos en el archivo de presentación.
Disponibilizaremos un servidor SFTP desde donde podrás descargar los archivos de Transacciones y Presentaciones.
Tenemos dos ambientes para los servidores SFTP: un ambiente productivo y otro de desarrollo.
Para conectarte a los servidores SFTP necesitaremos que nos envíes una llave pública para generarte un usuario.
Estos son los datos para conectarte a cada ambiente:
Host: sftp.pomelo.la
Puerto: 22
Usuario: <tu_usuario> # el que te generamos a partir de tus llaves públicas.
Host: sftp-dev.pomelo.la
{Puerto}: 22
Usuario: <tu_usuario> # el que te generamos a partir de tus llaves públicas.
Para generar la clave pública tendrás que usar el comando acorde a tu sistema operativo:
$Cliente
por el nombre propiossh-keygen -t rsa -b 2048 -C $Cliente
El comando creará un par de claves RSA de 2048 bits de forma predeterminada. También podrás crear una clave más grande de 4096 bits ingresando -b 4096.
El comando produce esta salida:
Generating public/prive rsa key pair.
Ingresa un archivo en el que guardar la clave (/your_home/.ssh/id_rsa):
Presiona Enter
para guardar el par de claves en .ssh /, o especifica otra ubicación.
Presiona Enter
para dejarlo en blanco y usa solo la clave para establecer conexiones SSH. Ingresa una contraseña para una capa de seguridad adicional.
cat ~/.ssh/id_rsa.pub
La clave generada comenzará con ssh-rsa.
Ahora puedes copiar y pegar tu clave SSH pública en tu consola Shell, o en cualquier servidor, para establecer una conexión segura.
Genera claves SSH usando PuTTY. Instala PuTTY desde la página del desarrollador: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html
Instala PuTTY desde la página del desarrollador: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html
puttygen
.PuTTYgen
.Ejecutar como administrador
.Sí
si el sistema te consulta “¿Desea permitir que esta aplicación realice cambios en su dispositivo?”Si bien la herramienta PuTTY keygen ofrece varios otros algoritmos, te contaremos cómo generar claves RSA, una de las más usadas:
Generar
.Guardar clave pública
. Luego tendrás que elegir una ubicación para guardar la clave y asignarle un nombre a la clave.Conversiones
en la parte superior.Sí
.El endpoint /transactions/authorizations
permite autorizar las transacciones.
Te enviaremos una solicitud para autorizar o rechazar la transacción.
Esperamos una respuesta rápida para garantizar una buena experiencia. Si la respuesta se demora, rechazaremos la transacción.
El endpoint /transactions/adjustments/{type}
nos permite hacer ajustes de crédito y débito en las transacciones.
Te enviaremos una solicitud para informarle que la red (MC, VISA) forzó una autorización.
Este endpoint se usa durante la conciliación y los flujos online, principalmente para hacer ajustes durante el proceso de liquidación y también en caso de devoluciones.
Este servicio permite notificar cuando se resuelve una transacción, ya sea por parte de Pomelo o por parte de la bandera (Mastercard, Visa, etc.).
Esperamos una respuesta del tipo 2XX para asegurarnos que la notificación fue recibida. Caso contrario, volveremos a enviarla.