Passes de Carteira

Para gerar um Passe de Carteira (Wallet Pass) é usada a action chamada save-in-wallet, que funciona semelhantemente à action de Cartões Virtuais e possui a seguinte estrutura:

{
  "icon": "EAAE",
  "name": "save-in-wallet",
  "order": 0,
  "parameters": [
    {
      "title": "querystring",
      "value": "?path=wallet"
    }
  ],
  "path": "MS_PASS",
  "permissionLevel": 2,
  "publishLevel": 1
}

Ao acionar a action, o fluxo executado é o da imagem abaixo:

Essa action pode ser adicionada em qualquer ponto da aplicação, e uma vez selecionada ela inicia o fluxo de geração do pass (card) e em seguida permite o usuário adicionar no Google ou Apple Wallet.

Você pode adicionar a action save-in-wallet na tela de carteirina. Parra isso basta retornar a action no JSON dos dados do cartão, como descrito na área de Cartões Virtuais, na seção Formato dos dados retornados na integração.

Observe que a action save-in-wallet possui um segundo path que deve ser passado na querystring, e é importante fazemos a distinção entre eles.

Para que a action save-in-wallet funcione é importante que:

• O valor do path principal sempre seja MS_PASS. Esta é a forma que o backend identifica que o passe precisa ser gerado.

• O path secundário, definido dentro do parameter com título querystring, é o path para a integração que retorna os dados do cartão.

O conteúdo retornado pela integração definida no path secundário deve retornar os dados do cartão no seguinte formato:

{
        "pageContent": {
            "header": "mobileX CARD Plus",
            "codeType": "QR",
            "barcodeValue": "https://www.uol.com.br",
            "background": "#4C2D6E",
            "passId": "123456789",
            "logo": "https://mobilex.blob.core.windows.net/files/sem_imagem_logo.jpeg",
            "android": {
                "cardTitle": "Cartão mobileX User",
                "subHeader": "5468 1265 7489 0056",
                "heroImage": "https://t4.ftcdn.net/jpg/15/73/59/37/360_F_1573593750_kGfnEj1Ch4lPKTTqsjwlCkoccFLEjepl.jpg",
                "state": "active",
                "messages": [
                    {
                        "header": "VALIDADE",
                        "body": "12/30"
                    },
                    {
                        "header": "TELEFONE",
                        "body": "(71) 9999-9999"
                    }
                ],
                "links": [
                    {
                        "description": "link de acesso",
                        "uri": "https://www.uol.com.br"
                    }
                ],
                "validTimeInterval": {
                  "start": {
                    "date": "2025-09-17T00:00:00Z"
                  },
                  "end": {
                    "date": "2025-09-20T01:45:00Z"
                  }
                }
            },
            "ios": {
                "labelColor": "#ffffff",
                "foregroundColor": "#ffffff",
                "icon": "https://mobilex.blob.core.windows.net/files/sem_imagem_logo.jpeg",
                "thumbnail": "https://mobilex.blob.core.windows.net/files/sem_imagem_logo.jpeg",
                "expirationDate": "2025-09-23T19:55:00Z",
                "primaryFields": [
                    {
                        "key": "name",
                        "label": "NOME",
                        "value": "Rinaldo Silva"
                    }
                ],
                "secondaryFields": [
                    {
                        "key": "expiration-date",
                        "label": "VALIDADE",
                        "value": "12/30"
                    },
                    {
                        "key": "customer-service",
                        "label": "TELEFONE",
                        "value": "(71) 9999-9999"
                    }
                ]
            }
        }
    }

Os parâmetros acima definem o pass conforme imagem abaixo:

No wallet do Google algumas informações são exibidas na área de menu de 3 pontinhos:

Para o iOS o formato é o seguinte:

Observe também que iOS e Android possuem objetos separados no json, visto que cada plataforma tem parâmetros específicos e individuais.

Note que o parâmetro codeType pode ter os valores QR para exibir um QRCode ou CODE_128 para exibir um código de barras, ambos utilizarão o valor do campo barcodeValue para gera seu conteúdo.

O campo passId deve ser informado um ID único do objeto para cada cartão gerado do usuário.

Quanto a validade do pass, cada plataforma tem uma maneira de informar, iOS por exemplo basta informas uma data de expiração no campo expirationDate e no Android no campos validTimeInterval que é um intervalo de tempo que o pass permanece válido, porém não é garantido a expiração imediata no final da validade, para efeito imediato utilize também para android o campo status com o valor expired.

Quando às cores o Android tem uma facilidade. A depender da tonalidade da cor de background, a cor dos textos é escolhida automaticamente. No caso do iOS o mesmo não acontece. É de sua responsabilidade definir também a cor dos textos se definir uma cor de fundo.

• pageContent.ios.labelColor: Cor dos títulos dos campos.

• pageContent.ios.foregroundColor: Cor dos valores dos campos.

Por exemplo, se eu tiver um campo com título NOME e valor Antônio Matos, NOME terá a cor do labelColor e Antônio Matos terá a cor do foregroundColor.

A imagem de ícone do iOS (pageContent.ios.icon) também é obrigatória, e deve ser 58x58.