Getting Started with DotDashPay

Step 1: Installation

Assuming you have node version 4.0 or greater installed, simply run:

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 2: Perform a Mobile Loyalty Transaction

Enrolling a customer into a native mobile loyalty program or identifying a customer that is already a part of the loyalty program can be accomplished via a simple pair of SDK calls:

var util = require("util") var ddp = require("dotdashpay") ddp.platform.initialize({ environment: "MIDDLEWARE_SIMULATOR" }) .onInitialized(performLoyaltyTransaction) .onInitializeError(printResult("onInitializeError")) function performLoyaltyTransaction() { console.log("performing loyalty transaction") ddp.platform.listenForInteraction({ // transactionMode: "IDENTIFY" is telling DDP to get customer information from // transactions originating from a mobile wallet. If no loyalty pass is // found, a push notification will be sent to the mobile device that will // trigger the loyalty enrollment flow. transactionMode: "IDENTIFY" }) .onStartedListeningForInteraction(printResult("onStartedListeningForInteraction")) .onStartedInteraction(printResult("onStartedInteraction")) .onGotInteraction(res => { // at this point, if a customer does not have a mobile loyalty pass // then they will receive a push notification prompting them to // natively enroll in the loyalty program // If they do have a loyalty pass, res.customerProfile will be populated // with their loyalty information printResult("onGotInteraction")(res) ddp.close() }) .onListenForInteractionError(printResult("onListenForInteractionError")) } function printResult(step) { return result => { console.log(step, "result: ", util.inspect(result, { depth: 8 }, 4)) } }
copy

The ListenForInteraction SDK call asks the DotDashPay Platform to listen for any type of loyalty (or "IDENTIFY"-ing) data coming from the attached payment hardware (e.g. the NFC modules, etc). In a non-simulated environment, if a customer does not have a mobile loyalty pass then they will receive a push notification prompting them to natively enroll in the loyalty program.

Step 3: Understanding the DotDashPay SDK

Now that you've successfully used the DotDashPay SDK, let's discuss how the SDK works in more detail so that you can use it to craft the perfect experience.

The DotDashPay SDK is a simple set of requests to the DotDashPay Platform that you can use to create and manage loyalty accounts as well as settle, refund, void, and tokenize payments. Every request has an associated set of responses from the DotDashPay Platform that you handle by specifying function callbacks when you make the request.

There are two fundamental types of responses that are returned when a request is sent: update responses and completion responses. The only difference between these two is that once a completion response is received, there will be no more responses of any kind; they complete the request. In addition, at any point an error response may be returned. A error response is always a completion response and will contain data fields indicating what happened.

The SDK documentation lists the requests and responses in detail. To get a feel for how this works, let's create a simple loyalty experience using various SDK requests and callbacks. First, we add all of the response handlers to the ListenForInteraction request that we used in the above example:

In the GotInteraction response, we check for the existence of a customer profile and then greet the customer by name. In a non-simulated environment, if we do not have a customer profile for this customer, then a customer loyalty enrollment request will be sent to the customer's phone via the native Apple or Android loyalty enrollment functionality.

Once the transaction is complete, i.e. in the GotInteraction callback, we fetch the full transaction chain from DotDashPay using GetTransaction. This transaction chain contains all information about the complete transaction.

var util = require("util") var ddp = require("dotdashpay") ddp.platform.initialize({ environment: "MIDDLEWARE_SIMULATOR" }) .onInitialized(performLoyaltyTransaction) .onInitializeError(printResult("onInitializeError")) function performLoyaltyTransaction() { ddp.platform.listenForInteraction({ // transactionMode: "IDENTIFY" is telling DDP to get customer information from // transactions originating from a mobile wallet. If no loyalty pass is // found, a push notification will be sent to the mobile device // that will then trigger the loyalty enrollment flow. transactionMode: "IDENTIFY" }) .onStartedListeningForInteraction(printResult("onStartedListeningForInteraction")) .onStartedInteraction(printResult("onStartedInteraction")) .onGotInteraction(res => { printResult("onGotInteraction")(res) // Greet customers with a loyalty pass if (res.customerProfile && res.customerProfile.id) { console.log(`Hello, ${res.customerProfile.fullName}`) } // Here we fetch the full transaction chain, which will include details of // every step of the transaction. ddp.payment.getTransaction({ transactionChainId: res.transactionChainId }) .onGotTransaction(res => { printResult("onGetTransaction")(res) if (res.interaction.response.customerProfile && res.interaction.response.customerProfile.id) { console.log(`Thanks for shopping with us ${res.interaction.response.customerProfile.fullName}!`) } ddp.close() }).onGetTransactionError(err => { printResult("onGetTransactionError")(err) ddp.close() }) }) .onListenForInteractionError(printResult("onListenForInteractionError")) } function printResult(step) { return result => { console.log(step, "result: ", util.inspect(result, { depth: 8 }, 4)) } }
copy

These simple examples have shown you the basics of using the DotDashPay SDK. The next step is to install the DotDashPay middleware and build a demo using real payments hardware: