Transações

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

Vamos consumir seus endpoints nestes momentos:

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

Considerações:

  • Se houver uma diferença na conciliação, solicitaremos um ajuste para 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.
  • Usaremos um header de idempotência para evitar criar dois ou mais recursos para a mesma solicitação. Saiba 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 do Postman incluída em nosso repositório público de exemplos. Você poderá importar a coleção para uma instância do Postman e simular pedidos reais para seu backend, incluindo o algoritmo de geração e verificação de assinatura.

 

Arquivo de conciliação


Diariamente, enviaremos dois arquivos em formato CSV por meio de 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 na etapa de Autorização.

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.

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 realizar a operação. Lembre-se de que validaremos a assinatura e rejeitaremos a transação se a assinatura não coincidir ou tiver expirado.

Pode encontrar mais informações em Configuração de Webhooks.

Parâmetros disponíveis
Body Parameters
transactionobject
Informações relacionadas à transação
merchantobject
Informações relacionadas ao comércio
cardobject
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.
userobject
Informações relacionadas ao usuário que realizou a transação.
amountobject
Informações relacionadas aos valores da transação. Podem ser maiores ou iguais a zero.
extra_dataobject
Informações relacionadas aos 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ê deve deduzir o valor do saldo do usuário. Se for crédito, você deve adicionar fundos ao saldo do usuário. NOTA: Se você já integrou o endpoint de autorizações sem /debit, não verá alterações no comportamento.
Enum: debitcredit
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
balanceobject
Saldo da conta. Retorna apenas quando o tipo 'BALANCE_INQUIRY' é inserido. Disponível apenas no 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"
"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} permite que você faça ajustes de crédito e débito nas transações.

Además, a través de este endpoint te enviaremos una solicitud de ajuste cuando las banderas (Mastercard o Visa) fuerzan una transacción.

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.

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 realizar a operação. Lembre-se de que validaremos a assinatura e rejeitaremos a transação se a assinatura não coincidir ou tiver expirado.

Pode encontrar mais informações em Configuração de Webhooks.

Parâmetros disponíveis
Body Parameters
transactionobject
Informações relacionadas à transação
merchantobject
Informações relacionadas ao comércio
cardobject
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.
userobject
Informações relacionadas ao usuário que realizou a transação.
amountobject
Informações relacionadas aos valores da transação. 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ê deve deduzir o valor do saldo do usuário. Se for crédito, você deve adicionar fundos ao saldo do usuário. NOTA: Você pode receber ajustes com valores muito pequenos; caberá a você decidir se deseja aplicá-los no saldo dos seus clientes 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"
"source":
"ONLINE"
"network":
"MASTERCARD"
"cardless_withdrawal_user_id":
"string"
"cardless_withdrawal_token":
"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

Notificações

Este serviço permite que você notifique quando uma transação é resolvida, seja pela Pomelo ou pela bandeira (Mastercard, Visa, etc.).

Considerações

Esperamos uma resposta do tipo 2XX para termos certeza de que a notificação foi recebida. Caso contrário, vamos enviá-la novamente.

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ções relacionadas ao evento. Isso pode variar dependendo do tipo de evento.
idempotency_keystring
Identificador idempotente para criar o 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