1. Propósito da API
A API permite que mediators (clientes da Flagship) gerem QR Codes Pix para realizar cobranças a clientes finais. Isso proporciona integração simplificada com o sistema de pagamentos instantâneos (Pix).
2. Autenticação
A API usa autenticação robusta:
Certificado mTLS: O cliente deve enviar um certificado client válido em todas as requisições. Para instruções detalhadas de geração dos certificados client e root, siga os passos de 1 a 8 descritos neste artigo: Introdução à autenticação mTLS no Amazon API Gateway.
OAuth2: É necessário obter um token de acesso com client_id, client_secret e o campo grant_type com valor client_credentials.
Transaction-Hash: Gerado dinamicamente para cada requisição usando:
Campos concatenados: alias + totalAmount + accountId + recipientAmount (nessa ordem).
SecretKey do cliente.
Algoritmo: CryptoJS.HmacSHA256. O algoritmo deve ser aplicado nos campos concatenados anteriormente, utilizando a secretKey como chave.
3. URLs dos Endpoints
Produção
URL para geração do token: https://mtls-mp.prd.flagship.maas.link/auth/realms/Matera/protocol/openid-connect/token
URL para geração do QR Code: https://mtls-mp.prd.flagship.maas.link/v1/payments
Homologação
URL para geração do token: https://mtls-mp.hml.flagship.maas.link/auth/realms/Matera/protocol/openid-connect/token
URL para geração do QR Code: https://mtls-mp.hml.flagship.maas.link/v1/payments
4. Fluxo de Uso
Geração do Certificado
Crie um certificado root (10 anos) e um certificado client (1 ano), conforme orientação enviada no passo 2 acima.
Envie o root para a Flagship via ticket no portal de suporte (Freshdesk).
Utilize o certificado client para assinar as requisições.
Geração do Token
Faça uma requisição para o endpoint de token com os seguintes parâmetros no body:
grant_type=client_credentials
client_id=<SEU_CLIENT_ID>
client_secret=<SEU_CLIENT_SECRET>
Exemplo de cURL em homologação:
curl -L -X POST 'https://mtls-mp.hml.flagship.maas.link/auth/realms/Matera/protocol/openid-connect/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'client_id=teste' \
-d 'client_secret=teste1234556'
Exemplo de Resposta:
{
"accesstoken": "<SEU-TOKEN>",
"expires_in": 1800,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}
Geração do QR Code
Use o token obtido e os cabeçalhos necessários.
Monte o corpo da requisição com as informações do pagamento.
Cabeçalhos necessários:
Content-Type: application/json
Authorization: Bearer <TOKEN>
Transaction-Hash: <HASH_GERADO>
Exemplo de Geração do QR Code (Homologação):
curl -L -X POST 'https://mtls-mp.hml.flagship.maas.link/v1/payments' \
-H 'Content-Type: application/json' \
-H 'Transaction-Hash: bd647df67cc31083b0ce131ceb4f1e799398382a680aaf1182a336428ef90bdf' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
"externalIdentifier": "CA26F0B1-CDB2-4C74-B8D9-7F6ED56AB7F8",
"totalAmount": "38.95",
"currency": "BRL",
"paymentInfo": {
"transactionType": "InstantPayment",
"instantPayment": {
"accountHolderCity": "Campinas",
"alias": "95b3a8c1-3350-4b07-a459-1ce0e7c7f7f7",
"qrCodeImageGenerationSpecification": {
"errorCorrectionLevel": "M",
"imageWidth": 400,
"generateImageRendering": true
},
"expiration": 86400,
"additionalInformation": [
{
"name": "ID DO PEDIDO",
"content": "123456",
"showToPayer": true
}
]
}
},
"recipients": [
{
"account": {
"accountId": "23DE716E-C37A-96D8-AE99-9207897E1CD5"
},
"amount": "38.95",
"currency": "BRL",
"mediatorFee": 1.37,
"recipientComment": "Recipient comment 123"
}
],
"callbackAddress": "https://testemockqr.requestcatcher.com/"
}'
Exemplo de Resposta:
{
"data": {
"transactionId": "6A24B1E5-8805-993F-B689-C4FD7551954D",
"externalIdentifier": "37709E49-DE65-4BBF-A0F3-48542DC2960C",
"financialStatement": {
"status": "CREATED"
},
"transactionDate": "2025-01-22T12:06:59.81-03:00",
"transactionType": "InstantPayment",
"totalAmount": 38.95,
"paidAmount": 38.95,
"instantPayment": {
"textContent": "00020101021226990014br.gov.bcb.pix2577pix-h.bpp.com.br/23114447/qrs1/v2/01iqIHT91ZWssUgJyjVGsgBfv9QHqsIO4Q5CxDPSCCs520400005303986540538.955802BR5923Razao Social da Empresa6008Campinas62070503***63042D32",
"reference": "QRS1TXPZBRHLCQBCMSNSFP9MWC8YLKPI0FP",
"qrcodeURL": "https://pix-h.bpp.com.br/23114447/qrs1/v2/01iqIHT91ZWssUgJyjVGsgBfv9QHqsIO4Q5CxDPSCCs",
"generateImage": {
"imageContent": "<BASE_64_DO_QR_CODE>",
"mimeType": "image/png",
"actualImageWidth": 400
},
"dynamicQrCodeType": "IMMEDIATE"
}
}
}
5. Validações e Boas Práticas
Sempre teste primeiro no ambiente de homologação.
Armazene o certificado root com segurança, sempre lembrando quem em 1 ano o client irá vencer, e deverá ser gerado um novo que será assinado pelo mesmo root.
Registre os erros e mensagens retornadas pela API para facilitar suporte.
Documentação Oficial: Para mais detalhes, consulte a documentação oficial da API de geração de QR Code da Flagship.