WalletJS

Accept Apple Pay and Google Pay™ payments on your website with a simple JavaScript integration.

What Is WalletJS?

WalletJS is a JavaScript library that lets you add Apple Pay and Google Pay buttons to your checkout flow. Customers can pay with cards already stored in their digital wallets—no manual card entry required.

Why Use Digital Wallets?

Benefit	Description
Faster checkout	Customers pay with a single tap or click—no typing card numbers
Higher conversion	Reduced friction means fewer abandoned carts
Better security	Tokenized transactions protect card data
Mobile-friendly	Optimized for the devices your customers already use

Quick Comparison

Feature	Google Pay	Apple Pay
Supported devices	Android, Chrome on any device	Safari on Apple devices
Setup complexity	Moderate (Google merchant ID required)	More complex (certificates required)
Button provided	Yes, via SDK	No, you create your own
Test environment	Use test cards in Chrome	Requires Apple sandbox account

Google Pay™

Google Pay allows customers to pay using cards stored in their Google account.

Prerequisites

Before integrating, review Google's requirements:

All merchants must adhere to the Google Pay APIs Acceptable Use Policy and accept the Google Pay API Terms of Service.

Setup Steps

Step 1: Get Your Google Merchant ID

Visit the Google Pay Business Console
Create a merchant account and complete the sign-up process
Once approved, you'll receive your Google Pay merchant ID

Step 2: Add the Script

html

<head>
  <script src="https://sandbox.gosparrowone.com/walletjs/walletjs.js"></script>
</head>
<body>
  <div id="google-pay-button"></div>
</body>

TIP

No need to add Google's pay.js script—WalletJS includes it automatically.

Step 3: Initialize Google Pay

javascript

const googlePay = new walletjs.GooglePay({
  // Where to place the button
  container: '#google-pay-button',
  
  // Your merchant info
  merchantName: 'Your Store Name',
  merchantId: 'your-google-merchant-id',        // From Google Pay Business Console
  gatewayMerchantId: 'pub_XXXXXXXXXXXXXX',      // Your public API key
  
  // Payment options
  allowedCardNetworks: ['VISA', 'MASTERCARD', 'AMEX', 'DISCOVER'],
  allowedCardAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
  
  // Transaction details
  transactionInfo: {
    countryCode: 'US',
    currencyCode: 'USD',
    totalPrice: '25.00'
  },
  
  // Handle the response
  onGooglePaymentButtonClicked: (paymentDataRequest) => {
    paymentDataRequest
      .then((paymentData) => {
        // Get the token from Google's response
        const token = paymentData.paymentMethodData.tokenizationData.token
        
        // Send token to your server to process the payment
        sendToServer(token)
      })
      .catch((err) => {
        console.error('Google Pay error:', err)
      })
  }
})

Step 4: Process the Token (Server-Side)

Send the token to your backend, then call the API with the token as the payment method:

bash

curl -X POST "https://sandbox.gosparrowone.com/api/transaction" \
  -H "Authorization: <your-secret-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sale",
    "amount": 2500,
    "payment_method": {
      "google_pay_token": "<token-from-google-pay>"
    }
  }'

Token Format

You can pass the token as either a raw JSON string or a parsed object—both formats are accepted.

Google Pay Settings Reference

Setting	Type	Description
`container`	`string` or `HTMLDivElement`	CSS selector or element where the button will render
`merchantName`	`string`	Your business name (shown in payment sheet)
`merchantId`	`string`	Your Google Pay merchant ID
`gatewayMerchantId`	`string`	Your public API key
`allowedCardNetworks`	`string[]`	Accepted networks: `VISA`, `MASTERCARD`, `AMEX`, `DISCOVER`, `INTERAC`, `JCB`
`allowedCardAuthMethods`	`string[]`	Auth methods: `PAN_ONLY`, `CRYPTOGRAM_3DS`
`transactionInfo`	`object`	Transaction details (see below)
`onGooglePaymentButtonClicked`	`function`	Callback to handle the payment response

transactionInfo Object:

Property	Type	Description
`countryCode`	`string`	ISO Alpha-2 country code (e.g., `US`)
`currencyCode`	`string`	ISO Alpha-3 currency code (e.g., `USD`)
`totalPrice`	`string`	Amount as a string (e.g., `'25.00'`)

