Wallets

Essa seção descreve todas as etapas necessárias para a integração do fluxo de pagamento com as wallets Apple Pay e o Google Pay.

Uma das mudanças significativas entre pagamentos via wallet e transações tradicionais (endpoint transactions) está no formato do response, que pode ser tanto síncrono quanto assíncrono. No caso das wallets, as transações introduzem um novo status síncrono SENT, enquanto a atualização do status final da transação ocorre de forma assíncrona via webhook, indicando se o pagamento foi concluído com sucesso ou não.

IMPORTANTE

Esta documentação, por enquanto, cobre apenas a integração do Google Pay e Apple Pay para web.

Integração Web

Para processar pagamentos com Google Pay e Apple Pay na web, é necessário integrar as APIs de cada plataforma entretanto ambas as plataformas seguem o mesmo padrão de implementação, que são:

* Incluir os scripts necessários no seu site para carregar os SDKs e inicializar os métodos de pagamento;
* Definir as configurações exigidas por cada plataforma, como métodos de pagamento aceitos, moeda e país;
* Validar e encaminhar os dados validados para a Marlim para processar e concluir o pagamento.

Google Pay

Etapa 1 - Importação do SDK

Para utilizar o Google Pay, é necessário carregar o SDK JavaScript. Isso permite inicializar o botão de pagamento e o processamento da transação. Inclua o código abaixo importanto o script SDK Javascript do Google Pay.

<script async src="https://pay.google.com/gp/p/js/pay.js"></script>

Etapa 2 - Inicializar o SDK

Após carregar o script do SDK, o próximo passo é inicializar a instância que permitirá interagir com a API do Google Pay e gerenciar o fluxo de pagamentos. Durante a realização de testes, defina a propriedade environment para o valor TEST. Para produção, altere o valor como PRODUCTION.

const paymentsClient = new google.payments.api.PaymentsClient({
  environment: "TEST",
});

Etapa 3 - Exibir Botão de pagamento

Para exibir o botão do Google Pay na interface do usuário, primerio é necessário criar um elemento HTML onde ele será renderizado. Esse elemento servirá como um contêiner para o botão, permitindo que o SDK do Google Pay o insira dinamicamente na página. Inclua a seguinte div onde deseja na página.

<div id="gpay-button"></div>

O passo seguinte é repassar o elemento div para o SDK informando onde o botão deverá ser renderizado.

const processPayment(paymentsClient) = (paymentsClient) => { }

const button = paymentsClient.createButton({
    onClick: () => processPayment(paymentsClient), // Iremos falar sobre o método processPayment na etapa 5
});
    
document.getElementById("gpay-button").appendChild(button);

Etapa 4 - Montar Request para o SDK

Após inicializar o SDK, o próximo passo é definir os detalhes da transação, especificando os campos que devem ser enviados na requisição para Google Pay.

Atributo	Tipo	Descrição
apiVersion	number	Versão da API do Google Pay.
apiVersionMinor	number	Versão menor da API do Google Pay.
allowedPaymentMethods	array	Métodos de pagamento que habilita o uso de cartões de crédito.
allowedAuthMethods	array	Métodos de autenticação permitidos para o pagamento. Utilize sempre CRYPTOGRAM_3DS e PAN_ONLY.
allowedCardNetworks	Array	Redes de cartões permitidos. Utilize sempre MASTERCARD, VISA e AMEX.
allowCreditCards	boolean	Define se cartões de crédito são permitidos. Use sempre como true.
allowPrepaidCards	boolean	Define se cartões pré-pagos são permitidos. Use sempre como false
tokenizationSpecification	object	Especifica os detalhes de tokenização do pagamento, incluindo o gateway de pagamento e o ID do comerciante (Worldpay).
gateway	string	Nome do gateway de pagamento utilizado. Utilize sempre como worldpay
gatewayMerchantId	string	ID único fornecido pelo gateway de pagamento. Ambiente de teste use b3ee6508b9d95bd; de produção use ...
merchantId	string	ID único usado para identificar a loja.
merchantName	string	Nome do comerciante ou da loja. (ex: Mercado Bitcoin)
totalPriceStatus	string	Status do preço total da transação. Utilize sempre como FINAL
totalPriceLabel	string	Rótulo do preço total na interface de pagamento (ex: Total).
totalPrice	string	Valor total da transação em formato string e permitido para apenas duas casas decimais. (ex: 100, 100.01, 100.99)
currencyCode	string	Código da moeda para a transação. Utilize sempre BRL.
countryCode	string	Código do país onde a transação será realizada. Utilize sempre BR.
checkoutOption	string	Opção de finalização de compra. Para o cliente ser cobrado imediatamente após a confirmação utilize COMPLETE_IMMEDIATE_PURCHASE.

Abaixo segue o formato de como deve ser o payload que será enviado no método de processamento do SDK.

const googlePaymentRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [
    {
      type: "CARD",
      parameters: {
        allowedAuthMethods: ["CRYPTOGRAM_3DS", "PAN_ONLY"],
        allowedCardNetworks: ["MASTERCARD", "VISA", "AMEX"],
        allowCreditCards: true,
        allowPrepaidCards: false,
      },
      tokenizationSpecification: {
        type: "PAYMENT_GATEWAY",
        parameters: {
          gateway: "worldpay",
          gatewayMerchantId: "b3ee6508b9d95bd",
        },
      },
    },
  ],
  merchantInfo: {
    merchantId: "12345678910",
    merchantName: "Mercado Bitcoin",
  },
  transactionInfo: {
    totalPriceStatus: "FINAL",
    totalPriceLabel: "Total",
    totalPrice: "100.00",
    currencyCode: "BRL",
    countryCode: "BR",
    checkoutOption: "COMPLETE_IMMEDIATE_PURCHASE",
  },
};

Etapa 5 - Extrair o Token

Nesta etapa envie o payload da etapa anterior para o Google Pay e, ao receber a resposta, você irá extrair o token de resposta para enviá-lo à API de Transações da Marlim.
Complete a função processPayment criada na etapa 2, pois é nela que o token será extraído.

async function processPayment(googlePaymentsClient) {
  try {
    const response = await googlePaymentsClient.loadPaymentData(
      googlePaymentRequest
    );
    const token = response.paymentMethodData.tokenizationData.token;

    console.log("Payment data", {
      token,
      response
    });
  } catch (err) {
    console.log("Load Payment error, err);
  }
}

Apple Pay

IMPORTANTE

Esta documentação será descrita em breve...

Inicie uma transação

Depois de concluir as etapas descritas anteriormente, seja para Google Pay ou Apple Pay, há um novo campo dedicado para cada integração e que devera ser enviado na API de transações do tipo wallets: v3/transactions/wallets

IMPORTANTE

Só será aceito um campo por vez, não é permitido o envio de ambos os campos juntos!

Atributo	Descrição
google_pay_token	Campo dedicado para o envio do token do Google Pay.
apple_pay_token	Campo dedicado para o envio do token da Apple Pay.

Request

curl -X POST "https://api.crypto.mb.marlim.co/v3/transactions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "item_id": "123456789",
  "item_url": "https://seusite.com/pedido/123456789",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1122",
  "card_cvv": "123",
  "customer[name]": "Luke Skywalker",
  "customer[email]": "luke@jedimaster.sw",
  "customer[document_number]": "00099988877",
  "customer[phone][type]": "mobile",
  "customer[phone][area]": "11",
  "customer[phone][number]": "988887777",
  "customer[address][zipcode]": "95351",
  "customer[address][state]": "CA",
  "customer[address][city]": "Modesto",
  "customer[address][neighborhood]": "East Modesto",
  "customer[address][street]": "Sunset Ave",
  "customer[address][number]": "713",
  "google_pay_token": "{\"signature\":\"MEUCIQC0UjNrPOwkpYgo1mFF/9O7U88iWeUxlosNk4E55KbBJwIgD/0G78NXW\\u003d\",\"protocolVersion\":\"ECv1\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"c30IFg4sq34/iW4MFpPcs84BM8f+r+...EZ9ssPJlVSm2zEIch0tgJP5hYkBlKHWCFNLtdMi4JAkOKzV+3p2vn7fDSqhwe3eTyLcvKEDNnfuY/tdXKjEc0CxThibkTiGibPfl9xQ5jPgEfXnU+y1+Oykx0kU14l06EBXUAXAcPFAtepipFB0fgXKlg+...Xvn5Ar1yNDfkn7E9jUBW9S/xw\\\\u003d\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BDyWw95K1IVBKh7lmA4wXkFYmVESrkqed...W63WIIYIpGryXQi/FVrFA\\\\u003d\\\",\\\"tag\\\":\\\"QA5+UyDcQWlEpXBrzBiCdmK+...6Vw9c\\\\u003d\\\"}\"}",
  "soft_descriptor": "Star Wars"
}'

Response200

{
  "status": "sent",
  "date_created": "2025-02-28T11:53:12.954Z",
  "date_updated": "2025-02-28T11:53:12.954Z",
  "net_value": 1000000,
  "authorized_amount": 103950,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "11122233"
}

Webhooks

Após o usuário finalizar o pagamento, a Wallet emite uma atualização para o nosso Adquirente, informando se a transação foi bem sucedida ou não. A Marlim, por sua vez, emite o Webhook com os dados transacionais.

Request

curl -X POST "https://seusite.com/pedido/123456789/callback" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-d '{
  "transaction_id": "98765432",
  "event": "transaction_status_changed",
  "old_status": "processing",
  "current_status": "paid",
  "nsu": "98765432",
  "date_created": "2025-02-28T11:53:12.954Z",
  "date_updated": "2025-02-28T11:53:12.954Z",
  "net_value": 1000000,
  "authorized_amount": 103950,
  "paid_amount": 103950,
  "refunded_amount": 0,
  "installments": "1",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000"
}'