ddp.api.node

Node.js API

The open source DotDashPay Node.js API defines and implements a set of functions that can be used to interact with the DotDashPay IoT Payments Platform (the DotDashPay Chip). The DotDashPay Chip abstracts away all of the low-level protocols and connectivity aspects of interacting with payment-related hardware and payment processors. You simply connect your machine to the DotDashPay Chip, write a few API calls, and your machine accepts payments!

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 how the DotDashPay API (this library) fits into the payments flow:

Installation

npm install dotdashpay

Getting Started

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

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, you can start building your 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 Section for information on how to control the Responses you receive from the simulator.

Making Requests

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:

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

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

Full Example

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.

dotdashpay.hardware API

hardware.checkSerialConnection

Check the serial connection to the DotDashPay Chip.

Arguments

None

Update Responses

None

Completion Responses

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

// Callback data
{
    "request_name": "FinishedSerialCheck",  // String
    "id": "id-of-the-corresponding-request",  // String
    "status": 0 // 0 if serial connection established, 1 if not connected
    "info": "additional information about the connectivity"  // String
 
}

hardware.listenForPaymentData

Listen for payment data from the payments-related peripheral hardware

Arguments

• onlyNewData {Boolean}: specify whether the DotDashPay Chip 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
{
    "response_name": "MSRStartRead",
    "id": "id-of-the-corresponding-request"
}

Completion Responses

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

// Callback data
{
    "response_name": "MSRFinishedRead",
    "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"   // String
}

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
{
    "response_name": "AttachedPeripheralsList",
    "id": "id-of-the-corresponding-request",
    "peripherals": [
        {
            "id": "id-of-attached-peripheral",  // String
            "peripheral_name": "name of attached peripheral", // String
            "status": 0 // 0 if in a good state 1 if in a bad state
        }
    ]
}

dotdashpay.payment API

payment.authorizePayment

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. Alternatively, 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
{
    "response_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": "id of the transaction",  // String
    "info": "additional information about the transaction", // String
    "customer_id": "custid" //String
}

payment.listenForPaymentDataThenSettle

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
{
    "response_name": "MSRStartRead",  // String
    "id": "id-of-the-corresponding-request"  // String
}

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

// Callback data
{
    "response_name": "MSRFinishedRead",  // 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
{
    "response_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
{
    "response_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": "additional information about the transaction"  // String
}

payment.refundPayment

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
{
    "response_name": "FinishedRefund",  //String
    "id": "id-of-the-corresponding-request", // String
    "status": 0, // 0 if refunded, 1 if fail
    "transaction_id": "id of the transaction",  // String
    "info": "additional information about the refund" // String
}

payment.settlePayment

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
{
    "response_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

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
{
    "response_name": "FinishedVoid",  //String
    "id": "id-of-the-corresponding-request", // String
    "status": 0, // 0 if voided, 1 if fail
    "transaction_id": "id of the transaction",  // String
    "info": "additional information about the void" // String
}

dotdashpay.network API

network.checkNetworkConnectivity

Check the network connectivity for the DotDashPay Chip.

Arguments

None

Update Responses

None

Completion Responses

FinishedNetworkCheck : response after the network connection for the DotDashPay Chip has been checked

// Callback data
{
    "response_name": "FinishedNetworkCheck",  // String
    "id": "id-of-the-corresponding-request",  // String
    "status": 0 // 0 if connected to the network, 1 if not connected
    "info": "additional information about the connectivity"  // String
}

network.postData

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

Arguments

• url {String}: the URL to send the HTTP POST request to
• 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
{
    "response_name": "FinishedPostData",  // String
    "id": "id-of-the-corresponding-request",
    "response_code": 0, // Number: HTTP response code
    "response": "data"  // String
}

simulator API

The DotDashPay Chip simulator closely simulates the actual DotDashPay hardware. This simulator should enable you to fully develop your application without needing to connect to the DotDashPay chip or interface with any hardware.

The dotdashpay.simulator namespace provides a set of functions to control how the simulator responds to your Requests, i.e. you can directly control the Responses you receive in your callback functions.

To use the simulator, simply set simulate to true when initializing the dotdashpay API:

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

simulator.setResponse

The DotDashPay Chip simulator has a set of prespecified Responses for a given Request. This function can be used to overwrite the data in a given Response OR it can be used to specify that an Error should be returned in lieu of the Response itself.

For example,

setResponse("MSRFinishedRead", {"payid": "custom-id"})

would make it so that everytime the DotDashPay Chip Simulator sends an MSRFinishedRead Response, the payid attribute would be "custom-id".

You could also cause an Error to always be returned in lieu of the MSRFinishedRead Response by calling setResponse with the parameter raiseError parameter true, e.g.

setResponse("MSRFinishedRead", {"descriptioin": "MSR internal error", "code": 37}, true)

Note that the data parameter in this case specifies the error data. Consult the Error Codes Section if you want to use the appropriate error codes in your simulated errors.

You can reset the response using "dotdashpay.simulator.resetResponse("MSRFinishedRead")` or reset all responses using "dotdashpay.simulator.resetAllResponses().

Arguments

• responseName {String}: The name of the Response that will have its data overwritted with the key/values in the data argument.
• data {Object}: A set of key/value pairs that will overwrite the corresponding Response data for responseName. (see the example in the function signature)
• raiseError {Boolean}: if true, an Error Response will be returned in lieu of the Response with name responseName. You can specify the type of Error that should be returned via the data parameter. (see the example in the function signature)

simulator.resetResponse

Reset a specific Response that you previously changed using dotdashpay.simulator.setResponse

Arguments

• responseName {String}: The name of the Response that had its Response data overwritted.

simulator.resetAllResponses

Reset all Responses that you previously changed using dotdashpay.simulator.setResponse

Arguments

None

Configuration Options

All configuration options are optional when simulate is set to true. When simulate is false you must specify the set of attached peripherals as well as the payment processor. The default values are provided below for each attribute.

{
    "testMode": true,  // use sandbox payment processing
    "simulate": true,  // use the DDP simulation
    "peripherals": [
        {
            "type": "magstripe",
            "id": "peripheral-id"  // contact us
        },
        {
            "type": "emv",
            "id": "peripheral-id"  // contact us
        }
        {
            "type": "nfcp",
            "id": "peripheral-id"  // contact us
        }
    ],
 
    // contact your DDP representative to set up
    // your desired payment processor
    "paymentProcessing": {
        "type": "ddp",  
        "authToken": "0123456789"
    }
 
    // The DotDashPay chip will sequentially try to
    // connect to the provided wifi networks
    "wifiNetworks": [
        {
            "network": "MyWifiNetwork",
            "passphrase": "MyWifiNetwork Passphrase",
        }
    ]
}