DotDashPay API Node.js Library

The DotDashPay API Node.js library defines and implements a set of functions that can be used to interact with the Dot Mini IoT Payments Platform. The Dot Mini connects your machine to payments.

The goal of DotDashPay is to abstract away all of the low-level protocols and connectivity aspects of interacting with payment-related hardware and payment processors. You simply write a few API calls, connect your machine to the DotDashPay chip, and you're finished! Oh, and don't worry about payments-related compliance and regulations for your hardware and software. We take care of that too! Here is a visual overview of the scope of the API library:

Installation

npm install ddpay

Guide

• Quick Start
• API
  • Overview
  • Hardware
    • #listenForPaymentData
  • Payment
    • #settlePayment
  • Network

Quick Start

After installing the DotDashPay API, we recommend running the simple usage example below, which you can find in the examples directory. This API includes a simulator for the Dot chip, so you don't need any hardware to dive in and get started!

Example: Performing a Transaction

var ddpay = require("ddpay");
var CONFIG = require("./configuration_example.json");


ddpay.init(CONFIG);

// wait for the payment data from the DDPay peripherals
ddpay.hardware.listenForPaymentData()
    .onUpdate(function () { console.log("waitForPaymentData onUpdate"); })
    .onCompletion(function (err, hwData) {
        if (err) {
            return console.log("Error getting payment data", err);
        }

        // specify the amount to charge
        var payData = {
            payid: hwData.payid,
            dollars: 1,
            cents: 28
        };

        console.log("settling payment", payData);

        // settle the payment
        ddpay.payment.settlePayment(payData)
            .onUpdate(function (err, data) { console.log("settlePayment onUpdate"); })
            .onCompletion(function (err, data) { console.log("settlePayment onCompletion"); });
    });

You can find this example in the examples directory.

API

Overview

The DotDashPay API has three namespaces:

• ddpay.payment: all payment-processing related functions, e.g. processing, voiding, authorizing, refunding, etc transactions
• ddpay.hardware: all payment-hardware related functions, e.g. reading card data, testing NFC connectivity, etc
• ddpay.network: all network related functions, e.g. sending data chunks, checking network connectivity, etc

All API functions in each namespace send a request to The DotDashPay chip and return a Request object. The Request object has two functions for setting callbacks:

• onUpdate
• onCompletion

where the callback function passed into onUpdate is called for non-terminating update events from The Dot and the function passed into onCompletion is called when the request is finished, i.e. there will be no more onUpdate callbacks. From the simple example above:

var ddpay = require("ddapy")
ddpay.init();
ddpay.hardware.listenForPaymentData()
    .onUpdate(function (err, data) { console.log("listenForPaymentData Updated") });
    .onCompletion(function (err, data) { console.log("listenForPaymentData Complete") });)

Notice that the callback functions accepts two arguments:

• err: Will be null if there was not an error. In the event of an error,err will be an object with the format

{
    "description": "a string description of the error",
    "code": 1  // an integer code for the particular error
}

• data: A request-related data object with a format dependent on the exact response: check the relevant API function documentation for the expected format. All data objects have at least the following two fileds:

{
    "name": "name-of-the-response",
    "id": "id-of-the-corresponding-request"
    // response-specific data fields
    // ...
}

hardware API

#listenForPaymentData(onlyNewData)

Listen for payment data from the payments-related peripheral hardware

Arguments

• onlyNewData {Boolean}: specify whether we should only listen for new payments data from the payments hardware, e.g. ignore card swipes that occured before this method was called

Update Responses MSRStartRead: response when the magnetic-stripe reader starts reading data from a magnetic stripe card

// Callback data
{
    "name": "MSRStartRead",
    "id": "id-of-the-corresponding-request"
}

Completion Responses MSREndRead : response when the magnetic-stripe reader finishes reading data from a magnetic stripe card.

// Callback data
{
    "name": "MSREndRead",
    "id": "id-of-the-corresponding-request",
    // e.g. pass `payid` into the object argument of `ddpay.payment.settlePayment`
    "payid": "id-for-referencing-the-given-magstripe-card" 
}

payment API

#settlePayment(paymentData)

Settles a payment: you may call this function either after receiving data from hardware.listenForPaymentData or after receiving data from payment.authorizePayment If called directly after receiving payment data from the hardware, then this immediently charges the payer. If called after authorizing the payment, then this request will finalize the transaction and the transaction cannot be voided later on.

Arguments

• paymentData {Object}: an object that specifies the parameter of the payment and has the following format:

// `paymentData` format
{
    // e.g. this should come from `ddpay.hardware.listenForPaymentData`
    "payid": "id-for-referencing-the-given-payment-method", 

     // number of dollars to charge, the X in $X.Y
    "dollars": 1,
    
    // number of cents to charge, the Y in $X.Y
    "cents": 28
}

Update Responses

None

Completion Responses FinishedAuthorization : response when the payment

// Callback data
{
    "name": "MSREndRead",
    "id": "id-of-the-corresponding-request",
    "payid": "id-for-referencing-the-given-magstripe-card" // e.g. pass this id into `ddpay.payment.SettlePayment`,
    "status": 0, // 0 if success, 1 if fail
    "transaction_id": "istring id of the transaction",
    "info": "string with additional information about the transaction"
}

network API

We have not yet exposed the network API: this should be ready in October 2015.

NOTE

This API library is under active development. Contact Colorado Reed if you need specific functionality that is not yet implemented here.