dotdashpay

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 DotDashPay chip). The DotDashPay enables payments on your machine by providing you with a simple, robust API to communicate to your payment peripherals and payment processor.

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 dotdashpay

Guide

• Getting Started
  • Setup The API
  • Making Requests and Providing Callbacks
  • Full Example
• API
  • Hardware
    • #listenForPaymentData
    • #listPeripherals
  • Payment
    • #authorizePayment
    • #listenForPaymentDataThenSettle
    • #refundPayment
    • #settlePayment
    • #voidPayment
  • Network
    • #postData
• Configuration options
• Simulator Responses

Getting Started

Here we provide a brief "getting started" guide to help you quickly get up to speed with the DotDashPay API.

(1) Setup the API

To get started, require the dotdashpay module in your code.

var dotdashpay = require("dotdashpay");

and call init with the your desired configuration object. For example

dotdashpay.init({"simulate": true})

here we use the built-in DotDashPay Chip simulator by setting the configuration option simulate to true. This way, we can start building our application without having to connect to the chip or deal with any hardware. See the configuration options section for more details about these options and also see simulator responses section for information on how to control the responses you receive from the simulator.

(2) Making Requests and Providing Callbacks

The DotDashPay API has three namespaces:

• dotdashpay.payment: all payment-processing related functions, e.g. processing, voiding, authorizing, refunding, etc transactions
• dotdashpay.hardware: all payment-hardware related functions, e.g. reading card data, testing NFC connectivity, etc
• dotdashpay.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. These functions return a Request object that you can use to setup callbacks that handle the responses from the chip. The Request object has two functions for setting callbacks:

• onUpdate
• onCompletion

where the callback function passed into onUpdate will be called for non-terminating update events from the DotDashPay Chip and the function passed into onCompletion is called when the request is finished, i.e. there will be no more onUpdate callbacks. Here's a simple example use:

dotdashpay.hardware.listenForPaymentData()
    .onUpdate(function (err, data) { console.log("listenForPaymentData UPDATE with data:", data); })
    .onCompletion(function (err, data) { console.log("listenForPaymentData COMPLETE with data", data); })

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
    // ...
}

You can use the name field to differentiate between different Update and Completion responses and the id field to associate the response with a particular request.

(3) Full Example: Performing a Transaction

Here's a full example of performing a transaction. Note: this transaction uses two requests but could be accomplished with a single request using #listenForPaymentDataThenSettle.

var dotdashpay = require("dotdashpay");
dotdashpay.init({simulate: true});

// wait for the payment data from the dotdashpay peripherals
dotdashpay.hardware.listenForPaymentData()
    .onUpdate(function (err, data) { console.log("waitForPaymentData onUpdate with data:", data); })
    .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
        dotdashpay.payment.settlePayment(payData)
            .onUpdate(function (err, data) { console.log("settlePayment onUpdate with data:", data); })
            .onCompletion(function (err, data) { console.log("settlePayment onCompletion with data:", data); });
    });

You can find this example in the examples directory.

API

Here we describe the various request functions you can use to communicate with the DotDashPay Chip. See the Getting Started Section for an overview of this API.

---

---

API: dotdashpay.hardware

#hardware.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 `dotdashpay.payment.settlePayment`
    "payid": "id-for-referencing-the-given-magstripe-card" 
}

---

---

#hardware.listPeripherals()

Asks the DotDashPay chip to return a list of all attached hardware peripherals.

Arguments

None

Update Responses

None

Completion Responses

AttachedPeripheralsList : response when the magnetic-stripe reader finishes reading data from a magnetic stripe card.

// Callback data
{
    "name": "AttachedPeripheralsList",
    "id": "id-of-the-corresponding-request",
    "peripherals": [
        {
            "id": "id-of-attached-peripheral",  // String
            "name": "name of attached peripheral", // String
            "status": 0 // 0 if in a good state 1 if in a bad state
        }
    ]
}

---

---

API: dotdashpay.payment

#payment.authorizePayment(paymentData)

Authorize a payment, i.e. verify that the payment_info is accurate and that the desired funds can be withdrawn.

