Autorización

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

Utilización del token

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.

Solicitar Token

El endpoint /oauth/token se usa para obtener un token de acceso. Al realizar una autenticación exitosa, guárdalo ya que lo necesitarás para comunicarte con nuestras APIs.

Cada token es un JWT que contiene un tiempo de expiración. Deberás solicitar un nuevo token únicamente cuando el que tengas haya expirado.

Parámetros disponibles
Header Parameters
content-typestringrequired
Enum: application/json
Body Parameters
client_idstringrequired
client_secretstringrequired
audiencestringrequired
Audiencia de API
grant_typestringrequired
Enum: client_credentials
Detalle de respuestas
access_tokenstring
Ejemplo: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IloyTmZOUTQwWVVrNXh0WnNRRDlHYSJ9.eyJodHRwczovL3BvbWVsby5sYS9jbGllbnRfaWQiOiIyZmYxMjM0MTY3MzRmMjI5MmUxMTE0ODdiZWRlZmMxZTI1NDkxY2E4YzI1ZTEyMjAzM2E5MGE3NjM2ZDllNDI0IiwiaXNzIjoiaHR0cHM6Ly9wb21lbG8tZGV2ZWxvcC51cy5hdXRoMC5jb20vIiwic3ViIjoiMWNxdXBVM0U0bFpIY2U2ZFdVbHpuU29nZU1rR3ozelFAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vYXV0aC1kZXYucG9tZWxvLmxhIiwiaWF0IjoxNjMxMDM1MDQzLCJleHAiOjE2MzExMjE0NDMsImF6cCI6IjFjcXVwVTNFNGxaSGNlNmRXVWx6blNvZ2VNa0d6M3pRIiwic2NvcGUiOiJhcmc6Y2FyZHM6Z2V0LWNhcmQgYXJnOmNhcmRzOmdldC11c2VyLWNhcmQgYXJnOmNhcmRzOmNyZWF0ZS1iYXRjaCBhcmc6Y2FyZHM6YWN0aXZhdGUtY2FyZCBhcmc6Y2FyZHM6Y3JlYXRlLWNhcmQgYXJnOmNhcmRzOmNyZWF0ZS1jYXJkIGFyZzpjYXJkczp1cGRhdGUtYnVsay1jYXJkcyBhcmc6Y2FyZHM6c2VhcmNoLWNhcmQgYXJnOnVzZXJzOmdldC11c2VyIGFyZzp1c2VyczpjcmVhdGUtdXNlciBhcmc6dXNlcnM6c2VhcmNoLXVzZXIgYXJnOnVzZXJzOnVwZGF0ZS11c2VyIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.DkNi4BtLVdq1YMN5UFrtqvm2p-3DExt1X90janSfRWLbZHo2dtPtXkGfRF9kpdD3ZDA98euB68pt5nxZAGThaqm5g59pKkRz0nFzsDGUCH-Mfd6vYKGksO-dlyTeOwHyF189zYSvOMHcdaEOY2QybCWheOQnUgpFB7WaIPk6M8ZWI9SHSPtUjt6ePY7jsvDmVTtpXQM3ttB-0OarKN0qPi-A7WeD13Q7FuZHgQBxMipMlxeOfsz-RDOMwX7zTBhVNFp-Eu1Jtx1vFHVhDbG7tDW5N2np7kZvYXS5-wSP-fZMc57I1NmXrjbCACMWFhsnqTuHRJiHn3l-kG6nb7_EIw
scopestring
Ejemplo: arg:cards:get-card arg:cards:get-user-card
expires_ininteger
Ejemplo: 86400
token_typestring
Ejemplo: Bearer
¿Te resultó útil esta sección?
POST/oauth/token
{
"client_id":
"3LBFuOiEHrl4BailkRlsnIMmSctMLb7A"
"client_secret":
"s5u3oYK0-A9CV6TkszPQThUa_qxMfr2yyd3-eJwQ ..."
"audience":
"https://auth-dev.pomelo.la"
"grant_type":
"client_credentials"
}
Ejemplo de respuestas

Usuarios

La API de Usuarios contiene todos los endpoints necesarios para administrar las bases de usuarios. Podrás usarla para crear, actualizar o incluso buscar usuarios bajo determinados parámetros.

Crear Usuario

El endpoint /users/v1/ te permite crear un nuevo usuario en nuestra base de datos.

La cantidad de parámetros requeridos para crear un usuario varía dependiendo del producto que hayas contratado, pero siempre te pediremos email y operation_country.

Consideraciones sobre usuarios repetidos

Cada usuario debe tener un email único, También debe ser única la combinación de tipo de documento de identidad y valor.

Consideraciones sobre los documentos de identidad a utilizar

Para Argentina

Los tipos de documento de identidad aceptados son los siguientes:

  • DNI
  • LE
  • LC
  • CI
  • PASSPORT

En el caso del DNI, validaremos que su extensión sea de 7 u 8 caracteres.

El tipo de documento fiscal aceptado es el CUIL.

Para Brasil

Los tipos de documento de identidad aceptados son los siguientes:

  • RG
  • CNH

El tipo de documento fiscal aceptado es el CPF. Validaremos que su extensión sea de 11 caracteres.

Para México

Los tipos de documento de identidad aceptados son los siguientes:

  • INE
  • PASSPORT

El tipo de documento fiscal aceptado es el RFC, pero no será obligatorio incluirlo.

Para Argentina

Si operas en Argentina, el domicilio legal del usuario tendrá que ser de alguna de estas provincias:

  • Buenos Aires
  • Catamarca
  • Chaco
  • Chubut
  • Ciudad Autónoma de Buenos Aires
  • Corrientes
  • Córdoba
  • Entre Ríos
  • Formosa
  • Jujuy
  • La Pampa
  • La Rioja
  • Mendoza
  • Misiones
  • Neuquén
  • Río Negro
  • Salta
  • San Juan
  • San Luis
  • Santa Cruz
  • Santa Fe
  • Santiago del Estero
  • Tierra del Fuego
  • Tucumán

Para Brasil

Si operas en Brasil, deberás completar el campo zipcode con un dato válido, ya que lo usaremos para determinar la dirección legal del usuario.

Para México

En caso que el país de operatoria sea México, no existe ningún requisito especial respecto a los campos de dirección legal del usuario.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID único en cada request para utilizar nuestro esquema de idempotencia.
Ejemplo: fRwX12Dg3345AD
Body Parameters
namestring
Ejemplo: Diego
surnamestring
Ejemplo: Pomelo
identification_typestring
Enum: DNILELCCIPASSPORT
identification_valuestring
Ejemplo: 42345678
birthdatestring
ISO 8601
Ejemplo: 1998-08-20
genderstring
Ejemplo: MALE
emailstringrequired
phonestring
Ejemplo: 1123456789
tax_identification_typestring
Ejemplo: CUIL
Enum: CUIL
tax_identification_valuestring
Ejemplo: 20423456789
legal_addressobject
operation_countrystringrequired
ISO 3166 alpha-3
Ejemplo: ARG
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
POST/users/v1/
{
"name":
"Diego"
"surname":
"Pomelo"
"identification_type":
"DNI"
"identification_value":
42345678
"birthdate":
"1998-08-20"
"gender":
"MALE"
"phone":
"1123456789"
"tax_identification_type":
"CUIL"
"tax_identification_value":
20423456789
"legal_address":{
"street_name":
"Av. Corrientes"
"street_number":
300
"floor":
1
"apartment":
"A"
"zip_code":
1414
"neighborhood":
"Villa Crespo"
"city":
"CABA"
"region":
"Buenos Aires"
"additional_info":
"Torre 2"
"country":
"ARG"
}
"operation_country":
"ARG"
}
Ejemplo de respuestas

Buscar Usuarios

El endpoint /users/v1/ te permite buscar un grupo de usuarios y recibir una lista ordenada en base a los parámetros especificados.

Consideraciones

Tendrás que especificar tus filtros como parámetros siguiendo este patrón: filter[campo]=valor. Por ejemplo: /users/v1/?filter[status]=ACTIVE Para filtrar un atributo con varios valores posibles, deberás separar los valores con comas. Veamos un ejemplo: filter[status]=ACTIVE,BLOCKED

Los resultados serán paginados y podrás especificar la cantidad de datos por página y también qué página ver utilizando: page[number]=valor y page[size]=valor

Ordenamiento

Podrás especificar el orden de los resultados con determinados parámetros que deberás enviar como una lista de strings en el filtro de tipo sort. Por ejemplo: ?filter[status]=ACTIVE&sort=status,gender

El ordenamiento por defecto será ascendente. Para especificar un orden descendente, deberás enviar el carácter '-' como prefijo del atributo. Por ejemplo: /users/v1/?filter[status]=ACTIVE&sort=status,-gender

Los posibles atributos para ordenar son:

  • id
  • gender
  • identification_type
  • identification_value
  • status

