# WalletJS

Start accepting Apple Pay and/or Google Pay™ payments.

# Overview

# Google Pay™

Google Pay allows users to quickly and easily pay using credit cards stored on their Google account.

We've made it easy to get set up as quickly as possible. By adding our JavaScript file to your website, you can begin accepting Google Pay right away.

Before continuing, please be sure to review the following links:

All merchants must adhere to the Google Pay APIs Acceptable Use Policy (opens new window) and accept the terms defined in the Google Pay API Terms of Service (opens new window).

You can integrate Google Pay using their pay.js library directly and following the Web developer documentation link above, or you can use our SDK as shown below.

# Step 1 - Create a Google Merchant ID

Visit the Google Pay Business Console (opens new window) to create a merchant account with Google.

Follow the sign up process and once approved, you will receive your Google Pay merchant ID. This will be passed in as a parameter when creating the Google Pay button via our SDK.

# Step 2 - Add JavaScript file

<!doctype html>
<html>
<head>
    <!-- Add walletjs.js -->
    <script src="https://sandbox.basysiqpro.com/walletjs/walletjs.js"></script>

    <!-- Add script tag -->
    <script>
        // Create the settings.
        const settings = {
            container: '#container',
            merchantName: 'Example Merchant',
            merchantId: '12345678901234567890',
            gatewayMerchantId: '<PUBLIC_API_KEY>',
            allowedCardNetworks: ['VISA'],
            allowedCardAuthMethods: ['PAN_ONLY'],
            transactionInfo: {
                countryCode: 'US',
                currencyCode: 'USD',
                totalPrice: '1.23'
            },
            onGooglePaymentButtonClicked: paymentDataRequest => {
                paymentDataRequest
                    .then(paymentData => {
                        // Get the token.
                        const token = paymentData.paymentMethodData.tokenizationData.token

                        // Send the token to your backend server, which will
                        // then call our API to create a new transaction with
                        // the token set as the payment method.
                    }).catch(err => {
                        console.log(err)
                    })
            }
        }
        
        // Create a new Google Pay instance with your
        // given settings.
        let gp = new walletjs.GooglePay(settings)
    </script>
</head>

<body>
    <!-- The div where the button will go -->
    <div id="container"></div>
</body>
</html>

There's no need to add the Google pay.js script to your page, as our SDK automatically appends it.

If testing your integration, replace https://sandbox.basysiqpro.com with your sandbox/test environment URL. When you're ready to launch to production, replace this with your production environment URL.

# Settings

Below are the available settings you can choose from when creating a new Google Pay instance.

Please be sure to set the merchantId field to your Google Pay merchant ID created earlier, and the gatewayMerchantId field to your public API key. We will handle setting the gateway field required by Google's pay.js script for you behind the scenes.

Also, the customer's billing address is not required for our requests.

Name Type Definition
container string or HTMLDivElement An ID, class name, or HTMLDivElement referencing the container you want the Google Pay button to be placed in
merchantName string The name of your merchant account, will appear in payment sheet
merchantId string Your Google Pay merchant ID
gatewayMerchantId string Your public API key associated with our gateway
allowedCardNetworks array of strings Card networks you want to allow, must be one or more of the following:
AMEX, DISCOVER, INTERAC, JCB, MASTERCARD, VISA
allowedCardAuthMethods array of strings Card authentication methods you want to allow, must be one or more of the following:
PAN_ONLY, CRYPTOGRAM_3DS
transactionInfo object See table below for property descriptions
onGooglePaymentButtonClicked function Function to handle response from a successful or unsuccessful payment

transactionInfo

Name Type Definition
countryCode string ISO Alpha-2 country code
currencyCode string ISO Alpha-3 country code
totalPrice string Float amount in string format, i.e. '1.23'

# Step 3 - Process with token

Once you have received the token from the submission callback, you can use the token to replace a payment object in any of our direct API calls. You will usually want to send this token to your own backend server, and then call our API from that server.

See Transaction Processing for more details. Please note that while you can pass in a billing address, it is not required to process a transaction.

See below for an example:

# Process a sale with token as the raw string

We suggest that you take the raw token string as returned from Google and pass it in to the google_pay_token property of your transaction request, as shown below:

curl -v -X POST \
  -H "Authorization: <your API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sale",
    "amount": 123,
    "payment_method": {
        "google_pay_token": "{\"signature\":\"MEUCI...\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwE...\",\\\"keyExpiration\\\":\\\"1628153265706\\\"}\",\"signatures\":[\"MEUCI...\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"Al1A3...\",\\\"ephemeralPublicKey\\\":\\\"BHtVx...\",\"tag\\\":\\\"mBOa4...\\\"}\"}"
    },
    "billing_address": {
        "address_line_1": "123 Example St",
        "city": "Chicago"
        "state": "IL",
        "postal_code": "60601"
    }
}'   \
"<API URL goes here>/transaction"  

# Process a sale with token as an object

curl -v -X POST \
  -H "Authorization: <your API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sale",
    "amount": 123,
    "payment_method": {
        "google_pay_token": {
            "signature": "MEUCI...",
            "intermediateSigningKey": {
                "signedKey": "{\"keyValue\":\"MFkwE...",\"keyExpiration\":\"1628153265706\"}",
                "signatures": ["MEUCI..."]
            },
            "protocolVersion": "ECv2",
            "signedMessage": "{\"encryptedMessage\":\"Al1A3...",\"ephemeralPublicKey\":\"BHtVx...","tag\":\"mBOa4...\"}"
        }
    },
    "billing_address": {
        "address_line_1": "123 Example St",
        "city": "Chicago"
        "state": "IL",
        "postal_code": "60601"
    }
}'   \
"<API URL goes here>/transaction"  

# Apple Pay™

Apple Pay allows users to quickly and easily pay using credit cards stored on their Apple account.

We've made it easy to get set up as quickly as possible. By adding our JavaScript file to your website, you can begin accepting Apple Pay right away.

Before continuing, please be sure to review the following links:

# Step 1 - Add JavaScript file

<!doctype html>
<html>
<head>
    <!-- Add walletjs.js -->
    <script src="https://sandbox.basysiqpro.com/walletjs/walletjs.js"></script>

    <!-- Add script tag -->
    <script>
        const ap = new walletjs.ApplePay({
        key: "myKey0123456789",
        domain: "", //should be replaced with the environment you are looking to process in sandbox.<domain> or app.<domain>

        payment: {
            merchantCapabilities: ["supports3DS", "supportsCredit", "supportsDebit"],
            supportedNetworks: ["visa", "masterCard", "discover"],
            countryCode: "US",
            version: 3,
            merchantIdentifier: "my.merchant.id.app"
        },

        details: {
            total: {
            label: "Total Amount",
            amount: { currency: "USD", value: "10.61" }
            }
        },

        options: {
            requestShipping: false
        }
        });
    
        function submitApplePay() {
            var resp = ap.submit();
            console.log(resp);
        }
    </script>
</head>

<body>
    <!-- button goes here -->
    <button type="button" onclick="submitApplePay()">Apple Pay Button</button>
</body>
</html>

# Settings

Below are the available settings you can choose from when creating a new Apple Pay instance. The key is obtained in the merchant control panel under Settings->Apple Pay. Once you fill out that form you will recieve a key that you can use to initialize the Apple Pay instance.

Name Type Definition
key string This is the id of your Apple Pay certificate loaded in the gateway. Settings->Apple Pay
merchantIdentifier string The ID of your merchant account
supportedNetworks array of strings Card networks you want to allow, must be one or more of the following:
amex, discover, masterCard, visa
merchantCapabilities array of strings Card authentication methods you want to allow, must be one or more of the following:
supports3DS, supportsCredit, supportsDebit

# Step 2 - Process with token

Once you have received the token from the submission callback, you can use the token to replace a payment object in any of our direct API calls. You will usually want to send this token to your own backend server, and then call our API from that server.

See Transaction Processing for more details.

See below for an example:

# Process a sale with token

