Implementamos el estándar OAuth 2.0 para que puedas comunicarte con nuestras APIs con un único token del tipo Bearer.

Una vez que recibas el token de acceso deberás incluirlo como un header de autorización cada vez que te comuniques con nuestras APIs.

Ejemplo en curl:

curl https://api.pomelo.la -H 'Authorization: Bearer eyJhbGciOiJSUzI1Ni'

Cada API validará el token de acceso y verificará que el scope coincida con los permisos requeridos.

Para que los request sean válidos, deberás comunicarte con nuestras APIs únicamente por HTTPS e incluir el header de autorización indicando que es del tipo Bearer.

La API de Envíos contiene todos los endpoints y webhooks necesarios para crear un envío, obtener información sobre un envío y mantenerse actualizado sobre los eventos que afectan a un envío.

Necesitarás un endpoint público para que podamos comunicarte las novedades de los envíos en tiempo real.

Tu endpoint deberá terminar en /shipping/updates

Ahí te notificaremos si hay actualizaciones sobre un envío. Serás responsable de buscar el recurso para obtener el estado actualizado.

Url de ejemplo

POST https://api.current-customer.com/whatever/shipping/updates

Body

{
  'shipment_id': 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
  'meta': {
    'resource_url': 'http://localhost:8080/v1/{shipment_id}'
  }
}

Ejemplo en Curl

curl --request POST \
--url https://api.current-customer.com/whatever/shipping/updates \
--header 'Content-Type: application/json' \
--data '{
    'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
    'meta' : {
        'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
    }
}'

Como medida de seguridad, todas las notificaciones de novedades incluirán una firma hmac-sha256, pero no es necesario que la respuesta sea firmada por los clientes.

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.

A continuación explicamos con más profundidad los procesos de Intercambio de llaves y firma del pedido.

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.

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 usaste para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.

Veamos un curl de ejemplo indicando cómo se envía esta información dentro del request:

curl --location --request POST 'localhost:9090/shipping/updates' \
--header 'x-api-key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=' \
--header 'x-signature: hmac-sha256 kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=' \
--header 'x-timestamp: 1637117179' \
--header 'x-endpoint: {clientPath}/shipping/updates'
--header 'Content-Type: application/json' \
--data-raw '{
    'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
    'meta' : {
        'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
    }
}'

Para el armado de la firma se puede utilizar el siguiente snippet de código (en python 3) como por ejemplo:

import hmac, hashlib, base64, time

############# Pomelo's side ################
############################################

# pomelo's secret key
pomelo_secret_key = base64.b64decode('kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=')

# the update data pomelo is gonna use to make the signature
pomelo_update_body = '{
    'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
    'meta' : {
        'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
    }
}'
client_req_endpoint = '/shipping/updates'
pomelo_timestamp = str(int(time.time()))

# the request data signed out by pomelo
pomelo_signature = hmac.new(pomelo_secret_key, bytes(pomelo_timestamp + client_req_endpoint + pomelo_update_body, 'utf-8'), hashlib.sha256).digest()


############# Client's side ################
############################################

# client's secret key
client_secret_key = base64.b64decode('kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=')

# client's api endpoint
client_api_endpoint = '/transactions/authorizations'

# signature expiration offset
signature_expiration_offset = 60 #A minute of expiration

# the authorizacion data the client needs to use to recreate the signature
client_request_data = bytes(pomelo_timestamp + client_req_endpoint + pomelo_update_body, 'utf-8')

# the signature the client has recreated
signature = hmac.new(client_secret_key, client_request_data, hashlib.sha256).digest()

# if signature is not expired and they match you can trust the request, otherwise reject it
now = int(time.time()) - signature_expiration_offset

signatureExpired = int(pomelo_timestamp) < now
signaturesMatch = hmac.compare_digest(signature, pomelo_signature)
endpointsMatch = client_api_endpoint in client_req_endpoint

requestIsValid = not signatureExpired and signaturesMatch


################ Results ###################
############################################

