Getting Started with the DotDashPay Middleware

Step 0: SDK Installation

Similar to the SDK tutorial, first install the DotDashPay SDK (note: it is a good idea to first complete the Try the DotDashPay SDK tutorial.)

npm install --save dotdashpaycopy

In case you want a block of code to copy and paste to setup a new testing project:

mkdir -p ~/Development/DotDashPayExperiments
cd ~/Development/DotDashPayExperiments
npm init -y
npm install --save dotdashpaycopy

Step 1: Middleware Installation

The current DotDashPay middleware is in a private beta release. In order to use the DotDashPay middleware, you must first contact your DotDashPay technical contact and request a credentials.json file, which will allow your middleware instance to authenticate with our cloud infrastructure. Once you obtain the credentials.json file, place this file into /etc/dotdashpay/credentials.json:

mkdir -p /etc/dotdashpay
cp credentials.json /etc/dotdashpay/credentials.jsoncopy

At the moment, only Debian-like versions of Linux (i.e. those with aptitude) can install our middleware. In order to do this, you need to add in the DotDashPay GPG public key so you can verify packages are coming from DotDashPay, add the DotDashPay packages server to your sources.list, and then install the DotDashPay middleware using aptitude:

apt-key adv --keyserver --recv-keys 6DE41B66
echo "deb trusty main" >> /etc/apt/sources.list
apt-get update
apt-get install dotdashpaycopy

Note: if you get an error such as ddp: ERROR (no such group) during installation, run supervisorctl reload followed by apt-get install dotdashpay

Step 2: Verify the DotDashPay Middleware is running

Run the following command to verify that the dotdashpay binary started up correctly:

dotdashpay statuscopy

If the status output says something is wrong, verify that /etc/dotdashpay/credentials.json is not malformed and run

dotdashpay restartcopy

Step 3: Connect the Hardware Peripherals

Plug in your USB hardware peripheral, e.g. the IdTech 4880. The DotDashPay SDK will automatically detect and manage new hardware peripherals. However, if you are running the middleware in a docker container, you must restart the middleware after connecting a new hardware peripheral. This can be accomplished with dotdashpay restart.

Step 4: Create a Simple Loyalty Experience

The following code example shows how to access a customer loyalty profile when the customer has a loyalty pass in their mobile wallet. If the customer does not have a loyalty profile, then a loyalty enrollment request will be sent to the customer's phone via the native Apple or Android loyalty enrollment functionality. In other words, while building/testing your loyalty experience, you should first expect to see a push notification on your mobile device prompting you to enroll in the loyalty program, and for subsequent loyalty transactions, you should expect the loyalty pass to be accessible during the loyalty transaction.

NOTE: Setting up mobile loyalty passes so that customers receive native enrollment prompts involves some manual setup and configuration, e.g. creating the mobile loyalty pass styles and associating them with your account. As a beta customer, we (the DotDashPay engineering team) have already done this setup for you, so you should be able to be up and running right away. When the need arises for changes to the loyalty experience you're creating, moving things into production, etc, send us a message and we can work together to get everything setup just right. For instance, you’ll need to register a "pass id" with Apple, who will issue certain certificates that are required to send push notifications so customers can enroll and personalize their loyalty passes.

var util = require("util") var ddp = require("dotdashpay") console.log("Initializing DotDashPay platform...") ddp.platform.initialize({ // `environment` allows you to specify aspects of the payment pipeline you // may want to mock out. "PROCESSOR_SIMULATOR" implies that calls to the // payment processor will be mocked, but the rest of the interactions with // the DotDashPay platform on your system work as they normally would. To // mock out payment peripherals (eg. to simulate a card swipe) you can use // the "PERIPHERAL_SIMULATOR" environment. If you want to mock out the // DotDashPay platform completely, you can use the "MIDDLEWARE_SIMULATOR" // environment environment: "PROCESSOR_SIMULATOR", }).onInitialized(data => { console.log("initialized") performLoyaltyTransaction() }).onInitializeError(printError("Initialization error")) function performLoyaltyTransaction() { ddp.platform.listenForInteraction({ // The argument choice here is subtle yet intentional. We're using // IDENTIFY_AND_PAYMENT rather than just IDENTIFY because a mobile wallet is // technically unable to transmit the right kind of data for an IDENTIFY // interaction until it has already enrolled with a loyalty pass i.e. // because it does not have a loyalty pass on the phone that it can transmit // to us. In IDENTIFY_AND_PAYMENT mode, the customer's already existing // mobile wallet credit card will trigger the success callbacks of the // system (e.g. onGotInteraction), and since we have `amount` set to 0, the // customer will not be charged anything. When a customer already has a // loyalty card, opt to use just IDENTIY mode and your loyalty pass should // be automatically selected. transactionMode: "IDENTIFY_AND_PAYMENT", amount: 0 }) .onStartedListeningForInteraction(res => { console.log("Tap your phone to the payment hardware") }) .onStartedInteraction(printResult("onStartedInteraction")) .onGotInteraction(res => { // Print a customer greeting if the customer has a loyalty profile // If the customer does not have a loyalty profile, then a loyalty // enrollment request will be sent to the customer's phone via the // native Apple or Android loyalty enrollment functionality. if (res.customerProfile && res.customerProfile.fullName) { console.log(`Hello, ${res.customerProfile.fullName}`) } else { console.log("Customer does not have a loyalty profile -- a loyalty enrollment request will be sent to their phone") // Using waitForCustomerEnrollment, you can listen for a loyalty pass enrollment and trigger // callbacks on success, error, and timeout ddp.platform.waitForCustomerEnrollment({ transactionChainId: res.transactionChainId, timeoutSeconds: 300 }).onCustomerEnrolled(res => { printResult("onCustomerEnrolled")(res) ddp.close() }).onWaitForCustomerEnrollmentError(printResult("onWaitForCustomerEnrollmentError")) } // If you want to view the full details of your loyalty transaction, you // can fetch the entire transaction with `ddp.payment.getTransaction()`. }) .onListenForInteractionError(printError("onListenForInteractionError")) } function printResult(step) { return result => { console.log(step, "result: ", util.inspect(result, {depth: 8}, 4)) } } function printError(step) { return error => { console.error(step, "error: ", util.inspect(error, {depth: 8}, 4)) process.exit(1) } }

Step 5: Send a Loyalty Push Notification

The DotDashPay platform makes it easy to send push notifications to customers enrolled in your mobile loyalty program. In order to send a push notification to a customer with e.g. customer id DEMO-CUSTOMER-ID, simply send an HTTP POST request to as follows:

curl -XPOST -H "Content-Type: application/json" -d '{"api_token": "your-api-token", "message": "This is a push notification message!", "customer_ids": ["DEMO-CUSTOMER-ID"]}'

In the above curl request, you should customize the api_token, message, and customer_ids fields. You can obtain your api_token in your account settings.

You can obtain a customer id in a few ways: first the onInteraction callback for a ListenForInteraction request contains the customer profile, which contains a customer id (as illustrated in the above example); second, the GetTransaction request returns the customer profile (as illustrated in the above example); and finally, you can obtain a list of all customer ids via the API endpoint (note that this API endpoint is currently only meant to be used in development).

curl -XPOST -H "Content-Type: application/json" -d '{"api_token": "your-api-token"}'