Si un parámetro es incorrecto o está mal escrito, responderemos con un error.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
filter[identification_value]string
filter[identification_type]string
Enum: DNILELCCIPASSPORTRGCNHINE
filter[gender]string
Enum: MALEFEMALE
filter[birthdate]string
ISO 8601
Ejemplo: 1998-08-20
filter[name]string
Ejemplo: Juan
filter[surname]string
Ejemplo: Rodriguez
filter[email]string
filter[status]string
filter[country_code]string
ISO 3166-1 alpha-3
page[size]number
Tamaño de página.
page[number]number
Número de página. El número de la primer página es 0.
sortstring
Ejemplo: id,-name
Detalle de respuestas
dataarray
metaobject
¿Te resultó útil esta sección?
GET/users/v1/
Ejemplo de respuestas

Obtener Usuario

El endpoint de /users/v1/{id} te permite consultar la información de un usuario a través de su id.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
idstringrequired
Id de usuario
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
GET/users/v1/{id}
Ejemplo de respuestas

Modificar Usuario

El endpoint /users/v1/{id} permite actualizar la información de un usuario a través de su id.

Consideraciones

Para bloquear un usuario deberás enviar el status con el valor BLOCKED y el valor CLIENT_INTERNAL_REASON en el campo status_reason.

Para reactivar un usuario que bloqueaste, deberás enviar status con valor ACTIVE.

Consideraciones sobre usuarios repetidos

Cada usuario debe tener un email único. También debe ser única la combinación de tipo de documento de identidad y valor.

Consideraciones sobre los documentos de identidad a utilizar

Para Argentina

Los tipos de documento de identidad aceptados son los siguientes:

  • DNI
  • LE
  • LC
  • CI
  • PASSPORT

En el caso del DNI, validaremos que su extensión sea de 7 u 8 caracteres.

El tipo de documento fiscal aceptado es el CUIL.

Para Brasil

Los tipos de documento de identidad aceptados son los siguientes:

  • RG
  • CNH

El tipo de documento fiscal aceptado es el CPF. Validaremos que su extensión sea de 11 caracteres.

Para México

Los tipos de documento de identidad aceptados son los siguientes:

  • INE
  • PASSPORT

El tipo de documento fiscal aceptado es el RFC, pero no será obligatorio incluirlo.

Para Argentina

Si operas en Argentina, el domicilio legal del usuario tendrá que ser de alguna de estas provincias:

  • Buenos Aires
  • Catamarca
  • Chaco
  • Chubut
  • Ciudad Autónoma de Buenos Aires
  • Corrientes
  • Córdoba
  • Entre Ríos
  • Formosa
  • Jujuy
  • La Pampa
  • La Rioja
  • Mendoza
  • Misiones
  • Neuquén
  • Río Negro
  • Salta
  • San Juan
  • San Luis
  • Santa Cruz
  • Santa Fe
  • Santiago del Estero
  • Tierra del Fuego
  • Tucumán

Para Brasil

Si operas en Brasil, deberás completar el campo zipcode con un dato válido, ya que lo usaremos para determinar la dirección legal del usuario.

Para México

En caso que el país de operatoria sea México, no existe ningún requisito especial respecto a los campos de dirección legal del usuario.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
namestring
Ejemplo: Diego
surnamestring
Ejemplo: Pomelo
identification_typestring
Enum: DNILELCCIPASSPORT
identification_valuestring
Ejemplo: 42345678
birthdatestring
ISO 8601
Ejemplo: 1998-08-20
genderstring
Ejemplo: MALE
emailstring
phonestring
Ejemplo: 1123456789
tax_identification_typestring
Ejemplo: CUIL
Enum: CUIL
tax_identification_valuestring
Ejemplo: 20423456789
statusstring
Enum: ACTIVEBLOCKED
status_reasonstring
Enum: CLIENT_INTERNAL_REASON
legal_addressobject
Path Parameters
idstringrequired
Id de usuario
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
PATCH/users/v1/{id}
{
"name":
"Diego"
"surname":
"Pomelo"
"identification_type":
"DNI"
"identification_value":
42345678
"birthdate":
"1998-08-20"
"gender":
"MALE"
"phone":
"1123456789"
"tax_identification_type":
"CUIL"
"tax_identification_value":
20423456789
"status":
"ACTIVE"
"status_reason":
"CLIENT_INTERNAL_REASON"
"legal_address":{
"street_name":
"Av. Corrientes"
"street_number":
300
"floor":
1
"apartment":
"A"
"zip_code":
1414
"neighborhood":
"Villa Crespo"
"city":
"CABA"
"region":
"Buenos Aires"
"additional_info":
"Torre 2"
"country":
"ARG"
}
}
Ejemplo de respuestas

Tarjetas

La API de Cards contiene todos los endpoints necesarios para crear tarjetas nominadas e innominadas, activarlas, hacer búsquedas, obtener la información de una tarjeta en particular y más.

Obtener Tarjeta

El endpoint /cards/v1/{id} te permite obtener información sobre una tarjeta en particular.

Consideraciones

El parámetro extend se usa para obtener datos adicionales de una tarjeta.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
extendstring
Permite obtener información adicional como el pan y cvc, que no están incluidos por defecto en la respuesta.
Enum: pancvvnameexpiration_date
Path Parameters
idstringrequired
Id público de la tarjeta
Detalle de respuestas
dataobject
metaobject
¿Te resultó útil esta sección?
GET/cards/v1/{id}
Ejemplo de respuestas

Actualizar Tarjeta

El endpoint /cards/v1/{id} te permite actualizar el estado de una tarjeta, su grupo de afinidad y el PIN.

Consideraciones

Deberás especificar una razón del siguiente listado para poder actualizar el estado de una tarjeta:

Nuevo estadoRazón válida
BLOCKED / DISABLEDCLIENT_INTERNAL_REASON
BLOCKED / DISABLEDUSER_INTERNAL_REASON
DISABLEDFRAUDULENT
DISABLEDLOST
DISABLEDSTOLEN
DISABLEDBROKEN
DISABLEDUPGRADE
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
affinity_group_idstring
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
statusstring
Enum: ACTIVEBLOCKEDDISABLED
status_reasonstring
Enum: CLIENT_INTERNAL_REASONUSER_INTERNAL_REASONPOMELO_INTERNAL_REASONFRAUDULENTLOSTSTOLENBROKENUPGRADE
pinstring
Ejemplo: 1234
Path Parameters
idstringrequired
Id público de la tarjeta
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
PATCH/cards/v1/{id}
{
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"status":
"ACTIVE"
"status_reason":
"CLIENT_INTERNAL_REASON"
"pin":
"1234"
}
Ejemplo de respuestas

Actualizar Envío de Tarjeta

El endpoint /cards/v1/{id}/shipment te permite actualizar el domicilio de envío de una tarjeta.

Consideraciones

La tarjeta deberá ser física nominada y tener estado CREATED.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
addressobject
Path Parameters
idstringrequired
Id público de la tarjeta
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
PUT/cards/v1/{id}/shipment
{
"address":{
"street_name":
"Street"
"street_number":
"123"
"floor":
"5"
"apartment":
"A"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5653"
"neighborhood":
"Palermo"
}
}
Ejemplo de respuestas

Buscar Tarjetas

El endpoint /cards/v1/ te permite buscar un grupo de tarjetas según los atributos que especifiques.

Consideraciones

Tendrás que especificar tus filtros como parámetros siguiendo este patrón: filter[campo]=valor. Por ejemplo: filter[status]=CREATED. Para filtrar un atributo con varios valores posibles, deberás separar los valores con comas. Veamos un ejemplo: filter[status]=CREATED,ACTIVE

Los resultados serán paginados y podrás especificar la cantidad de datos por página y también qué página ver utilizando: page[number]=valor y page[size]=valor

Ordenamiento

Podrás especificar el orden de los resultados con determinados parámetros que deberás enviar como una lista de strings en el filtro de tipo sort. Por ejemplo: /cards/v1/?sort=status,card_type.

El ordenamiento por defecto será ascendente. Para especificar un orden descendente, deberás enviar el carácter '-' como prefijo del atributo. Por ejemplo: /cards/v1/?sort=status,-card_type.

Los atributos para ordenar son:

  • card_type
  • user_id
  • status
  • affinity_group_id
  • status_detail
  • shipment_id
  • innominate.

Si un parámetro es incorrecto o está mal escrito, responderemos con un error.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
filter[card_type]string
Enum: VIRTUALPHYSICAL
filter[user_id]string
filter[status]string
filter[status_detail]string
Enum: CLIENT_INTERNAL_REASONUSER_INTERNAL_REASONPOMELO_INTERNAL_REASONFRAUDULENTLOSTSTOLENBROKENUPGRADE
filter[affinity_group_id]string
filter[shipment_id]string
filter[innominate]boolean
filter[product_type]string
Enum: PREPAIDCREDITDEBIT
filter[product_brand]string
Enum: MASTERCARDVISA
filter[country_code]string
ISO 3166-1 alpha-3
page[size]number
Tamaño de página.
page[number]number
Número de página. El número de la primer página es 0.
sortstring
Ejemplo: status,-card_type
Detalle de respuestas
dataarray
metaobject
¿Te resultó útil esta sección?
GET/cards/v1/
Ejemplo de respuestas

