Comunidade de Desenvolvedores maxiPago!

Pagamento com Apple Pay

 

Este manual de pagamento com Apple Pay visa tratar os conceitos básicos os detalhes técnicos de integração com o Apple Pay. Ele contém exemplos funcionais das requisições, que podem ser copiados e usados nos primeiros testes, além de observações importantes a serem levadas em conta durante a integração.

 

Pagamento com Apple Pay

 

Apple Pay é a carteira digital para os clientes dos produtos Apple (iPhone a partir do 6S, MacBook com o touch bar e Apple Watches). Um dos principais benefícios é que ele facilita o processo de checkout para o cliente.

Para oferecer Apple Pay para seus clientes, é preciso fazer a afiliação à Apple e ao Apple Pay (orientações no Guia de Afiliação – Apple Pay). Além disso, é imprescindível que seus compradores estejam acessando o site pelo browser Safari ou através do App em um dispositivo iOS compatível com o Apple Pay.

 

Integração via API

 

Existem dois fluxos de transação, um para web e outro para app. Essa divisão ocorre devido um processo de autenticação do lojista. Abaixo é possível ver os dois fluxos e as respectivas requisições e respostas.

 

1 – Fluxo Web

Fluxo de Pagamento do Apple Pay via Web

 

2 – Fluxo App

Fluxo de Pagamento do Apple Pay via App

 

WEB – SDK Apple Pay maxiPago!: https://github.com/maxipago/skd-java-apple-pay
iOS – SDK Apple Pay maxiPago!: https://github.com/maxipago/sdk-iOS-apple-pay

 

Modelos de Integração

 

Autenticação WEB Apple Pay (somente para solução para browser)

 

O Endpoint da API de criação da “ApplePaySession” (ambiente de testes) é: https://apple-pay-gateway-cert.apple.com/paymentservices/startSession

 

  • Método POST: /authentication
  • Endpoint: host/UniversalAPI/rest/EncryptedWallet/authentication

 

Nome Obrigatório Descrição
Wallet Sim Wallet da transação
Installments Sim Número de Parcelas
merchantIdentifier (Post JSON- Authenticate) Sim Merchat Identifier cadastrado na conta de Developer Apple
domainName Sim Domínio de origem da transação
displayName Sim Campo com informação que irá aparecer na tela do Apple Pay do cliente
validationURL Sim URL que representa o Endpoint para se autenticar nos servidores Apple

 

Parâmetros da Requisição de Autenticação (Web):

POST JSON – Authenticate

{
    "wallet":"applePay",
    "installments":"1",
    "walletDetail":{
        "merchantIdentifier":"merchant.maxipago.com",
        "domainName":"applestore-maxipago.herokuapp.com",
        "displayName":"your display name",
        "validationURL":"https://apple-pay-gateway-cert.apple.com/paymentservices/startSession"
    }
}

 

Response (HTTP 200):

Response – Apple Pay Session

{
    "merchantIdentifier": "51A8481F05813CC7395B6919A4ECC0CDE0DE372212F8...",
    "expiresAt": 1511904657790,
    "nonce": "1b9c462c",
    "domainName": "applepay-maxipago.herokuapp.com",
    "displayName": "your display name",
    "signature": "308006092a864886f70d010702a0803080020101310f300d06096086480165...",
    "merchantSessionIdentifier": "5780FC6CDEA3479B806355737602A019_916523AAED1343F5BC5815E12B...",
    "epochTimestamp": 1511897457790
}

 

Códigos de erro – Authenticate

 

400 – Bad Request

{
    "errorMessage": "Missing required parameters"
}

 

400 – Bad Request

{
    "errorMessage": "Invalid wallet"
}

 

400 – Bad Request

{
    "errorMessage": "Invalid JSON request"
}

 

500 – Internal Server Error

{
    "errorMessage": "Error processing authentication request"
}

Autenticação Transações WEB Apple Pay JSON (Web) e Apple Pay App (iOS)

 

Efetua a transação financeira através do envio dos dados do cartão e criptograma à adquirente. Método usado tanto para a solução web (Safari) tanto para os apps iOS.

 

  • Método POST: /order
  • Endpoint: host/UniversalAPI/rest/EncryptedWallet/order

 

