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

# Validar Sessão Apple Pay

> Endpoint para validar sessões Apple Pay necessário para integração web

## Visão Geral

Este endpoint é chamado automaticamente durante o fluxo de pagamento Apple Pay na web, quando o evento `onvalidatemerchant` é disparado pelo `ApplePaySession`.

A validação de sessão é necessária para estabelecer confiança entre o seu domínio, a Apple e a Autorizou antes de processar o pagamento.

<Note>
  Este endpoint **não requer** autenticação Bearer Token, mas deve ser chamado do frontend durante o fluxo Apple Pay.
</Note>

## Quando Este Endpoint é Usado

Este endpoint é chamado automaticamente quando você inicia uma sessão Apple Pay:

```javascript JavaScript theme={null}
const session = new ApplePaySession(3, paymentRequest);

session.onvalidatemerchant = async (event) => {
  const response = await fetch('/api/v1/apple-pay/validate-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      validationURL: event.validationURL,
      domainName: window.location.hostname
    })
  });
  
  const merchantSession = await response.json();
  session.completeMerchantValidation(merchantSession.sessionData);
};

session.begin();
```

## Parâmetros da Requisição

<ParamField body="validationURL" type="string" required>
  URL fornecida pela Apple no evento `onvalidatemerchant`

  **Exemplo:** `https://apple-pay-gateway-cert.apple.com/paymentservices/startSession`

  Esta URL é única para cada sessão e expira rapidamente.
</ParamField>

<ParamField body="domainName" type="string" required>
  Nome do domínio onde o Apple Pay está sendo usado

  **Exemplo:** `checkout.sualoja.com.br`

  Deve ser um domínio verificado no Apple Developer Portal.
</ParamField>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://pay.autorizou.dev/api/v1/apple-pay/validate-session \
    -H "Content-Type: application/json" \
    -d '{
      "validationURL": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
      "domainName": "checkout.sualoja.com.br"
    }'
  ```

  ```javascript JavaScript (Frontend) theme={null}
  async function validateMerchant(event) {
    try {
      const response = await fetch('https://pay.autorizou.dev/api/v1/apple-pay/validate-session', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          validationURL: event.validationURL,
          domainName: window.location.hostname
        })
      });

      if (!response.ok) {
        throw new Error('Falha na validação do merchant');
      }

      const data = await response.json();
      return data.sessionData;
    } catch (error) {
      console.error('Erro ao validar merchant:', error);
      throw error;
    }
  }
  ```

  ```php PHP theme={null}
  <?php

  $validationURL = 'https://apple-pay-gateway-cert.apple.com/paymentservices/startSession';
  $domainName = 'checkout.sualoja.com.br';

  $data = [
      'validationURL' => $validationURL,
      'domainName' => $domainName
  ];

  $curl = curl_init();
  curl_setopt_array($curl, [
      CURLOPT_URL => 'https://pay.autorizou.dev/api/v1/apple-pay/validate-session',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Content-Type: application/json'
      ],
      CURLOPT_POSTFIELDS => json_encode($data)
  ]);

  $response = curl_exec($curl);
  $result = json_decode($response, true);
  curl_close($curl);

  if (isset($result['sessionData'])) {
      echo "Sessão validada com sucesso!\n";
      print_r($result['sessionData']);
  } else {
      echo "Erro na validação\n";
  }
  ?>
  ```
</CodeGroup>

## Resposta de Sucesso

<ResponseField name="sessionData" type="object" required>
  Objeto de sessão retornado pela Apple, necessário para completar a validação no frontend

  <Expandable title="Estrutura do sessionData">
    <ResponseField name="epochTimestamp" type="integer">
      Timestamp Unix da criação da sessão
    </ResponseField>

    <ResponseField name="expiresAt" type="integer">
      Timestamp Unix de expiração da sessão (normalmente 5 minutos)
    </ResponseField>

    <ResponseField name="merchantSessionIdentifier" type="string">
      Identificador único da sessão do merchant
    </ResponseField>

    <ResponseField name="nonce" type="string">
      Nonce criptográfico para segurança
    </ResponseField>

    <ResponseField name="merchantIdentifier" type="string">
      Seu Merchant ID Apple Pay
    </ResponseField>

    <ResponseField name="domainName" type="string">
      Domínio validado
    </ResponseField>

    <ResponseField name="displayName" type="string">
      Nome de exibição do merchant
    </ResponseField>

    <ResponseField name="signature" type="string">
      Assinatura criptográfica da Apple
    </ResponseField>
  </Expandable>
</ResponseField>

### Exemplo de Resposta

```json theme={null}
{
  "sessionData": {
    "epochTimestamp": 1705319400000,
    "expiresAt": 1705319700000,
    "merchantSessionIdentifier": "SSH2EAF8AFAEAA94DEA3EB4E797AE2D2E6_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24",
    "nonce": "89dba098",
    "merchantIdentifier": "merchant.com.suaempresa.sualoja",
    "domainName": "checkout.sualoja.com.br",
    "displayName": "Sua Loja",
    "signature": "308006092a864886f70d010702a0803080020101310f300d06096..."
  }
}
```

## Códigos de Erro

<AccordionGroup>
  <Accordion title="400 - Bad Request" icon="circle-xmark">
    Parâmetros faltando ou inválidos

    ```json theme={null}
    {
      "message": "ValidationURL and domainName are required",
      "errors": {
        "validationURL": ["ValidationURL is required"],
        "domainName": []
      }
    }
    ```

    **Causas comuns:**

    * `validationURL` ou `domainName` não foram fornecidos
    * Formato inválido dos parâmetros
  </Accordion>

  <Accordion title="400 - Apple Pay Session Validation Failed" icon="circle-xmark">
    Falha na validação com a Apple

    ```json theme={null}
    {
      "message": "Apple Pay session validation failed"
    }
    ```

    **Causas comuns:**

    * Domínio não foi registrado pela Autorizou (solicite ao suporte)
    * Arquivo de verificação não está acessível no seu domínio
    * `validationURL` expirada (execute o fluxo mais rapidamente)

    **Solução:**

    1. Confirme que solicitou o registro do domínio ao suporte da Autorizou
    2. Verifique se o arquivo está acessível em: `https://seu-dominio/.well-known/apple-developer-merchantid-domain-association.txt`
    3. Se persistir, entre em contato com o suporte
  </Accordion>

  <Accordion title="500 - Internal Server Error" icon="circle-xmark">
    Erro na configuração interna da Autorizou. Pode retornar uma das mensagens abaixo:

    ```json theme={null}
    {
      "message": "Apple Pay certificates not configured properly"
    }
    ```

    ```json theme={null}
    {
      "message": "Session validation failed due to server error"
    }
    ```

    **Solução:**

    * Entre em contato com o suporte da Autorizou
    * Informe o domínio e horário do erro
    * A equipe técnica verificará a configuração
  </Accordion>