Crear Tarjeta

El endpoint /cards/v1/ permite crear una nueva tarjeta nominada que puede ser física o virtual.

Consideraciones

Para crear una nueva tarjeta física, deberás especificar el domicilio de envío.

Podrás usar el parámetro previous_card_id, para especificar que una tarjeta es reemplazo de una anterior.

Para asegurar que una solicitud no se ejecute más de una vez te pediremos que envíes el header: x-idempotency-key con un ID único para usar nuestro esquema de idempotencia. Si dos solicitudes tienen el header con el mismo ID, solo crearemos una tarjeta y las dos solicitudes tendrán la misma respuesta positiva

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID único en cada request para usar nuestro esquema de idempotencia.
Ejemplo: fRwX12Dg3345AD
Body Parameters
user_idstringrequired
Ejemplo: usr-1625758043579BAR6D4
affinity_group_idstringrequired
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
card_typestringrequired
Ejemplo: PHYSICAL
addressobject
previous_card_idstring
Si envías este atributo, trataremos la nueva tarjeta como un reemplazo de esta.
Ejemplo: crd-20gRqyp809SvDzXzhSeG2w6UiO5
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
POST/cards/v1/
{
"user_id":
"usr-1625758043579BAR6D4"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"card_type":
"PHYSICAL"
"address":{
"street_name":
"Street"
"street_number":
"123"
"floor":
"5"
"apartment":
"A"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5653"
"neighborhood":
"Palermo"
}
"previous_card_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
}
Ejemplo de respuestas

Crear Lote de Tarjetas Innominadas

El endpoint /cards/v1/batches te permite crear un lote de tarjetas innominadas.

Consideraciones

Un lote puede tener un máximo de 1000 tarjetas.

La dirección de envío es obligatoria si el tipo de distribución es CLIENT.

Procesaremos la llamada de forma asincrónica, es decir que es posible que las tarjetas no estén disponibles inmediatamente.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
affinity_group_idstringrequired
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
quantitynumber(minimum: 1, maximum: 1000)required
Ejemplo: 100
distribution_typestringrequired
Enum: CLIENTWAREHOUSE
addressobject
Address es obligatorio cuando la distribución es de tipo CLIENT
receiverobject
Receiver es obligatorio cuando la distribución es de tipo CLIENT.
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
POST/cards/v1/batches
{
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"quantity":
100
"distribution_type":
"CLIENT"
"address":{
"street_name":
"Street"
"street_number":
"123"
"floor":
"5"
"apartment":
"A"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5653"
"neighborhood":
"Palermo"
}
"receiver":{
"full_name":
"Gonzalo Iglesias"
"document_type":
"enum - DNI - LE - LC - CI - PASSPORT - I ..."
"document_number":
"35354896"
"telephone_number":
"1132421452"
}
}
Ejemplo de respuestas

Actualizar Envío de un lote de tarjetas

El endpoint /cards/v1/batches/shipments/{shipmentId} te permite actualizar el domicilio de envío de un lote de tarjetas.

Consideraciones

El lote de tarjetas deberá ser física innominada y tener estado CREATED.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
addressobject
receiverobject
Path Parameters
shipmentIdstringrequired
Id público del envío
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
PUT/cards/v1/batches/shipments/{shipmentId}
{
"address":{
"street_name":
"Street"
"street_number":
"123"
"floor":
"5"
"apartment":
"A"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5653"
"neighborhood":
"Palermo"
}
"receiver":{
"full_name":
"Gonzalo Iglesias"
"document_type":
"enum - DNI - LE - LC - CI - PASSPORT - I ..."
"document_number":
"35354896"
"telephone_number":
"1132421452"
}
}
Ejemplo de respuestas

Activar Tarjeta

El endpoint /cards/v1/activation te permite activar una tarjeta física y también configurar un PIN.

Consideraciones

El usuario deberá estar activo y la tarjeta deberá tener estado EMBOSSED.

El PIN a configurar:

  • Debe ser de 4 dígitos
  • No puede ser una secuencia ascendente. Por ejemplo: 1234
  • No puede ser una secuencia descendente. Por ejemplo: 4321
  • No puede ser una repetición de números. Por ejemplo: 1111

Podrás usar el parámetro previous_card_id, para especificar que una tarjeta es reemplazo de una anterior.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
user_idstringrequired
Id público del tarjetahabiente
Ejemplo: usr-1625758043579BAR6D4
panstringrequired
El PAN de la tarjeta que está siendo activada
Ejemplo: 4242424242424242
pinstringrequired
Nuevo PIN de la tarjeta elegido por el usuario
Ejemplo: 1234
previous_card_idstring
Si envías este atributo, trataremos la nueva tarjeta como un reemplazo de esta.
Ejemplo: crd-20gRqyp809SvDzXzhSeG2w6UiO5
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
POST/cards/v1/activation
{
"user_id":
"usr-1625758043579BAR6D4"
"pan":
"4242424242424242"
"pin":
"1234"
"previous_card_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
}
Ejemplo de respuestas

Envíos

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.

WebHooks

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

Consideraciones

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'
    }
}'

Seguridad

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.

Firma hmac-sha256 del pedido

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.

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=
  1. Creas tu clave pública-privada:
$ openssl genrsa -out private.pem 2048
$ openssl rsa -in private.pem -pubout -out public.pem
  1. Nos envías tu clave pública public.pem por email o Slack.

  2. 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
  1. Enviamos el archivo api-credentials.txt.enc por email o Slack

  2. 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=
  1. 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 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))

Crear Envío

El endpoint /shipping/v1/ se usa para crear un nuevo envío.

Para Brasil

Si operas en Brasil, deberás completar el campo region con el código UF de dos carácteres. Ejemplo: 'SP' para São Paulo Ver códigos UF

Para Brasil el taxIdentificationNumber es obligatorio.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID único en cada request para usar nuestro esquema de idempotencia.
Ejemplo: fRwX12Dg3345AD
Body Parameters
shipment_typestringrequired
Enum: CARD_FROM_WAREHOUSE
affinity_group_idstringrequired
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
countrystringrequired
Ejemplo: ARG
addressobject
receiverobject
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
POST/shipping/v1/
{
"shipment_type":
"CARD_FROM_WAREHOUSE"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"country":
"ARG"
"address":{
"street_name":
"Libertador"
"street_number":
"539"
"floor":
"2"
"apartment":
"B"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5346"
"neighborhood":
"string"
}
"receiver":{
"full_name":
"Gonzalo Iglesias"
"document_type":
"dni"
"document_number":
"243432423"
"tax_identification_number":
"38912151888"
"telephone_number":
"53454342"
}
}
Ejemplo de respuestas

Buscar Envios

El endpoint /shippining/v1/ te permite buscar un grupo de envios según los atributos que especifiques.

Consideraciones

Tendrás que especificar tus filtros como parámetros siguiendo este patrón: filter[campo]=valor. Por ejemplo: filter[shipment_type]=BOX. Para filtrar un atributo con varios posibles valores, deberás separar los valores por coma. Veamos un ejemplo: filter[shipment_type]=BOX,WAREHOUSE

Los resultados serán paginados y podrás especificar la cantidad de datos por página y también qué página ver utilizando: page[1] y page[2]

Ordenamiento

Podrás especificar el orden de los resultados con determinados parámetros que deberás enviar como una lista de strings en el filtro de tipo sort. Por ejemplo: /shipping/v1/?sort=status,shipment_type.

El ordenamiento por defecto será ascendente. Para especificar un orden descendente, deberás enviar el carácter '-' como prefijo del atributo. Por ejemplo: /shipping/v1/?sort=status,-shipment_type.

Los atributos para ordenar son:

  • shipment_type
  • status
  • status_detail

