> ## 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.

# Cartao

> Como gerar cobrancas de cartao pela AXNPAY sem precisar escolher a adquirente no payload.

## Como funciona

No fluxo de cartao:

`Cliente final -> AXNPAY -> checkout ativo -> AXNPAY -> webhook do merchant`

Isso significa:

* voce nao precisa enviar `acquirer` no fluxo normal
* a AXNPAY identifica o checkout de cartao ativo na sua conta
* o frontend recebe apenas configuracoes publicas e dados seguros
* a confirmacao oficial continua chegando pelo webhook da AXNPAY

## Endpoints

* `GET /v1/integrations/card/config`
* `POST /v1/integrations/create-transaction`
* `GET /v1/integrations/card/checkout-session`

## Passo 1. Ler a configuracao publica do checkout

Use:

```http theme={null}
GET /v1/integrations/card/config
Authorization: Bearer sk_live_prod_<sua_secret_key>
```

Esse endpoint informa, quando o checkout web estiver disponivel:

* `publishableKey`
* `supportedUiModes`
* `defaultUiMode`
* `isReadyForHostedCheckout`
* `isReadyForSelfHostedCheckout`

## Passo 2. Gerar a cobranca

Use:

```http theme={null}
POST /v1/integrations/create-transaction
Authorization: Bearer sk_live_prod_<sua_secret_key>
Content-Type: application/json
```

### Exemplo hosted

```json theme={null}
{
  "amount": 150,
  "currency": "brl",
  "productName": "Pedido #1001",
  "description": "Plano Premium",
  "clientName": "Maria",
  "clientEmail": "maria@example.com",
  "referenceId": "9e4a5fb4-61bb-4b38-9bb6-b7029b74bdf6",
  "checkoutUiMode": "hosted",
  "paymentMethodTypes": ["card", "link"],
  "successUrl": "https://merchant.example.com/checkout/success",
  "cancelUrl": "https://merchant.example.com/checkout/cancel",
  "tracking_parameters": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "launch"
  }
}
```

### Exemplo self-hosted

```json theme={null}
{
  "amount": 150,
  "currency": "brl",
  "productName": "Pedido #1001",
  "clientEmail": "maria@example.com",
  "referenceId": "ef17ad6d-b9f7-4130-b0e9-4f7fd704b151",
  "checkoutUiMode": "custom",
  "paymentMethodTypes": ["card", "link"],
  "returnUrl": "https://merchant.example.com/checkout/return"
}
```

### Campos importantes

* nao envie `acquirer` no fluxo padrao
* `checkoutUiMode: "hosted" | "embedded" | "custom"`
* `paymentMethodTypes`
* `successUrl` e `cancelUrl` para hosted
* `returnUrl` para embedded ou custom
* `tracking_parameters` para UTMs

### Wallets e metodos

* Apple Pay: use `card`
* Google Pay: use `card`
* Link: adicione `link`
* wallets adicionais aparecem automaticamente quando o checkout ativo suportar o metodo

Exemplo:

```json theme={null}
{
  "paymentMethodTypes": ["card", "link"]
}
```

## Passo 3. Interpretar a resposta

Se for PIX, a resposta vem com `pixCode`.

Se for cartao, a resposta vem com `checkout`.

### Campos mais importantes de `checkout`

* `sessionId`
* `uiMode`
* `url` para redirect hosted
* `clientSecret` para self-hosted
* `publishableKey` para o frontend
* `paymentStatus`
* `status`

## Passo 4. Consultar o status depois

Use:

```http theme={null}
GET /v1/integrations/card/checkout-session?transactionId=<uuid>
```

Voce tambem pode consultar por:

* `sessionId`
* `id` legado

## Webhook final para o merchant

No fluxo de cartao, a AXNPAY recebe o retorno interno do checkout e depois envia o evento para o webhook do merchant.

O payload enviado pela AXNPAY pode incluir:

* `checkoutSessionId`
* `paymentIntentId`
* `trackingParameters`
* `tracking_parameters`
* campos planos `utm_*`

Trate a confirmacao oficial sempre pelo webhook da AXNPAY ou pelo status sincronizado em `/v1/integrations/card/checkout-session`.