</AccordionGroup>

## Fluxo Completo de Integração

Este endpoint faz parte de um fluxo maior. Veja como ele se encaixa:

<Steps>
  <Step title="Usuário clica no botão Apple Pay">
    Frontend detecta o clique e inicia `ApplePaySession`
  </Step>

  <Step title="Apple dispara evento onvalidatemerchant">
    Fornece `validationURL` única para esta sessão
  </Step>

  <Step title="Frontend chama este endpoint">
    Envia `validationURL` e `domainName` para validação
  </Step>

  <Step title="Autorizou valida com Apple">
    Usa certificados Merchant Identity para estabelecer confiança
  </Step>

  <Step title="Retorna sessionData">
    Frontend recebe dados de sessão validados
  </Step>

  <Step title="Frontend completa validação">
    Chama `session.completeMerchantValidation(sessionData)`
  </Step>

  <Step title="Apple Pay exibe interface">
    Usuário pode selecionar cartão e autorizar pagamento
  </Step>

  <Step title="Processa pagamento">
    Token Apple Pay é enviado para `/api/v1/charges/orders`
  </Step>
</Steps>

## Segurança

### Como Funciona a Validação

1. **Seu domínio** deve estar verificado no Apple Developer Portal
2. **Certificado Merchant Identity** prova que você controla o Merchant ID
3. **Apple valida** que domínio + certificado + Merchant ID são consistentes
4. **Apple retorna** sessão criptografada válida por 5 minutos

### Boas Práticas

<Check>**✓ Sempre** use HTTPS para servir a página com Apple Pay</Check>
<Check>**✓ Valide** que o domínio está correto antes de chamar o endpoint</Check>
<Check>**✓ Trate erros** adequadamente e mostre mensagem amigável ao usuário</Check>
<Check>**✓ Não reutilize** sessionData - cada sessão é única</Check>

<Warning>
  **Nunca** armazene ou faça cache do `sessionData`. Ele é único por sessão e expira rapidamente (5 minutos).
</Warning>

## Próximos Passos

Após validar a sessão com sucesso:

1. [Implementar fluxo completo de Apple Pay](/api-reference/payments/apple-pay-integration)
2. [Criar pedido com Apple Pay](/api-reference/charges/orders/create-order#pagamento-com-apple-pay)
3. [Configurar webhooks](/api-reference/webhooks/webhook-configuration) para notificações

## Recursos Adicionais

<CardGroup cols={2}>
  <Card title="Guia Completo Apple Pay" icon="apple" href="/api-reference/payments/apple-pay-integration">
    Documentação completa de integração
  </Card>

  <Card title="Apple Developer Docs" icon="book" href="https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/requesting_an_apple_pay_payment_session">
    Documentação oficial da Apple
  </Card>

  <Card title="Criar Pedido" icon="shopping-cart" href="/api-reference/charges/orders/create-order">
    Processar pagamento Apple Pay
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/webhook-configuration">
    Receber notificações de pagamento
  </Card>
</CardGroup>