Pomelo

Autorização

Implementamos o padrão OAuth 2.0 para que você possa se comunicar com nossas APIs por meio de um único token do tipo Bearer.

Usando o token

Após receber o token de acesso, você deverá incluí-lo como header de autorização toda vez que se comunicar com nossas APIs.

Exemplo em Curl:

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

Cada API validará o token de acesso e verificará se o escopo corresponde às permissões necessárias.

Para que as solicitações sejam válidas, você deverá se comunicar com nossas APIs apenas via HTTPS e incluir o header de autorização, indicando que é do tipo Bearer.

Solicitar Token

O endpoint /oauth/v1/token é utilizado para obtenção do token de acesso. Ao realizar uma autenticação bem sucedida, salve-a, pois você precisará dela para se comunicar com nossas APIs.

Cada token é um JWT contendo um prazo de validade. Solicite um novo token somente quando o que você obteve expirar.

Parâmetros disponíveis
Header Parameters
content-typestringrequired
Enum: application/json
Body Parameters
client_idstringrequired
client_secretstringrequired
audiencestringrequired
Audiencia de API
grant_typestringrequired
Enum: client_credentials
Detalhe de respostas
access_tokenstring
Exemplo: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IloyTmZOUTQwWVVrNXh0WnNRRDlHYSJ9.eyJodHRwczovL3BvbWVsby5sYS9jbGllbnRfaWQiOiIyZmYxMjM0MTY3MzRmMjI5MmUxMTE0ODdiZWRlZmMxZTI1NDkxY2E4YzI1ZTEyMjAzM2E5MGE3NjM2ZDllNDI0IiwiaXNzIjoiaHR0cHM6Ly9wb21lbG8tZGV2ZWxvcC51cy5hdXRoMC5jb20vIiwic3ViIjoiMWNxdXBVM0U0bFpIY2U2ZFdVbHpuU29nZU1rR3ozelFAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vYXV0aC1kZXYucG9tZWxvLmxhIiwiaWF0IjoxNjMxMDM1MDQzLCJleHAiOjE2MzExMjE0NDMsImF6cCI6IjFjcXVwVTNFNGxaSGNlNmRXVWx6blNvZ2VNa0d6M3pRIiwic2NvcGUiOiJhcmc6Y2FyZHM6Z2V0LWNhcmQgYXJnOmNhcmRzOmdldC11c2VyLWNhcmQgYXJnOmNhcmRzOmNyZWF0ZS1iYXRjaCBhcmc6Y2FyZHM6YWN0aXZhdGUtY2FyZCBhcmc6Y2FyZHM6Y3JlYXRlLWNhcmQgYXJnOmNhcmRzOmNyZWF0ZS1jYXJkIGFyZzpjYXJkczp1cGRhdGUtYnVsay1jYXJkcyBhcmc6Y2FyZHM6c2VhcmNoLWNhcmQgYXJnOnVzZXJzOmdldC11c2VyIGFyZzp1c2VyczpjcmVhdGUtdXNlciBhcmc6dXNlcnM6c2VhcmNoLXVzZXIgYXJnOnVzZXJzOnVwZGF0ZS11c2VyIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.DkNi4BtLVdq1YMN5UFrtqvm2p-3DExt1X90janSfRWLbZHo2dtPtXkGfRF9kpdD3ZDA98euB68pt5nxZAGThaqm5g59pKkRz0nFzsDGUCH-Mfd6vYKGksO-dlyTeOwHyF189zYSvOMHcdaEOY2QybCWheOQnUgpFB7WaIPk6M8ZWI9SHSPtUjt6ePY7jsvDmVTtpXQM3ttB-0OarKN0qPi-A7WeD13Q7FuZHgQBxMipMlxeOfsz-RDOMwX7zTBhVNFp-Eu1Jtx1vFHVhDbG7tDW5N2np7kZvYXS5-wSP-fZMc57I1NmXrjbCACMWFhsnqTuHRJiHn3l-kG6nb7_EIw
scopestring
Exemplo: arg:cards:get-card arg:cards:get-user-card
expires_ininteger
Exemplo: 86400
token_typestring
Exemplo: Bearer
Esta seção foi útil para você?
POST/oauth/token
{
"client_id":
"3LBFuOiEHrl4BailkRlsnIMmSctMLb7A"
"client_secret":
"s5u3oYK0-A9CV6TkszPQThUa_qxMfr2yyd3-eJwQ ..."
"audience":
"https://auth-dev.pomelo.la"
"grant_type":
"client_credentials"
}
Respostas de amostra

Usuários

A API de Usuários contém todos os endpoints necessários para administrar a base de usuários. É possível usá-la para criar, atualizar ou até mesmo pesquisar usuários sob determinados parâmetros.

Criar usuário

O endpoint '/users/v1/' permite criar um novo usuário em nosso banco de dados.

O número de parâmetros necessários para criar um usuário varia de acordo com o produto que você contratou, mas sempre solicitaremos o e-mail e 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.

Considerações sobre os documentos de identidade

Para Argentina

Os tipos de documentos de identidade aceitos são:

  • DNI
  • LE
  • LC
  • CI
  • PASSPORT

No caso do DNI, validaremos que sua extensão é de 7 ou 8 caracteres.

O tipo de documento fiscal aceito é o CUIL.

Para o Brasil

Os tipos de documentos de identidade aceitos são:

  • RG
  • CNH

O tipo de documento fiscal aceito é o CPF. Vamos validar que a extensão tenha 11 caracteres.

Para o México

Os tipos de documentos de identidade aceitos são:

  • INE
  • PASSPORT

O tipo de documento fiscal aceito é o RFC, mas não será obrigatório incluí-lo.

Para Argentina

Se você opera na Argentina, o endereço legal do usuário deve ser de uma das seguintes províncias:

  • 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 o 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 o México

Se você opera no México, não há requisitos especiais em relação aos campos de endereço legal do usuário.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID exclusiva em cada solicitação para utilizar nosso esquema de idempotência.
Exemplo: fRwX12Dg3345AD
Body Parameters
namestring
Exemplo: Diego
surnamestring
Exemplo: Pomelo
identification_typestring
Enum: DNILELCCIPASSPORT
identification_valuestring
Exemplo: 42345678
birthdatestring
ISO 8601
Exemplo: 1998-08-20
genderstring
Exemplo: MALE
emailstringrequired
phonestring
Exemplo: 1123456789
tax_identification_typestring
Exemplo: CUIL
Enum: CUIL
tax_identification_valuestring
Exemplo: 20423456789
legal_addressobject
operation_countrystringrequired
ISO 3166 alpha-3
Exemplo: ARG
Detalhe de respostas
dataobject
Esta seção foi útil para você?
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"
}
Respostas de amostra

Buscar usuários

O endpoint '/users/v1/' permite buscar um grupo de usuários e receber uma lista ordenada com base nos parâmetros especificados.

Considerações

Será necessário especificar os filtros desejados como parâmetros de acordo com o seguinte padrão: filter[campo]=valor. Por exemplo: /users/v1/?filter[status]=ACTIVE Para filtrar um atributo com vários valores possíveis, você deve separar os valores com vírgulas. Vejamos um exemplo: filter[status]=ACTIVE,BLOCKED

Os resultados serão paginados e pode-se especificar a quantidade de dados por página, bem como qual página visualizar, usando: page[number]=value e page[size]=value

Ordenação

É possível especificar a ordem dos resultados com certos parâmetros que deverão ser enviados como uma lista de strings no filtro do tipo sort. Por exemplo: ?filter[status]=ACTIVE&sort=status,gender

A ordenação padrão será crescente. Para especificar uma ordem decrescente, deve-se enviar o caractere '-' como prefixo do atributo. Por exemplo: /users/v1/?filter[status]=ACTIVE&sort=status,-gender

Os atributos que podem ser ordenados são:

  • id
  • gender
  • identification_type
  • identification_value
  • status

Se um parâmetro estiver errado ou mal redigido, responderemos com um erro.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: 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
Exemplo: 1998-08-20
filter[name]string
Exemplo: Juan
filter[surname]string
Exemplo: Rodriguez
filter[email]string
filter[status]string
filter[country_code]string
ISO 3166-1 alpha-3
page[size]number
Tamanho de página.
page[number]number
Número de página. O número da primeira página é 0.
sortstring
Exemplo: id,-name
Detalhe de respostas
dataarray
metaobject
Esta seção foi útil para você?
GET/users/v1/
Respostas de amostra

Obter usuário

O endpoint de '/users/v1/{id}' permite consultar as informações de um usuário por meio do seu ID.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
idstringrequired
ID do usuário
Detalhe de respostas
dataobject
Esta seção foi útil para você?
GET/users/v1/{id}
Respostas de amostra

Modificar usuário

O endpoint '/users/v1/{id}' permite atualizar as informações de um usuário por meio do seu ID.

Considerações

Para bloquear um usuário você deve enviar o status com o valor BLOCKED e o valor CLIENT_INTERNAL_REASON no campo status_reason.

Para reativar um usuário que você bloqueou, você precisará enviar status com 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.

Considerações sobre os documentos de identidade

Para Argentina

Os tipos de documentos de identidade aceitos são:

  • DNI
  • LE
  • LC
  • CI
  • PASSPORT

No caso do DNI, validaremos que sua extensão é de 7 ou 8 caracteres.

O tipo de documento fiscal aceito é o CUIL.

Para o Brasil

Os tipos de documentos de identidade aceitos são:

  • RG
  • CNH

O tipo de documento fiscal aceito é o CPF. Vamos validar que a extensão tenha 11 caracteres.

Para o México

Os tipos de documentos de identidade aceitos são:

  • INE
  • PASSPORT

O tipo de documento fiscal aceito é o RFC, mas não será obrigatório incluí-lo.

Para Argentina

Se você opera na Argentina, o endereço legal do usuário deve ser de uma das seguintes províncias:

  • 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 o 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 o México

Se você opera no México, não há requisitos especiais em relação aos campos de endereço legal do usuário.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
namestring
Exemplo: Diego
surnamestring
Exemplo: Pomelo
identification_typestring
Enum: DNILELCCIPASSPORT
identification_valuestring
Exemplo: 42345678
birthdatestring
ISO 8601
Exemplo: 1998-08-20
genderstring
Exemplo: MALE
emailstring
phonestring
Exemplo: 1123456789
tax_identification_typestring
Exemplo: CUIL
Enum: CUIL
tax_identification_valuestring
Exemplo: 20423456789
statusstring
Enum: ACTIVEBLOCKED
status_reasonstring
Enum: CLIENT_INTERNAL_REASON
legal_addressobject
Path Parameters
idstringrequired
ID do usuário
Detalhe de respostas
dataobject
Esta seção foi útil para você?
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"
}
}
Respostas de amostra

Cartões

A API de Cartões contém todos os endpoints necessários para criar cartões nomeados e não nomeados, ativá-los, realizar pesquisas, obter as informações de um determinado cartão e muito mais.

Obter cartão

O endpoint /cards/v1/{id} permite obter informações sobre um cartão específico.

Considerações

O parâmetro extend é utilizado para obter dados adicionais de um cartão.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Query Parameters
extendstring
Permite obter informações adicionais, como número e CVV do cartão, que não são incluídas por padrão na resposta.
Enum: pancvvnameexpiration_date
Path Parameters
idstringrequired
Id pública do cartão
Detalhe de respostas
dataobject
metaobject
Esta seção foi útil para você?
GET/cards/v1/{id}
Respostas de amostra

Atualizar cartão

O endpoint /cards/v1/{id} permite atualizar o status, o grupo de afinidade e o PIN de um cartão.

Considerações

Será necessário especificar um motivo da lista abaixo para atualizar o status de um cartão:

Novo statusMotivo válido
BLOCKED / DISABLEDCLIENT_INTERNAL_REASON
BLOCKED / DISABLEDUSER_INTERNAL_REASON
DISABLEDFRAUDULENT
DISABLEDLOST
DISABLEDSTOLEN
DISABLEDBROKEN
DISABLEDUPGRADE
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
affinity_group_idstring
Exemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
statusstring
Enum: ACTIVEBLOCKEDDISABLED
status_reasonstring
Enum: CLIENT_INTERNAL_REASONUSER_INTERNAL_REASONPOMELO_INTERNAL_REASONFRAUDULENTLOSTSTOLENBROKENUPGRADE
pinstring
Exemplo: 1234
Path Parameters
idstringrequired
Id pública do cartão
Detalhe de respostas
dataobject
Esta seção foi útil para você?
PATCH/cards/v1/{id}
{
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"status":
"ACTIVE"
"status_reason":
"CLIENT_INTERNAL_REASON"
"pin":
"1234"
}
Respostas de amostra

Atualizar envio de cartão

O endpoint /cards/v1/{id}/shipment permite atualizar o endereço de envio de um cartão.

Considerações

O cartão deverá ser nomeado fisicamente e possuir o status CREATED.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
addressobject
Path Parameters
idstringrequired
Id pública do cartão
Detalhe de respostas
dataobject
Esta seção foi útil para você?
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"
}
}
Respostas de amostra

Buscar cartões

O endpoint /cards/v1/ permite buscar um grupo de cartões com base nos atributos especificados.

Considerações

Será necessário especificar os filtros desejados como parâmetros de acordo com este padrão: filter[campo]=valor. Por exemplo: filter[status]=CREATED. Para filtrar um atributo com vários valores possíveis, você deve separar os valores com vírgulas. Vejamos um exemplo: filter[status]=CREATED,ACTIVE

Os resultados serão paginados e pode-se especificar a quantidade de dados por página, bem como qual página visualizar, usando: page[number]=value e page[size]=value

Ordenação

É possível especificar a ordem dos resultados com certos parâmetros que deverão ser enviados como uma lista de strings no filtro do tipo sort. Por exemplo: /cards/v1/?sort=status,card_type.

A ordenação padrão será crescente. Para especificar uma ordem decrescente, deve-se enviar o caractere '-' como prefixo do atributo. Por exemplo: /cards/v1/?sort=status,-card_type.

Os atributos que podem ser ordenados são:

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

Se um parâmetro estiver errado ou mal redigido, responderemos com um erro.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: 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
Tamanho de página.
page[number]number
Número de página. O número da primeira página é 0.
sortstring
Exemplo: status,-card_type
Detalhe de respostas
dataarray
metaobject
Esta seção foi útil para você?
GET/cards/v1/
Respostas de amostra

Criar cartão

O endpoint /cards/v1/ permite criar um novo cartão, tanto físico como virtual.

Considerações

Para criar um novo cartão físico, será preciso especificar o endereço de envio.

Será possível usar o parâmetro previous_card_id, para especificar que um cartão é substituto de um anterior.

Para garantir que uma solicitação não seja executada mais de uma vez, solicitaremos que você envie o header x-idempotency-key com uma ID única para usar nosso esquema de idempotência. Se duas solicitações tiverem a mesma ID de header, criaremos apenas um cartão e ambas as solicitações terão a mesma resposta positiva

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID única em cada solicitação para utilizar nosso esquema de idempotência.
Exemplo: fRwX12Dg3345AD
Body Parameters
user_idstringrequired
Exemplo: usr-1625758043579BAR6D4
affinity_group_idstringrequired
Exemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
card_typestringrequired
Exemplo: PHYSICAL
addressobject
previous_card_idstring
Se este atributo for enviado, o novo cartão será tratado como substituto do cartão fornecido.
Exemplo: crd-20gRqyp809SvDzXzhSeG2w6UiO5
Detalhe de respostas
dataobject
Esta seção foi útil para você?
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"
}
Respostas de amostra

Criar lote de cartões não nomeados

O endpoint /cards/v1/batches permite criar um lote de cartões sem nome.

Considerações

Um lote pode ter no máximo 1000 cartões.

O endereço de entrega é obrigatório se o tipo de distribuição for CLIENT.

Processaremos a chamada de forma assíncrona, o que significa que os cartões podem não estar disponíveis imediatamente.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
affinity_group_idstringrequired
Exemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
quantitynumber(minimum: 1, maximum: 1000)required
Exemplo: 100
distribution_typestringrequired
Enum: CLIENTWAREHOUSE
addressobject
O endereço é obrigatório quando a distribuição é do tipo CLIENT
receiverobject
O destinatário é obrigatório quando a distribuição é do tipo CLIENT.
Detalhe de respostas
dataobject
Esta seção foi útil para você?
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"
}
}
Respostas de amostra

Atualizar envio de lote de cartões

O endpoint /cards/v1/batches/shipments/{shipmentId} permite atualizar o endereço de envio de um lote de cartões.

Considerações

O lote de cartões deverá ser nomeado fisicamente e possuir status CREATED.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
addressobject
receiverobject
Path Parameters
shipmentIdstringrequired
Id pública do envio
Detalhe de respostas
dataobject
Esta seção foi útil para você?
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"
}
}
Respostas de amostra

Ativar cartão

O endpoint /cards/v1/activation permite ativar um cartão físico e configurar um PIN.

Considerações

O usuário deve estar ativo e o cartão deverá possuir statusEMBOSSED.

O PIN a ser configurado:

  • Deve ter 4 dígitos
  • Não pode estar em uma sequência ascendente. Por exemplo: 1234
  • Não pode estar em uma sequência descendente. Por exemplo: 4321
  • Não pode ser formado por uma repetição de números. Por exemplo: 1111

Será possível usar o parâmetro previous_card_id, para especificar que um cartão é substituto de um anterior.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
user_idstringrequired
Id pública do titular do cartão
Exemplo: usr-1625758043579BAR6D4
panstringrequired
O número do cartão que está sendo ativado
Exemplo: 4242424242424242
pinstringrequired
Nova senha do cartão escolhida pelo usuário
Exemplo: 1234
previous_card_idstring
Se este atributo for enviado, o novo cartão será tratado como substituto do cartão fornecido.
Exemplo: crd-20gRqyp809SvDzXzhSeG2w6UiO5
Detalhe de respostas
dataobject
Esta seção foi útil para você?
POST/cards/v1/activation
{
"user_id":
"usr-1625758043579BAR6D4"
"pan":
"4242424242424242"
"pin":
"1234"
"previous_card_id":
"crd-20gRqyp809SvDzXzhSeG2w6UiO5"
}
Respostas de amostra

Remessas

A API de remessa contém todos os endpoints e webhooks necessários para criar uma remessa, obter informações sobre uma remessa e manter-se atualizado sobre eventos que afetam uma remessa.

WebHooks

Você precisará de um endpoint público para que possamos mantê-lo atualizado sobre as remessas em tempo real.

Considerações

Seu endpoint deve terminar em /shipping/updates

Nesse ponto, o notificaremos se houver atualizações sobre uma remessa. Você será responsável por buscar o recurso para obter o status atualizado.

Url de exemplo

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

Body

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

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

Segurança

Como medida de segurança, todas as notificações de novas informações incluirão uma assinatura hmac-sha256, mas a resposta não precisa ser assinada pelos clientes.

Assinatura hmac-sha256 da solicitação

Para garantir que os únicos participantes da comunicação sejam nossos backends (Pomelo e o Cliente), no momento da integração, forneceremos uma api-key e uma api-secret para assinar digitalmente o conteúdo da comunicação.

A seguir, explicamos com mais profundidade os processos de troca de chaves e assinatura da solicitação.

Processo de troca de chaves

Durante o processo de integração, criaremos uma api-key e uma api-secret específicas para você.

Também é possível usar gpg ou algum plugin de e-mail (como https://flowcrypt.com/).

Vejamos um exemplo usando openssl na linha de comando.

  1. Criamos a api-key e a 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. Você cria sua chave privada:
$ openssl genrsa -out private.pem 2048
$ openssl rsa -in private.pem -pubout -out public.pem
  1. Você nos envia sua chave pública public.pem por e-mail ou slack.

  2. Criptografamos o arquivo de credenciais com a chave pública que você nos fornecer:

$ openssl rsautl -encrypt -in api-credentials.txt -out api-credentials.txt.enc -inkey public.pem -pubin
  1. Enviamos o arquivo api-credentials.txt.enc por e-mail ou slack

  2. Você descriptografa o arquivo api-credentials.txt.enc com sua chave privada private.pem:

$ openssl rsautl -decrypt -in api-credentials.txt.enc -inkey private.pem
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=
  1. Você mantém a api-secret em um local seguro e acessível somente pelo aplicativo de autorização de pagamentos associado à api-key.

Processo de assinatura da solicitação

Juntamente com a solicitação de autorização ou ajuste, enviaremos headers HTTP com a assinatura, o carimbo de data e hora da assinatura e a api -key para que você possa verificar se a assinatura está correta.

Os headers HTTP que enviamos são:

  • x-api-key : este header permitirá identificar qual api-secret deve-se usar, caso vários pares de api-key e api-secret tenham sido configurados.

  • x-signature : este header contém a assinatura digital (body + timestamp + endpoint) que deve ser verificada para garantir a integridade da solicitação. Se a assinatura não corresponder, você deve rejeitar a solicitação.

  • x-timestamp : este header contém a hora em que a solicitação foi assinada no formato unix-epoch para que você possa verificar se a assinatura não expirou.

  • x-endpoint : o endpoint usado para gerar a assinatura. Use este header para gerar novamente a assinatura a ser validada, compare-a com o endpoint do seu serviço e verifique se elas correspondem.

Vejamos um exemplo de curl indicando como essas informações são enviadas dentro da solicitação:

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 construir a assinatura, pode-se usar o seguinte snippet de código (em python 3), como:

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

Criar remessa

O endpoint /shipments/v1/ é utilizado para criação de uma nova remessa.

Para o 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 disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID única em cada solicitação para utilizar nosso esquema de idempotência.
Exemplo: fRwX12Dg3345AD
Body Parameters
shipment_typestringrequired
Enum: CARD_FROM_WAREHOUSE
affinity_group_idstringrequired
Exemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
countrystringrequired
Exemplo: ARG
addressobject
receiverobject
Detalhe de respostas
dataobject
Esta seção foi útil para você?
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"
}
}
Respostas de amostra