Nome Obrigatório Descrição
Wallet Sim Wallet da transação
referenceNumber/ referenceNum Sim Identificador do pedido no estabelecimento. Este campo aceita apenas valores alfanuméricos e deve ser único.
installments Sim Número de cobranças a serem efetuadas.
chargeInterest Não Define se o parcelamento é do tipo loja ou cartão.
merchantIdentifier (Requisição) Sim Merchant Identifier cadastrado na conta de Developer Apple
transactionType Sim Campo de identificação do tipo de transação. Deve ser preenchido com auth (se for autorização), sale (se for Venda Direta) ou recurringPayment (se for criar uma recorrência)
paymentData Sim TAG originada pela requisição à Apple a ser incluída na requisição. Clique aqui para mais informações sobre as variáreis
processorID Não Código da adquirente que irá processar a transação

 

Parâmetros da Requisição de Autenticação (APP):

 

Pré-autorização com Captura posterior

{ 
   "wallet":"applePay",
   "referenceNumber":"TEST-APPLE-PAY-RF",
   "installments":4,
   "processorID":2,
   "chargeInterest":"Y",
   "walletDetail":{ 
      "merchantIdentifier":"merchant.maxipago.com",
      "transactionType":"auth",
      "applePayPayment":{ 
         "paymentData":{ 
            "version":"EC_v1",
            "data":"NdLVzUigHCHna6WaPP9J8Vk...",
            "signature":"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID...",
            "header":{ 
               "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEiQVImitonX2VcD8duPXsB8atbNo6O...",
               "publicKeyHash":"tjYuPcGjV8tsg33iOYlEGHv3qko4yTNHDjxfBppIEGY=",
               "transactionId":"17f1aa463c315f95f1febe6956aa180eb2cb643bca46e17..."
            }
         },
         "paymentMethod":{ 
            "displayName":"MasterCard 1488",
            "network":"MasterCard",
            "type":"credit"
         },
         "transactionIdentifier":"17F1AA463C315F95F1FEBE6956AA180EB2..."
      }
   }
}

 

Autorização com Captura Automática

{ 
   "wallet":"applePay",
   "referenceNumber":"TEST-APPLE-PAY-RF",
   "installments":4,
   "processorID":2,
   "chargeInterest":"Y",
   "walletDetail":{ 
      "merchantIdentifier":"merchant.maxipago.com",
      "transactionType":"sale",
      "applePayPayment":{ 
         "paymentData":{ 
            "version":"EC_v1",
            "data":"NdLVzUigHCHna6WaPP9J8Vk...",
            "signature":"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID...",
            "header":{ 
               "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEiQVImitonX2VcD8duPXsB8atbNo6O...",
               "publicKeyHash":"tjYuPcGjV8tsg33iOYlEGHv3qko4yTNHDjxfBppIEGY=",
               "transactionId":"17f1aa463c315f95f1febe6956aa180eb2cb643bca46e17..."
            }
         },
         "paymentMethod":{ 
            "displayName":"MasterCard 1488",
            "network":"MasterCard",
            "type":"credit"
         },
         "transactionIdentifier":"17F1AA463C315F95F1FEBE6956AA180EB2..."
      }
   }
}

 

Exemplo de Retorno da Transação

 

Response – Retorno da Adquirente (HTTP 200)

{
    "transaction-response": {
        "errorMessage": "",
        "authCode": 123456,
        "responseCode": 0,
        "creditCardLast4": 2409,
        "orderID": "0A0104A3:01621AACC4D6:3867:47710E49",
        "cvvResponseCode": "M",
        "creditCardScheme": "Mastercard",
        "processorReferenceNumber": 301519,
        "transactionID": 1791850,
        "processorMessage": "APPROVED",
        "avsResponseCode": "YYY",
        "referenceNum": "Sandbox_teste_1",
        "responseMessage": "AUTHORIZED",
        "creditCardBin": 551015,
        "creditCardCountry": "US",
        "processorCode": "A",
        "transactionTimestamp": 1520865952,
        "processorName": "SIMULATOR",
        "processorTransactionID": 237476
    }
}

 

Como realizar testes de transações Apple Pay?

 

Para utilizar o ambiente sandbox de Apple Pay, acesse o link: https://developer.apple.com/support/apple-pay-sandbox/

No ambiente maxiPago!, a transação deve ser em nosso ambiente sandbox como se fosse uma transação normal, de acordo com o manual a seguir https://www.maxipago.com/docs/manual_maxipago_api.pdf

IMPORTANTE: Este manual não contém as demais requisições necessárias para se transacionar com a maxiPago!. Caso seja necessário, consulte os manuais das referidas transações em http://maxipago.com/developers/