Etapa 1: configurar o sandbox

O sandbox é um ambiente de teste para o serviço de identidade da Carteira do Google. Ele usa IDs de teste em vez de IDs reais para que você possa criar e depurar sua integração sem tocar nos dados de produção.

Por padrão, a Carteira do Google opera no modo de produção com documentos de identificação reais. Nesta etapa, você vai alternar um dispositivo de teste para o modo sandbox e configurar o servidor para solicitações e respostas de sandbox.

Etapas nesta página

Antes de começar

• Um dispositivo Android que você pode redefinir. A mudança para o sandbox exclui os dados de produção da Carteira do dispositivo. Por isso, não use seu smartphone pessoal.
• Uma Conta do Google@gmail.com conectada à Carteira do Google no dispositivo.
• Somente para registradores de verificadores:envie o formulário de admissão de registradores de verificadores com seus certificados de CA raiz de sandbox e de produção para que o Google possa adicionar sua CA raiz de sandbox ao repositório de confiança de sandbox. Consulte a Etapa 5.A: enviar o formulário de admissão, os certificados raiz e aceitar os Termos de Serviço.

Etapa A: solicitar acesso ao sandbox para sua conta de teste

A opção de alternar entre sandbox e produção fica oculta por padrão. Para ativar o botão no dispositivo de teste, sua Conta do Google precisa ser adicionada à lista de permissões do sandbox:

1. Preencha o formulário de solicitação de acesso ao sandbox do Google Pay com a Conta do Google que você usa na Carteira do Google.
2. Se você estiver testando em um país ou região onde os documentos de identificação digitais ainda não foram lançados oficialmente, envie também os endereços do Gmail das suas contas de teste para wallet-identity-rp-support@google.com.

Etapa B: mudar o dispositivo para o modo sandbox

1. Abra o app Configurações no dispositivo Android de teste.
2. Toque na sua Conta do Google / foto do perfil na parte de cima da tela (seu nome e "Serviços e preferências do Google" vão aparecer).
3. Se solicitado, escolha seu perfil e toque em Todos os serviços.
4. Acesse a categoria Outro e toque em Ambiente de TapAndPay. Se Ambiente de TapAndPay não estiver aparecendo, reinicie o dispositivo e recomece da etapa 1. Se ainda estiver faltando, verifique se sua conta está na lista de permissões do sandbox (Etapa A).

5. Toque no menu suspenso e escolha SANDBOX.

   

6. Uma caixa de diálogo notifica que o ambiente mudou. Toque em OK e reinicie o dispositivo.

   

7. Abra a Carteira do Google após a reinicialização. Se a caixa de diálogo a seguir aparecer, force o fechamento e reabra a Carteira do Google para que ela seja sincronizada com o ambiente de sandbox:

   

Etapa C: confirmar se o dispositivo está no modo sandbox

1. Abra o app Carteira do Google wallet.
2. No canto superior direito, toque na sua foto do perfil ou em Conta account_circle > Configurações da Carteira.
3. Vá até a parte de baixo da página. Se aparecer uma mensagem de confirmação com SANDBOX, seu dispositivo está configurado para chamadas de sandbox. Se nenhuma mensagem for exibida, ele estará no modo de produção.

Alguns dispositivos não mostram a Carteira do Google nas Configurações do Google. Para abrir as configurações da Carteira do Google nesses dispositivos, use adb com o seguinte comando:

adb shell am start -n com.google.android.gms/com.google.android.gms.tapandpay.settings.TapAndPaySettingsActivity

Voltar para a produção

Repita a Etapa B, mas selecione PRODUÇÃO em vez de SANDBOX.

Dispositivos Wear OS

Para ativar o modo sandbox em um dispositivo Wear OS conectado, adicione um arquivo vazio e reinicie:

adb shell touch /sdcard/Download/android_pay_env_override_sandbox
adb reboot

Para voltar ao modo de produção, exclua o arquivo e reinicie o dispositivo:

adb shell rm /sdcard/Download/android_pay_env_override_sandbox
adb reboot

Etapa D: configurar o servidor para o sandbox

No sandbox, seu servidor precisa de duas coisas:

