Socket
Socket
Sign inDemoInstall

dotdashpay

Package Overview
Dependencies
129
Maintainers
1
Versions
21
Alerts
File Explorer

Advanced tools

npm Scripts
License

Install Socket

Detect and block malicious and high-risk dependencies

Install

Comparing version 0.3.0 to 0.3.1

2

lib/server.js

@@ -90,3 +90,3 @@ /**

var reqObj = requestWrapper.request;
if (reqObj._signals[response.name]) {
if (reqObj._signals[response.name] && reqObj._signals[response.name].getNumListeners() > 0) {
logger.debug("Server received handled API response", response);

@@ -93,0 +93,0 @@ reqObj._signals[response.name].dispatch(response.message);

2

package.json
{
"name": "dotdashpay",
"version": "0.3.0",
"version": "0.3.1",
"description": "DotDashPay Node API",

@@ -5,0 +5,0 @@ "main": "index.js",

543

README.md

@@ -9,544 +9,5 @@ # Node.js API

Oh, and don't worry about payments-related compliance and regulations for your hardware and software. We take care of that too!
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:
<p align="center">
<img src="http://dotdashpay.com/img/ddp-overview.jpg" alt="DotDashPay API Library Scope" width="100%" >
</p>
## <a name="installation"></a>Installation
npm install dotdashpay
## <a name="gstart"></a> Getting Started
Here we provide a brief "getting started" guide to help you quickly get up to speed with the DotDashPay API.
### <a name="gstart-setup"></a>Setup the API
To get started, require the `dotdashpay` module in your code.
```javascript
var dotdashpay = require("dotdashpay");
```
and call `init` with the your desired configuration object. For example
```javascript
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 <a href="#configuration-options">configuration options section</a> for more details about these options and also see <a href="#apisimulator">Simulator Section</a> for information on how to control the Responses you receive from the simulator.
### <a name="gstart-make-request"></a>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:
```javascript
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
```javascript
{
"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:
```javascript
{
"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.
### <a name="gstart-example"></a>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 <a href="#listenForPaymentDataThenSettle">listenForPaymentDataThenSettle</a>.
```javascript
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](examples).
# <a name="api"></a>API
Here we describe the various request functions you can use to communicate with the DotDashPay Chip. See the <a href="#gettingstarted">Getting Started Section</a> for an overview of this API.
## <a name="apihardware"></a> dotdashpay.hardware API
### <a name="checkSerialConnection" href="#checkSerialConnection">hardware.checkSerialConnection</a>
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.
```javascript
// 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
}
```
### <a name="listenForPaymentData" href="#listenForPaymentData">hardware.listenForPaymentData</a>
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
```javascript
// 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.
```javascript
// 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
}
```
### <a name="listPeripherals" href="#listPeripherals">hardware.listPeripherals</a>
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.
```javascript
// 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
}
]
}
```
## <a name="apipayment"></a>dotdashpay.payment API
### <a name="authorizePayment" href="#authorizePayment">payment.authorizePayment</a>
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 <a href="#settlePayment">payment.settlePayment</a>(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:
```javascript
// `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.
```javascript
// 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
}
```
### <a name="listenForPaymentDataThenSettle" href="#listenForPaymentDataThenSettle">payment.listenForPaymentDataThenSettle</a>
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:
```javascript
// `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
```javascript
// 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.
```javascript
// 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.
```javascript
// 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.
```javascript
// 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
}
```
### <a name="refundPayment" href="#authorizePayment">payment.refundPayment</a>
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 <a href="#settlePayment">settlePayment</a>
__Update Responses__
_None_
__Completion Responses__
`FinishedRefund` : response when the payment refund returns from the payment processor.
```javascript
// 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
}
```
### <a name="settlePayment" href="#settlePayment">payment.settlePayment</a>
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:
```javascript
// `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.
```javascript
// 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
}
```
### <a name="voidPayment" href="#voidPayment">payment.voidPayment</a>
Void an authorized payment. You can only call this function for a payment that was successfully authorized but has not been settled. Call <a href="#refundPayment">refundPayment</a> if the payment was settled.
__Arguments__
* `transactionId` {String}: the transaction id returned from <a href="#authorizePayment">authorizePayment</a>
__Update Responses__
_None_
__Completion Responses__
`FinishedVoid` : response when the payment refund returns from the payment processor.
```javascript
// 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
}
```
## <a name="apinetwork"></a>dotdashpay.network API
### <a name="checkNetworkConnectivity" href="#checkNetworkConnectivity">network.checkNetworkConnectivity</a>
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
```javascript
// 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
}
```
### <a name="postData" href="#postData">network.postData</a>
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.
```javascript
// Callback data
{
"response_name": "FinishedPostData", // String
"id": "id-of-the-corresponding-request",
"response_code": 0, // Number: HTTP response code
"response": "data" // String
}
```
## <a name="apisimulator">simulator API</a>
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:
```javascript
var dotdashpay = require("dotdashpay");
dotdashpay.init({"simulate": true})
```
### <a name="setResponse" href="#setResponse">simulator.setResponse</a>
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,
```javascript
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.
```javascript
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](#ErrorCodes) if you want to use the appropriate error codes in your simulated errors.
You can reset the response using <a href="#resetResponse">"dotdashpay.simulator.resetResponse("MSRFinishedRead")`</a> or reset all responses using <a href="#resetAllResponses">"dotdashpay.simulator.resetAllResponses()</a>.
__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)
### <a name="resetResponse" href="#resetResponse">simulator.resetResponse</a>
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.
### <a name="resetAllResponses" href="#resetAllResponses">simulator.resetAllResponses</a>
Reset all Responses that you previously changed using `dotdashpay.simulator.setResponse`
__Arguments__
_None_
# <a name="configuration-options">Configuration Options</a>
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.
```javascript
{
"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",
}
]
}
```
**The API documentation and getting started guides can be found at https://connect.dotdashpay.com**
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

About

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc