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.

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.

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

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.

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

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

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

Durante o fluxo on-line

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:

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.

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

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

Estes são alguns dos fornecedores mais reconhecidos

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

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

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.

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.

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:

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

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

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

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

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

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.

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

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

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.

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

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.

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.

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

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.

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.