> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axnpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Regras de contrato

> Contrato de integracao para transacoes de entrada (CASHIN).

## Identificadores

* `transactionId` e o ID publico (UUID) para conciliacao.
* `id` inteiro e legado e nao deve ser usado como chave principal no cliente.

## Payload publico de criacao

No endpoint `POST /v1/integrations/create-transaction`, o contrato publico usa:

* `amount` obrigatorio
* `description`, `productName`
* `clientName`, `clientEmail`, `clientPhone`, `clientCpf`
* `tracking_parameters` com `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`
* `referenceId` para idempotencia
* `checkoutUiMode`, `paymentMethodTypes`, `successUrl`, `cancelUrl` e `returnUrl` para checkout de cartao

<Info>
  No fluxo padrao, nao envie `acquirer`. A AXNPAY escolhe automaticamente o processador ativo para PIX, boleto ou cartao.
</Info>

Para PIX, o retorno inclui `pixCode`.

Para cartao, o retorno inclui `checkout`.

## Tracking e atribuicao

Se enviados na criacao da cobranca, os UTMs ficam salvos na transacao e tambem sao reenviados nos webhooks da AXNPAY dentro de:

* `trackingParameters`
* `tracking_parameters`
* campos planos `utm_*`

## Status de transacao

* `PENDING`: criada e aguardando pagamento.
* `PROCESSING`: em processamento interno ou no provedor.
* `COMPLETED`: pagamento confirmado.
* `FAILED`: falhou.
* `REVERSED`: estornada.
* `CANCELLED`: cancelada.
* `CHARGEBACK`: disputa ou chargeback.

## Campo `pixCode`

Para PIX, a API retorna `pixCode` no formato copia e cola EMV.
Considere a transacao paga apenas quando `status = COMPLETED`.

## Campo `checkout`

Para checkout de cartao, a API retorna `checkout`.

Os campos mais importantes sao:

* `sessionId`
* `uiMode`
* `url` para checkout hosted
* `clientSecret` para checkout self-hosted
* `publishableKey` quando o fluxo exigir frontend dedicado

Veja o guia completo em [Cartao](/card-checkout).

## Privacidade de dados

A resposta da Integrations API expoe apenas os dados necessarios ao integrador.