O que é?

Este documento define o padrão de comunicação de dados entre a Linx Commerce e parceiros de meios de pagamento integrados através do modelo GenericExternal (Pagamento Externo Genérico).

O contrato tem como objetivo padronizar as chamadas de API, os formatos de requisição e resposta, e os comportamentos esperados no fluxo de pagamento.

Tipos de Requisições

  1. Criação de Transação

    • Método: POST

    • URL: definida pelo parceiro ({CreateUrl})

    • Headers obrigatórios:

      • API-AppKey: {chave fornecida}

      • API-AppToken: {token fornecido}

      • Content-Type: application/json

      • LinxCommerce-Tenant: {TenantName}

    • Corpo da requisição (exemplo genérico):

      {
   "MerchantOrderId":"uuid-loja",
   "TransactionId":"uuid-transacao",
   "OrderNumber":"123456",
   "Currency":"BRL",
   "Installments":1,
   "TotalAmount":10000,
   "Customer":{
      "Name":"Nome do Cliente",
      "DocumentNumber":"XXXXXXXXXXX",
      "DocumentType":"CPF",
      "Email":"[email protected]",
      "BillingAddress":{
         "Street":"Rua Exemplo",
         "Number":"123",
         "ZipCode":"00000000",
         "City":"Cidade",
         "State":"UF",
         "Country":"BRA"
      }
   },
   "Items":[
      {
         "Id":"1",
         "Name":"Produto Teste",
         "Price":10000,
         "Quantity":1
      }
   ],
   "CallbackUrl":"https://parceiro.com/api/payment/callback"
}

    • Retorno esperado (exemplo):

      {
   "status":"Pending",
   "acquirer":"NOME_DO_PARCEIRO",
   "transactionId":"uuid-transacao",
   "tid":"id-interno-do-parceiro",
   "authenticationUrl":"https://parceiro.com/checkout/session/xyz"
}

2 - Sincronização de Transação

    • Método: GET

    • URL: {SynchronizeUrl}/{TransactionId}/status

    • Headers obrigatórios: mesmos do item 1.

    • Retorno esperado (exemplo):

      {
   "status":"approved",
   "transactionId":"uuid-transacao",
   "reconciliationNumber":"uuid-conciliacao"
}

3 - Cancelamento de Transação

    • Método: POST

    • URL: {CancellationUrl}/{TransactionId}/cancel

    • Headers obrigatórios: mesmos do item 1.

    • Retorno esperado (exemplo):

      {
   "status":"canceled",
   "transactionId":"uuid-transacao",
   "reconciliationNumber":"uuid-conciliacao"
}

Observações Importantes

  • O campo status deve seguir padrões pré-estabelecidos:

    • approved → pagamento aprovado

    • denied → pagamento negado

    • pending → pagamento em processamento

    • canceled → pagamento cancelado

  • URLs de integração (CreateUrl, SynchronizeUrl, CancellationUrl) são fornecidas pelo parceiro e configuradas no painel da Linx Commerce.

  • A segurança das transações deve ser garantida pelo uso de AppKey, AppToken e protocolos HTTPS.

  • O CallbackUrl deve ser utilizado pelo parceiro para notificar a Linx Commerce em tempo real sobre mudanças de status.

  • Sem rótulos