1. Solicite credenciais de assinatura confiáveis para o sandbox da Carteira do Google:
   • Partes confiáveis:use o par de chaves de teste do sandbox pré-confiável do Google e os seguintes metadados de amostra. Não é necessário enviar um formulário.
   • Registradores de verificação:assine solicitações assinadas com um certificado de folha emitido pela sua própria CA raiz do sandbox (depois que o Google o adicionar ao repositório de confiança do sandbox) e gere seu próprio gw_rp_metadata_bytes, conforme descrito na Etapa 3.A: configurar o perfil do certificado de CA e os metadados CBOR.
2. Âncora de confiança de verificação de resposta:as partes confiáveis e os registradores de verificação precisam adicionar o certificado do Utopia Sandbox ao repositório de confiança do servidor para validar as respostas de um ID de teste de sandbox.

Chaves e metadados de teste de sandbox (partes confiáveis)

Para testar solicitações assinadas no ambiente de sandbox sem registrar suas próprias chaves de produção, use o par de chaves de teste a seguir. Essas chaves são pré-confiáveis no ambiente de sandbox.

Instruções

1. Use a chave privada de teste para assinar sua solicitação (JWS).
2. Incorpore o certificado público de teste no cabeçalho x5c da solicitação.
3. Defina client_id como o x509_hash desse certificado. Consulte Solicitações assinadas para saber como calcular o hash.
4. Defina gw_rp_metadata_bytes em client_metadata como os seguintes metadados de teste da parte confiável (Base64url CBOR).

Chave privada (PEM):

-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQggRmIZIHQhXcYIeZ7
KSqS/WwJrsOetdI8ZE4HG0fd+3uhRANCAAR3GR6mdt/NOErO7+XtKqo7orgXWPMI
jEQDeE1PP4KWXTBAhuewPvF8uOiYakz5Jqd1kEFKfiecZEZRrLnC7U+e
-----END PRIVATE KEY-----

Metadados da parte confiável (Base64url CBOR):

2BhY56Juc2NoZW1hX3ZlcnNpb25idjFnZGlzcGxheaNsZGlzcGxheV9uYW1leBhURVNUIFVTRSBPTkxZIFNhbmRib3ggUlBobG9nb191cml4YWh0dHBzOi8vZm9udHMuZ3N0YXRpYy5jb20vcy9pL3Byb2R1Y3Rsb2dvcy9nb29nbGVnL3Y2L3dlYi02NGRwL2xvZ29fZ29vZ2xlZ19jb2xvcl8xeF93ZWJfNjRkcC5wbmdycHJpdmFjeV9wb2xpY3lfdXJpeCNodHRwczovL3BvbGljaWVzLmdvb2dsZS5jb20vcHJpdmFjeQ

Metadados da parte confiável (CBOR Dump):

#24# .bstr

{
  "schema_version": "v1",
  "display": {
    "display_name": "TEST USE ONLY Sandbox RP",
    "logo_uri": "https://fonts.gstatic.com/s/i/productlogos/googleg/v6/web-64dp/logo_googleg_color_1x_web_64dp.png",
    "privacy_policy_uri": "https://policies.google.com/privacy"
  }
}

