2 - Conta Sandbox

Esta etapa é necessária para validar corretamente o fluxo do Tap to Pay on iPhone em ambiente de testes. Além da criação da conta sandbox da Apple, também é necessário configurar o SDK com o ambiente correto, usar as credenciais sandbox da Zoop e garantir que o aplicativo iOS tenha acesso ao endpoint sandbox.

Antes de começar

Antes de seguir com a configuração, valide os itens abaixo:

• Garanta que o aplicativo possui o entitlement de Tap to Pay on iPhone devidamente aprovado pela Apple para o bundle utilizado nos testes, sem esse entitlement aprovado, o fluxo de inicialização e pagamento não será concluído com sucesso, mesmo com conta sandbox e credenciais corretas.

• Acesse sua conta Apple Developer em developer.apple.com/account.
• Separe um e-mail válido para criar o usuário sandbox.
• Tenha em mãos as credenciais Zoop do ambiente sandbox:
  • marketplace
  • seller
  • accessKey
• Garanta que os testes serão executados em um iPhone físico compatível com Tap to Pay on iPhone.
• Se ainda não configurou o projeto iOS, revise a etapa anterior: 1 - Adicionar ao projeto

Criando a conta sandbox

1. Abra sua conta Apple Developer e acesse Usuários e Acesso.

   

2. No menu lateral, abra a opção Sandbox.

   

3. Clique no botão + para adicionar um novo usuário sandbox.

4. Preencha os dados do usuário e conclua a criação da conta.

   

Ao final desse processo, você terá um usuário sandbox da Apple disponível para uso nos testes do fluxo.

Configurando a conta no telefone

1. No iPhone, abra a área de configuração da conta.

2. Selecione o usuário criado e defina essa conta como conta base para os testes.

   

Resultado esperado

Depois da configuração, o iPhone passa a usar a conta sandbox criada para executar os testes do fluxo.

Configurando o SDK para usar sandbox

Além de configurar a conta sandbox no iPhone, o aplicativo integrador também deve configurar o SDK para operar no ambiente sandbox.

A definição do ambiente é feita na chamada de TapOnPhone.setConfig(...), por meio do objeto ConfigParameters.

Exemplo:

let credentials = TapOnPhoneCredentials(
    marketplace: "<MARKETPLACE>",
    seller: "<SELLER>",
    accessKey: "<ACCESS_KEY>"
)

let config = ConfigParameters(
    credentials: credentials,
    environment: .sandbox,
    logLevel: .error,
    sdkConfig: SdkConfig()
)

TapOnPhone.setConfig(configParameters: config)

O que validar nessa etapa

• O marketplace informado pertence ao ambiente sandbox.
• O seller informado pertence ao ambiente sandbox.
• O accessKey informado pertence ao ambiente sandbox.
• O valor de environment foi definido como .sandbox.

Quando a validação da configuração acontece

A chamada de TapOnPhone.setConfig(...) aplica a configuração local do SDK, mas não valida imediatamente as credenciais na API.

Na prática, isso significa que:

• setConfig(...) não confirma sozinho que a conta sandbox está pronta para uso.
• Erros de credencial, ambiente, conectividade ou ativação costumam aparecer em initialize(...) ou na primeira chamada de pay(...).

Esse comportamento é esperado.

Sequência recomendada de integração em sandbox

Para reduzir falhas de configuração e facilitar o diagnóstico, use a sequência abaixo:

• Chame TapOnPhone.setConfig(...).
• Execute processOnboarding(...), quando aplicável.
• Execute processTermsAndConditions(...), quando aplicável.
• Chame initialize(...).
• Chame pay(...).

Essa ordem ajuda a identificar em qual etapa a integração falha.

Configuração de rede no aplicativo iOS

Para o ambiente sandbox, o aplicativo iOS também precisa estar apto a se comunicar com a API correspondente.

Domínio do ambiente sandbox:

• payments.api.sandbox.zoop.ws

Se houver falha de comunicação mesmo com as credenciais corretas, revise a configuração de rede do aplicativo, incluindo as definições de NSAppTransportSecurity e NSExceptionDomains no Info.plist, conforme necessário para o acesso ao ambiente sandbox.