Buscar remessa

O endpoint /shippining/v1/ permite pesquisar um grupo de remessas com base nos atributos que você especificar.

Considerações

Será necessário especificar os filtros desejados como parâmetros de acordo com o seguinte padrão: filter[campo]=valor. Por exemplo: filter[shipment_type]=BOX. Para filtrar um atributo com vários valores possíveis, você deve separar os valores com vírgulas. Vejamos um exemplo: filter[shipment_type]=BOX,WAREHOUSE

Os resultados serão paginados e pode-se especificar a quantidade de dados por página, bem como qual página visualizar, usando: page[1] e page[2]

Ordenação

É possível especificar a ordem dos resultados com certos parâmetros que deverão ser enviados como uma lista de strings no filtro do tipo sort. Por exemplo: /shipping/v1/?sort=status,shipment_type.

A ordenação padrão será crescente. Para especificar uma ordem decrescente, deve-se enviar o caractere '-' como prefixo do atributo. Por exemplo: /shipping/v1/?sort=status,-shipment_type.

Os atributos que podem ser ordenados são:

  • shipment_type
  • status
  • status_detail

Se um parâmetro estiver errado ou mal redigido, responderemos com um erro.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: 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
Tamanho de página.
page[number]number
Número de página. O número da primeira página é 0.
sortstring
Exemplo: pid, shipment_type, status, status_detail
Detalhe de respostas
idstring
Exemplo: shi-23hJL4bm94q9BFEd2sGhBjY6xbH
external_tracking_idstring
Exemplo: f923da123
statusstring
Enum: CREATEDPENDINGTRACKEDREJECTEDIN_WAREHOUSEIN_TRANSITDISTRIBUTIONDELIVEREDNOT_DELIVEREDSTART_OF_CUSTODYEND_OF_CUSTODYDESTRUCTIONACCIDENT
status_detailstring
Exemplo: IN_TRANSIT
shipment_typestring
Enum: SINGLE_CARDBOXWAREHOUSE_BOXCARD_FROM_WAREHOUSEEXTERNAL_SINGLE_CARDEXTERNAL_BOX
affinity_group_idstring
Exemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
created_atstring
Exemplo: 2020-07-10 15:00:00.000
batchobject
addressobject
receiverobject
Esta seção foi útil para você?
GET/shipping/v1/
Respostas de amostra

Obter remessa

O endpoint /shipping/v1/{shipment_id} é utilizado para obtenção de informações sobre uma remessa específica.

Considerações

Será preciso especificar o shipping_id para fazer a 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 disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
shipment_idstringrequired
ID da remessa
Detalhe de respostas
dataobject
Esta seção foi útil para você?
GET/shipping/v1/{shipment_id}
Respostas de amostra

Transações

Será preciso implementar e expor os endpoints “Authorization” e “ Adjustments” em seu backend para que possamos nos comunicar.

Fluxo do processador de pagamentos:

Flujo Online / Offline

Vamos consumir seus endpoints nestes momentos:

Durante o fluxo on-line

Toda vez que um usuário usa seu cartão em qualquer loja ou e-commerce.

Durante a conciliação

Quando a rede (Mastercard, Visa etc.) solicita a reconciliação de todos os pagamentos apresentados pelos estabelecimentos.

Considerações

Se houver diferença na reconciliação, solicitaremos uma correção de sua API. Precisaremos que seus endpoints respondam o mais rápido possível para garantir uma boa experiência do usuário. Se a resposta demorar, recusaremos a transação.

Idempotência

Como uma solicitação HTTP pode expirar, precisamos garantir que, ao tentar novamente, seja processada apenas uma vez. Para isso, em cada solicitação, enviaremos um header x-idempotency-key com uma ID única que deve ser processada com um cache na memória (por exemplo: redis).

No início de cada transação, você terá de verificar se a chave de idempotência que lhe enviamos já está no cache na memória e, dependendo se estiver ou não, você terá de fazer o seguinte:

O header de idempotência não existe no cache.

Será preciso armazenar em cache na memória a relação chave de idempotência → solicitação com um estado em trânsito com um TTL de 3 minutos.

Ao aprovar ou rejeitar a transação, você deverá armazenar em cache o resultado e atualizar o estado da chave de idempotência para “concluído”.

O header de idempotência existe no cache

Em caso de solicitação duplicada, será necessário verificar o status da transação no cache.

  • Se estiver com status “concluído”, você deve responder com um código HTTP 200 com o corpo esperado para o endpoint e completá-lo com o resultado do cache.
  • Se o status for em trânsito, você deverá responder com um código HTTP 425 (Too Early: RFC 8470) com o corpo esperado para o endpoint. Voltaremos a verificar a resposta a esta solicitação alguns milissegundos depois.

Segurança

A comunicação entre nossos backends deve ser estritamente segura, pois os endpoints permitirão que os recursos sejam carregados e deduzidos.

Para isso, exigimos que três medidas sejam implementadas:

  • Expor endpoint HTTPS
  • Whitelist dos IPs da Pomelo
  • Assinatura hmac-sha256 da solicitação e a resposta

Expor endpoint HTTPS

Toda comunicação conosco deve ser via HTTPS, independentemente de quem emite o certificado.

Estes são alguns dos fornecedores mais reconhecidos

Whitelist dos IPs da Pomelo

Sempre nos comunicaremos com seu backend a partir de IPs específicos. Recomendamos que você só aceite solicitações dos IPs abaixo e recuse quaisquer outras solicitações:

IPs da Pomelo:

  • Ambiente de testing/staging:
34.226.254.178            
44.198.3.59
  • Ambiente de produção:
34.206.159.176            
52.0.20.124

Assinatura hmac-sha256 da solicitação e a resposta

Para garantir que os únicos participantes da comunicação sejam nossos backends (Pomelo e o Cliente), no momento da integração, forneceremos uma api-key e uma api-secret para assinar digitalmente o conteúdo da comunicação.

O processo será mais ou menos assim:

1. Na integração, trocaremos as chaves api-key e api-secret.

2.

No momento de uma autorização de pagamento, assinamos com hmac-sha256 cada solicitação de autorização com api-secret.

4. Você valida a assinatura hmac-sha256 com sua api-secret que corresponde à api-key da solicitação.

5. Você autoriza a solicitação, debita os recursos do usuário e assina a resposta com hmac-sha256, usando a api-secret.

6. Verificamos a assinatura hmac-sha256 e finalizamos o processamento de pagamento.

Processo de troca de chaves

Durante o processo de integração, criaremos uma api-key e uma api-secret específicas para você.

