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.
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.
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.
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.
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.
Cada usuario debe tener un email único, También debe ser única la combinación de tipo de documento de identidad y valor.
Os tipos de documentos de identidade aceitos são:
No caso do DNI, validaremos que sua extensão é de 7 ou 8 caracteres.
O tipo de documento fiscal aceito é o CUIL.
Os tipos de documentos de identidade aceitos são:
O tipo de documento fiscal aceito é o CPF. Vamos validar que a extensão tenha 11 caracteres.
Os tipos de documentos de identidade aceitos são:
O tipo de documento fiscal aceito é o RFC, mas não será obrigatório incluí-lo.
Se você opera na Argentina, o endereço legal do usuário deve ser de uma das seguintes províncias:
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.
Se você opera no México, não há requisitos especiais em relação aos campos de endereço legal do usuário.
O endpoint '/users/v1/' permite buscar um grupo de usuários e receber uma lista ordenada com base nos parâmetros especificados.
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
É 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.
O endpoint de '/users/v1/{id}' permite consultar as informações de um usuário por meio do seu ID.
O endpoint '/users/v1/{id}' permite atualizar as informações de um usuário por meio do seu ID.
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
.
Cada usuario debe tener un email único. También debe ser única la combinación de tipo de documento de identidad y valor.
Os tipos de documentos de identidade aceitos são:
No caso do DNI, validaremos que sua extensão é de 7 ou 8 caracteres.
O tipo de documento fiscal aceito é o CUIL.
Os tipos de documentos de identidade aceitos são:
O tipo de documento fiscal aceito é o CPF. Vamos validar que a extensão tenha 11 caracteres.
Os tipos de documentos de identidade aceitos são:
O tipo de documento fiscal aceito é o RFC, mas não será obrigatório incluí-lo.
Se você opera na Argentina, o endereço legal do usuário deve ser de uma das seguintes províncias:
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.
Se você opera no México, não há requisitos especiais em relação aos campos de endereço legal do usuário.
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.
O endpoint /cards/v1/{id}
permite obter informações sobre um cartão específico.
O parâmetro extend
é utilizado para obter dados adicionais de um cartão.
O endpoint /cards/v1/{id}
permite atualizar o status, o grupo de afinidade e o PIN de um cartão.
Será necessário especificar um motivo da lista abaixo para atualizar o status de um cartão:
Novo status | Motivo válido |
---|---|
BLOCKED / DISABLED | CLIENT_INTERNAL_REASON |
BLOCKED / DISABLED | USER_INTERNAL_REASON |
DISABLED | FRAUDULENT |
DISABLED | LOST |
DISABLED | STOLEN |
DISABLED | BROKEN |
DISABLED | UPGRADE |
O endpoint /cards/v1/{id}/shipment
permite atualizar o endereço de envio de um cartão.
O cartão deverá ser nomeado fisicamente e possuir o status CREATED
.
O endpoint /cards/v1/
permite buscar um grupo de cartões com base nos atributos especificados.
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
É 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.
O endpoint /cards/v1/
permite criar um novo cartão, tanto físico como virtual.
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
O endpoint /cards/v1/batches
permite criar um lote de cartões sem nome.
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.
O endpoint /cards/v1/batches/shipments/{shipmentId}
permite atualizar o endereço de envio de um lote de cartões.
O lote de cartões deverá ser nomeado fisicamente e possuir status CREATED
.
O endpoint /cards/v1/activation
permite ativar um cartão físico e configurar um PIN.
O usuário deve estar ativo e o cartão deverá possuir statusEMBOSSED
.
O PIN a ser configurado:
Será possível usar o parâmetro previous_card_id
, para especificar que um cartão é substituto de um anterior.
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.
Você precisará de um endpoint público para que possamos mantê-lo atualizado sobre as remessas em tempo real.
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.
POST https://api.current-customer.com/whatever/shipping/updates
{
'shipment_id': 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
'meta': {
'resource_url': 'http://localhost:8080/v1/{shipment_id}'
}
}
curl --request POST \
--url https://api.current-customer.com/whatever/shipping/updates \
--header 'Content-Type: application/json' \
--data '{
'shipment_id' : 'shi-20VphpUWbbGm0Nwo8DMqsFBJgYv',
'meta' : {
'resource_url' : 'http://localhost:8080/v1/shi-20VphpUWbbGm0Nwo8DMqsFBJgYv'
}
}'
Como medida de 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.
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.
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.
$ echo -e 'api-key=$(openssl rand -base64 32)\napi-secret=$(openssl rand -base64 32)' > api-credentials.txt
$ cat api-credentials.txt
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=
$ openssl genrsa -out private.pem 2048
$ openssl rsa -in private.pem -pubout -out public.pem
Você nos envia sua chave pública public.pem por e-mail ou slack.
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
Enviamos o arquivo api-credentials.txt.enc por e-mail ou slack
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=
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))
O endpoint /shipments/v1/
é utilizado para criação de uma nova remessa.
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.
O endpoint /shippining/v1/
permite pesquisar um grupo de remessas com base nos atributos que você especificar.
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]
É 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.
O endpoint /shipping/v1/{shipment_id}
é utilizado para obtenção de informações sobre uma remessa específica.
Será preciso especificar o shipping_id para fazer a consulta.
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.
Será preciso implementar e expor os endpoints “Authorization” e “ Adjustments” em seu backend para que possamos nos comunicar.
Toda vez que um usuário usa seu cartão em qualquer loja ou e-commerce.
Quando a rede (Mastercard, Visa etc.) solicita a reconciliação de todos os pagamentos apresentados pelos estabelecimentos.
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.
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:
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”.
Em caso de solicitação duplicada, será necessário verificar o status da transação no cache.
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.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:
Toda comunicação conosco deve ser via HTTPS, independentemente de quem emite o certificado.
Estes são alguns dos fornecedores mais reconhecidos
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:
34.226.254.178
44.198.3.59
34.206.159.176
52.0.20.124
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:
api-key
e api-secret
.No momento de uma autorização de pagamento, assinamos com hmac-sha256 cada solicitação de autorização com api-secret
.
api-key
da solicitação.api-secret
.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.
$ echo -e 'api-key=$(openssl rand -base64 32)\napi-secret=$(openssl rand -base64 32)' > api-credentials.txt
$ cat api-credentials.txt
api-key=tgeAkX0795jKTxrVR0cJbb//D8UlhHn0KZwTcDG3gyg=
api-secret=un/OHwD+fMN1TTSaEhs0vupQEDQS7DVaUdlNOu7Fpyw=
$ openssl genrsa -out private.pem 2048
$ openssl rsa -in private.pem -pubout -out public.pem
public.pem
por e-mail ou slack.$ openssl rsautl -encrypt -in api-credentials.txt -out api-credentials.txt.enc -inkey public.pem -pubin
api-credentials.txt.enc
por e-mail ou slackapi-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=
api-secret
em um local seguro e acessível somente pelo aplicativo de autorização de pagamentos
associado à api-key
.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.
Esse é um processo opcional, mas recomendamos executá-lo diariamente.
Em um bucket de S3 que disponibilizaremos, você encontrará esses arquivos:
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
{Atributo} | Descrição | Valores permitidos |
---|---|---|
TRANSACTION_ID | A ID que permite que a transação seja identificada como única. | |
LOCAL_TRANSACTION_DATE_TIME | ||
TRANSACTION_TYPE | Indica 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 produto | PREPAID CREDIT DEBIT |
PROVIDER | É a marca do cartão emitido. | VISA MASTERCARD |
AFFINITY_GROUP_ID | ||
USER_ID | A ID de usuário da Pomelo do titular do cartão. | |
CARD_ID | ||
BIN | Os primeiros seis ou oito dígitos do número do cartão. | |
LAST_FOUR | Os últimos quatro dígitos do PAN. | |
ORIGIN | DOMESTIC: a transação ocorreu no país do emissor. INTERNATIONAL: a transação não ocorreu no país do emissor. | |
MERCHANT_ID | ||
MERCHANT_MCC | Có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_CURRENCY | Código de moeda de LOCAL_TOTAL no ISO_4217 formato ALPHA-3. | |
TRANSACTION_AMOUNT | Valor da transação sem impostos e na moeda original enviada pelo estabelecimento. | |
TRANSACTION_CURRENCY | Código de moeda de TRANSACTION_TOTAL no ISO_4217 formato ALPHA-3. | |
SETTLEMENT_AMOUNT | valor da transação em USD, conforme enviado pela rede. As transações domésticas também terão esse campo em USD. | |
SETTLEMENT_CURRENCY | Código de moeda de LOCAL_TOTAL no ISO_4217 formato ALPHA-3. | |
ENTRY_MODE | Como o cartão foi usado no ponto de venda do estabelecimento. | UNKNOWN MANUAL CHIP CONTACTLESS CREDENTIAL_ON_FILE MAG_STRIPE OTHERS |
STATUS | O status da transação. | APPROVED REJECTED HELD |
STATUS_DETAIL | Razão adicional por que a transação foi aprovada ou recusada. | Veja a tabela abaixo |
SOURCE | Indica 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_ID | Esse valor pode estar vazio se a transação não estiver relacionada a outra transação. | |
COUNTRY_CODE | Este é o código do país no formato [ISO-3166] (https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). | |
POINT_TYPE | POS ECOMMERCE ATM MOTO | |
CLIENT_NAME | El nombre del cliente que aprueba o rechaza la transacción, dado que el reporte se segmenta por cliente, va a tener el mismo valor para todas las filas | |
CLIENT_COUNTRY_CODE | El coódigo de país del cliente en formato ISO-3166 | |
INSTALLMENTS_GRACE_PERIOD | [OPCIONAL*] El período de gracia refiere a la cantidad de meses previo a que comiencen los pagos en cuotas. Puede ir de 0 a 99. | |
INSTALLMENTS_QUANTITY | [OPCIONAL*] La cantidad de cuotas | |
INSTALLMENTS_CREDIT_TYPE | [OPCIONAL*] El tipo de crédito otorgado | NO_PROMOTION WITHOUT_INTEREST WITH_INTEREST BUY_TODAY_PAY_LATER |
*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.
Status detail | Descrição |
---|---|
CARD_BLOCKED | Status do cartão BLOCKED. |
CARD_DISABLED | Status do cartão DISABLED |
CARD_NOT_ACTIVE | Status do cartão EMBOSSED ou CREATED |
CARD_NOT_CONFIGURED | O cartão está sem configurações. |
CARD_NOT_FOUND | Não conseguimos encontrar o PAN do cartão. |
CRYPTO_ERROR | Há um erro nos criptogramas (EMV). |
DUPLICATE_TRANSMISSION_DETECTED | Recebemos uma transação repetida da rede. |
EXPIRED_CARD | Status do cartão EXPIRED. |
EXTRA_FIELDS | As mensagens da rede vêm com campos inesperados. |
INSUFFICIENT_FUNDS | O cliente responde que a conta não dispõe de recursos. |
INVALID_AMOUNT | Os limites do grupo de afinidade foram ultrapassados. |
INVALID_CVV | O CVV não corresponde. |
INVALID_EXPIRATION_DATE | A data de validade recebida não corresponde à do cartão. |
INVALID_MERCHANT | O cliente recusou o merchant por algum motivo específico. |
INVALID_PIN | PIN incorreto |
INVALID_TRANSACTION | Transação inválida. |
LOST_CARD | Status do cartão LOST. |
MISSING_FIELDS | As mensagens da rede vêm sem campos obrigatórios. |
NOT_DECLINED | Uma 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. |
OTHER | Não reconhecemos o caso. |
RESTRICTED_USER | Status do usuário ACTIVE. |
SECURITY_VIOLATION | Excede um limite de fraude. |
SERVICE_UNAVAILABLE | O cliente ou um serviço da Pomelo está inativo. |
STOLEN_CARD | Status do cartão STOLEN. |
SYSTEM_ERROR | Erro imprevisto no sistema. |
APPROVED | O cliente aprovou uma transação. |
TRANSACTION_NOT_PERMITTED | Tipo de transação não permitido no grupo de afinidade. |
Está na Pomelo? | Está no cliente? | Tem o mesmo status? | Action |
---|---|---|---|
Y | Y | Y | Nada a fazer/Marcar como correspondente |
Y | Y | N | 1) Fazer um ajuste que debite/credite o usuário final, se aplicável. 2) Marcar como corresponte. |
Y | N | N | 1) IF STATUS == APPROVED: Fazer um ajuste que debite/credite o usuário final, se aplicável. 2) Marcar como corresponte. |
N | Y | N | Nã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.
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
Atributo | Descrição | Valores permitidos |
---|---|---|
PRESENTMENT_ID | ||
TRANSACTION_ID | A ID da transação original que gerou a apresentação. | |
LOCAL_TRANSACTION_DATE_TIME | ||
TRANSACTION_TYPE | Indica 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_ID | A ID de usuário da Pomelo do titular do cartão | |
CARD_ID | ||
BIN | Os primeiros seis ou oito dígitos do número do cartão. | |
LAST_FOUR | Os últimos quatro dígitos do PAN. | |
ORIGIN | DOMESTIC: a transação ocorreu no país do emissor. INTERNATIONAL: a transação não ocorreu no país do emissor. | |
MERCHANT_ID | ||
MERCHANT_MCC | Código de categoria do estabelecimento, conforme o ISO-18245. | |
MERCHANT_NAME | ||
TRANSACTION_AMOUNT | Valor da transação sem impostos e na moeda original enviada pelo estabelecimento. | |
TRANSACTION_CURRENCY | Código de moeda de TRANSACTION_TOTAL no ISO_4217 formato ALPHA-3. | |
SETTLEMENT_AMOUNT | O valor da transação apresentado pela marca. | |
SETTLEMENT_CURRENCY | O 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_AMOUNT | Valor 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_CURRENCY | O 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_FEE | Comissão por uma transação | |
INTERCHANGE_RATE | Valor alfanumérico que identifica a taxa de câmbio da transação apresentada pelo adquirente. | |
TAX | Imposto associado à taxa de câmbio, devido à regulamentação local. Esses valores devem ter um IVA (imposto sobre valor agregado) calculado.. | |
FUNCTION_CODE | Esse é o tipo de apresentação. | FIRST_PRESENTMENT SECOND_PRESENTMENT_FULL SECOND_PRESENTMENT_PARTIAL |
REVERSE_PRESENTMENT | Significa que a apresentação foi revertida a partir da rede. | TRUE FALSE |
REASON_CODE | Motivo da segunda apresentação. | |
ICA_ACQUIRER | ||
TAX_ID | ID asociado a los impuestos de la transacción | |
INSTALLMENTS_GRACE_PERIOD | [OPCIONAL*] El período de gracia refiere a la cantidad de meses previo a que comiencen los pagos en cuotas. Puede ir de 0 a 99. | |
INSTALLMENTS_QUANTITY | [OPCIONAL*] La cantidad de cuotas | |
INSTALLMENTS_CREDIT_TYPE | [OPCIONAL*] El tipo de crédito otorgado | NO_PROMOTION WITHOUT_INTEREST WITH_INTEREST BUY_TODAY_PAY_LATER |
*_Para los clientes que operen con crédito, se agregan los datos del contrato de cuotas.
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.
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:
Host: sftp.pomelo.la
Porta: 22
Usuário: <tu_usuario> # aquele que geramos a partir de suas chaves públicas.
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:
$Cliente
pelo nome própriossh-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.
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.
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.
Gere chaves SSH, usando PuTTY. Instale o PuTTY na página do desenvolvedor: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html
Instale o PuTTY na página do desenvolvedor: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html
PuTTYgen
.Executar como administrador
.Sim
se o sistema gerar a seguinte consulta: Deseja permitir que este aplicativo faça alterações em seu dispositivo?
Embora a ferramenta de geração de chaves PuTTY ofereça vários outros algoritmos, mostraremos como gerar chaves RSA, uma das mais usadas:
Gerar
.Salvar chave pública
. Você terá, então, de escolher um local para salvar a chave e dar um nome à chave.Conversões
, na parte superior da tela.Sim
.O endpoint/transactions/authorizations permite autorizar transações.
Enviaremos uma solicitação para autorizar ou recusar a transação.
Esperamos uma resposta rápida para garantir uma boa experiência. Se a resposta demorar, recusaremos a transação.
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.
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.
O serviço de Core permite criar e gerenciar as contas digitais de seus usuários.
Para ter uma conta, seus usuários devem:
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.
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
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.
status_update_motive
é OTHER
.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
.
ACTIVE
.status_update_motive
é OTHER
.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:
Qualquer operação com a intenção de alterar o saldo de uma conta. Ou seja:
Idiomas ordenados de acordo com sua preferência. Especificação técnica
Idiomas ordenados de acordo com sua preferência. Especificação técnica
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:
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.
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
.
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.
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.CREDIT
y, para débito, CREDIT
.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
.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
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.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ís | Network | ID |
---|---|---|
Argentina | Pago Fácil | PAGO_FACIL |
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.
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.
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:
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.
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ís | Network | ID |
---|---|---|
Brasil | Boleto | BOLETO |
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::
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..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).
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:
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.
A transferência é feita em dois passos simples:
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.
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.
O endpoint /sessions permite realizar uma pesquisa com filtros específicos.
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.
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
É 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.
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.Este serviço será responsável por notificá-lo quando uma sessão de validação de identidade for concluída.
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
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.
api-secret
deve-se usar, caso vários pares de api-key
e api-secret
tenham sido configurados.