Certificado público (PEM):

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            97:99:aa:8b:09:93:5a:20:c1:8b:27:6c:e2:da:91:97:f2:b7:79:8d
        Signature Algorithm: ecdsa-with-SHA256
        Issuer: O=Google, OU=Wallet, CN=TEST USE ONLY Sandbox RP
        Validity
            Not Before: Jun  2 00:39:54 2026 GMT
            Not After : Jun  2 00:39:54 2027 GMT
        Subject: O=Google, OU=Wallet, CN=TEST USE ONLY Sandbox RP
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                pub:
                    04:77:19:1e:a6:76:df:cd:38:4a:ce:ef:e5:ed:2a:
                    aa:3b:a2:b8:17:58:f3:08:8c:44:03:78:4d:4f:3f:
                    82:96:5d:30:40:86:e7:b0:3e:f1:7c:b8:e8:98:6a:
                    4c:f9:26:a7:75:90:41:4a:7e:27:9c:64:46:51:ac:
                    b9:c2:ed:4f:9e
                ASN1 OID: prime256v1
                NIST CURVE: P-256
        X509v3 extensions:
            X509v3 Subject Key Identifier:
                29:CA:DA:07:9B:1F:68:FA:80:01:E1:68:E3:38:E8:5A:5C:28:B1:6A
            X509v3 Authority Key Identifier:
                29:CA:DA:07:9B:1F:68:FA:80:01:E1:68:E3:38:E8:5A:5C:28:B1:6A
            X509v3 Basic Constraints: critical
                CA:TRUE
            1.3.6.1.4.1.11129.10.1:
                . ...?..!H.Z\j...uT2. .u.:.O.... 0
    Signature Algorithm: ecdsa-with-SHA256
    Signature Value:
        30:46:02:21:00:91:94:fa:b9:85:82:92:bd:6a:98:44:73:ec:
        30:26:1f:92:01:8f:5b:06:d7:8f:21:34:dc:76:f0:89:3c:04:
        8c:02:21:00:ae:3e:9d:46:99:bd:63:7a:cc:59:30:66:48:d0:
        75:cc:c9:82:07:ca:39:f1:f0:df:2b:07:7b:32:b9:5b:3f:0a

-----BEGIN CERTIFICATE-----
MIICFDCCAbmgAwIBAgIVAJeZqosJk1ogwYsnbOLakZfyt3mNMAoGCCqGSM49BAMC
MEUxDzANBgNVBAoMBkdvb2dsZTEPMA0GA1UECwwGV2FsbGV0MSEwHwYDVQQDDBhU
RVNUIFVTRSBPTkxZIFNhbmRib3ggUlAwHhcNMjYwNjAyMDAzOTU0WhcNMjcwNjAy
MDAzOTU0WjBFMQ8wDQYDVQQKDAZHb29nbGUxDzANBgNVBAsMBldhbGxldDEhMB8G
A1UEAwwYVEVTVCBVU0UgT05MWSBTYW5kYm94IFJQMFkwEwYHKoZIzj0CAQYIKoZI
zj0DAQcDQgAEdxkepnbfzThKzu/l7SqqO6K4F1jzCIxEA3hNTz+Cll0wQIbnsD7x
fLjomGpM+SandZBBSn4nnGRGUay5wu1PnqOBhTCBgjAdBgNVHQ4EFgQUKcraB5sf
aPqAAeFo4zjoWlwosWowHwYDVR0jBBgwFoAUKcraB5sfaPqAAeFo4zjoWlwosWow
DwYDVR0TAQH/BAUwAwEB/zAvBgkrBgEEAdZ5CgEEIgQg5taUP70bIUiJWlxqkwYP
dVQyoyCvdaw62E8u4ASBIDAwCgYIKoZIzj0EAwIDSQAwRgIhAJGU+rmFgpK9aphE
c+wwJh+SAY9bBtePITTcdvCJPASMAiEArj6dRpm9Y3rMWTBmSNB1zMmCB8o58fDf
Kwd7MrlbPwo=
-----END CERTIFICATE-----

Certificado raiz da IACA do sandbox (todos os parceiros)

Os documentos de identificação de teste provisionados no sandbox são assinados pela autoridade emissora do sandbox do Google (Utopia). Para validar criptograficamente a assinatura issuerAuth nas respostas retornadas de um passe de identificação de teste de sandbox, adicione este certificado raiz ao repositório de confiança do verificador (não confie nele em produção):

Para certificados raiz de IACA de produção em estados e países compatíveis dos EUA, consulte Emissores e certificados de IACA compatíveis.

Tempo de atividade do sandbox

O ambiente de sandbox não tem SLAs de tempo de atividade, como existem para nosso ambiente de produção. Caso você se depare com um erro e suspeite que ele está relacionado a uma interrupção do serviço no sandbox, aguarde um dia útil nos Estados Unidos antes de entrar em contato com a gente. Na maioria dos casos, essas interrupções são resolvidas dentro desse período. Devido à possibilidade de inatividade, o melhor é que nenhum de seus processos de lançamento crítico seja dependente do ambiente de sandbox.

Próxima etapa

Etapa 2: criar um ID de teste →