Também é possível usar gpg ou algum plugin de e-mail (como https://flowcrypt.com/).

Vejamos um exemplo usando openssl na linha de comando.

1. Criamos a api-key e a 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. Você cria sua chave público-privada:

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

3. Você nos envia sua chave pública public.pem por e-mail ou slack.

4. Criptografamos o arquivo de credenciais com a chave pública que você nos fornecer:

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

5. Enviamos o arquivo api-credentials.txt.enc por e-mail ou slack

6. Você descriptografa o arquivo api-credentials.txt.enc com sua chave privada private.pem:

$ openssl rsautl -decrypt -in api-credentials.txt.enc -inkey private.pem
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=

7. Você mantém a api-secret em um local seguro e acessível somente pelo aplicativo de autorização de pagamentos associado à api-key.

Processo de assinatura da solicitação

Juntamente com a solicitação de autorização ou ajuste, enviaremos headers HTTP com a assinatura, o carimbo de data e hora da assinatura e a api -key para que você possa verificar se a assinatura está correta.

Os headers HTTP que enviamos são:

  • x-api-key : este header permitirá identificar qual api-secret deve-se usar, caso vários pares de api-key e api-secret tenham sido configurados.

  • x-signature : este header contém a assinatura digital (body + timestamp + endpoint) que deve ser verificada para garantir a integridade da solicitação. Se a assinatura não corresponder, você deve rejeitar a solicitação.

  • x-timestamp : este header contém a hora em que a solicitação foi assinada no formato unix-epoch para que você possa verificar se a assinatura não expirou.

  • x-endpoint : o endpoint para o qual a solicitação é realizada. Use este header para gerar novamente a assinatura a ser validada, e compare-o com o endpoint do seu serviço para verificar se eles correspondem.

Vejamos um exemplo de curl indicando como essas informações são enviadas dentro da solicitação:

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 construir a assinatura, pode-se usar o seguinte snippet de código (em python 3), como o exemplo:

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: será preciso assinar seu body junto com o timestamp e o endpoint de resposta com sua api-secret após realizar a operação. Observe que validaremos a assinatura e recusaremos a transação se a assinatura não corresponder ou tiver expirado.

Liquidação

Esse é um processo opcional, mas recomendamos executá-lo diariamente.

Em um bucket de S3 que disponibilizaremos, você encontrará esses arquivos:

  • Arquivo de transações
  • Arquivo de apresentação

Arquivo de transações

Contém as informações de cada transação que geramos no dia anterior. O nome do arquivo tem este formato: apresentaçõesyyyy_mm_dd.csv

Estrutura do arquivo de transações

{Atributo}DescriçãoValores permitidos
TRANSACTION_IDA ID que permite que a transação seja identificada como única.
LOCAL_TRANSACTION_DATE_TIME
TRANSACTION_TYPEIndica o tipo de transação.PURCHASE
WITHDRAWAL
EXTRACASH
REFUND
PAYMENT
REVERSAL_PURCHASE
REVERSAL_WITHDRAWAL
REVERSAL_EXTRACASH
REVERSAL_REFUND
REVERSAL_PAYMENT
PRODUCT_TYPEÉ o tipo de produtoPREPAID
CREDIT
DEBIT
PROVIDERÉ a marca do cartão emitido.VISA
MASTERCARD
AFFINITY_GROUP_ID
USER_IDA ID de usuário da Pomelo do titular do cartão.
CARD_ID
BINOs primeiros seis ou oito dígitos do número do cartão.
LAST_FOUROs últimos quatro dígitos do PAN.
ORIGINDOMESTIC: a transação ocorreu no país do emissor.
INTERNATIONAL: a transação não ocorreu no país do emissor.
MERCHANT_ID
MERCHANT_MCCCódigo de categoria do estabelecimento, conforme o ISO-18245.
MERCHANT_NAME
LOCAL_AMOUNTÉ o valor total da transação que deve ser deduzido do saldo do usuário, acrescido de impostos e taxas (quando aplicável). Sempre convertido para a moeda local do cartão.
LOCAL_CURRENCYCódigo de moeda de LOCAL_TOTAL no ISO_4217 formato ALPHA-3.
TRANSACTION_AMOUNTValor da transação sem impostos e na moeda original enviada pelo estabelecimento.
TRANSACTION_CURRENCYCódigo de moeda de TRANSACTION_TOTAL no ISO_4217 formato ALPHA-3.
SETTLEMENT_AMOUNTvalor da transação em USD, conforme enviado pela rede. As transações domésticas também terão esse campo em USD.
SETTLEMENT_CURRENCYCódigo de moeda de LOCAL_TOTAL no ISO_4217 formato ALPHA-3.
ENTRY_MODEComo o cartão foi usado no ponto de venda do estabelecimento.UNKNOWN
MANUAL
CHIP
CONTACTLESS
CREDENTIAL_ON_FILE
MAG_STRIPE
OTHERS
STATUSO status da transação.APPROVED
REJECTED
HELD
STATUS_DETAILRazão adicional por que a transação foi aprovada ou recusada.Veja a tabela abaixo
SOURCEIndica qual fluxo/processo desencadeou a transação, conforme visto pela Pomelo.ONLINE: origina-se no fluxo transacional a partir de transações em tempo real enviadas pela rede
CLEARING: origina-se durante o processo de acordo entre a Pomelo e a rede ao gerenciar o arquivo de liquidação
PURGE: transações que não foram apresentadas no arquivo de liquidação de rede.
ORIGINAL_TRANSACTION_IDEsse valor pode estar vazio se a transação não estiver relacionada a outra transação.
COUNTRY_CODEEste é o código do país no formato [ISO-3166] (https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).
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.

Tabela de STATUS_DETAIL

Status detailDescrição
CARD_BLOCKEDStatus do cartão BLOCKED.
CARD_DISABLEDStatus do cartão DISABLED
CARD_NOT_ACTIVEStatus do cartão EMBOSSED ou CREATED
CARD_NOT_CONFIGUREDO cartão está sem configurações.
CARD_NOT_FOUNDNão conseguimos encontrar o PAN do cartão.
CRYPTO_ERRORHá um erro nos criptogramas (EMV).
DUPLICATE_TRANSMISSION_DETECTEDRecebemos uma transação repetida da rede.
EXPIRED_CARDStatus do cartão EXPIRED.
EXTRA_FIELDSAs mensagens da rede vêm com campos inesperados.
INSUFFICIENT_FUNDSO cliente responde que a conta não dispõe de recursos.
INVALID_AMOUNTOs limites do grupo de afinidade foram ultrapassados.
INVALID_CVVO CVV não corresponde.
INVALID_EXPIRATION_DATEA data de validade recebida não corresponde à do cartão.
INVALID_MERCHANTO cliente recusou o merchant por algum motivo específico.
INVALID_PINPIN incorreto
INVALID_TRANSACTIONTransação inválida.
LOST_CARDStatus do cartão LOST.
MISSING_FIELDSAs mensagens da rede vêm sem campos obrigatórios.
NOT_DECLINEDUma transação vem com um valor de 0 para validar se a conta está ativa.
ORIGINAL_NOT_FOUNDÉ feita uma tentativa de reverter uma transação que não encontramos.
OTHERNão reconhecemos o caso.
RESTRICTED_USERStatus do usuário ACTIVE.
SECURITY_VIOLATIONExcede um limite de fraude.
SERVICE_UNAVAILABLEO cliente ou um serviço da Pomelo está inativo.
STOLEN_CARDStatus do cartão STOLEN.
SYSTEM_ERRORErro imprevisto no sistema.
APPROVEDO cliente aprovou uma transação.
TRANSACTION_NOT_PERMITTEDTipo de transação não permitido no grupo de afinidade.

Conciliação do arquivo de transações

Está na Pomelo?Está no cliente?Tem o mesmo status?Action
YYYNada a fazer/Marcar como correspondente
YYN1) Fazer um ajuste que debite/credite o usuário final, se aplicável.
2) Marcar como corresponte.
YNN1) IF STATUS == APPROVED: Fazer um ajuste que debite/credite o usuário final, se aplicável.
2) Marcar como corresponte.
NYNNão é um caso de uso possível.

Caso você esteja tentando ajustar um crédito a um usuário final que não tenha fundo suficientes na conta, você deve continuar tentando obter os fundos desse usuário.

Torna-se uma dívida entre o cliente e o usuário final.

Arquivo de apresentação

Contém as informações de cada transação apresentada pelos estabelecimentos no dia anterior. O nome do arquivo tem este formato: apresentaçõesyyyy_mm_dd.csv

Estrutura do arquivo de apresentação

AtributoDescriçãoValores permitidos
PRESENTMENT_ID
TRANSACTION_IDA ID da transação original que gerou a apresentação.
LOCAL_TRANSACTION_DATE_TIME
TRANSACTION_TYPEIndica o tipo de transação.PURCHASE
WITHDRAWAL
EXTRACASH
REFUND
PAYMENT
PRODUCT_TYPEÉ o tipo de produto.PREPAID
CREDIT
DEBIT
PROVIDERÉ a marca do cartão emitido.VISA
MASTERCARD
AFFINITY_GROUP_ID
USER_IDA ID de usuário da Pomelo do titular do cartão
CARD_ID
BINOs primeiros seis ou oito dígitos do número do cartão.
LAST_FOUROs últimos quatro dígitos do PAN.
ORIGINDOMESTIC: a transação ocorreu no país do emissor.
INTERNATIONAL: a transação não ocorreu no país do emissor.
MERCHANT_ID
MERCHANT_MCCCódigo de categoria do estabelecimento, conforme o ISO-18245.
MERCHANT_NAME
TRANSACTION_AMOUNTValor da transação sem impostos e na moeda original enviada pelo estabelecimento.
TRANSACTION_CURRENCYCódigo de moeda de TRANSACTION_TOTAL no ISO_4217 formato ALPHA-3.
SETTLEMENT_AMOUNTO valor da transação apresentado pela marca.
SETTLEMENT_CURRENCYO código da moeda de SETTLEMENT_AMOUNT no ISO_4217 formato ALPHA-3; se for uma transação doméstica, será apresentada em moeda local, caso contrário em USD.
DEBT_AMOUNTValor da transação na moeda a ser paga à Pomelo. Se o valor for devido à Pomelo, sempre é um valor positivo; caso contrário, será um valor negativo.
DEBT_CURRENCYO código da moeda de DEBT_AMOUNT no ISO_4217 formato ALPHA-3; se for uma transação doméstica, deverá ser paga em moeda local, caso contrário em USD.
RECONCILIATION_DATE
INTERCHANGE_FEEComissão por uma transação
INTERCHANGE_RATEValor alfanumérico que identifica a taxa de câmbio da transação apresentada pelo adquirente.
TAXImposto associado à taxa de câmbio, devido à regulamentação local. Esses valores devem ter um IVA (imposto sobre valor agregado) calculado..
FUNCTION_CODEEsse é o tipo de apresentação.FIRST_PRESENTMENT
SECOND_PRESENTMENT_FULL
SECOND_PRESENTMENT_PARTIAL
REVERSE_PRESENTMENTSignifica que a apresentação foi revertida a partir da rede.TRUE
FALSE
REASON_CODEMotivo da segunda apresentação.
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.

Conciliação do arquivo de apresentação

Nossa equipe financeira enviará uma notificação diariamente com a dívida a ser paga. Essa notificação terá todas as apresentações que recebemos no arquivo de apresentação.

Obtenção dos arquivos de Transações e Apresentações

Forneceremos um servidor SFTP de onde será possível baixar os arquivos de Transações e Apresentações.

Dispomos de dois ambientes para osw servidores SFTP, um de produção e outro de desenvolvimento.

Para se conectar aos servidores SFTP, precisaremos que você nos envie uma chave pública para gerar um usuário.

Aqui estão os dados para se conectar a cada ambiente:

Produção:

Host: sftp.pomelo.la
Porta: 22
Usuário: <tu_usuario> # aquele que geramos a partir de suas chaves públicas.

Desenvolvimento:

Host: sftp-dev.pomelo.la
{Puerto}: 22
Usuário: <tu_usuario> # aquele que geramos a partir de suas chaves públicas.

Para gerar a chave pública, você terá de usar o comando de acordo com seu sistema operacional:

Linux / MacOs:

1. Crie um par de chaves RSA, alterando a variável $Cliente pelo nome próprio

ssh-keygen -t rsa -b 2048 -C $Cliente

O comando criará um par de chaves RSA de 2048 bits por padrão. ​Você também pode criar uma chave maior, de 4096 bits, inserindo -b 4096.

O comando produz a seguinte saída:

Generating public/prive rsa key pair.
Digite um arquivo onde salvar a chave (/your_home/.ssh/id_rsa):

Pressione Enter para salvar o par de chaves em .ssh /, ou especifique outro local.

2. Crie uma senha para sua chave SSH.

Pressione Enter para deixá-la em branco e use apenas a chave para estabelecer conexões SSH. Insira uma senha para uma camada extra de segurança.

3. Obtenha a chave pública gerada, lendo o conteúdo do arquivo público

cat ~/.ssh/id_rsa.pub

A chave gerada começará com ssh-rsa.

Agora, você pode copiar e colar sua chave SSH pública em seu console Shell ou em qualquer servidor para estabelecer uma conexão segura.

Windows

Gere chaves SSH, usando PuTTY. Instale o PuTTY na página do desenvolvedor: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

1. Gere chaves SSH, usando PuTTY

Instale o PuTTY na página do desenvolvedor: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

2. Execute o gerador de chaves PuTTY SSH

  • Pressione a tecla Windows.
  • Escreva puttygen.
  • Clique com o botão direito do mouse em PuTTYgen.
  • Clique em Executar como administrador.
  • ​Clique em Sim se o sistema gerar a seguinte consulta: Deseja permitir que este aplicativo faça alterações em seu dispositivo?

3. Use PuTTY para criar um par de chaves SSH

Embora a ferramenta de geração de chaves PuTTY ofereça vários outros algoritmos, mostraremos como gerar chaves RSA, uma das mais usadas:

  • Na janela do gerador de chaves PuTTY, clique em Gerar.
  • Mova o cursor na caixa cinza para preencher a barra verde.
  • Gerando um par de chaves SSH no Putty.
  • Salve a chave pública, clicando no botão Salvar chave pública. Você terá, então, de escolher um local para salvar a chave e dar um nome à chave.
  • Salve a chave privada:
    • Clique no menu Conversões, na parte superior da tela.
    • Clique em Exportar chave OpenSSH.
    • O sistema perguntará se você quer salvar uma chave sem uma senha. Clique em Sim.
    • Escolha um local para salvar a chave (geralmente, a mesma pasta da chave pública).
    • Nomeie a chave (por exemplo, putty_key).

