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
transactionobjectrequired
Informação relacionada à transação
merchantobjectrequired
Informação relacionada ao comércio
cardobjectrequired
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.
userobjectrequired
Informação relacionada ao usuário que realizou a transação
amountobjectrequired
Informação relacionada aos montantes da transação. Esses montantes podem ser maiores ou iguais a zero
extra_dataobjectrequired
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
transactionobjectrequired
Informação relacionada à transação
merchantobjectrequired
Informação relacionada ao comércio
cardobjectrequired
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.
userobjectrequired
Informação relacionada ao usuário que realizou a transação
amountobjectrequired
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 de transações

Este serviço permite que você receba notificações sempre que uma transação for resolvida, seja aprovada ou rejeitada por você, por nós ou pela bandeira (Mastercard, Visa, etc.).

Encontre mais informações sobre este webhook na nossa documentação.

Além disso, se você tiver dúvidas sobre a implementação, visite este artigo sobre Como configurar um webhook.

Considerações

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

Parâmetros disponíveis
Body Parameters
event_idstringrequired

Identificador de evento.

  • Notifique todas as transações rejeitadas: authorization-advice
  • Notifique todas as transações aprovadas: approved-authorization-advice
Enum: authorization-adviceapproved-authorization-advice
event_detailobject
Informação relacionada ao evento. Esta pode variar conforme o tipo de evento.
idempotency_keystringrequired
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

Notificações de Apresentações

Este serviço permite receber notificações sempre que uma transação for apresentada para liquidação através do processo de clearing. O estado da apresentação pode ser APPROVED ou IN_REVIEW.

Encontre mais informações sobre este webhook na nossa documentação. Além disso, se você tiver dúvidas sobre a implementação, veja este artigo sobre Como configurar um webhook.

Considerações

{{Deberás indicarnos un endpoint para recibir las notificaciones de cada presentación. Importante: tendrás que devolvernos un código HTTP del tipo 2xx para que no volvamos a enviarte la notificación. Caso contrario, volveremos a enviarla.}}

Parâmetros disponíveis
Body Parameters
event_idstringrequired
Identificador de evento.
Exemplo: presentment-notification
Enum: presentment-notification
event_detailobjectrequired
Informação relacionada ao evento. Esta pode variar conforme o tipo de evento.

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

POST/presentments/v1/notifications
{
"event_id":
"presentment-notification"
"event_detail":{
"type":
"PRESENTMENT"
"id":
"cpr-2gxSB260ekE5kBJyS5Pn70OPwoQ"
"card_id":
"crd-2LQkDbo3SV0CWbryv1Udt39R2gD"
"user_id":
"usr-2YHh6VWcO8E9zjKr8BmkPmJU75o"
"acquirer_reference_data":
"75177134145298388477491"
"affinity_group_id":
"afg-2EUsW7fqKtCjQrIh5IEuNx0JghL"
"associated_transactions":
"ctx-inc1,ctx-inc2,ctx-adj1"
"banknet_ref_number":
"MCC2507200720"
"client":{
...
}
"original_transaction_data":{
...
}
"function_code":
"200"
"message_reason_code":
"MULTICLEARING_PARTIAL"
"ica_acquirer":
"003499"
"installments_data":{
...
}
"amounts":{
...
}
"network":
"MASTERCARD"
"origin":
"DOMESTIC"
"reverse_presentment":
false
"product_type":
"CREDIT"
"provider":
"MASTERCARD"
"public_id":
"cpr-2gxSB260ekE5kBJyS5Pn70OPwoQ"
"reconciliation_date":
"2024-05-25T00:00:00"
"settlement_date":
"2024-05-27T00:00:00"
"transaction_date_time":
"2024-05-24T01:01:01"
"tax_id":
"MAG 2105031W3"
"status":
"APPROVED"
}
}
Respostas de amostra