print('pomelo' signature = {0}'.format(base64.b64encode(pomelo_signature)))
print('client's signature = {0}'.format(base64.b64encode(signature)))
print('signature expired = {0}'.format(signatureExpired))
print('signatures match = {0}'.format(signaturesMatch))
print('endpoints match = {0}'.format(endpointsMatch))
print('request is valid = {0}'.format(requestIsValid))

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

Durante el flujo online

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:

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.

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

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

• https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started-client-side-ssl-authentication.html
• https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html
• https://cloud.google.com/load-balancing/docs/ssl-certificates/google-managed-certs

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

• Ambiente de Producción:

34.206.159.176            
52.0.20.124

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.

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.

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.

Veamos un curl de ejemplo indicando cómo se envía esta información dentro del request:

curl --location --request POST 'localhost:9090/shipping/updates' \
--header 'x-api-key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=' \
--header 'x-signature: hmac-sha256 kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=' \
--header 'x-timestamp: 1637117179' \
--header 'x-endpoint: {clientPath}/shipping/updates'
--header 'Content-Type: application/json' \
--data-raw '{
    'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
    'meta' : {
        'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
    }
}'

Para el armado de la firma se puede utilizar el siguiente snippet de código (en python 3) como ejemplo:

import hmac, hashlib, base64, time

############# Pomelo's side ################
############################################

# pomelo's secret key
pomelo_secret_key = base64.b64decode('kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=')

# the update data pomelo is gonna use to make the signature
pomelo_update_body = '{
    'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
    'meta' : {
        'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
    }
}'
client_req_endpoint = '/shipping/updates'
pomelo_timestamp = str(int(time.time()))

# the request data signed out by pomelo
pomelo_signature = hmac.new(pomelo_secret_key, bytes(pomelo_timestamp + client_req_endpoint + pomelo_update_body, 'utf-8'), hashlib.sha256).digest()


############# Client's side ################
############################################

# client's secret key
client_secret_key = base64.b64decode('kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=')

# client's api endpoint
client_api_endpoint = '/transactions/authorizations'

# signature expiration offset
signature_expiration_offset = 60 #A minute of expiration

# the authorizacion data the client needs to use to recreate the signature
client_request_data = bytes(pomelo_timestamp + client_req_endpoint + pomelo_update_body, 'utf-8')

# the signature the client has recreated
signature = hmac.new(client_secret_key, client_request_data, hashlib.sha256).digest()

# if signature is not expired and they match you can trust the request, otherwise reject it
now = int(time.time()) - signature_expiration_offset

signatureExpired = int(pomelo_timestamp) < now
signaturesMatch = hmac.compare_digest(signature, pomelo_signature)
endpointsMatch = client_api_endpoint in client_req_endpoint

requestIsValid = not signatureExpired and signaturesMatch


################ Results ###################
############################################

