Transações

Se você não usar nosso Core de crédito ou nosso Autorizador, você deverá implementar e expor em seu backend os endpoints de “Autorização” e “Ajustes” para que possamos nos comunicar.

Vamos consumir seus endpoints neste momento:

  • Durante o fluxo online, sempre que um usuário utiliza seu cartão em qualquer loja ou comércio eletrônico.
  • Quando a rede (Mastercard, Visa, etc) solicita a conciliação de todos os pagamentos que os comerciantes apresentam.

Considerações:

  • Se houver uma diferença na conciliação, solicitaremos um ajuste à sua API.
  • Precisamos que seus endpoints respondam o mais rápido possível para garantir uma boa experiência do usuário. Se a resposta demorar, rejeitaremos a transação.
  • Usaremos um cabeçalho de idempotência para evitar criar dois ou mais recursos para a mesma solicitação. Saber mais
  • Você terá que validar e assinar as autorizações seguindo os passos desta documentação.

Como testar sua implementação e código de exemplo


Você pode testar a implementação do seu backend com algumas operações típicas que enviaremos com uma coleção de Postman incluída em nosso repositório de exemplos públicos. Você poderá importar a coleção para uma instância do Postman e assim simular pedidos reais para o seu backend, incluído o algoritmo de geração e verificação de assinatura.

 

Arquivo de conciliação


Diariamente enviaremos dois arquivos em formato CSV através de um SFTP (Secure File Transfer Protocol) para que você possa conciliar todas as transações entre seu sistema e o nosso.

 

Autorizar

O endpoint /transactions/authorizations/{type} permite autorizar as transações de débito ou crédito que chegam pelo fluxo online à etapa de Autorização.

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

Considerações

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

Além de validar a assinatura que enviamos, ao gerar a resposta você deve assinar seu body junto com o timestamp e o endpoint de resposta com seu api-secret após impactar a operação. Tenha em mente que validaremos a assinatura e rejeitaremos a transação se a assinatura não coincidir ou tiver expirado.

Você pode encontrar mais informações em Configuração de Webhooks.

Parâmetros disponíveis
Body Parameters
transactionobject
Informação relacionada à transação
merchantobject
Informação relacionada ao comércio
cardobject
Informação não sensível relacionada ao cartão
installmentsobject
Informação relacionada às parcelas da transação, este parâmetro será recebido apenas para autorizações de compra com parcelas no cartão de crédito.
userobject
Informação relacionada ao usuário que realizou a transação
amountobject
Informação relacionada aos montantes da transação. Esses montantes podem ser maiores ou iguais a zero
extra_dataobject
Informação relacionada a campos extras da transação
Path Parameters
typestringrequired
O tipo de operação que executaremos no saldo do seu cliente. Se for débito, você deverá deduzir o valor do saldo do usuário. Se for crédito, você deverá adicionar fundos ao saldo do usuário. NOTA: Se você já integrou o endpoint de autorizações sem /debit, não verá mudanças no comportamento.
Enum: debitcredit
Detalhe de respostas
statusstring
Um estado que nos indica se devemos aprovar ou rejeitar a transação
Enum: APPROVEDREJECTED
messagestring
Mensagem descritiva com o resultado da operação
status_detailstring
Permite rastrear o motivo pelo qual a transação não foi aprovada
Enum: APPROVEDINSUFFICIENT_FUNDSINVALID_MERCHANTINVALID_AMOUNTSYSTEM_ERROROTHER
balanceobject
Saldo da conta. É devolvido apenas no caso de ser enviado o tipo 'BALANCE_INQUIRY'. Disponível apenas para o México.

Esta seção foi útil para você?

POST/transactions/authorizations/{type}
{
"transaction":{
"id":
"ctx-200kXoaEJLNzcsvNxY1pmBO7fEx"
"type":
"PURCHASE"
"point_type":
"POS"
"entry_mode":
"MANUAL"
"country_code":
"ARG"
"origin":
"DOMESTIC"
"source":
"ONLINE"
"network":
"MASTERCARD"
"cardless_withdrawal_user_id":
"string"
"cardless_withdrawal_token":
"string"
"tl_id":
"string"
"original_transaction_id":
"ctx-200kirg6qicg1qHSCbgaStrEHjI"
"local_date_time":
"2019-08-24T14:15:22"
}
"merchant":{
"id":
"string"
"mcc":
"string"
"address":
"string"
"name":
"string"
"terminal_id":
"string"
"country":
"string"
"city":
"string"
}
"card":{
"id":
"c-1625519392748E6XZBK"
"product_type":
"PREPAID"
"provider":
"MASTERCARD"
"last_four":
"1573"
}
"installments":{
"quantity":
"12"
"credit_type":
"NO_PROMOTION"
"grace_period":
"0"
"current_installment":
"1"
"promotion_type":
"MSI_PROMOTION"
}
"user":{
"id":
"u-1625758043579BAR6D4"
}
"amount":{
"local":{
...
}
"settlement":{
...
}
"transaction":{
...
}
"details":[
...
]
}
"extra_data":{
"cardholder_verification_method":
"FAIL_PROCESSING"
"pin_presence":
"ONLINE"
"pin_validation":
"VALID"
"cvv_presence":
"PRESENT"
"cvv_validation":
"MATCHING"
"expiration_date_presence":
"PRESENT"
"expiration_date_validation":
"EXPIRED"
"function_code":
"STANDARD"
"tokenization_wallet_name":
"Apple_Pay"
"tokenization_wallet_id":
"0"
"cardholder_presence":
"CARDHOLDER_PRESENCE_PRESENT"
"card_presence":
"PRESENT"
"pin_change_send":
"SENT"
"pin_change_result":
"APPLIED"
}
}
Respostas de amostra
{
"status":
"APPROVED"
"message":
"string"
"status_detail":
"APPROVED"
"balance":{
"total":
"982345.12"
"currency":
"ARS"
}
}