Apple Pay™

Apple Pay allows customers to pay using cards stored in their Apple Wallet.

Prerequisites

Apple Pay requires more setup than Google Pay:

Apple Developer Account — You need an active Apple Developer membership
Processing Certificate — Used to decrypt payment data
Merchant Certificate — Used to authenticate with Apple Pay servers
Verified Domain — Apple must verify your domain

Setup Steps

Step 1: Create and Upload Certificates

See Creating Certificates below for detailed instructions.

Step 2: Get Your Key from the Control Panel

After uploading your certificates:

Navigate to Settings → Apple Pay in your control panel
Copy the key value provided—you'll use this to initialize Apple Pay

Step 3: Add the Script and Button

html

<head>
  <script src="https://sandbox.gosparrowone.com/walletjs/walletjs.js"></script>
</head>
<body>
  <!-- You must provide your own Apple Pay button -->
  <button type="button" onclick="submitApplePay()">
    Pay with Apple Pay
  </button>
</body>

Apple Pay Button Guidelines

Apple has strict Human Interface Guidelines for Apple Pay buttons. Use their official button styles.

Step 4: Initialize Apple Pay

javascript

const applePay = new walletjs.ApplePay({
  // Your key from the control panel
  key: 'your-apple-pay-key',
  
  // Your gateway domain (sandbox or production)
  domain: 'sandbox.yourgateway.com',  // or 'app.yourgateway.com' for production
  
  // Payment configuration
  payment: {
    merchantIdentifier: 'merchant.com.yourcompany.app',
    merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
    supportedNetworks: ['visa', 'masterCard', 'amex', 'discover'],
    countryCode: 'US',
    version: 3
  },
  
  // Transaction details
  details: {
    total: {
      label: 'Your Store Name',
      amount: { currency: 'USD', value: '25.00' }
    }
  },
  
  // Options
  options: {
    requestShipping: false
  }
})

// Call this when your button is clicked
function submitApplePay() {
  applePay.submit()
    .then((token) => {
      // Send token to your server
      sendToServer(token)
    })
    .catch((err) => {
      console.error('Apple Pay error:', err)
    })
}

Step 5: Process the Token (Server-Side)

bash

curl -X POST "https://sandbox.gosparrowone.com/api/transaction" \
  -H "Authorization: <your-secret-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sale",
    "amount": 2500,
    "payment_method": {
      "apple_pay_token": {
        "temporary_token": "<token-from-apple-pay>"
      }
    }
  }'

Apple Pay Settings Reference

Setting	Type	Description
`key`	`string`	Your Apple Pay key from the control panel
`domain`	`string`	Gateway domain (`sandbox.` or `app.`)
`payment.merchantIdentifier`	`string`	Your Apple merchant identifier
`payment.merchantCapabilities`	`string[]`	Capabilities: `supports3DS`, `supportsCredit`, `supportsDebit`
`payment.supportedNetworks`	`string[]`	Networks: `visa`, `masterCard`, `amex`, `discover`
`payment.countryCode`	`string`	ISO Alpha-2 country code
`payment.version`	`number`	Apple Pay version (use `3`)
`payment.requiredBillingContactFields`	`string[]`	Optional: `email`, `name`, `phone`, `postalAddress`
`details.total.label`	`string`	Label shown in payment sheet
`details.total.amount`	`object`	`{ currency: 'USD', value: '25.00' }`
`options.requestShipping`	`boolean`	Request shipping address

Creating Certificates (Apple Pay)

Apple Pay requires two certificates:

Certificate	Purpose
Processing Certificate	Decrypts payment data from Apple
Merchant Certificate	Authenticates sessions with Apple Pay servers

Processing Certificate

1. Generate a private key:

bash

openssl ecparam -out private.key -name prime256v1 -genkey

2. Create a Certificate Signing Request (CSR):

bash

openssl req -new -sha256 -key private.key -nodes -out request.csr

3. Upload to Apple:

Go to your Apple Developer Portal
Find Apple Pay Payment Processing Certificate
Upload request.csr
Download the resulting apple_pay.cer

4. Convert the certificate to PEM:

bash

openssl x509 -inform DER -outform PEM -in apple_pay.cer -out ApplePay.crt.pem

