API Reference

Estado del servicio

Transacciones

Deberás implementar y exponer en tu backend los endpoints de “Autorización” y “Ajustes” para que podamos comunicarnos.

Flujo del Procesador de Pagos:

Vamos a consumir tus endpoints en estos momentos:

Durante el flujo online

Cada vez que un usuario utiliza su tarjeta en cualquier tienda o comercio electrónico.

Durante la conciliación

Cuando la red (Mastercard, Visa, etc) solicita la conciliación de todos los pagos que presentan los comerciantes.

Consideraciones

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.

Idempotencia

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:

No existe el header de idempotencia en la caché

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.

Existe el header de idempotencia en la caché

En caso de una solicitud duplicada, deberás verificar el estado de la transacción en la caché.

Si está en estado 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é.
Si está en estado 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.

Requests en curso

Si recibes un segundo request con el mismo ID de idempotencia y el primero aún está en curso, debes responder con un http-status 425 y body vacío

Seguridad

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:

Exponer endpoint HTTPS
Whitelist de las IPs de Pomelo
Firma hmac-sha256 del pedido y la respuesta

Exponer endpoint HTTPS

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

Whitelist de las IPs de Pomelo

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:

Ambiente de Testing/Staging:

34.226.254.178            
44.198.3.59
34.223.185.46
100.20.205.117

Ambiente de Producción:

34.206.159.176            
52.0.20.124
35.84.78.117
52.43.46.111

Firma hmac-sha256 del pedido y la respuesta

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í:

1. En el onboarding haremos el intercambio de llaves `api-key` y `api-secret`.

2.

Al momento de una autorización de pago, nosotros firmamos con hmac-sha256 cada pedido de autorización con el api-secret.

4. Validas la firma hmac-sha256 con tu api-secret que se corresponde con el `api-key` del request.

5. Autorizas el pedido, debitas los fondos del usuario y firmas la respuesta con hmac-sha256 usando el `api-secret`.

6. Verificamos la firma hmac-sha256 y terminamos de procesar el pago.

Proceso de intercambio de llaves

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.

1. Creamos las api-key y api-secret:

$ 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=

2. Creas tu clave pública-privada:

$ openssl genrsa -out private.pem 2048
$ openssl rsa -in private.pem -pubout -out public.pem

3. Nos envías tu clave pública `public.pem` por email o Slack.

4. Encriptamos el archivo de credenciales con la clave pública que nos diste:

$ openssl rsautl -encrypt -in api-credentials.txt -out api-credentials.txt.enc -inkey public.pem -pubin

5. Enviamos el archivo `api-credentials.txt.enc` por email o Slack