print('pomelo' signature = {0}'.format(base64.b64encode(pomelo_signature)))
print('client's signature = {0}'.format(base64.b64encode(signature)))
print('signature expired = {0}'.format(signatureExpired))
print('signatures match = {0}'.format(signaturesMatch))
print('endpoints match = {0}'.format(endpointsMatch))
print('request is valid = {0}'.format(requestIsValid))

Importante: deberás firmar tu body junto con el timestamp y el endpoint utilizando 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ó.

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

En un bucket de S3 que te disponibilizaremos encontrarás estos archivos:

• Archivo de transacciones
• Archivo de presentación

Contiene el detalle de cada transacción que te generamos el día anterior. El nombre del archivo tiene el siguiente formato: presentacionesyyyy_mm_dd.csv

*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.

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: presentacionesyyyy_mm_dd.csv

*_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:

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.

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

El servicio de Core te permite crear y administrar las cuentas digitales de tus usuarios.

Para tener una cuenta tus usuarios deberán:

• Estar registrados en Pomelo.
• Encontrarse en estado “Activo”.
• Tener verificada su identidad. Esta verificación solo la hacemos si contrataste nuestro producto de Identity.

Las cuentas tendrán alguno de estos estados:

• ACTIVE: La cuenta está activa y se puede usar para hacer transacciones normalmente. Cuando se crea una cuenta su estado inicial será ACTIVE.
• FROZEN: La cuenta podrá recibir dinero pero las transacciones de débito estarán bloqueadas.
• DISABLED: La cuenta no tiene permitida ninguna transacción.
• DELETED: La cuenta está eliminada sin posibilidad de volver a activarla.

Para cambiar el estado de una cuenta entre los estados ACTIVE, FREEZED y DISABLED deberás usar el endpoint PATCH de este servicio.

Para cambiar el estado de una cuenta a DELETED usa el endpoint DELETE.

Si falla alguna operación, devolveremos un error con una lista de las posibles operaciones asociadas:

• ACCOUNT_VALIDATION_ERROR: No se pudo validar correctamente la cuenta. Por ejemplo, cuando la key de idempotencia utilizada en la request, ya está en uso por otro usuario.
  • CREATE
• USER_VALIDATION_ERROR: No pudimos validar la identidad del usuario o el usuario no existe.
  • CREATE
• CLIENT_VALIDATION_ERROR: No pudimos identificar a qué cliente pertenece el usuario al que estás intentando crearle una cuenta.
  • CREATE
• USER_ACCOUNT_LIMIT_REACHED: El usuario alcanzó el límite de cuentas que puede tener y por eso no es posible crearle una nueva.
  • CREATE
• ACCOUNT_NOT_FOUND: El ID de cuenta no existe.
  • UPDATE
  • DELETE
• ACCOUNT_DELETED: El ID de cuenta fue eliminado.
  • UPDATE
  • DELETE
• INVALID_ACCOUNT_STATUS: El estado de actualización de la cuenta es inválido.
  • UPDATE
  • DELETE
• LOCKED_ACCOUNT_STATUS: No es posible actualizar una cuenta que modificamos nosotros desde Pomelo.
  • UPDATE
  • DELETE
• INVALID_UPDATE_STATUS_MOTIVE: El motivo de actualización del estado de la cuenta que ingresaste es inválido. Para DELETE los motivos válidos son OTHER, INTERNAL_REASON, USER_REQUEST y FRAUD. Para DISABLED son OTHER, LOST, INTERNAL_REASON, STOLEN, FRAUD y INHIBITION. Para FROZEN son OTHER y SEIZURE
  • UPDATE
  • DELETE
• ACCOUNT_HAS_FUNDS: No es posible eliminar una cuenta que no está completamente vacía.
  • DELETE

Accounts Query API es un servicio que agrupa toda la información de las cuentas digitales de Pomelo y la disponibiliza para que puedas consultarla.

Te permitirá consultar:

• La información de las cuentas. Esta información incluye los identificadores bancarios como CVU y alias para Argentina o PIX para Brasil.
• El balance de cada cuenta.
• Las actividades de todas tus cuentas.

Es cualquier operación que tuvo la intención de modificar el balance de una cuenta. Es decir:

• Transacciones concretadas que modificaron el balance de una cuenta.
• Transacciones que fueron procesadas pero rechazadas. Por ejemplo transacciones de débito que no se pudieron procesar
• Transacciones no procesadas porque no cumplen con algún requisito. Por ejemplo, intentos de pagos con tarjeta que no

• Listar cuentas con sus respectivos balances.
• Obtener información y balance de una cuenta.
• Listar actividades de todas las cuentas.
• Listar actividades de una cuenta.
• Obtener información de una actividad.

Este servicio te permite autorizar transacciones.

Las transacciones solo tienen dos estados posibles:

• APPROVED: Si la transacción es aprobada.
• REJETED: Si la transacción es rechazada.

Todas las transacciones que son aprobadas modificarán el balance de la cuenta por el monto especificado.

Todos los montos de las transacciones están expresados en la moneda de la cuenta y con signo positivo. Para distinguir si la intención de la transacción es ingresar o retirar dinero de una cuenta utiliza el parámetro entry_type. Este parámetro puede tomar estos valores:

• DEBIT: Para transacciones que quieran retirar dinero de la cuenta.
• CREDIT: Para transacciones que quieran ingresar dinero a la cuenta.

Todas las transacciones tienen un tipo, que indicamos con el parámetro type. Cada tipo de transacción tiene distintos datos que se envían con la transacción dentro del objeto tx_properties.

Podrás solicitar datos extras de todas las transacciones usando el objeto metadata.

La propiedad details se puede usar para descomponer el monto total de una transacción en las partes que lo componen. Por ejemplo supongamos que se está procesando una transacción que representa una compra en una tienda digital por un total de $149,99. Supongamos además, que este total se compone por:

• $119,00 de la compra.
• $40,00 de impuestos.
• -$10,00 de descuentos.

Esta descomposición se puede informar agregando multiples items a la lista details. Cada detalle debe tener un tipo asociado:

• BASE: Gasto base de la transacción.
• FEE: Gastos de comisión.
• TAX: Impuestos.
• EXTRACASH: Extracciones de dinero.
• DISCOUNT: Descuentos.

Es posible agregar más de un detalle con el mismo tipo. La única restricción es que la sumatoria de los montos de los detalles sea igual al monto total de la transacción.

Cada transacción lleva un campo process_type que puede tomar alguno de estos valores:

• ORIGINAL: Transacción nueva.
• ADJUSTMENT: Ajuste.
• REFUND: Reintegro o devolución.
• REVERSAL: Reversa.

Para las transacciones que sean REFUND o REVERSAL se puede especificar la transacción originaria que las motiva. Esa transacción se conoce como “transacción padre” y la indicamos mediante el campo parent_tx_id.

Los pedidos de autorización de transacciones tienen un mecanismo de idempotencia para prevenir el procesamiento duplicado.

Deberás acompañar cada request de autorización con un header X-Idempotency-Key que tenga un identificador único para la transacción a procesar. En caso de que no obtengas respuesta o recibas una respuesta con status code del tipo 5xx, deberás volver a repetir el request con la misma key de idempotencia hasta obtener una respuesta exitosa (code 201).

Los requests repetidos que utilicen la misma key de idempotencia solo tendrán como resultado la creación de una transacción. El primer request creará la transacción y los siguientes devolverán la misma respuesta que se devolvió para el primer request, pero no crearán una transacción nueva.

Si un pedido de autorización tiene una key de idempotencia que ya usaste en otra transacción, responderemos con un error.

Las transacciones que procesamos correctamente se informan con un status code 201. Pero atención: este estado no indica si la transacción fue aprobada. Para saber eso, tendrás que leer el campo 'result' de la respuesta e identificar si su valor es APPROVED o REJECTED.

Cualquier otro status code indica que algo salió mal y te indicaremos el motivo de rechazo en el campo rejection_reason. Este campo puede tomar los siguientes valores:

• INSUFFICIENT_FUNDS: La cuenta no tiene fondos suficientes.
• ACCOUNT_DISABLED: La cuenta está deshabilitada.
• ACCOUNT_FROZEN: La cuenta no puede procesar transacciones de débito (DEBIT).
• CLIENT_MONTHLY_AMOUNT_LIMIT_REACHED: Superó el límite de movimientos mensual que tenía
• CLIENT_DAILY_AMOUNT_LIMIT_REACHED: Superó el límite de movimientos diarios que tenía.
• PROCESS_TIME_EXPIRED: La transacción no comenzó a procesarse antes del tiempo indicado por el campo process_before, que es opcional.

Cuando no podemos procesar una transacción devolveremos una respuesta de error con el campo error_code indicando el motivo:

• ACCOUNT_NOT_FOUND: No encontramos la cuenta.
• INVALID_AUTHORIZATION_REQUEST: El request para autorizar la transacción no es válido.
• INVALID_PARENT_TX_ID: La transacción padre que especificaste es inválida.
• DUPLICATED_IDEMPOTENCY_KEY: Ya usaste la key de idempotencia en otra transacción.