Si un parámetro es incorrecto o está mal escrito, responderemos con un error.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
filter[shipment_type]string
Enum: SINGLE_CARDBOXCARD_FROM_WAREHOUSEWAREHOUSE_BOX
filter[batch_id]string
filter[email]string
filter[status]string
filter[batch_status]string
filter[document_number]string
filter[start_date]string
filter[end_date]string
filter[country_code]string
ISO 3166-1 alpha-3
page[size]number
Tamaño de página.
page[number]number
Número de página. El número de la primer página es 0.
sortstring
Ejemplo: pid, shipment_type, status, status_detail
Detalle de respuestas
idstring
Ejemplo: shi-23hJL4bm94q9BFEd2sGhBjY6xbH
external_tracking_idstring
Ejemplo: f923da123
statusstring
Enum: CREATEDPENDINGTRACKEDREJECTEDIN_WAREHOUSEIN_TRANSITDISTRIBUTIONDELIVEREDNOT_DELIVEREDSTART_OF_CUSTODYEND_OF_CUSTODYDESTRUCTIONACCIDENT
status_detailstring
Ejemplo: IN_TRANSIT
shipment_typestring
Enum: SINGLE_CARDBOXWAREHOUSE_BOXCARD_FROM_WAREHOUSEEXTERNAL_SINGLE_CARDEXTERNAL_BOX
affinity_group_idstring
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
created_atstring
Ejemplo: 2020-07-10 15:00:00.000
batchobject
addressobject
receiverobject
¿Te resultó útil esta sección?
GET/shipping/v1/
Ejemplo de respuestas

Obtener Envío

El endpoint /shipping/v1/{shipment_id} te permite obtener información sobre un envío en particular.

Consideraciones

Deberás especificar el shipment_id para hacer la consulta.

Envíos hacia un warehouse y en territorio mexicano:

Para los envíos hacia un warehouse y también para los que se realizan en México, no devolveremos un ID externo de seguimiento, ¡pero descuida! Te mantendremos informado sobre el estado del envío desde el Dashboard y también vía webhooks.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
shipment_idstringrequired
Id del envío
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
GET/shipping/v1/{shipment_id}
Ejemplo de respuestas

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:

Flujo Online / Offline

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.

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
  • Ambiente de Producción:
34.206.159.176            
52.0.20.124

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.

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

Liquidación

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

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

Estructura del archivo de transacciones

{Atributo}DescripciónValores permitidos
TRANSACTION_IDEl id que permite identificar la transacción como única.
LOCAL_TRANSACTION_DATE_TIME
TRANSACTION_TYPEIndica el tipo de transacción.PURCHASE
WITHDRAWAL
EXTRACASH
REFUND
PAYMENT
REVERSAL_PURCHASE
REVERSAL_WITHDRAWAL
REVERSAL_EXTRACASH
REVERSAL_REFUND
REVERSAL_PAYMENT
PRODUCT_TYPEEs el tipo de productoPREPAID
CREDIT
DEBIT
PROVIDEREs la marca de la tarjeta emitida.VISA
MASTERCARD
AFFINITY_GROUP_ID
USER_IDEl id del usuario de Pomelo titular de la tarjeta.
CARD_ID
BINLos primeros seis u ocho dígitos del PAN.
LAST_FOURLos últimos cuatro dígitos del PAN.
ORIGINDOMESTIC: 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_MCCEl código de categoría de comerciante según se define en el ISO-18245.
MERCHANT_NAME
LOCAL_AMOUNTEs 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_CURRENCYEl código de la moneda de LOCAL_TOTAL en ISO_4217 formato ALPHA-3.
TRANSACTION_AMOUNTEl monto de la transacción sin impuestos y en la moneda original enviada por el comerciante.
TRANSACTION_CURRENCYEl código de la moneda de TRANSACTION_TOTAL en ISO_4217 formato ALPHA-3.
SETTLEMENT_AMOUNTEl monto de la transacción en USD según lo enviado por la red. Las transacciones nacionales también tendrán este campo en USD.
SETTLEMENT_CURRENCYEl código de la moneda de SETTLEMENT_TOTAL en ISO_4217 formato ALPHA-3, siempre es USD.
ENTRY_MODEEl modo en que se usó la tarjeta en el punto de venta del comerciante.UNKNOWN
MANUAL
CHIP
CONTACTLESS
CREDENTIAL_ON_FILE
MAG_STRIPE
OTHERS
STATUSEl estado de la transacción.APPROVED
REJECTED
HELD
STATUS_DETAILRazón adicional por la que la transacción se aprueba o rechaza.Ver tabla a continuación
SOURCEIndica 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_IDEste valor podría estar vacío si la transacción no está relacionada con otra.
COUNTRY_CODEEste es el código de país en formato ISO-3166.
POINT_TYPEPOS
ECOMMERCE
ATM
MOTO
CLIENT_NAMEEl 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_CODEEl coódigo de país del cliente en formato ISO-3166
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 otorgadoNO_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 detailDescripción
CARD_BLOCKEDEl estado de la tarjeta es BLOCKED.
CARD_DISABLEDEl estado de la tarjeta es DISABLED
CARD_NOT_ACTIVEEl estado de la tarjeta es EMBOSSED o CREATED
CARD_NOT_CONFIGUREDA la tarjeta le faltan configuraciones.
CARD_NOT_FOUNDNo podemos encontrar el PAN de la tarjeta.
CRYPTO_ERRORHay un error en los criptogramas (EMV).
DUPLICATE_TRANSMISSION_DETECTEDRecibimos una transacción repetida por parte de la network.
EXPIRED_CARDEl estado de la tarjeta es EXPIRED.
EXTRA_FIELDSLa mensajería de parte de la network viene con campos no esperados.
INSUFFICIENT_FUNDSEl cliente nos responda que la cuenta no tiene fondos.
INVALID_AMOUNTSe superan los límites del grupo de afinidad.
INVALID_CVVEl CVV no coincide.
INVALID_EXPIRATION_DATELa fecha de expiración recibida no coincide con la tarjeta.
INVALID_MERCHANTEl cliente rechaza al merchant por algún motivo específico.
INVALID_PINEl PIN es incorrecto
INVALID_TRANSACTIONLa transacción es inválida.
LOST_CARDEl estado de la tarjeta es LOST.
MISSING_FIELDSLa mensajería de parte de la network viene sin campos obligatorios.
NOT_DECLINEDUna transacción viene con monto en 0 para validar si la cuenta está activa.
ORIGINAL_NOT_FOUNDSe intenta hacer una reversal de una transacción que no encontramos.
OTHERNo reconocemos el caso.
RESTRICTED_USEREl estado del usuario no es ACTIVE.
SECURITY_VIOLATIONSupera un umbral de fraude.
SERVICE_UNAVAILABLEEl cliente o un servicio de Pomelo están caídos.
STOLEN_CARDEl estado de la tarjeta es STOLEN.
SYSTEM_ERRORError imprevisto en el sistema.
APPROVEDEl cliente aprueba una transacción.
TRANSACTION_NOT_PERMITTEDEl tipo de transacción no está permitido en el grupo de afinidad.

Conciliación del archivo de transacciones

¿Está en Pomelo?¿Está en el cliente?¿Tiene el mismo estado?Action
YYYNo hacer nada / Marcar como coincidente
YYN1) Registrar un ajuste que debite / acredite al usuario final si corresponde.
2) Marcar como coincidente.
YNN1) IF STATUS == APPROVED: Registrar un ajuste que debite / acredite al usuario final si corresponde.
2) Marcar como coincidente.
NYNNo 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: presentacionesyyyy_mm_dd.csv

Estructura del archivo de presentación

AtributoDescripciónValores permitidos
PRESENTMENT_ID
TRANSACTION_IDEl id de la transacción original que generó la presentación.
LOCAL_TRANSACTION_DATE_TIME
TRANSACTION_TYPEIndica el tipo de transacción.PURCHASE
WITHDRAWAL
EXTRACASH
REFUND
PAYMENT
PRODUCT_TYPEEs el tipo de producto.PREPAID
CREDIT
DEBIT
PROVIDEREs la marca de la tarjeta emitida.VISA
MASTERCARD
AFFINITY_GROUP_ID
USER_IDEl id del usuario de Pomelo titular de la tarjeta
CARD_ID
BINLos primeros seis u ocho dígitos del PAN.
LAST_FOURLos últimos cuatro dígitos del PAN.
ORIGINDOMESTIC: 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_MCCEl código de categoría de comerciante según se define en el ISO-18245.
MERCHANT_NAME
TRANSACTION_AMOUNTEl monto de la transacción sin impuestos y en la moneda original enviada por el comerciante.
TRANSACTION_CURRENCYEl código de la moneda de TRANSACTION_TOTAL en ISO_4217 formato ALPHA-3.
SETTLEMENT_AMOUNTEl monto de la transacción presentado por la marca.
SETTLEMENT_CURRENCYEl código de la moneda de SETTLEMENT_AMOUNT en ISO_4217 formato ALPHA-3, si es una transacción doméstica será presentada en moneda local, de lo contrario en USD.
DEBT_AMOUNTEl 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_CURRENCYEl 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_FEEComisión por una transacción aplicada al intercambio de la misma.
INTERCHANGE_RATEValor alfanumérico que identifica la tasa de intercambio de la transacción presentada por el adquirente.
TAXEste es el impuesto asociado a la tasa de intercambio, debido a la regulación local, esos montos deben tener un IVA calculado.
FUNCTION_CODEEste es el tipo de presentación.FIRST_PRESENTMENT
SECOND_PRESENTMENT_FULL
SECOND_PRESENTMENT_PARTIAL
REVERSE_PRESENTMENTSignifica que la presentación fue revertida desde la red.TRUE
FALSE
REASON_CODERazón de la segunda presentación.
ICA_ACQUIRER
TAX_IDID 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
INSTALLMENTS_CREDIT_TYPE[OPCIONAL*] El tipo de crédito otorgadoNO_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.

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 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 .
    • 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
transactionobjectrequired
Información relacionada con la transacción
merchantobjectrequired
Información relacionada con el comerciante
cardobjectrequired
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.
userobjectrequired
Información relacionada al usuario que realizó la transacción
amountobjectrequired
Información relacionada a los montos 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
¿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"
"original_transaction_id":
"ctx-200kirg6qicg1qHSCbgaStrEHjI"
"local_date_time":
"2019-08-24T14:15:22"
}
"merchant":{
"id":
"string"
"mcc":
"string"
"address":
"string"
"name":
"string"
}
"card":{
"id":
"c-1625519392748E6XZBK"
"product_type":
"PREPAID"
"provider":
"MASTERCARD"
"last_four":
"1573"
}
"installments":{
"quantity":
"12"
"credit_type":
"NO_PROMOTION"
"grace_period":
"0"
}
"user":{
"id":
"u-1625758043579BAR6D4"
}
"amount":{
"local":{
...
}
"settlement":{
...
}
"transaction":{
...
}
"details":[
...
]
}
}
Ejemplo de respuestas

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
transactionobjectrequired
Información relacionada con la transacción
merchantobjectrequired
Información relacionada con el comerciante
cardobjectrequired
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.
userobjectrequired
Información relacionada al usuario que realizó la transacción
amountobjectrequired
Información relacionada a los montos de la transacción
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"
"original_transaction_id":
"ctx-200kirg6qicg1qHSCbgaStrEHjI"
"local_date_time":
"2019-08-24T14:15:22"
}
"merchant":{
"id":
"string"
"mcc":
"string"
"address":
"string"
"name":
"string"
}
"card":{
"id":
"c-1625519392748E6XZBK"
"product_type":
"PREPAID"
"provider":
"MASTERCARD"
"last_four":
"1573"
}
"installments":{
"quantity":
"12"
"credit_type":
"NO_PROMOTION"
"grace_period":
"0"
}
"user":{
"id":
"u-1625758043579BAR6D4"
}
"amount":{
"local":{
...
}
"settlement":{
...
}
"transaction":{
...
}
"details":[
...
]
}
}
Ejemplo de respuestas

Core

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

Requisitos para crear una cuenta

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.

Ciclo de vida de las cuentas

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.

Posibles respuestas de error

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

Crear Cuenta

El endpoint /core/accounts/v1 te permite crear una cuenta digital para un usuario de Pomelo. Si creas bien la cuenta, te devolveremos un status 201
Parámetros disponibles
Header Parameters
X-Idempotency-Keystringrequired

Identificador idempotente de creación de cuenta. Deberás generar este valor para cada cuenta que quieras crear. Si dos requests idénticos tienen el mismo identificador de idempotencia solo crearás una cuenta aunque ambos reciban una respuesta exitosa.

Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
countrystringrequired
País de la cuenta.
Enum: ARGBRA
currencystringrequired
Moneda de la cuenta.
Enum: ARSBRL
metadataobject
Es un campo opcional para que puedas agregar los datos extra que quieras.
Ejemplo: {"extra_property_1":"My value"}
user_idstringrequired
ID del usuario dueño de la cuenta.
Ejemplo: usr-20I2tIqG3buTsvHKKORrtY2MkFH
Detalle de respuestas
dataobjectrequired
¿Te resultó útil esta sección?
POST/core/accounts/v1
{
"country":
"ARG"
"currency":
"ARS"
"metadata":{
"extra_property_1":
"My value"
}
"user_id":
"usr-20I2tIqG3buTsvHKKORrtY2MkFH"
}
Ejemplo de respuestas

Eliminar Cuenta

El endpoint /core/accounts/v1/{id} te permitirá eliminar una cuenta específica. Al hacerlo, su estado pasará a DELETED y ya no se podrá usar para hacer transacciones.
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
status_update_motivestringrequired
Enum: OTHERINTERNAL_REASONUSER_REQUESTFRAUD
status_update_commentstring
Este campo es obligatorio cuando el status_update_motive es OTHER.
Ejemplo: Motivo de actualización del estado de la cuenta.
Path Parameters
idstringrequired
Ejemplo: acc-20I4qJinTCudWvJULZygeC257wy
Detalle de respuestas
dataobjectrequired
¿Te resultó útil esta sección?
DELETE/core/accounts/v1/{id}
{
"status_update_motive":
"OTHER"
"status_update_comment":
"Motivo de actualización del estado de la ..."
}
Ejemplo de respuestas

Actualizar Cuenta

El endpoint /core/accounts/v1/{id} te servirá para cambiar el estado de una cuenta. Los estados de la cuenta pueden alterarse entre Para los últimos dos estados es necesario indicar el motivo del cambio de estado

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
statusstringrequired
Enum: ACTIVEDISABLEDFROZEN
status_update_motivestring
Este campo es obligatorio cuando el status no es ACTIVE.
Enum: OTHERLOSTINTERNAL_REASONSTOLENFRAUDINHIBITIONSEIZURE
status_update_commentstring
Este campo es obligatorio cuando el status_update_motive es OTHER.
Ejemplo: Motivo de actualización del estado de la cuenta.
Path Parameters
idstringrequired
Ejemplo: acc-20I4qJinTCudWvJULZygeC257wy
Detalle de respuestas
dataobjectrequired
¿Te resultó útil esta sección?
PATCH/core/accounts/v1/{id}
{
"status":
"ACTIVE"
"status_update_motive":
"OTHER"
"status_update_comment":
"Motivo de actualización del estado de la ..."
}
Ejemplo de respuestas

Consultas

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.

¿Qué es una actividad?

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

Capacidades de Query API

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

Listar Actividades

El endpoint /core/activities/v1 devuelve un listado paginado de todas las actividades. Puedes usar filtros para especificar que solo se devuelvan las actividades de una cuenta particular.
Parámetros disponibles
Header Parameters
Accept-Languagestring

Lenguajes ordenados según tu preferencia. Especificación técnica

Ejemplo: Accept-Language: en-US;q=1.0,en-*;q=0.5
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
page[number]integer(format: int32)
Número de página
page[size]integer(format: int32)
Tamaño de página
Ejemplo: 5
filter[country]string
País de origen de la cuenta.
Ejemplo: ARG
Enum: ARGBRAMEX
filter[account_id]string
ID de la cuenta de la cual quieras obtener el listado de actividades.
Ejemplo: acc-20I5vMjljS3VEyafcX8lA3T3g0c
filter[result]array
Lista de resultados de las transacciones asociadas a las actividades.
Ejemplo: APPROVED,PENDING,REJECTED
Enum: APPROVEDREJECTEDPENDING
filter[type]array
Lista de tipos de transacciones asociadas a las actividades que quieras obtener en el listado.
Ejemplo: CARD_PURCHASE,EXTRACASH
Enum: CARD_PURCHASEEXTRACASHCASHOUT_STORECASHOUT_ATMBANK_TRANSFER_INBANK_TRANSFER_OUTCASHOUTCASHINMANUAL_MOVEMENTCLIENT_PAYMENT
filter[created_from]string(format: date-time)
Fecha de creación base de las actividades que quieras obtener en el listado.
Ejemplo: 2021-12-30T14:47:30.969Z
filter[created_until]string(format: date-time)
Fecha de creación límite de las actividades que quieras obtener en el listado.
Ejemplo: 2021-12-31T14:47:30.969Z
filter[updated_from]string(format: date-time)
Fecha de actualización base de las actividades que quieras obtener en el listado.
Ejemplo: 2021-12-30T14:47:30.969Z
filter[updated_until]string(format: date-time)
Fecha de actualización límite de las actividades que quieras obtener en el listado.
Ejemplo: 2021-12-31T14:47:30.969Z
filter[upsert_from]string(format: date-time)
Fecha de creación o actualización base de las actividades que quieras obtener en el listado.
Ejemplo: 2021-12-30T14:47:30.969Z
filter[upsert_until]string(format: date-time)
Fecha de creación o actualización límite de las actividades que quieras obtener en el listado.
Ejemplo: 2021-12-31T14:47:30.969Z
sortstring
Ordenamiento que quieras aplicar al listado.
Ejemplo: -created_at,total_amount
Detalle de respuestas
metaobject
dataarray
¿Te resultó útil esta sección?
GET/core/activities/v1
Ejemplo de respuestas

Obtener Actividades

El endpoint /core/activities/v1/{id} permite obtener información de la actividad que especifiques.
Parámetros disponibles
Header Parameters
Accept-Languagestring

Lenguajes ordenados según tu preferencia. Especificación técnica

Ejemplo: Accept-Language: en-US;q=1.0,en-*;q=0.5
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
idstringrequired
Detalle de respuestas
dataobjectrequired
¿Te resultó útil esta sección?
GET/core/activities/v1/{id}
Ejemplo de respuestas

Listar Cuentas

El endpoint /core/accounts/v1 devuelve un listado paginado de las cuentas digitales junto con sus balances.
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
page[number]integer(format: int32)
Número de página
page[size]integer(format: int32)
Tamaño de página
Ejemplo: 5
filter[country]string
País de origen de la cuenta.
Ejemplo: ARG
Enum: ARGBRAMEX
filter[status]array
Estado de las cuentas que quieras obtener en el listado.
Ejemplo: ACTIVE,DISABLED,DELETED,FROZEN
Enum: ACTIVEDISABLEDDELETEDFROZEN
filter[user_id]string
ID del usuario del cual quieras obtener sus cuentas.
Ejemplo: usr-20I2tIqG3buTsvHKKORrtY2MkFH
filter[created_from]string(format: date-time)
Fecha de creación base de las actividades que quieras obtener en el listado.
Ejemplo: 2021-12-30T14:47:30.969Z
filter[created_until]string(format: date-time)
Fecha de creación límite de las actividades que quieras obtener en el listado.
Ejemplo: 2021-12-31T14:47:30.969Z
sortstring
Ordenamiento que quieras aplicar al listado.
Ejemplo: -created_at,balance
Detalle de respuestas
metaobject
dataarrayrequired
¿Te resultó útil esta sección?
GET/core/accounts/v1
Ejemplo de respuestas

Obtener Cuenta

El endpoint /core/accounts/v1/{id} devuelve la información de la cuenta solicitada, junto con su balance.
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
idstring(maxLength: 256, minLength: 0)required
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
GET/core/accounts/v1/{id}
Ejemplo de respuestas

Transacciones

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.

Tipos de procesamiento

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.

Idempotencia

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.

Respuestas

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.

Autorizar Transacción

El endpoint /core/transactions/v1 te permite autorizar transacciones de entrada y salida de dinero de las cuentas digitales. Las transacciones procesadas correctamente devolverán el status code 201, ya sea que fueran aprobadas o rechazadas. Revisa el campo result para ver el resultado.
Parámetros disponibles
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
account_idrequired
ID de una cuenta de Pomelo
Ejemplo: acc-23GMRyaPjVbczjGtLfQ6zgUJmLv
typestringrequired
Tipo de la transacción.
Enum: CARD_PURCHASEEXTRACASHCASHOUT_STORECASHOUT_ATMBANK_TRANSFER_INBANK_TRANSFER_OUTCASHINCASHOUTMANUAL_MOVEMENTCLIENT_PAYMENT
process_typestringrequired
Sirve para indicar si la transacción se trata de un movimiento original, un reintegro, reversa o un ajuste.
Ejemplo: REFUND
Enum: ORIGINALADJUSTMENTREFUNDREVERSAL
parent_tx_id
ID de una transacción.
Ejemplo: atx-23GMkfOa7V1MqUlvEic4Dp7XhTT
dataobject
entry_typestringrequired
Indica si la transacción quiere ingresar o debitar dinero de una cuenta. Para ingresar dinero se debe usar CREDIT y para debitar CREDIT.
Ejemplo: DEBIT
Enum: CREDITDEBIT
total_amountstringrequired
Monto total de la transacción.
Ejemplo: 999.99
process_beforestring(format: date-time)
Este campo es opcional y sirve para indicar una fecha limite para el procesamiento de una transacción. Es útil para flujos asincrónicos.
Detalle de respuestas
idstringrequired
Ejemplo: atx-230ReKOtS2lv0yUi2FKG98ycdXZ
resultstringrequired
Ejemplo: REJECTED
Enum: APPROVEDREJECTED
rejection_reasonstring
Ejemplo: INSUFFICIENT_FUNDS
Enum: INSUFFICIENT_FUNDSACCOUNT_DISABLEDACCOUNT_FROZENMONTHLY_AMOUNT_LIMIT_REACHEDDAILY_AMOUNT_LIMIT_REACHEDCLIENT_MONTHLY_AMOUNT_LIMIT_REACHEDCLIENT_DAILY_AMOUNT_LIMIT_REACHEDPROCESS_TIME_EXPIREDSOURCE_ACCOUNT_TX_REJECTEDDESTINATION_ACCOUNT_TX_REJECTED
created_atstring(format: date-time)required
¿Te resultó útil esta sección?
POST/core/transactions/v1
{
"account_id":
"acc-23GMRyaPjVbczjGtLfQ6zgUJmLv"
"type":
"CARD_PURCHASE"
"process_type":
"REFUND"
"parent_tx_id":
"atx-23GMkfOa7V1MqUlvEic4Dp7XhTT"
"data":{
"description":
"{'es-AR':'Alguna descripción.','en-US':' ..."
"details":[
...
]
"metadata":
"{'custom-property': 'value'}"
}
"entry_type":
"DEBIT"
"total_amount":
"999.99"
"process_before":
"2022-05-20T02:56:06.650Z"
}
Ejemplo de respuestas

Webhooks

Este servicio será el encargado de notificarte todas las actividades de tus cuentas.

Una notificación puede tratarse de una creación o de una modificación de una actividad. Para determinar de qué caso se trata podrás leer el campo type, el cual puede tener alguno de estos valores:

  • ACTIVITY_CREATED: La notificación se trata de la creación de una nueva actividad.
  • ACTIVITY_UPDATED: La notificación se trata de la modificación de una actividad. Las actividades pueden cambiar su estado de PENDING a APPROVED o de PENDING a REJECTED.

Proceso de verificación de la firma digital del request

Junto con la notificación enviaremos un conjunto de headers HTTP que te servirán para verificar la autenticidad de la misma.

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

La firma digital es un código HMAC-SHA256 que se construye utilizando él api-secret y una serie de bytes que está compuesta por la concatenación del timestamp, endpoint y request body codificados en UTF-8.

El siguiente es un pseudo-código para verificar que la firma digital de un request sea legítima:

requestSignature = request.headers['x-signature'] signatureData = encode(request.headers['x-timestamp'] + request.headers['x-endpoint'] + request.body , 'UTF-8') recreatedSignature = hmac(apiSecret, signatureData, 'SHA256') validSignature = requestSignature == recreatedSignature

Notificación de actividades

El siguiente endpoint deberá estar en el servicio del cliente para que pueda recibir los requests de las actividades creadas/actualizadas. Si dicho request retorna un codigo HTTP del tipo 2xx, el mismo no volverá a ser enviado y sera marcado como Enviado correctamente. Caso contrario, se reintentará nuevamente.
Parámetros disponibles
Header Parameters
X-Api-Keystringrequired
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
Ejemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este header contiene la firma digital (timestamp + endpoint + body) que deberás verificar para asegurar la integridad del request.Si la firma no coincide, deberás rechazar el pedido.
Ejemplo: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
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ó.
Ejemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
Este header se usa para regenerar la firma a chequear y deberás compararlo con el endpoint de tu servicio para verificar que son coincidentes.
Ejemplo: X-Endpoint: /client/api/activities/updates
Body Parameters
typestringrequired
Tipo de proceso de la actividad.
Ejemplo: ACTIVITY_CREATED
versionstringrequired
Número de version del evento.
Ejemplo: 1.0.0
idempotency_keystringrequired
Identificador idempotente de creación del evento.
Ejemplo: act-20I2tIqG3buTsvHKKORrtY2MkFH
datetimestring(format: date-time)required
Fecha de la creacion del evento.
Ejemplo: 2021-12-31T23:59:59.999Z
activityobject
¿Te resultó útil esta sección?
POST/<url-del-cliente>
{
"type":
"ACTIVITY_CREATED"
"version":
"1.0.0"
"idempotency_key":
"act-20I2tIqG3buTsvHKKORrtY2MkFH"
"datetime":
"2021-12-31T23:59:59.999Z"
"activity":{
"account":{
...
}
"origin_tx_id":
"atx-200mVjWAnL8tD4vlG3fexiQeWvN"
"origin":
"string"
"process_type":
"string"
"type":
"string"
"data":{
...
}
"total_amount":
"1200.15"
"entry_type":
"DEBIT"
"result":
"string"
"rejection_reason":
"string"
"rejection_message":{
...
}
"forced":
true
"created_at":
"2021-12-31T23:59:59.999Z"
"updated_at":
"2021-12-31T23:59:59.999Z"
}
}
Ejemplo de respuestas

Cash Networks Argentina

Este servicio te permite integrarte con distintas redes de efectivo para consultar los datos de una cuenta y poder ingresar dinero (cash in) o registrar intenciones de extracción de dinero (cash out intent).