6. Desencriptas el archivo `api-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=

7. Guardas la `api-secret` en un lugar seguro y que sea accesible únicamente por la aplicación de “Autorizar pagos”, asociada al `api-key`.

Proceso de Firma del pedido

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ó.

Como Testear tu implementación y código de ejemplo

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.

Liquidación

Este es un proceso opcional, pero recomendamos ejecutarlo a diario.

En el servidor SFTP que te disponibilizaremos encontrarás estos archivos:

Archivo de transacciones
Archivo de presentación

Archivo de transacciones

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

Estructura del archivo de transacciones

{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.

Tabla de STATUS_DETAIL

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.

Conciliación del archivo de transacciones

¿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.

Archivo de presentación

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

Estructura del archivo de presentación

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.

Conciliación del archivo de presentación

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.

Obtención de los archivos de Transacciones y Presentaciones

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:

Producción:

Host: sftp.pomelo.la
Puerto: 22
Usuario: <tu_usuario> # el que te generamos a partir de tus llaves públicas.

Desarrollo:

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:

Linux / MacOs:

1. Crea una RSA Key Pair, cambiando la variable `$Cliente` por el nombre propio

ssh-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.

2. Crea una frase de contraseña para tu clave SSH

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.

3. Obtener la clave pública generada leyendo el contenido del archivo público

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.

Windows

Genera claves SSH usando PuTTY. Instala PuTTY desde la página del desarrollador: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

1. Genera claves SSH usando PuTTY

Instala PuTTY desde la página del desarrollador: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

2. Ejecuta el generador de claves PuTTY SSH

Presiona la tecla de Windows.
Escribe puttygen.
Haz clic con el botón derecho en PuTTYgen.
Haz clic en Ejecutar como administrador.
Haz clic en Sí si el sistema te consulta “¿Desea permitir que esta aplicación realice cambios en su dispositivo?”

3. Usa PuTTY para crear un par de claves SSH

Si bien la herramienta PuTTY keygen ofrece varios otros algoritmos, te contaremos cómo generar claves RSA, una de las más usadas:

En la ventana del generador de claves PuTTY, toca Generar.
Mueve el cursor en el cuadro gris para llenar la barra verde.
Genera un par de claves SSH en Putty.
Guarda la clave pública haciendo clic en el botón Guardar clave pública. Luego tendrás que elegir una ubicación para guardar la clave y asignarle un nombre a la clave.
Guarda la clave privada:
- Haz clic en el menú Conversiones en la parte superior.
- Haz clic en Exportar clave OpenSSH.
- El sistema te preguntará si quieres guardar una clave sin una frase de contraseña. Haz clic en Sí.
- Elige una ubicación para guardar la clave (generalmente la misma carpeta que la clave pública).
- Asigna un nombre a la clave (por ejemplo, putty_key).

Autorizar Transacción

El endpoint /transactions/authorizations permite autorizar las transacciones.

Te enviaremos una solicitud para autorizar o rechazar la transacción.

Consideraciones

Esperamos una respuesta rápida para garantizar una buena experiencia. Si la respuesta se demora, rechazaremos la transacción.

Parámetros disponibles

Body Parameters

transactionobject

Información relacionada con la transacción

merchantobject

Información relacionada con el comerciante

cardobject

Información no sensible relacionada a la tarjeta

installmentsobject

Información relacionada a las cuotas de la transacción, se recibirá este parámetro solo para autorizaciones de compra con cuotas en tarjeta de crédito.

userobject

Información relacionada al usuario que realizó la transacción

amountobject

Información relacionada a los montos de la transacción. Estos montos podrán ser mayor o igual a cero

extra_dataobject

Información relacionada a campos extras de la transacción

Detalle de respuestas

statusstring

Un estado que nos indica si debemos aprobar o rechazar la transacción

Enum: APPROVEDREJECTED

messagestring

Mensaje descriptivo con el resultado de la operación

status_detailstring

Permite rastrear el motivo por el que no se aprobó la transacción

Enum: APPROVEDINSUFFICIENT_FUNDSINVALID_MERCHANTINVALID_AMOUNTSYSTEM_ERROROTHER

balanceobject

Balance de la cuenta. Se devuelve sólo en caso de que se mande el type 'BALANCE_INQUIRY'. Disponible sólo para México.

¿Te resultó útil esta sección?

POST/transactions/authorizations

{

"transaction":{

"id":

"ctx-200kXoaEJLNzcsvNxY1pmBO7fEx"

"type":

"PURCHASE"

"point_type":

"POS"

"entry_mode":

"MANUAL"

"country_code":

"ARG"

"origin":

"DOMESTIC"

"source":

"ONLINE"

"network":

"MASTERCARD"

"cardless_withdrawal_user_id":

"string"

"cardless_withdrawal_token":

"string"

"original_transaction_id":

"ctx-200kirg6qicg1qHSCbgaStrEHjI"

"local_date_time":

"2019-08-24T14:15:22"

}

"merchant":{

"id":

"string"

"mcc":

"string"

"address":

"string"

"name":

"string"

"terminal_id":

"string"

}

"card":{

"id":

"c-1625519392748E6XZBK"

"product_type":

"PREPAID"

"provider":

"MASTERCARD"

"last_four":

"1573"

}

"installments":{

"quantity":

"12"

"credit_type":

"NO_PROMOTION"

"grace_period":

"0"

"current_installment":

"1"

}

"user":{

"id":

"u-1625758043579BAR6D4"

}

"amount":{

"local":{

...

}

"settlement":{

...

}

"transaction":{

...

}

"details":[

...

]

}

"extra_data":{

"cardholder_verification_method":

"FAIL_PROCESSING"

"pin_presence":

"ONLINE"

"pin_validation":

"VALID"

"cvv_presence":

"PRESENT"

"cvv_validation":

"MATCHING"

"expiration_date_presence":

"PRESENT"

"expiration_date_validation":

"EXPIRED"

"function_code":

"PREAUTH"

"tokenization_wallet_name":

"Apple_Pay"

"tokenization_wallet_id":

"0"

"cardholder_presence":

"CARDHOLDER_PRESENCE_PRESENT"

"card_presence":

"PRESENT"

"pin_change_send":

"SENT"

"pin_change_result":

"APPLIED"

}

Ejemplo de respuestas

Una transacción manejada con éxito, haya sido aprobada o no.

{

"status":

"APPROVED"

"message":

"string"

"status_detail":

"APPROVED"

"balance":{

"total":

"982345.12"

"currency":

"ARS"

}

Ajustes

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.

Consideraciones

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.

Parámetros disponibles

Body Parameters

transactionobject

Información relacionada con la transacción

merchantobject

Información relacionada con el comerciante

cardobject

Información no sensible relacionada a la tarjeta

installmentsobject

Información relacionada a las cuotas de la transacción, se recibirá este parámetro solo para autorizaciones de compra con cuotas en tarjeta de crédito.

userobject

Información relacionada al usuario que realizó la transacción

amountobject

Información relacionada a los montos de la transacción. Estos montos podrán ser mayor o igual a cero

Path Parameters

typestringrequired

El tipo de operación que se ejecutará en el saldo del usuario. Si es débito, se debe deducir el monto del saldo del usuario. Si es crédito, se debe agregar fondos al saldo del usuario. NOTA: Es posible que reciba ajustes con valores muy pequeños, depende del cliente si desea afectarlos en el saldo del usuario o no.

Enum: debitcredit

Detalle de respuestas

¿Te resultó útil esta sección?

POST/transactions/adjustments/{type}

{

"transaction":{

"id":

"ctx-200kXoaEJLNzcsvNxY1pmBO7fEx"

"type":

"PURCHASE"

"point_type":

"POS"

"entry_mode":

"MANUAL"

"country_code":

"ARG"

"origin":

"DOMESTIC"

"source":

"ONLINE"

"network":

"MASTERCARD"

"cardless_withdrawal_user_id":

"string"

"cardless_withdrawal_token":

"string"

"original_transaction_id":

"ctx-200kirg6qicg1qHSCbgaStrEHjI"

"local_date_time":

"2019-08-24T14:15:22"

}

"merchant":{

"id":

"string"

"mcc":

"string"

"address":

"string"

"name":

"string"

"terminal_id":

"string"

}

"card":{

"id":

"c-1625519392748E6XZBK"

"product_type":

"PREPAID"

"provider":

"MASTERCARD"

"last_four":

"1573"

}

"installments":{

"quantity":

"12"

"credit_type":

"NO_PROMOTION"

"grace_period":

"0"

"current_installment":

"1"

}

"user":{

"id":

"u-1625758043579BAR6D4"

}

"amount":{

"local":{

...

}

"settlement":{

...

}

"transaction":{

...

}

"details":[

...

]

}

Ejemplo de respuestas

Ajuste recibido.

Notificaciones

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.).

Consideraciones

Esperamos una respuesta del tipo 2XX para asegurarnos que la notificación fue recibida. Caso contrario, volveremos a enviarla.

Parámetros disponibles

Body Parameters

event_idstring

Identificador de evento.

Ejemplo: authorization-advice

event_detailobject

Información relacionada al evento. Esta puede variar según el tipo de evento.

idempotency_keystring

Identificador idempotente de creación del evento.

Ejemplo: ctx-2CIllOHdIcC5qWjpiwRlFy2nZM8

¿Te resultó útil esta sección?

POST/transactions/v1/notifications

{

"event_id":

"authorization-advice"

"event_detail":{

"transaction":{

...

}

"merchant":{

...

}

"card":{

...

}

"installments":{

...

}

"user":{

...

}

"amount":{

...

}

"status":

"REJECTED"

"status_detail":

"string"

"extra_detail":

"string"

"extra_data":{

...

}

"idempotency_key":

"ctx-2CIllOHdIcC5qWjpiwRlFy2nZM8"

}

Ejemplo de respuestas

Respuesta exitosa por parte del cliente.

API Reference

Transacciones

Flujo del Procesador de Pagos:#

Vamos a consumir tus endpoints en estos momentos:#

Durante el flujo online

Durante la conciliación#

Consideraciones#

Idempotencia#

No existe el header de idempotencia en la caché

Existe el header de idempotencia en la caché

Requests en curso#

Seguridad#

Exponer endpoint HTTPS#

Whitelist de las IPs de Pomelo#

Firma hmac-sha256 del pedido y la respuesta#

1. En el onboarding haremos el intercambio de llaves api-key y api-secret.

2.

4. Validas la firma hmac-sha256 con tu api-secret que se corresponde con el api-key del request.

5. Autorizas el pedido, debitas los fondos del usuario y firmas la respuesta con hmac-sha256 usando el api-secret.

6. Verificamos la firma hmac-sha256 y terminamos de procesar el pago.

Proceso de intercambio de llaves#

1. Creamos las api-key y api-secret:

2. Creas tu clave pública-privada:

3. Nos envías tu clave pública public.pem por email o Slack.

4. Encriptamos el archivo de credenciales con la clave pública que nos diste:

5. Enviamos el archivo api-credentials.txt.enc por email o Slack

6. Desencriptas el archivo api-credentials.txt.enc con tu clave privada private.pem:

7. Guardas la api-secret en un lugar seguro y que sea accesible únicamente por la aplicación de “Autorizar pagos”, asociada al api-key.

Proceso de Firma del pedido#

Como Testear tu implementación y código de ejemplo#

Liquidación#

Archivo de transacciones#

Estructura del archivo de transacciones#

Tabla de STATUS_DETAIL#

Conciliación del archivo de transacciones#

Archivo de presentación#

Estructura del archivo de presentación#

Conciliación del archivo de presentación#

Obtención de los archivos de Transacciones y Presentaciones#

Producción:#

Desarrollo:#

Linux / MacOs:#

1. Crea una RSA Key Pair, cambiando la variable $Cliente por el nombre propio

2. Crea una frase de contraseña para tu clave SSH

3. Obtener la clave pública generada leyendo el contenido del archivo público

Windows#

1. Genera claves SSH usando PuTTY

2. Ejecuta el generador de claves PuTTY SSH

3. Usa PuTTY para crear un par de claves SSH

Autorizar Transacción

Consideraciones#

¿Te resultó útil esta sección?

Ajustes

Consideraciones#

¿Te resultó útil esta sección?

Notificaciones

Consideraciones#

¿Te resultó útil esta sección?

Flujo del Procesador de Pagos:

Vamos a consumir tus endpoints en estos momentos:

Durante la conciliación

Consideraciones

Idempotencia

Requests en curso

Seguridad

Exponer endpoint HTTPS

Whitelist de las IPs de Pomelo

Firma hmac-sha256 del pedido y la respuesta

1. En el onboarding haremos el intercambio de llaves `api-key` y `api-secret`.

4. Validas la firma hmac-sha256 con tu api-secret que se corresponde con el `api-key` del request.

5. Autorizas el pedido, debitas los fondos del usuario y firmas la respuesta con hmac-sha256 usando el `api-secret`.

Proceso de intercambio de llaves

3. Nos envías tu clave pública `public.pem` por email o Slack.

5. Enviamos el archivo `api-credentials.txt.enc` por email o Slack

6. Desencriptas el archivo `api-credentials.txt.enc` con tu clave privada `private.pem`:

7. Guardas la `api-secret` en un lugar seguro y que sea accesible únicamente por la aplicación de “Autorizar pagos”, asociada al `api-key`.

Proceso de Firma del pedido

Como Testear tu implementación y código de ejemplo

Liquidación

Archivo de transacciones

Estructura del archivo de transacciones

Tabla de STATUS_DETAIL

Conciliación del archivo de transacciones

Archivo de presentación

Estructura del archivo de presentación

Conciliación del archivo de presentación

Obtención de los archivos de Transacciones y Presentaciones

Producción:

Desarrollo:

Linux / MacOs:

1. Crea una RSA Key Pair, cambiando la variable `$Cliente` por el nombre propio

Windows

Consideraciones

Consideraciones

Consideraciones