This request does not charge the card: you will have to call payment.settlePayment(returnObjFromAuthorizePayment) later. Alternatevily, you can later call voidPayment(returnObjFromAuthorizePayment) in order to void the given payment without ever having charged the card.

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 `dotdashpay.hardware.listenForPaymentData`
    "payid": "id-for-referencing-the-given-payment-method",  // String

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

Update Responses

None

Completion Responses

FinishedAuthorization : response when the payment authorization returns from the payment processor.

// Callback data
{
    "name": "FinishedAuthorization",  //String
    "id": "id-of-the-corresponding-request", // String
    "payid": "id-for-referencing-the-given-magstripe-card", // String  
    "status": 0, // 0 if authorized, 1 if fail
    "transaction_id": "string id of the transaction",
    "info": "additional information about the transaction", // String
    "customer_id": "custid" //String
}

---

---

#payment.listenForPaymentDataThenSettle(paymentData)

This is a convenience request that combines listenForPaymentData and settlePayment into a single request. Once the user interacts with a payment peripheral, they are immediently charged for the amount you specify. Generally, this is quicker than calling listenForPaymentData then settlePayment.

Arguments

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

// `paymentData` format
{
     // 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

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

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

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

// Callback data
{
    "name": "MSREndRead",  // String
    "id": "id-of-the-corresponding-request",  // String
    "payid": "id-for-referencing-the-given-magstripe-card"  // String
}

StartSettlement : response when the settle payment request is sent to the payment processor.

// Callback data
{
    "name": "StartSettlement",  // String
    "id": "id-of-the-corresponding-request",  // String
    "payid": "id-for-referencing-the-given-magstripe-card" // String, 
}

Completion Responses

FinishedSettlement : response when the settle payment request returns from the payment processor.

// Callback data
{
    "name": "FinishedSettlement",  // String
    "id": "id-of-the-corresponding-request",  // String
    "payid": "id-for-referencing-the-given-magstripe-card", // String
    "status": 0, // 0 if success, 1 if fail
    "transaction_id": "string id of the transaction",  // String
    "info": "string with additional information about the transaction"  // String
}

---

#payment.refundPayment(transactionId)

Refund a settled payment. You can only call this function for a payment that was successfully settled

Arguments

• transactionId {String}: the transaction id returned from #settlePayment

Update Responses

None

Completion Responses

FinishedRefund : response when the payment refund returns from the payment processor.

// Callback data
{
    "name": "FinishedRefund",  //String
    "id": "id-of-the-corresponding-request", // String
    "status": 0, // 0 if refunded, 1 if fail
    "transaction_id": "string id of the transaction",
    "info": "additional information about the refund" // String
}

---

---

#payment.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 `dotdashpay.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

FinishedSettlement : response when the settle payment request returns from the payment processor.

// Callback data
{
    "name": "FinishedSettlement",  // String
    "id": "id-of-the-corresponding-request",  // String
    "payid": "id-for-referencing-the-given-magstripe-card" // String
    "status": 0, // 0 if success, 1 if fail
    "transaction_id": "id of the transaction",  // String
    "info": "additional information about the transaction"  // String
}

---

---

#payment.voidPayment(transactionId)

Void an authorized payment. You can only call this function for a payment that was successfully authorized but has not been settled. Call refundPayment if the payment was settled.

Arguments

• transactionId {String}: the transaction id returned from #authorizePayment

Update Responses

None

Completion Responses

FinishedVoid : response when the payment refund returns from the payment processor.

// Callback data
{
    "name": "FinishedVoid",  //String
    "id": "id-of-the-corresponding-request", // String
    "status": 0, // 0 if voided, 1 if fail
    "transaction_id": "string id of the transaction",
    "info": "additional information about the void" // String
}

API: dotdashpay.network

#network.postData(url, data)

Send an HTTP POST request with the data argument to the url argument

Arguments

• url {String}:
• data {Object or String}: A JSON encodable object or String to post to url

Update Responses

None

Completion Responses

FinishedPostData : response when the settle payment request returns from the payment processor.

// Callback data
{
    "name": "FinishedPostData",  // String
    "id": "id-of-the-corresponding-request",
    "response_code": 0, // Number: HTTP response code
    "response": "data"  // String
}

NOTE

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

<a name="configuration-options>Configuration Options

TODO(cjrd)

<a name="simulator-responses>Simulator Responses

TODO(cjrd)