Para ingresar dinero, cada cuenta tendrá un alias que te permitirá identificarla en una red de pagos. Ese alias se autogenera y asocia a la cuenta cuando se crea.

Para los casos de extracciones, deberás registrar un cash out intent, que, combinado con el alias, podrás usar para extraer efectivo de una cuenta en las redes de pagos habilitadas.

PaísNetworkID
ArgentinaPago FácilPAGO_FACIL

Crear intento de cash out

El endpoint POST /networks/cash/v1/cashout/intents te permitirá generar un intento de cash out para una cuenta determinada. Cada intento representa la intención de extraer dinero del saldo de una cuenta a través de una red de pago.

Consideraciones

Solo podrá existir un intento activo por cuenta y red. El intento se resuelve cuando se realice efectivamente la extracción a través de una red de cash o cuando llegue la fecha de expiración. La creación de un nuevo intento sobreescribe el intento anterior.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
account_idstringrequired
Identificador de la cuenta
Ejemplo: acc-20I4qJinTCudWvJULZygeC257wy
network_namestringrequired
Identificador de la red de pago
Ejemplo: PAGO_FACIL
amountstring
Monto de la intención de extracción
Ejemplo: 397.67
Detalle de respuestas
dataobject
metaobject
¿Te resultó útil esta sección?
POST/networks/cash/v1/cashout/intents
{
"account_id":
"acc-20I4qJinTCudWvJULZygeC257wy"
"network_name":
"PAGO_FACIL"
"amount":
"397.67"
}
Ejemplo de respuestas

Listar intentos de cash out

El endpoint GET /networks/cash/v1/cashout/intents/{account_id} te permite obtener el último cash out intent vigente. Para considerar un cash out vigente se deben cumplir las siguientes condiciones:

  • Que no se haya usado para una extracción.
  • Que no haya expirado.
  • Que no haya sido reemplazado por un nuevo intento de cash out.
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
account_idstringrequired
Identificador de la cuenta
Ejemplo: acc-20I4qJinTCudWvJULZygeC257wy
Detalle de respuestas
dataobject
metaobject
¿Te resultó útil esta sección?
GET/networks/cash/v1/cashout/intents/{account_id}
Ejemplo de respuestas

Obtener alias de cash in

El endpoint GET /networks/cash/v1/alias/{account_id} te permitirá obtener el alias de una cuenta. Se trata de un valor único asociado a la cuenta, que te servirá para hacer una operación de cash in en la red de pagos.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
account_idstringrequired
Identificador de la cuenta
Ejemplo: acc-20I4qJinTCudWvJULZygeC257wy
Detalle de respuestas
dataobject
metaobject
¿Te resultó útil esta sección?
GET/networks/cash/v1/alias/{account_id}
Ejemplo de respuestas

Cash Networks Brasil

Este servicio te permite integrarte con distintas redes de efectivo para consultar los datos de una cuenta y registrar intenciones de ingresos de dinero (cash in intent) para una cuenta en una red de efectivo.

Para ingresar dinero, deberás registrar un cash in intent en alguna de las redes de pagos habilitadas.

PaísNetworkID
BrasilBoletoBOLETO

Crear Intento de Cash in

El endpoint POST /networks/cash/v1/cashin/intents te permitirá generar un intento de cash in para una cuenta determinada. Cada intento representa la intención de ingresar dinero al balance de una cuenta a través de una red de pago.

Ciclo de vida

El intento se resuelve cuando se realice efectivamente el ingreso de dinero a través de una red de cash o cuando se alcance la fecha de expiración, lo primero que ocurra.

El intento puede tener distintos estados dependiendo qué acción haya sido aplicada al mismo:

  • ACTIVE: el intento se encuentra activo y puedes usarlo hasta la fecha de expiración (expires_at). Cuando llega la fecha de expiración no podrás usar ese intent para ingresar dinero, deberás generar uno nuevo.
  • REJECTED: la integración con la red de cash rechazó la creación del intent.
  • PAID: el intent se pagó en su totalidad por el monto que solicitaste.
  • PARTIALLY_PAID: el intent se pagó parcialmente, es decir que la sumatoria los pagos que efectuaron en nombre de este intent es menor que el monto que solicitaste. Es posible hacer pagos parciales hasta la fecha de expiración del intent.
  • CANCELLED: este estado puede alcanzarse por distintas vías. La primera es que hayas cancelado el intent con el endpoint de cancelación o bien, que el proveedor de la red de efectivo proactivamente anule el intent que generaste.
Parámetros disponibles
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
account_idstringrequired
Identificador de la cuenta
Ejemplo: acc-20I4qJinTCudWvJULZygeC257wy
networkstringrequired
Identificador de la red de pago
Ejemplo: BOLETO
amountstringrequired
Monto de la intención de ingreso
Ejemplo: 397.67
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
POST/networks/cash/v1/cashin/intents
{
"account_id":
"acc-20I4qJinTCudWvJULZygeC257wy"
"network":
"BOLETO"
"amount":
"397.67"
}
Ejemplo de respuestas

Obtener intento de cash in

El endpoint GET /networks/cash/v1/cashin/intents/{intent_id} te permitirá obtener todos los datos de una intención de cashin a través de su identificador.
Parámetros disponibles
Path Parameters
intent_idstringrequired
Identificador del intento de cash in
Ejemplo: cin-20I4qJinTCudWvJULZygeC257wy
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
GET/networks/cash/v1/cashin/intents/{intent_id}
Ejemplo de respuestas

Cancelar intento de cash in

El endpoint DELETE /networks/cash/v1/cashin/intents/{intent_id} te permitirá cancelar un cash in intent.
Parámetros disponibles
Path Parameters
intent_idstringrequired
Identificador del intento de cash in
Ejemplo: cin-20I4qJinTCudWvJULZygeC257wy
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
DELETE/networks/cash/v1/cashin/intents/{intent_id}
Ejemplo de respuestas

Listar intentos de cash in por cuenta

El endpoint GET /networks/cash/v1/cashin/intents/account/{account_id} te permitirá listar todos los cash in intents de una cuenta en particular.
Parámetros disponibles
Query Parameters
filter[status]string
Estado
Enum: ACTIVEREJECTEDPAIDPARTIALLY_PAIDCANCELLED
filter[date_from]string(format: date-time)
Fecha desde
filter[date_to]string(format: date-time)
Fecha hasta
page[number]integer(format: int32)
Página
page[size]integer(format: int32)
Tamaño de página
Ejemplo: 10
Path Parameters
account_idstringrequired
Identificador de la cuenta
Ejemplo: acc-20I4qJinTCudWvJULZygeC257wy
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
GET/networks/cash/v1/cashin/intents/account/{account_id}
Ejemplo de respuestas

Cuentas Bancarias Argentina

El servicio de Bank Account API dentro del flujo de transferencias es el que se encarga de la gestión de los atributos bancarios de la cuenta y de obtener la información de una cuenta destino al iniciar una transferencia.

Dentro de la gestión de los atributos de una cuenta se encuentra el cambio de Alias. Cada cuenta nace con un CVU y un alias seteado por defecto, este último podrá ser modificado por el usuario según su preferencia.

En cuanto a la obtención de información de una cuenta destino, cada transferencia que se realiza comienza con la validación de la cuenta destino mediante el uso del CVU o alias. Este servicio es el que se encarga de hacer esa gestión y de devolver la cuenta destino ya validada con información adicional del titular (CBU, código de banco, nombre y CUIT).

Obtener información de una cuenta

Parámetros disponibles
Path Parameters
id-typestringrequired
Ejemplo: ALIAS
Enum: ALIASCBUCVU
id-valuestringrequired
Ejemplo: EVIL.DOG
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
GET/networks/bank/v1/transfers/destination-information/{id-type}/{id-value}
Ejemplo de respuestas

Actualizar atributos de la cuenta

Parámetros disponibles
Body Parameters
keystring
Ejemplo: ALIAS
valuestring
Ejemplo: NUEVO.ALIAS
Path Parameters
account-idstringrequired
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
PATCH/networks/bank/v1/accounts/{account-id}
{
"key":
"ALIAS"
"value":
"NUEVO.ALIAS"
}
Ejemplo de respuestas

Cuentas Bancarias Brasil

El servicio de Bank Account API dentro del flujo de transferencias es el que se encarga de la gestión de los atributos bancarios de la cuenta.

Dentro de la gestión de los atributos de una cuenta se encuentra el ABM de la llave PIX.

Consideraciones:

  • Por el momento, solamente tenemos disponibles las llaves aleatorias
  • Será posible crear y eliminar llaves aleatorias sin límite
  • Se podrán tener hasta 5 llaves activas en simultáneo

Obtener listado de llaves PIX

Parámetros disponibles
Path Parameters
account_idstringrequired
Ejemplo: acc-0ujsszgFvbiEr7CDgE3z8MAUPFt
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
GET/networks/bank/v1/accounts/{account_id}/keys
Ejemplo de respuestas