5. Convert the private key to PEM:

bash

openssl x509 -inform DER -outform PEM -in apple_pay.cer -out temp.pem
openssl pkcs12 -export -out key.p12 -inkey private.key -in temp.pem
openssl pkcs12 -in key.p12 -out ApplePay.key.pem -nocerts -nodes

6. Upload to Control Panel:

Navigate to Settings → Apple Pay → Create Advanced
Paste contents of ApplePay.crt.pem into Processing Certificate
Paste contents of ApplePay.key.pem into Processing Certificate Key
Save

Merchant Certificate

1. Generate private key and CSR:

bash

openssl req -new -newkey rsa:2048 -nodes \
  -keyout applepay.key \
  -out applepay.csr \
  -subj '/O=Your Company Name/C=US'

2. Upload to Apple:

Go to your Apple Developer Portal
Find Apple Pay Merchant Identity Certificate
Upload applepay.csr
Download the resulting merchant_id.cer

3. Convert to PEM:

bash

openssl x509 -inform der -in merchant_id.cer -out merchant_id.pem

4. Upload to Control Panel:

Navigate to Settings → Apple Pay → Create Advanced
Paste contents of merchant_id.pem into Merchant Certificate
Paste contents of applepay.key into Merchant Certificate Key
Save

Saving Cards to Vault

Both Google Pay and Apple Pay tokens can be saved to the customer vault for future use:

bash

curl -X POST "https://sandbox.gosparrowone.com/api/transaction" \
  -H "Authorization: <your-secret-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "verification",
    "amount": 0,
    "create_vault_record": true,
    "payment_method": {
      "google_pay_token": "<token>"
    }
  }'

This performs a zero-dollar verification and stores the card for future transactions.

Testing

Google Pay

Use Chrome browser
Add a test card to your Google account
Set your environment URL to sandbox
Test the full flow

Apple Pay

Use Safari on an Apple device
Set up an Apple Sandbox account
Add test cards to your sandbox Wallet
Set the domain to your sandbox environment

Troubleshooting

Issue	Solution
Google Pay button not appearing	Verify `container` selector matches your DOM element
"Merchant not authorized"	Check that your Google merchant ID is approved and correct
Apple Pay not available	Ensure you're testing on Safari with a compatible Apple device
Certificate errors	Verify PEM files include `-----BEGIN` and `-----END` markers
Token processing fails	Confirm you're using the correct token format for each wallet type
Domain verification failed	Ensure your domain is registered in Apple Developer Portal

WalletJS ​

What Is WalletJS? ​

Why Use Digital Wallets? ​

Quick Comparison ​

Google Pay™ ​

Prerequisites ​

Setup Steps ​

Step 1: Get Your Google Merchant ID ​

Step 2: Add the Script ​

Step 3: Initialize Google Pay ​

Step 4: Process the Token (Server-Side) ​

Google Pay Settings Reference ​

Apple Pay™ ​

Prerequisites ​

Setup Steps ​

Step 1: Create and Upload Certificates ​

Step 2: Get Your Key from the Control Panel ​

Step 3: Add the Script and Button ​

Step 4: Initialize Apple Pay ​

Step 5: Process the Token (Server-Side) ​

Apple Pay Settings Reference ​

Creating Certificates (Apple Pay) ​

Processing Certificate ​

Merchant Certificate ​

Saving Cards to Vault ​

Testing ​

Google Pay ​

Apple Pay ​

Troubleshooting ​

WalletJS

What Is WalletJS?

Why Use Digital Wallets?

Quick Comparison

Google Pay™

Prerequisites

Setup Steps

Step 1: Get Your Google Merchant ID

Step 2: Add the Script

Step 3: Initialize Google Pay

Step 4: Process the Token (Server-Side)

Google Pay Settings Reference

Apple Pay™

Prerequisites

Setup Steps

Step 1: Create and Upload Certificates

Step 2: Get Your Key from the Control Panel

Step 3: Add the Script and Button

Step 4: Initialize Apple Pay

Step 5: Process the Token (Server-Side)

Apple Pay Settings Reference

Creating Certificates (Apple Pay)

Processing Certificate

Merchant Certificate

Saving Cards to Vault

Testing

Google Pay

Apple Pay

Troubleshooting