Checklist de validação para sandbox

Antes de iniciar os testes de pagamento, valide todos os pontos abaixo.

Entitlement da Apple

• O bundle identifier usado no app de testes possui o entitlement de Tap to Pay on iPhone aprovado pela Apple.
• O provisioning profile e a assinatura do app correspondem ao bundle com esse entitlement aprovado.
• O app instalado no dispositivo foi gerado com a configuração correta de assinatura e entitlement.

Conta sandbox da Apple

• A conta sandbox foi criada com sucesso na Apple Developer.
• O usuário sandbox foi configurado no iPhone.
• O usuário sandbox foi definido como conta base para os testes.

Configuração do SDK

• O app chamou TapOnPhone.setConfig(...).
• O objeto ConfigParameters foi montado com environment: .sandbox.
• O app está usando marketplace, seller e accessKey da conta sandbox.

Fluxo de habilitação

• O onboarding foi executado com sucesso, quando aplicável.
• O fluxo de termos e condições foi executado com sucesso, quando aplicável.
• O teste seguiu a ordem recomendada de chamadas.

Dispositivo

• O teste está sendo feito em iPhone físico.
• O dispositivo é compatível com Tap to Pay on iPhone.
• O aparelho está na versão de iOS suportada pelo SDK.

Rede

• O dispositivo está com acesso à internet.
• Não há VPN bloqueando o tráfego.
• Não há proxy interceptando as chamadas.
• Não há firewall corporativo bloqueando o acesso.
• O aplicativo iOS possui a configuração de rede necessária para o ambiente sandbox.

Troubleshooting do erro 6069

O erro 6069 indica falha de comunicação com a API.

Esse erro normalmente está relacionado a configuração incorreta do ambiente, uso de credenciais inválidas para sandbox, pendência na habilitação do fluxo de testes ou bloqueio de comunicação de rede.

Se receber 6069 em sandbox, valide na ordem abaixo:

• Confirme que o app chamou TapOnPhone.setConfig(...) com environment: .sandbox.
• Confirme que marketplace, seller e accessKey pertencem ao ambiente sandbox.
• Confirme que a conta sandbox da Apple foi criada e configurada no iPhone como conta base para os testes.
• Confirme que o onboarding e o fluxo de termos foram concluídos, quando aplicável.
• Confirme que o app iOS possui a configuração de rede necessária para acessar payments.api.sandbox.zoop.ws.
• Confirme que o dispositivo está com internet disponível e sem restrições de VPN, proxy ou firewall.
• Confirme em qual etapa o erro ocorre:
  1. processOnboarding(...)
  2. processTermsAndConditions(...)
  3. initialize(...)
  4. pay(...)
• Confirme que o app em teste possui o entitlement de Tap to Pay on iPhone aprovado pela Apple para o bundle utilizado, pois esse é um pré-requisito para o fluxo completo.

Evidências recomendadas para análise

Se o problema persistir após o checklist, reúna as informações abaixo para acelerar a análise:

• Trecho de integração que monta o ConfigParameters.
• Confirmação de que o environment foi definido como .sandbox.
• Confirmação de que as credenciais usadas pertencem ao ambiente sandbox.
• Indicação de em qual método o erro ocorreu.
• Logs do callback de erro, com dados sensíveis mascarados.
• Versão do iOS.
• Modelo do iPhone.
• Confirmação de que o teste foi feito em dispositivo físico.
• Confirmação de que a conta sandbox da Apple foi configurada como conta base para os testes no iPhone.

Resumo

Para testar com sucesso no ambiente sandbox, valide sempre estes quatro pontos principais:

• A conta sandbox da Apple foi criada e configurada no iPhone como conta base para os testes.
• O SDK foi configurado com environment: .sandbox.
• As credenciais utilizadas pertencem ao ambiente sandbox.
• O aplicativo iOS possui a configuração de rede necessária para acessar a API sandbox.

Se qualquer um desses pontos estiver incorreto, o fluxo pode falhar antes mesmo do pagamento.