Creación de llave PIX

Parámetros disponibles
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
account_idstring
Ejemplo: acc-0ujsszgFvbiEr7CDgE3z8MAUPFt
typestring
Ejemplo: EVP
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
POST/networks/bank/v1/key/pix
{
"account_id":
"acc-0ujsszgFvbiEr7CDgE3z8MAUPFt"
"type":
"EVP"
}
Ejemplo de respuestas

Eliminar llave PIX

Parámetros disponibles
Path Parameters
keystringrequired
Ejemplo: 41c2b4e0-9425-43a0-8087-b2d239f00b63
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
DELETE/networks/bank/v1/{account_id}/key/pix/{key}
Ejemplo de respuestas

Transferencias Argentina

La transferencia se realizará mediante un posteo en la Transfer API, una vez que la información de la cuenta destino se valide por el servicio de Bank Account API.

La respuesta de la transferencia puede ser sincrónica o asincrónica. En el caso de una respuesta sincrónica el servicio de Transfer API devolverá el estado final de la transacción (SUCCESS or FAILED). Si la respuesta es asincrónica porque se demora algunos segundos más, el servicio de Transfer API devolverá un estado pendiente de manera sincrónica (IN_PROGRESS) y la notificación del estado final de la transacción se notificará como Actividad a través del servicio de Webhooks de Core.

Realizar Transferencia

Parámetros disponibles
Header Parameters
X-Idempotency-Keystring
Body Parameters
account_idstring(format: uuid)
Ejemplo: acc-14688cf5-1b2d-41b1-ba0d-9e669b8540b9
credit_accountobject
amountobject
conceptstring
Ejemplo: VAR
Enum: ALQAPCBRHBRNCUOEXPFACHABHONOINOIHPREROPSEGSISSONVAR
descriptionstring
Ejemplo: Pago
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
POST/networks/bank/v1/transfers
{
"account_id":
"acc-14688cf5-1b2d-41b1-ba0d-9e669b8540b9"
"credit_account":{
"tax_type":
"CBU"
"tax_value":
"1500633400063361138832"
}
"amount":{
"currency":
"ARS"
"value":
1050.5
}
"concept":
"VAR"
"description":
"Pago"
}
Ejemplo de respuestas

Transferencias Brasil

La transferencia se realiza en 2 simples pasos:

  • Validación de cuenta destino mediante una llave PIX (por medio del endpoint 'Obtener información de llave PIX destino')
  • Con la información de la cuenta destino se debe ejecutar el segundo paso de la operación que es mandar la transacción en sí misma (por medio del endpoint “Realizar Transferencia”)

La respuesta de la transferencia puede ser sincrónica o asincrónica. En el caso de una respuesta sincrónica, el servicio de Transfer API devolverá el estado final de la transacción (SUCCESS or FAILED). Si la respuesta es asincrónica (porque se demora algunos segundos más), el servicio de Transfer API devolverá un estado pendiente de manera sincrónica (IN_PROGRESS) y la notificación del estado final de la transacción se verá como Actividad a través del servicio de Webhooks de Core.

Obtener información de llave pix destino

Parámetros disponibles
Path Parameters
account_idstringrequired
Sender account id
Ejemplo: acc-26AA71defpMZiKvkwk2fwkCRRYU
keystringrequired
Ejemplo: 22222222222
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
GET/networks/bank/v1/transfers/{account_id}/key/{key}
Ejemplo de respuestas

Realizar Transferencia

Parámetros disponibles
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
transaction_idstring
Ejemplo: tr-9c94e7ce-792e-11ec-90d6-0242ac120003
valuenumber
Ejemplo: 100
descriptionstring
Ejemplo: Teste de transferência
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
POST/networks/bank/v1/transfers/out
{
"transaction_id":
"tr-9c94e7ce-792e-11ec-90d6-0242ac120003"
"value":
100
"description":
"Teste de transferência"
}
Ejemplo de respuestas

Identity

El servicio de Identity te permite gestionar el proceso de onboarding de tus usuarios de una manera ágil y sencilla, confirmando su identidad y previniendo fraudes.

Crear Sesión

El endpoint identity/v1/sessions te permite crear una nueva sesión de validación de identidad y te devuelve un identificador único de la misma.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Body Parameters
user_idstring(format: uuid)required
USER ID
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
POST/identity/v1/sessions
{
"user_id":
"a169451c-8525-4352-b8ca-070dd449a1a5"
}
Ejemplo de respuestas

Buscar Sesiones

El endpoint /sessions te permite realizar una búsqueda con filtros específicos.

Consideraciones

Tendrás que especificar tus filtros como parámetros siguiendo este patrón: filter[field]=value. Por ejemplo: filter[status]=IN_PROGRESS

Los resultados serán paginados y podrás especificar la cantidad de datos por página y también qué página ver.

Rango de fechas

Hay un filtro para el campo created_at, que podrás usar para obtener las sesiones creadas dentro un rango de fechas. Por ejemplo: filter[created_at][from]=2021-07-27&filter[created_at][to]=2021-07-28

Ordenamiento

Podrás especificar el orden de los resultados con determinados parámetros que deberás enviar como una lista de strings en el filtro de tipo sort. Por ejemplo: ?sort=status,user_id

El ordenamiento por defecto será ascendente. Para especificar un orden descendente, deberás enviar el carácter '-' como prefijo del atributo. Por ejemplo: ?sort=status,-user_id.

Los atributos para ordenar son user_id, status y created_at.

Si un parámetro es incorrecto o está mal escrito, responderemos con un error.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
filter[user_id]string
filter[status]string
Ejemplo: CREATED
Enum: CREATEDIN_PROGRESSPROCESSINGREJECTEDNOT_VALIDATEDCANCELLED
filter[created_at][from]string
ISO 8601
Ejemplo: 1998-08-20
filter[created_at][to]string
ISO 8601
Ejemplo: 1998-08-20
page[size]number
page[number]number
Detalle de respuestas
dataarray
metaobject
¿Te resultó útil esta sección?
GET/identity/v1/sessions
Ejemplo de respuestas

Obtener Sesión

El endpoint identity/v1/sessions/{id} te permite obtener datos de una sesión de validación de identidad.
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
uuidrequired
Session ID
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
GET/identity/v1/sessions/{uuid}
Ejemplo de respuestas

Cancelar Sesión

El endpoint identity/v1/sessions/{id} te permite cancelar una sesión de validación de identidad.
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
uuidstring(format: uuid)required
Session ID
Detalle de respuestas
¿Te resultó útil esta sección?
DELETE/identity/v1/sessions/{uuid}
Ejemplo de respuestas

Obtener Reporte de Sesión

El endpoint identity/v1/sessions/{id}/report te permite obtener los datos de un usuario recabados en una sesión de validación de identidad.
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
uuidstringrequired
Detalle de respuestas
dataobject
¿Te resultó útil esta sección?
GET/identity/v1/sessions/{uuid}/report
Ejemplo de respuestas

Webhooks

Este servicio será el encargado de notificarte cuando se complete una sesión de validación de identidad.

Proceso de verificación de la firma digital del request

Junto con la notificación, enviaremos un conjunto de headers HTTP que te servirán para verificar su autenticidad.

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.

La firma digital es un código HMAC-SHA256 que se construye usando el api-secret y una serie de bytes que contienen la concatenación del timestamp, endpoint y request body codificados en UTF-8.

El siguiente es un pseudo-código para verificar que la firma digital de un request sea legítima:

requestSignature = request.headers['x-signature']
signatureData = encode(request.headers['x-timestamp'] + request.headers['x-endpoint'] + request.body , 'UTF-8')
recreatedSignature = hmac(apiSecret, signatureData, 'SHA256')
validSignature = requestSignature == recreatedSignature

Notificación de sesión completada

Deberás informarnos este endpoint para recibir las notificaciones de finalización de una sesión de validación de identidad. Nos deberás devolver un código HTTP del tipo 2xx para que no volvamos a enviar la notificación. Caso contrario, volveremos a enviarla.

Parámetros disponibles
Header Parameters
X-Api-Keystringrequired
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.
Ejemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
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.
Ejemplo: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
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ó.
Ejemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
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.
Ejemplo: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Identificador de evento.
Ejemplo: identity-session-completed
idempotency_keystringrequired
Identificador idempotente de creación del evento.
Ejemplo: 27Ky00tAZ0Rdi7G2Vt9iino8AYs
sessionobject
Sesión de validación de identidad
¿Te resultó útil esta sección?
POST/identity/v1/<client-url>
{
"event_id":
"identity-session-completed"
"idempotency_key":
"27Ky00tAZ0Rdi7G2Vt9iino8AYs"
"session":{
"id":
"iss-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"status":
"CANCELLED"
}
}
Ejemplo de respuestas