curl -v -X POST \
  -H "Authorization: <your API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sale",
    "amount": 123,
    "payment_method": {
        "apple_pay_token": {
            temporary_token: "<token goes here>"
        }
    }
}'   \
"<API URL goes here>/transaction"  

# Creating Certificates

In order to process payments through Apple Pay, you will need to create both a processing certificate and merchant certificate. Doing so involves creating a CSR (Certificate Signing Request) for both certificates, uploading them to Apple via your Apple Developer Portal, downloading the resultant certificates created by Apple, then finally converting them to .pem format and uploading them to us.

The processing certificate is used to decrypt payment information, while the merchant certificate is used to authenticate sessions with Apple Pay servers.

# Creating the Processing Certificate

There are two options for creating and converting the processing certificate.

# Option 1

  1. Create a new private key that will be used to create the CSR:

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

  1. Create a new CSR using the private key from the prior step:

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

  1. In your Apple Developer Portal, locate the 'Apple Pay Payment Processing Certificate' section and upload the request.csr file.

  2. Download the processing certificate from the Apple Developer portal, which should download a file named apple_pay.cer. This contains both the certificate and the private key.

  3. Convert apple_pay.cer to .pem format using this command:

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

  1. Convert the private key to .pem format using these commands:

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

  2. Login to your control panel and navigate to Settings -> Apple Pay -> Create Advanced.

  3. Copy the contents of ApplePay.crt.pem, starting at -----BEGIN CERTIFICATE----- and ending at -----END CERTIFICATE-----.

  4. Paste this in the ‘Processing Certificate’ textbox.

  5. Copy the contents of ApplePay.key.pem, starting at -----BEGIN PRIVATE KEY----- and ending at -----END PRIVATE KEY-----.

  6. Paste this in the ‘Processing Certificate Key’ textbox.

  7. Save.

# Option 2 (if using MacOS)

  1. Follow steps 1-4 shown above in option 1 to get the apple_pay.cer certificate.

  2. Double click the apple_pay.cer file to add it to Mac Keychain.

  3. Open up the Keychain app and locate the Apple Pay key that was just added.

  4. Export the certificate (make sure the type is certificate) in .p12 format.

  5. Run the following commands to convert both the certificate and private key to .pem format, replacing [filename].p12 with the filename of the exported .p12 file:

    a. openssl pkcs12 -in [filename].p12 -out ApplePay.crt.pem -nokeys
    b. openssl pkcs12 -in [filename].p12 -out ApplePay.key.pem -nocerts

  6. Login to your control panel and navigate to Settings -> Apple Pay -> Create Advanced.

  7. Copy the contents of ApplePay.crt.pem, starting at -----BEGIN CERTIFICATE----- and ending at -----END CERTIFICATE-----.

  8. Paste this in the ‘Processing Certificate’ textbox.

  9. Copy the contents of ApplePay.key.pem, starting at -----BEGIN PRIVATE KEY----- and ending at -----END PRIVATE KEY-----.

  10. Paste this in the ‘Processing Certificate Key’ textbox.

  11. Save.

# Creating the Merchant Certificate

  1. Create a new private key and CSR, making sure to replace 'Company Name' with your company name, and 'US' with your country:

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

This will output two files, applepay.key which is your private key, and applepay.csr which is your certificate signing request.

  1. In your Apple Developer Portal, locate the 'Apple Pay Merchant Identity Certificate' section and upload the applepay.csr file.

  2. Download the merchant certificate from the Apple Developer portal, which should download a file named merchant_id.cer.

  3. Convert merchant_id.cer to .pem format using this command:

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

  1. Login to your control panel and navigate to Settings -> Apple Pay -> Create Advanced.

  2. Copy the contents of merchant_id.pem, starting at -----BEGIN CERTIFICATE----- and ending at -----END CERTIFICATE-----.

  3. Paste this in the ‘Merchant Certificate’ textbox.

  4. Copy the contents of applepay.key, starting at -----BEGIN PRIVATE KEY----- and ending at -----END PRIVATE KEY-----.

  5. Paste this in the ‘Merchant Certificate Key’ textbox.

  6. Save.