Ajustes

O endpoint /transactions/adjustments/{type} nos permite fazer ajustes de crédito e débito nas transações.

Além disso, através deste endpoint, enviaremos uma solicitação de ajuste quando as bandeiras (Mastercard ou Visa) forçam uma transação. Você também pode receber Payments que nos chegam através do fluxo offline etapa de Compensação.

Não é possível rejeitar as transações deste endpoint. Sempre as consideraremos efetivas e com impacto financeiro, independentemente da resposta que recebermos. Esperaremos que você nos informe o resultado da transação em seu sistema. Isso não gerará mudanças em nossa operação, mas pode ser útil para casos de revisão manual.

Considerações

Este endpoint é usado durante a conciliação e os fluxos online, principalmente para fazer ajustes durante o processo de liquidação e também em caso de devoluções.

Além de validar a assinatura que enviamos, ao gerar a resposta você deve assinar seu body junto com o timestamp e o endpoint de resposta com seu api-secret após impactar a operação. Tenha em mente que validaremos a assinatura e rejeitaremos a transação se a assinatura não coincidir ou tiver expirado.

Você pode encontrar mais informações em Configuração de Webhooks.

Parâmetros disponíveis
Body Parameters
transactionobject
Informação relacionada à transação
merchantobject
Informação relacionada ao comércio
cardobject
Informação não sensível relacionada ao cartão
installmentsobject
Informação relacionada às parcelas da transação, este parâmetro será recebido apenas para autorizações de compra com parcelas no cartão de crédito.
userobject
Informação relacionada ao usuário que realizou a transação
amountobject
Informação relacionada aos montantes da transação. Esses montantes podem ser maiores ou iguais a zero
Path Parameters
typestringrequired
O tipo de operação que executaremos no saldo do seu cliente. Se for débito, você deverá deduzir o valor do saldo do usuário. Se for crédito, você deverá adicionar fundos ao saldo do usuário. NOTA: É possível que você receba ajustes com valores muito pequenos, dependerá de você impactá-los no saldo dos seus clientes ou não.
Enum: debitcredit
Detalhe de respostas
status_detailstring
Permite informar o resultado da transação
Enum: APPROVEDINSUFFICIENT_FUNDSINVALID_MERCHANTINVALID_AMOUNTSYSTEM_ERROROTHER
messagestring
Mensagem descritiva com o resultado da transação

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"
"source":
"ONLINE"
"network":
"MASTERCARD"
"cardless_withdrawal_user_id":
"string"
"cardless_withdrawal_token":
"string"
"tl_id":
"string"
"original_transaction_id":
"ctx-200kirg6qicg1qHSCbgaStrEHjI"
"local_date_time":
"2019-08-24T14:15:22"
}
"merchant":{
"id":
"string"
"mcc":
"string"
"address":
"string"
"name":
"string"
"terminal_id":
"string"
"country":
"string"
"city":
"string"
}
"card":{
"id":
"c-1625519392748E6XZBK"
"product_type":
"PREPAID"
"provider":
"MASTERCARD"
"last_four":
"1573"
}
"installments":{
"quantity":
"12"
"credit_type":
"NO_PROMOTION"
"grace_period":
"0"
"current_installment":
"1"
"promotion_type":
"MSI_PROMOTION"
}
"user":{
"id":
"u-1625758043579BAR6D4"
}
"amount":{
"local":{
...
}
"settlement":{
...
}
"transaction":{
...
}
"details":[
...
]
}
}
Respostas de amostra
{
"status_detail":
"APPROVED"
"message":
"string"
}

Notificações

Este serviço permite notificar quando uma transação é resolvida, seja por parte da Pomelo ou por parte da bandeira (Mastercard, Visa, etc.).

Considerações

Esperamos uma resposta do tipo 2XX para garantir que a notificação foi recebida. Caso contrário, reenviá-la-emos.

Você pode encontrar mais informações em Configuração de Webhooks.

Parâmetros disponíveis
Body Parameters
event_idstring
Identificador de evento.
Exemplo: authorization-advice
event_detailobject
Informação relacionada ao evento. Esta pode variar conforme o tipo de evento.
idempotency_keystring
Identificador idempotente de criação do evento.
Exemplo: ctx-2CIllOHdIcC5qWjpiwRlFy2nZM8

Esta seção foi útil para você?

POST/transactions/v1/notifications
{
"event_id":
"authorization-advice"
"event_detail":{
"transaction":{
...
}
"merchant":{
...
}
"card":{
...
}
"installments":{
...
}
"user":{
...
}
"amount":{
...
}
"status":
"REJECTED"
"status_detail":
"string"
"extra_detail":
"string"
"extra_data":{
...
}
}
"idempotency_key":
"ctx-2CIllOHdIcC5qWjpiwRlFy2nZM8"
}
Respostas de amostra