Basis Theory Apple Pay JS

!Version !GitHub Workflow Status (with event) !License

Utility library for decrypting Apple Payment Tokens in Node.js environments.

Features

- Apple Pay PKPaymentToken Decryption: Securely decrypt user-authorized Apple Pay transaction tokens using easy-to-interact interfaces.

| Encryption | Region | Support |
| ---------- | ---------- | ------- |
| RSA_v1 | China | ✅ |
| EC_v1 | All Others | ✅ |

- Payment Processing Certificate Rotation: Never worry about missing payments because of certificate rotation unpredictable behavior. Just add both certificates to the decryption context and rest assured that both new and old tokens will be decrypted during rotation window.
- Automatic Decryption Strategy Detection: Transparent integration for decrypting Apple's Payment Token regardless of the employed encryption standard.

Apple Pay Setup

A pre-requisite to use this package is that you must have completed your Merchant Apple Pay Setup. This can be a time-consuming process, so the guides below will help you with step-by-step instructions to obtain the necessary files to issue and decrypt Apple Pay Tokens:

1. Apple Developer Program Enrollment
2. Create a Merchant ID
3. Create a Payment Processing Certificate
4. Create a Merchant Identity Certificate

To collect payments with Apple Pay in your frontend, Apple has specific guides for:

- Web
- iOS

Installation

Install the package using NPM:

``shell
npm install @basis-theory/apple-pay-js --save
`

Or Yarn:

`shell
yarn add @basis-theory/apple-pay-js
`

Node.js

The examples below show how to load certificates from the File System into Buffers, using samples from this repository. But you can load them from your KMS, secret manager, configuration, etc.

If you need help understanding the risks associated with decrypting and manipulating the various forms of cardholder data in your own systems, reach out to us.

`javascript
import { ApplePaymentTokenContext } from '@basis-theory/apple-pay-js';
import fs from 'fs';
import token from './test/fixtures/ec/token.new.json';

// create the decryption context
const context = new ApplePaymentTokenContext({
// add as many merchant certificates you need
merchants: [
{
// optional certificate identifier
identifier: 'merchant.basistheory.com-old',
// the certificate and the private key are Buffers in PEM format
certificatePem: fs.readFileSync(
'./test/fixtures/ec/apple/apple_pay.new.pem'
),
privateKeyPem: fs.readFileSync(
'./test/fixtures/ec/apple/private.new.key'
),
},
{
identifier: 'merchant.basistheory.com-new',
certificatePem: fs.readFileSync(
'./test/fixtures/ec/apple/apple_pay.new.pem'
),
privateKeyPem: fs.readFileSync(
'./test/fixtures/ec/apple/private.new.key'
),
},
{
identifier: 'merchant.basistheory.china',
certificatePem: fs.readFileSync(
'./test/fixtures/rsa/apple/apple_pay.pem'
),
privateKeyPem: fs.readFileSync('./test/fixtures/rsa/apple/private.key'),
},
],
});

try {
// decrypts Apple's PKPaymentToken paymentData
console.log(context.decrypt(token.paymentData));
} catch (error) {
// couldn't decrypt the token with given merchant certificates
}
`

Reactors

This package is available to use in Reactors context. The example below shows how to decrypt Apple Pay tokens and vault the DPAN compliantly.

`javascript
const { Buffer } = require('buffer');
const { ApplePaymentTokenContext } = require('@basis-theory/apple-pay-js');
const {
CustomHttpResponseError,
} = require('@basis-theory/basis-theory-reactor-formulas-sdk-js');

module.exports = async function (req) {
const {
bt,
args: {
applePayToken: { paymentData, ...applePayToken },
},
configuration: {
PRIMARY_CERTIFICATE_PEM,
PRIMARY_PRIVATE_KEY_PEM,
SECONDARY_CERTIFICATE_PEM,
SECONDARY_PRIVATE_KEY_PEM,
},
} = req;

// creates token context from certificates / keys configured in Reactor
const context = new ApplePaymentTokenContext({
merchants: [
{
certificatePem: Buffer.from(PRIMARY_CERTIFICATE_PEM),
privateKeyPem: Buffer.from(PRIMARY_PRIVATE_KEY_PEM),
},
{
certificatePem: Buffer.from(SECONDARY_CERTIFICATE_PEM),
privateKeyPem: Buffer.from(SECONDARY_PRIVATE_KEY_PEM),
},
],
});

try {
// decrypts Apple's PKPaymentToken paymentData
const {
applicationPrimaryAccountNumber,
applicationExpirationDate,
...restPaymentData
} = context.decrypt(paymentData);

// vaults Apple Device PAN (DPAN)
const btToken = await bt.tokens.create({
type: 'card',
data: {
number: applicationPrimaryAccountNumber,
expiration_month: applicationExpirationDate.slice(2, 4),
expiration_year: 20${applicationExpirationDate.slice(-2)},
},
});

// returns transaction details and vaulted token without sensitive DPAN
return {
raw: {
btToken,
applePayToken: {
paymentData: restPaymentData,
...applePayToken,
},
},
};
} catch (error) {
throw new CustomHttpResponseError({
status: 500,
body: {
message: error.message,
},
});
}
};
``

💡 Inspiration

This package was inspired by Spreedly Gala, particularly this fork.