Autorizar transação

O endpoint/transactions/authorizations permite autorizar transações.

Enviaremos uma solicitação para autorizar ou recusar a transação.

Considerações

Esperamos uma resposta rápida para garantir uma boa experiência. Se a resposta demorar, recusaremos a transação.

Parâmetros disponíveis
Body Parameters
transactionobjectrequired
Informações relacionadas à transação
merchantobjectrequired
Informações relacionadas ao estabelecimento.
cardobjectrequired
Informações não confidenciais relacionadas ao cartão
installmentsobject
Informações relacionadas às parcelas de transação, este parâmetro será recebido apenas para autorizações de compra com parcelas em cartão de crédito.
userobjectrequired
Informações relacionadas ao usuário que realizou a transação.
amountobjectrequired
Informações relacionadas aos valores da transação
Detalhe de respostas
statusstring
Status que nos indica se devemos aprovar ou recusar a transação
Enum: APPROVEDREJECTED
messagestring
Mensagem descritiva com o resultado da operação
status_detailstring
Campo que permite rastrear por que a transação não foi aprovada
Enum: APPROVEDINSUFFICIENT_FUNDSINVALID_MERCHANTINVALID_AMOUNTSYSTEM_ERROROTHER
Esta seção foi útil para você?
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":[
...
]
}
}
Respostas de amostra

Ajustes

O endpoint /transactions/adjustments/{type} permite que você faça ajustes de crédito e débito nas transações.

Enviaremos uma solicitação para informar que a rede (MC, VISA) forçou uma autorização.

Considerações

Este endpoint é utilizado durante a conciliação e fluxos on-line, principalmente para ajustes durante o processo de liquidação e também em caso de devoluções.

Parâmetros disponíveis
Body Parameters
transactionobjectrequired
Informações relacionadas à transação
merchantobjectrequired
Informações relacionadas ao estabelecimento.
cardobjectrequired
Informações não confidenciais relacionadas ao cartão
installmentsobject
Informações relacionadas às parcelas de transação, este parâmetro será recebido apenas para autorizações de compra com parcelas em cartão de crédito.
userobjectrequired
Informações relacionadas ao usuário que realizou a transação.
amountobjectrequired
Informações relacionadas aos valores da transação
Path Parameters
typestringrequired
Tipo de operação que será executada sobre o saldo do usuário. Se for débito, o valor deverá ser descontado do saldo do usuário. Se for crédito, o valor deve ser adicionado ao saldo do usuário. OBSERVAÇÃO: É possível receber ajustes com valores muito pequenos, fica a critério do cliente afetá-los no saldo do usuário ou não.
Enum: debitcredit
Detalhe de respostas
Esta seção foi útil para você?
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":[
...
]
}
}
Respostas de amostra

Core

O serviço de Core permite criar e gerenciar as contas digitais de seus usuários.

Requisitos para criar uma conta

Para ter uma conta, seus usuários devem:

  • Estar cadastrados na Pomelo.
  • Ter status “Ativo”.
  • Tenha sua identidade verificada. Só fazemos esta verificação se tiver contratado o nosso produto Identity.

Ciclo de vida das contas

As contas terão um desses status:

  • ACTIVE: A conta está ativa e pode ser usada para fazer transações normalmente. Quando uma conta é criada, seu status inicial será ACTIVE.
  • FROZEN: A conta poderá receber valores, mas as transações de débito estarão bloqueadas.
  • DISABLED: Nenhuma transação na conta é permitida.
  • DELETED: A conta foi excluída sem possibilidade de ser reativada.

Para alterar o status de uma conta entre os estados ACTIVE, FREEZED e DISABLED, deve-se usar o endpoint PATCH deste serviço.

Para alterar o status de uma conta para DELETED, use o endpoint DELETE.

Possíveis respostas de erro

Se alguma operação falhar, retornaremos um erro com uma lista de possíveis operações associadas:

  • ACCOUNT_VALIDATION_ERROR: A conta não pôde ser validada corretamente. Por exemplo, quando a chave de idempotência usada na solicitação já está em uso por outro usuário.
    • CREATE
  • USER_VALIDATION_ERROR: Não foi possível validar a identidade do usuário ou o usuário não existe.
    • CREATE
  • CLIENT_VALIDATION_ERROR: Não foi possível identificar a qual cliente o usuário para o qual você está tentando criar uma conta pertence.
    • CREATE
  • USER_ACCOUNT_LIMIT_REACHED: O usuário atingiu o limite de contas que pode ter, sendo assim, não é possível criar uma nova conta.
    • CREATE
  • ACCOUNT_NOT_FOUND: A ID da conta não existe.
    • UPDATE
    • DELETE
  • ACCOUNT_DELETED: A ID da conta foi excluída.
    • UPDATE
    • DELETE
  • INVALID_ACCOUNT_STATUS: O status de atualização da conta é inválido.
    • UPDATE
    • DELETE
  • LOCKED_ACCOUNT_STATUS: Não é possível atualizar uma conta que modificamos na Pomelo.
    • UPDATE
    • DELETE
  • INVALID_UPDATE_STATUS_MOTIVE: A razão para atualizar o status da conta que você inseriu é inválida. Para DELETE as razões válidas são OTHER, INTERNAL_REASON, USER_REQUEST e FRAUD. Para DISABLED são OTHER, LOST, INTERNAL_REASON, STOLEN, FRAUD e INHIBITION. Para FROZEN são OTHER e SEIZURE
    • UPDATE
    • DELETE
  • ACCOUNT_HAS_FUNDS: Não é possível excluir uma conta que não esteja completamente vazia.
    • DELETE

Criar conta

O endpoint/core/accounts/v1 permite que você crie uma conta digital para um usuário Pomelo. Se você criar a conta corretamente, retornaremos um status 201.
Parâmetros disponíveis
Header Parameters
X-Idempotency-Keystringrequired

Id idempotente de criação de conta. Você precisará gerar esse valor para cada conta que deseja criar. Se duas solicitações idênticas tiverem o mesmo identificador de idempotência, você criará apenas uma conta, mesmo que ambas recebam uma resposta bem-sucedida.

Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
countrystringrequired
País da conta.
Enum: ARGBRA
currencystringrequired
Moeda da conta.
Enum: ARSBRL
metadataobject
Campo opcional para que você possa adicionar os dados extras que desejar.
Exemplo: {"extra_property_1":"My value"}
user_idstringrequired
ID do usuário proprietário da conta.
Exemplo: usr-20I2tIqG3buTsvHKKORrtY2MkFH
Detalhe de respostas
dataobjectrequired
Esta seção foi útil para você?
POST/core/accounts/v1
{
"country":
"ARG"
"currency":
"ARS"
"metadata":{
"extra_property_1":
"My value"
}
"user_id":
"usr-20I2tIqG3buTsvHKKORrtY2MkFH"
}
Respostas de amostra

Excluir conta

O endpoint/core/accounts/v1/{id} permitirá que você exclua uma conta específica. Isso definirá seu status como DELETED e não poderá mais ser usada para transações.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
status_update_motivestringrequired
Enum: OTHERINTERNAL_REASONUSER_REQUESTFRAUD
status_update_commentstring
Este campo é obrigatório quando o status_update_motive é OTHER.
Exemplo: Motivo da atualização do status da conta.
Path Parameters
idstringrequired
Exemplo: acc-20I4qJinTCudWvJULZygeC257wy
Detalhe de respostas
dataobjectrequired
Esta seção foi útil para você?
DELETE/core/accounts/v1/{id}
{
"status_update_motive":
"OTHER"
"status_update_comment":
"Motivo da atualização do status da conta ..."
}
Respostas de amostra

Atualizar conta

O endpoint /core/accounts/v1/{id} será usado para alterar o status de uma conta. Os status da conta podem alternar entre ACTIVE, FROZEN ou DISABLED. Para os dois últimos status, é necessário indicar a razão da alteração de status, usando a propriedade status_update_motive.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
statusstringrequired
Enum: ACTIVEDISABLEDFROZEN
status_update_motivestring
Este campo é obrigatório quando o status não é ACTIVE.
Enum: OTHERLOSTINTERNAL_REASONSTOLENFRAUDINHIBITIONSEIZURE
status_update_commentstring
Este campo é obrigatório quando o status_update_motive é OTHER.
Exemplo: Motivo da atualização do status da conta.
Path Parameters
idstringrequired
Exemplo: acc-20I4qJinTCudWvJULZygeC257wy
Detalhe de respostas
dataobjectrequired
Esta seção foi útil para você?
PATCH/core/accounts/v1/{id}
{
"status":
"ACTIVE"
"status_update_motive":
"OTHER"
"status_update_comment":
"Motivo da atualização do status da conta ..."
}
Respostas de amostra

Consultas

O Accounts Query API é um serviço que reúne todas as informações das contas digitais da Pomelo e as disponibiliza para consulta.

Permitirá a consulta de:

  • Informações das contas. Essas informações incluem identificadores bancários como a CVU (chave virtual uniforme) e o alias para a Argentina ou o PIX para o Brasil.
  • O saldo de cada conta.
  • As atividades de todas as suas contas.

O que é uma atividade?

Qualquer operação com a intenção de alterar o saldo de uma conta. Ou seja:

  • Transações concretizadas que alteraram o saldo de uma conta.
  • Transações que foram processadas, mas recusadas. Por exemplo, transações de débito que não pudemos processar devido a saldo insuficiente.
  • Transações não processadas, porque não atendem a algum requisito. Por exemplo, tentativas de pagamento com cartão que não puderam ser processadas, porque o CVV inserido está incorreto.

Recursos do Query API

  • Listar contas com seus respectivos saldos.
  • Obter informações e saldo de uma conta.
  • Listar atividades para todas as contas.
  • Listar as atividades de uma conta.
  • Obter informações sobre uma atividade.

Listar atividades

O endpoint/core/activities/v1 retorna uma lista paginada de todas as atividades. Pode-se usar filtros para especificar que apenas as atividades de uma determinada conta sejam retornadas.
Parâmetros disponíveis
Header Parameters
Accept-Languagestring

Idiomas ordenados de acordo com sua preferência. Especificação técnica

