dotdashpay
Advanced tools
The DotDashPay API Node.js library 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:
npm install dotdashpay
Here we provide a brief "getting started" guide to help you quickly get up to speed with the DotDashPay 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.
The DotDashPay API has three namespaces:
dotdashpay.payment: all payment-processing related functions, e.g. processing, voiding, authorizing, refunding, etc transactionsdotdashpay.hardware: all payment-hardware related functions, e.g. reading card data, testing NFC connectivity, etcdotdashpay.network: all network related functions, e.g. sending data chunks, checking network connectivity, etcAll 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:
onUpdateonCompletionwhere 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.
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.
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.
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
}
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 calledUpdate 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
MSREndRead : response when the magnetic-stripe reader finishes reading data from a magnetic stripe card.
// Callback data
{
"response_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" // String
}
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
}
]
}
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
}
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
}
MSREndRead : response when the magnetic-stripe reader finishes reading data from a magnetic stripe card.
// Callback data
{
"response_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
{
"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
}
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 settlePaymentUpdate 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
}
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
}
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 authorizePaymentUpdate 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
}
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
}
Send an HTTP POST request with the data argument to the url argument
Arguments
url {String}: the URL to send the HTTP POST request todata {Object or String}: A JSON encodable object or String to post to urlUpdate 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
}
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})
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("MSREndRead", {"payid": "custom-id"})
would make it so that everytime the DotDashPay Chip Simulator
sends an MSREndRead Response, the payid attribute would be
"custom-id".
You could also cause an Error to always be returned in lieu of
the MSREndRead Response by calling setResponse with the
parameter raiseError parameter true, e.g.
setResponse("MSREndRead", {"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("MSREndRead")` 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)Reset a specific Response that you previously changed using dotdashpay.simulator.setResponse
Arguments
Reset all Responses that you previously changed using dotdashpay.simulator.setResponse
Arguments
None
This API library is under active development. Contact apidev if you need specific functionality that is not yet implemented here.
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",
}
]
}
FAQs
DotDashPay Node SDK
The npm package dotdashpay receives a total of 5 weekly downloads. As such, dotdashpay popularity was classified as not popular.
We found that dotdashpay demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.