Exemplo: Accept-Language: en-US;q=1.0,en-*;q=0.5
Authorizationstringrequired
Exemplo: Bearer {access_token}
Query Parameters
page[number]integer(format: int32)
Número da página
page[size]integer(format: int32)
Tamanho da página
Exemplo: 5
filter[country]string
País de origem da conta.
Exemplo: ARG
Enum: ARGBRAMEX
filter[account_id]string
ID da conta da qual deseja-se obter a lista de atividades.
Exemplo: acc-20I5vMjljS3VEyafcX8lA3T3g0c
filter[result]array
Lista de resultados das transações associadas às atividades.
Exemplo: APPROVED,PENDING,REJECTED
Enum: APPROVEDREJECTEDPENDING
filter[type]array
Lista de tipos de transações associadas às atividades que deseja-se obter na lista.
Exemplo: CARD_PURCHASE,EXTRACASH
Enum: CARD_PURCHASEEXTRACASHCASHOUT_STORECASHOUT_ATMBANK_TRANSFER_INBANK_TRANSFER_OUTCASHOUTCASHINMANUAL_MOVEMENTCLIENT_PAYMENT
filter[created_from]string(format: date-time)
Data base de atualização das atividades que deseja-se obter na lista.
Exemplo: 2021-12-30T14:47:30.969Z
filter[created_until]string(format: date-time)
Data de criação das atividades que deseja-se obter na lista.
Exemplo: 2021-12-31T14:47:30.969Z
filter[updated_from]string(format: date-time)
Data base de atualização das atividades que deseja-se obter na lista.
Exemplo: 2021-12-30T14:47:30.969Z
filter[updated_until]string(format: date-time)
Data limite de atualização das atividades que deseja-se obter na lista.
Exemplo: 2021-12-31T14:47:30.969Z
filter[upsert_from]string(format: date-time)
Data limite de criação ou atualização das atividades que deseja-se obter na lista.
Exemplo: 2021-12-30T14:47:30.969Z
filter[upsert_until]string(format: date-time)
Data limite de criação ou atualização das atividades que deseja-se obter na lista.
Exemplo: 2021-12-31T14:47:30.969Z
sortstring
Ordenação que deseja-se aplicar à lista.
Exemplo: -created_at,total_amount
Detalhe de respostas
metaobject
dataarray
Esta seção foi útil para você?
GET/core/activities/v1
Respostas de amostra

Obter atividades

O endpoint/core/activities/v1/{id} permite obter informações sobre a atividade especificada.
Parâmetros disponíveis
Header Parameters
Accept-Languagestring

Idiomas ordenados de acordo com sua preferência. Especificação técnica

Exemplo: Accept-Language: en-US;q=1.0,en-*;q=0.5
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
idstringrequired
Detalhe de respostas
dataobjectrequired
Esta seção foi útil para você?
GET/core/activities/v1/{id}
Respostas de amostra

Listar contas

O endpoint/core/accounts/v1 retorna uma lista paginada de contas digitais juntamente com seus saldos.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Query Parameters
page[number]integer(format: int32)
Número da página
page[size]integer(format: int32)
Tamanho da página
Exemplo: 5
filter[country]string
País de origem da conta.
Exemplo: ARG
Enum: ARGBRAMEX
filter[status]array
Estado das contas que deseja obter na lista.
Exemplo: ACTIVE,DISABLED,DELETED,FROZEN
Enum: ACTIVEDISABLEDDELETEDFROZEN
filter[user_id]string
ID do usuário cujas contas deseja-se obter.
Exemplo: usr-20I2tIqG3buTsvHKKORrtY2MkFH
filter[created_from]string(format: date-time)
Data base de atualização das atividades que deseja-se obter na lista.
Exemplo: 2021-12-30T14:47:30.969Z
filter[created_until]string(format: date-time)
Data de criação das atividades que deseja-se obter na lista.
Exemplo: 2021-12-31T14:47:30.969Z
sortstring
Ordenação que deseja-se aplicar à lista.
Exemplo: -created_at,balance
Detalhe de respostas
metaobject
dataarrayrequired
Esta seção foi útil para você?
GET/core/accounts/v1
Respostas de amostra

Obter conta

O endpoint /core/accounts/v1/{id} retorna as informações de conta solicitadas, juntamente com seu saldo.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
idstring(maxLength: 256, minLength: 0)required
Detalhe de respostas
dataobject
Esta seção foi útil para você?
GET/core/accounts/v1/{id}
Respostas de amostra

Transações

Este serviço permite autorizar transações.

As transações têm apenas dois status possíveis:

  • APPROVED: se a transação for aprovada.
  • REJETED: se a transação for recusada.

Todas as transações aprovadas modificarão o saldo da conta pelo valor 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 transações de saque de valores da conta.
  • CREDIT: para transações de depósito de valores na conta.

Todas as transações têm um tipo, que indicamos com o parâmetro type. Cada tipo de transação possui dados diferentes, que são enviados com a transação dentro do objeto tx_properties.

É possível solicitar dados extras de todas as transações, usando o objeto metadata.

A propriedade details pode ser usada para decompor o valor total de uma transação em suas partes componentes. Por exemplo, suponhamos que está sendo processada uma transação que representa uma compra em uma loja digital no valor total de US$ 149,99. Suponhamos ainda que esse total seja composto por:

  • US$ 119,00 da compra
  • US$ 40,00 de impostos
  • -US$ 10,00 de descontos

Essa decomposição pode ser relatada, adicionando múltiplos itens à lista details. Cada detalhe deve estar associado a um tipo:

  • BASE: gasto base da transação.
  • FEE: gastos com comissão.
  • TAX: Taxas.
  • EXTRACASH: saques de quantias em dinheiro.
  • DISCOUNT: Descontos.

É possível agregar mais de um detalhe ao mesmo tipo. A única restrição é que a soma dos valores dos detalhes seja igual ao valor total da transação.

Tipos de processamento

Todas as transações contêm um campo process_type, que pode conter qualquer um desses valores:

  • ORIGINAL: transação nova.
  • ADJUSTMENT: Ajuste.
  • REFUND: reembolso ou devolução.
  • REVERSAL: reverter.

Para transações REFUND ou REVERSAL , a transação original que as motiva pode ser especificada. Essa transação é conhecida como “transação inicial” e a indicamos usando o campo parent_tx_id.

Idempotência

As solicitações de autorização de transação possuem um mecanismo de idempotência para evitar o processamento duplicado.

Deve-se acompanhar cada solicitação de autorização com um header X-Idempotency-Key que tenha um identificador único para a transação a ser processada. Caso não obtenha resposta ou receba uma resposta com um código de estado do tipo 5xx, será necessário repetir a solicitação com a mesma chave de idempotência até obter uma resposta bem sucedida (code 201).

Solicitações repetidas usando a mesma chave de idempotência resultarão apenas na criação de uma transação. A primeira solicitação criará a transação e as seguintes gerarão a mesma resposta que foi gerada para a primeira solicitação, mas não criarão uma nova transação.

Se uma solicitação de autorização tiver uma chave de idempotência que você já tenha usado em outra transação, responderemos com um erro.

Respostas

As transações que processamos corretamente são relatadas com um status code 201. Mas atenção: esse status não indica se a transação foi aprovada. Para sabê-lo, será necessário ler o campo resultado da resposta e identificar se seu valor é APROVED ou REJECTED.

Qualquer outro código de status mostra que algo deu errado e indicaremos a razão da rejeição no campo rejection_reason. Este campo pode assumir os seguintes valores:

  • INSUFFICIENT_FUNDS: a conta não tem saldo suficiente.
  • ACCOUNT_DISABLED: a conta está desativada.
  • ACCOUNT_FROZEN: a conta não processa transações de débito (DEBIT).
  • CLIENT_MONTHLY_AMOUNT_LIMIT_REACHED: ultrapassou o limite mensal de movimentação.
  • CLIENT_DAILY_AMOUNT_LIMIT_REACHED: ultrapassou o limite de movimentos diários.
  • PROCESS_TIME_EXPIRED: a transação não iniciou o processamento antes do horário indicado pelo campo process_before, que é opcional.

Quando não podemos processar uma transação, retornaremos uma resposta de erro com o campo error_code indicando o motivo:

  • ACCOUNT_NOT_FOUND: Não encontramos a conta.
  • INVALID_AUTHORIZATION_REQUEST: a solicitação para autorizar a transação não é válida.
  • INVALID_PARENT_TX_ID: a transação inicial especificada é inválida.
  • DUPLICATED_IDEMPOTENCY_KEY: Você já usou a chave da idempotência em outra transação.

Autorizar transação

O endpoint/core/transactions/v1 permite autorizar transações de entrada e saída de dinheiro de contas digitais. As transações processadas com êxito retornarão o código de status 201, independentemente de terem sido aprovadas ou rejeitadas. Verifique o campo de resultado para ver o resultado.
Parâmetros disponíveis
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
account_idrequired
ID de una cuenta de Pomelo
Exemplo: acc-23GMRyaPjVbczjGtLfQ6zgUJmLv
typestringrequired
Tipo de transação.
Enum: CARD_PURCHASEEXTRACASHCASHOUT_STORECASHOUT_ATMBANK_TRANSFER_INBANK_TRANSFER_OUTCASHINCASHOUTMANUAL_MOVEMENTCLIENT_PAYMENT
process_typestringrequired
Indica se a transação é um movimento original, um reembolso, uma transação reversa ou um ajuste.
Exemplo: REFUND
Enum: ORIGINALADJUSTMENTREFUNDREVERSAL
parent_tx_id
ID de una transacción.
Exemplo: atx-23GMkfOa7V1MqUlvEic4Dp7XhTT
dataobject
entry_typestringrequired
Indica se a transação contempla depósito ou débito de quantia em dinheiro em/de uma conta. Para depósito, deve-se usar CREDIT y, para débito, CREDIT.
Exemplo: DEBIT
Enum: CREDITDEBIT
total_amountstringrequired
Valor total da transação.
Exemplo: 999.99
process_beforestring(format: date-time)
Este campo é opcional e indica um prazo limite para o processamento de uma transação. Útil para fluxos assíncronos.
Detalhe de respostas
idstringrequired
Exemplo: atx-230ReKOtS2lv0yUi2FKG98ycdXZ
resultstringrequired
Exemplo: REJECTED
Enum: APPROVEDREJECTED
rejection_reasonstring
Exemplo: 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
Esta seção foi útil para você?
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-20T13:34:08.964Z"
}
Respostas de amostra

Webhooks

Este serviço será responsável por notificá-lo de todas as atividades das suas contas.

Uma notificação pode se referir a uma criação ou a uma modificação de uma atividade. Para determinar qual é o caso, basta ler o campo type, que terá algum desses valores:

  • ACTIVITY_CREATED: trata-se de uma notificação sobre a criação de uma nova atividade.
  • ACTIVITY_UPDATED: trata-se de uma notificação sobre a modificação de uma atividade. As atividades podem alterar seu status de PENDING para APPROVED ou de PENDING para REJECTED.

Processo de verificação da assinatura digital da request

Juntamente com a notificação, enviaremos um conjunto de headers HTTP que servirão para verificar a sua autenticidade.

Os headers HTTP que enviamos são:

  • x-api-key : este header permitirá identificar qual api-secret deve-se usar, caso vários pares de api-key e api-secret tenham sido configurados.

  • x-signature : este header contém a assinatura digital que deve ser verificada para garantir a integridade da solicitação. Se a assinatura não corresponder, você deve rejeitar a solicitação.

  • x-timestamp : este header contém a hora em que a solicitação foi assinada no formato unix-epoch para que você possa verificar se a assinatura não expirou.

  • x-endpoint : o endpoint para o qual a solicitação é realizada. Use este header para gerar novamente a assinatura a ser validada, e compare-o com o endpoint do seu serviço para verificar se eles correspondem.

A assinatura digital é um código HMAC-SHA256 construído usando o api-secret e uma série de bytes composta pela concatenação do timestamp, do endpoint e do request body codificados em UTF-8.

A seguir é usado um pseudo-código para verificar se a assinatura digital de uma request é 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

Notificação de atividades

O endpoint deve estar no serviço do cliente para que possa receber as solicitações das atividades criadas/atualizadas. Se o request retornar um código HTTP do tipo 2xx, ele não será enviado novamente e será marcado como Enviado corretamente. Caso contrário, tentaremos novamente.
Parâmetros disponíveis
Header Parameters
X-Api-Keystringrequired
Este header permitirá identificar qual api-secret deve-se usar, caso vários pares de api-key e api-secret tenham sido configurados.
Exemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este header contém a assinatura digital (timestamp + endpoint + body) que deve ser verificada para garantir a integridade da solicitação. Se a assinatura não corresponder, você deve rejeitar a solicitação.
Exemplo: 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ó.
Exemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
Esse header é usado para gerar novamente a assinatura a ser verificada e você deverá compará-la com o endpoint de seu serviço para verificar se correspondem.
Exemplo: X-Endpoint: /client/api/activities/updates
Body Parameters
typestringrequired
Tipo de processo da atividade.
Exemplo: ACTIVITY_CREATED
versionstringrequired
Número da versão do evento.
Exemplo: 1.0.0
idempotency_keystringrequired
Identificador idempotente para criar o evento.
Exemplo: act-20I2tIqG3buTsvHKKORrtY2MkFH
datetimestring(format: date-time)required
Data da criação do evento.
Exemplo: 2021-12-31T23:59:59.999Z
activityobject
Esta seção foi útil para você?
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"
}
}
Respostas de amostra

Cash Networks Argentina

Este serviço permite que você se integre com diferentes redes financeiras para consultar os dados de uma conta e realizar depósitos (cash in) ou registrar intenções de retirada de dinheiro (cash out intent).

Para fazer depósitos, cada conta terá um alias que permitirá identificá-la em uma rede de pagamento. Este alias é gerado e associado automaticamente à conta quando ela é criada.

Para os casos de retirada de dinheiro, será necessário registrar um cash out intent, que, junto com o alias, poderá ser usado para sacar dinheiro de uma conta nas redes de pagamento habilitadas.

PaísNetworkID
ArgentinaPago FácilPAGO_FACIL

Criar intenção de cash out

O endpoint POST /networks/cash/v1/cashout/intents permitirá que você gere uma intenção de cash out para uma determinada conta. Cada cash out intent representa a intenção de sacar dinheiro do saldo de uma conta por meio de uma rede de pagamento.

Considerações

Só pode existir um cash out intent ativo para cada conta e rede. O cash out intent é resolvido quando o saque é efetivamente realizado através de uma rede de dinheiro ou quando a data de vencimento expira. A criação de um novo cash out intent substitui o anterior.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
account_idstringrequired
Identificador da conta
Exemplo: acc-20I4qJinTCudWvJULZygeC257wy
network_namestringrequired
Identificador da rede de pagamento
Exemplo: PAGO_FACIL
amountstring
Valor do cash out intent
Exemplo: 397.67
Detalhe de respostas
dataobject
metaobject
Esta seção foi útil para você?
POST/networks/cash/v1/cashout/intents
{
"account_id":
"acc-20I4qJinTCudWvJULZygeC257wy"
"network_name":
"PAGO_FACIL"
"amount":
"397.67"
}
Respostas de amostra

Lista de cash out intents

O endpoint GET /networks/cash/v1/cashout/intents/{account_id} permite que você obtenha o último cash out intent vigente. Para que um cash out intent seja considerado vigente, deve-se cumprir as seguintes condições:

  • Que ele não tinha sido usado para um saque.
  • Que ele não tenha expirado.
  • Que ele não tenha sido substituído por um novo cash out intent.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
account_idstringrequired
Identificador da conta
Exemplo: acc-20I4qJinTCudWvJULZygeC257wy
Detalhe de respostas
dataobject
metaobject
Esta seção foi útil para você?
GET/networks/cash/v1/cashout/intents/{account_id}
Respostas de amostra

Obter alias de cash in

O endpoint GET /networks/cash/v1/alias/{account_id} permitirá que você obtenha o alias de uma conta. Trata-se de um valor único associado à conta, que irá ajudá-lo a fazer uma operação de cash in na rede de pagamentos.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
account_idstringrequired
Identificador da conta
Exemplo: acc-20I4qJinTCudWvJULZygeC257wy
Detalhe de respostas
dataobject
metaobject
Esta seção foi útil para você?
GET/networks/cash/v1/alias/{account_id}
Respostas de amostra

Cash Networks Brasil

Este serviço permite que você se integre com diferentes redes financeiras para consultar os dados de uma conta e registrar intenções de depósitos de dinheiro (cash in intent) para uma conta em uma rede de dinheiro.

Para fazer depósitos, é preciso registrar um cash in intent em alguma das redes de pagamento habilitadas.

PaísNetworkID
BrasilBoletoBOLETO

Criar cash in intent

O endpoint POST /networks/cash/v1/cashin/intents permitirá que você gere uma intenção de cash in para uma determinada conta.. Cada cash out intent representa a intenção de sacar dinheiro do saldo de uma conta por meio de uma rede de pagamento.

Ciclo de vida

O cash in intent é resolvido quando o depósito de dinheiro é efetivamente realizado por meio de uma rede financeira ou quando a sua data de vencimento expira, o que acontecer primeiro.

O cash in intent pode ter diferentes status, dependendo de qual ação tiver sido aplicada::

  • ACTIVE: o cash in intent está ativo e você pode usá-lo até a data de validade (expires_at). Quando a data de vencimento expira, não é mais possível utilizar esse cash in intent para realizar o depósito, e será necessário gerar um novo..
  • REJECTED: a integração com a rede de dinheiro rejeitou a criação do cash in intent..
  • PAID: o cash in intent foi pago integralmente no valor solicitado..
  • PARTIALLY_PAID: o cash in intent foi parcialmente pago, o que significa que a soma dos pagamentos realizados em nome desse cash in intent é menor do que o valor solicitado.. É possível fazer pagamentos parciais até a data de vencimento do cash in intent..
  • CANCELLED: este status pode ser obtido de diferentes maneiras.. A primeira é pelo cancelamento do cash in intent com o endpoint de cancelamento; a segunda pelo cancelamento proativo do cash in intent gerado pela parte do provedor da rede de dinheiro..
Parâmetros disponíveis
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
account_idstringrequired
Identificador da conta
Exemplo: acc-20I4qJinTCudWvJULZygeC257wy
networkstringrequired
Identificador da rede de pagamento
Exemplo: BOLETO
amountstringrequired
Valor do cash in intent
Exemplo: 397.67
Detalhe de respostas
dataobject
Esta seção foi útil para você?
POST/networks/cash/v1/cashin/intents
{
"account_id":
"acc-20I4qJinTCudWvJULZygeC257wy"
"network":
"BOLETO"
"amount":
"397.67"
}
Respostas de amostra

Obter cash in intent

O endpoint GET /networks/cash/v1/cashin/intents/{intent_id} permite obter todos os dados de um cash in intent através do seu ID.
Parâmetros disponíveis
Path Parameters
intent_idstringrequired
Identificador do cash in intent
Exemplo: cin-20I4qJinTCudWvJULZygeC257wy
Detalhe de respostas
dataobject
Esta seção foi útil para você?
GET/networks/cash/v1/cashin/intents/{intent_id}
Respostas de amostra

Cancelar cash in intent

O endpoint DELETE /networks/cash/v1/cashin/intents/{intent_id} permite cancelar um cash in intent.
Parâmetros disponíveis
Path Parameters
intent_idstringrequired
Identificador do cash in intent
Exemplo: cin-20I4qJinTCudWvJULZygeC257wy
Detalhe de respostas
dataobject
Esta seção foi útil para você?
DELETE/networks/cash/v1/cashin/intents/{intent_id}
Respostas de amostra

Listar cash in intents por conta

O endpoint GET /networks/cash/v1/cashin/intents/account/{account_id} permite listar todos os cash in intents de uma determinada conta.
Parâmetros disponíveis
Query Parameters
filter[status]string
Status
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)
Tamanho da página
Exemplo: 10
Path Parameters
account_idstringrequired
Identificador da conta
Exemplo: acc-20I4qJinTCudWvJULZygeC257wy
Detalhe de respostas
dataobject
Esta seção foi útil para você?
GET/networks/cash/v1/cashin/intents/account/{account_id}
Respostas de amostra

Contas Bancárias Argentinas

O serviço de Bank Account API dentro do fluxo de transferências é responsável por gerenciar os atributos bancários da conta e obter as informações de uma conta de destino ao se iniciar uma transferência.

Dentro da gestão dos atributos de uma conta está a mudança do alias. Cada conta é criada com uma CVU (Chave Virtual Uniforme) e um alias predefinido, sendo que este último pode ser modificado pelo usuário de acordo com a sua preferência.

Quanto à obtenção de informações de uma conta de destino, cada transferência realizada começa com a validação da conta de destino, por meio da CVU ou do alias. Esse serviço é responsável por fazer essa gestão e retornar à conta de destino já validada, com informações adicionais do titular: CBU (Chave Bancária Uniforme), código do banco, nome e CUIT (Código Único de Identificação Tributária).

Obter informações de uma conta

Parâmetros disponíveis
Path Parameters
id-typestringrequired
Exemplo: ALIAS
Enum: ALIASCBUCVU
id-valuestringrequired
Exemplo: EVIL.DOG
Detalhe de respostas
dataobject
Esta seção foi útil para você?
GET/networks/bank/v1/transfers/destination-information/{id-type}/{id-value}
Respostas de amostra

Atualizar atributos da conta

Parâmetros disponíveis
Body Parameters
keystring
Exemplo: ALIAS
valuestring
Exemplo: NUEVO.ALIAS
Path Parameters
account-idstringrequired
Detalhe de respostas
dataobject
Esta seção foi útil para você?
PATCH/networks/bank/v1/accounts/{account-id}
{
"key":
"ALIAS"
"value":
"NUEVO.ALIAS"
}
Respostas de amostra

Contas Bancárias Brasil

O serviço de Bank Account API dentro do fluxo de transferências é responsável pela gestão dos atributos bancários da conta.

Dentro da gestão dos atributos de uma conta está o ABM da chave PIX.

Considerações:

  • No momento, só temos as chaves aleatórias disponíveis.
  • Será possível criar e excluir chaves aleatórias sem limite.
  • É possível ter até 5 chaves ativas simultaneamente.

Obter lista de chaves PIX

Parâmetros disponíveis
Path Parameters
account_idstringrequired
Exemplo: acc-0ujsszgFvbiEr7CDgE3z8MAUPFt
Detalhe de respostas
dataobject
Esta seção foi útil para você?
GET/networks/bank/v1/accounts/{account_id}/keys
Respostas de amostra

Criação da chave PIX

Parâmetros disponíveis
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
account_idstring
Exemplo: acc-0ujsszgFvbiEr7CDgE3z8MAUPFt
typestring
Exemplo: EVP
Detalhe de respostas
dataobject
Esta seção foi útil para você?
POST/networks/bank/v1/key/pix
{
"account_id":
"acc-0ujsszgFvbiEr7CDgE3z8MAUPFt"
"type":
"EVP"
}
Respostas de amostra

Excluir chave PIX

Parâmetros disponíveis
Path Parameters
keystringrequired
Exemplo: 41c2b4e0-9425-43a0-8087-b2d239f00b63
Detalhe de respostas
dataobject
Esta seção foi útil para você?
DELETE/networks/bank/v1/{account_id}/key/pix/{key}
Respostas de amostra

Transferências Argentina

A transferência será feita mediante envio na Transfer API, uma vez que as informações da conta de destino são validadas pelo serviço de Bank Account API.

A resposta da transferência pode ser síncrona ou assíncrona. No caso de uma resposta síncrona, o serviço de Transfer API dará um retorno sobre o status final da transação (SUCCESS ou FAILED). Se a resposta for assíncrona (porque está levando mais alguns segundos), o serviço de Transfer API dará um retorno de status pendente síncrono (IN_PROGRESS), e a notificação do status final da transação ficará disponível como Atividade por meio do serviço de Webhooks do Core.

Fazer transferência

Parâmetros disponíveis
Header Parameters
X-Idempotency-Keystring
Body Parameters
account_idstring(format: uuid)
Exemplo: acc-14688cf5-1b2d-41b1-ba0d-9e669b8540b9
credit_accountobject
amountobject
conceptstring
Exemplo: VAR
Enum: ALQAPCBRHBRNCUOEXPFACHABHONOINOIHPREROPSEGSISSONVAR
descriptionstring
Exemplo: Pago
Detalhe de respostas
dataobject
Esta seção foi útil para você?
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"
}
Respostas de amostra

Transferências Brasil

A transferência é feita em dois passos simples:

  • Validação da conta de destino usando uma chave PIX (por meio do endpoint “Obter informações de chave PIX do destino”)
  • Obtidas as informações da conta de destino, a segunda etapa da operação é enviar a própria transação (por meio do endpoint “Fazer transferência”)

A resposta da transferência pode ser síncrona ou assíncrona. No caso de uma resposta síncrona, o serviço de Transfer API dará um retorno sobre o status final da transação (SUCCESS ou FAILED). Se a resposta for assíncrona (porque está levando mais alguns segundos), o serviço de Transfer API dará um retorno de status pendente síncrono (IN_PROGRESS), e a notificação do status final da transação ficará disponível como Atividade por meio do serviço de Webhooks do Core.

Obter informações de chave pix destino

Parâmetros disponíveis
Path Parameters
account_idstringrequired
Sender account id
Exemplo: acc-26AA71defpMZiKvkwk2fwkCRRYU
keystringrequired
Exemplo: 22222222222
Detalhe de respostas
dataobject
Esta seção foi útil para você?
GET/networks/bank/v1/transfers/{account_id}/key/{key}
Respostas de amostra

Fazer transferência

Parâmetros disponíveis
Header Parameters
X-Idempotency-Keystringrequired
Body Parameters
transaction_idstring
Exemplo: tr-9c94e7ce-792e-11ec-90d6-0242ac120003
valuenumber
Exemplo: 100
descriptionstring
Exemplo: Teste de transferência
Detalhe de respostas
dataobject
Esta seção foi útil para você?
POST/networks/bank/v1/transfers/out
{
"transaction_id":
"tr-9c94e7ce-792e-11ec-90d6-0242ac120003"
"value":
100
"description":
"Teste de transferência"
}
Respostas de amostra

Identity

O serviço de Identity permite que você gerencie o processo de integração de seus usuários de forma ágil e simples, confirmando sua identidade e prevenindo fraudes.

Criar sessão

O endpoint identity/v1/sessions permite que você crie uma nova sessão de validação de identidade e retorne um identificador exclusivo para ela.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Body Parameters
user_idstring(format: uuid)required
USER ID
Detalhe de respostas
dataobject
Esta seção foi útil para você?
POST/identity/v1/sessions
{
"user_id":
"a169451c-8525-4352-b8ca-070dd449a1a5"
}
Respostas de amostra

Buscar sessão

O endpoint /sessions permite realizar uma pesquisa com filtros específicos.

Considerações

Será necessário especificar os filtros desejados como parâmetros de acordo com o seguinte padrão: filter[field]=value. Por exemplo: filter[status]=IN_PROGRESS

Os resultados serão fornecidos por página. É possível especificar a quantidade de dados por página e também qual página se deseja visualizar.

Período

Há um filtro para o campo created_at, que pode er usado para obter as sessões criadas dentro de um intervalo de datas. Por exemplo: filter[created_at][from]=2021-07-27&filter[created_at][to]=2021-07-28

Ordenação

É possível especificar a ordem dos resultados com certos parâmetros que deverão ser enviados como uma lista de strings no filtro do tipo sort. Por exemplo: ?sort=status,user_id

A ordenação padrão será crescente. Para especificar uma ordem decrescente, deve-se enviar o caractere '-' como prefixo do atributo. Por exemplo: ?sort=status,-user_id.

Os atributos a serem pedidos são user_id, status e created_at.

Se um parâmetro estiver errado ou mal redigido, responderemos com um erro.

Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Query Parameters
filter[user_id]string
filter[status]string
Exemplo: CREATED
Enum: CREATEDIN_PROGRESSPROCESSINGREJECTEDNOT_VALIDATEDCANCELLED
filter[created_at][from]string
ISO 8601
Exemplo: 1998-08-20
filter[created_at][to]string
ISO 8601
Exemplo: 1998-08-20
page[size]number
page[number]number
Detalhe de respostas
dataarray
metaobject
Esta seção foi útil para você?
GET/identity/v1/sessions
Respostas de amostra

Obter sessão

O endpoint identity/v1/session/{id} permite que você obtenha dados de uma sessão de validação de identidade.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
uuidrequired
Session ID
Detalhe de respostas
dataobject
Esta seção foi útil para você?
GET/identity/v1/sessions/{uuid}
Respostas de amostra

Cancelar sessão

O endpoint identity/v1/session/{id} permite que você cancele uma sessão de validação de identidade.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
uuidstring(format: uuid)required
Session ID
Detalhe de respostas
Esta seção foi útil para você?
DELETE/identity/v1/sessions/{uuid}
Respostas de amostra

Obter relatório de sessão

O endpoint identity/v1/sessions/{id}/report permite que você obtenha os dados de um usuário coletados em uma sessão de validação de identidade.
Parâmetros disponíveis
Header Parameters
Authorizationstringrequired
Exemplo: Bearer {access_token}
Path Parameters
uuidstringrequired
Detalhe de respostas
dataobject
Esta seção foi útil para você?
GET/identity/v1/sessions/{uuid}/report
Respostas de amostra

Webhooks

Este serviço será responsável por notificá-lo quando uma sessão de validação de identidade for concluída.

Processo de verificação da assinatura digital da request

Juntamente com a notificação, enviaremos um conjunto de headers HTTP que servirão para verificar a sua autenticidade.

Os headers HTTP que enviamos são:

  • x-api-key : este header permitirá identificar qual api-secret deve-se usar, caso vários pares de api-key e api-secret tenham sido configurados.

  • x-signature : este header contém a assinatura digital (body + timestamp + endpoint) que deve ser verificada para garantir a integridade da solicitação. Se a assinatura não corresponder, você deve rejeitar a solicitação.

  • x-timestamp : este header contém a hora em que a solicitação foi assinada no formato unix-epoch para que você possa verificar se a assinatura não expirou.

  • x-endpoint : o endpoint usado para gerar a assinatura. Use este header para gerar novamente a assinatura a ser validada, compare-a com o endpoint do seu serviço e verifique se elas correspondem.

A assinatura digital é um código HMAC-SHA256 construído usando o api-secret e uma série de bytes composta pela concatenação do timestamp, do endpoint e do request body codificados em UTF-8.

A seguir é usado um pseudo-código para verificar se a assinatura digital de uma request é 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

Notificação de sessão concluída

Você precisará nos informar este endpoint para receber as notificações de finalização de uma sessão de validação de identidade. Você deverá nos enviar um código HTTP do tipo 2xx para que não enviemos a notificação novamente. Caso contrário, vamos enviá-la novamente.

Parâmetros disponíveis
Header Parameters
X-Api-Keystringrequired
Este header permitirá identificar qual api-secret deve-se usar, caso vários pares de api-key e api-secret tenham sido configurados.
Exemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este header contém a assinatura digital (body + timestamp + endpoint) que deve ser verificada para garantir a integridade da request. Se a assinatura não corresponder, você deve rejeitar a solicitação.
Exemplo: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
Este header contém a hora em que a solicitação foi assinada, no formato unix-epoch, para que você possa verificar se a assinatura não expirou.
Exemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
O endpoint que você usou para gerar a assinatura, e para o qual é feita a solicitação. Use este header para gerar novamente a assinatura a ser validada, e compare-o com o endpoint do seu serviço para verificar se eles correspondem.
Exemplo: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Identificador de evento.
Exemplo: identity-session-completed
idempotency_keystringrequired
Identificador idempotente para criar o evento.
Exemplo: 27Ky00tAZ0Rdi7G2Vt9iino8AYs
sessionobject
Sessão de validação de identidade
Esta seção foi útil para você?
POST/identity/v1/<client-url>
{
"event_id":
"identity-session-completed"
"idempotency_key":
"27Ky00tAZ0Rdi7G2Vt9iino8AYs"
"session":{
"id":
"iss-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"status":
"CANCELLED"
}
}
Respostas de amostra