NAV
Node.js (Javascript)

Platform

Initialize

This function sets up the SDK and establishes a connection to the DotDashPay Platform and validates all of the input configuration options.

Platform.InitializeArgs

var args = {
  environment: "MIDDLEWARE_SIMULATOR",
  simulatorConfiguration: { 'apiToken': 'aeac1bc8f0735e4283305652ab' },
  connectionRetries: 500,
};

dotdashpay.platform.initialize(args)
  .onInitialized(function(response) {
    console.log("Received onInitialized response", JSON.stringify(response, null, 2));
  })
  .onInitializeError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default
 environment
enum Environment:
UNKNOWN_ENVIRONMENT: 0PRODUCTION: 1DEVELOPMENT: 2MIDDLEWARE_SIMULATOR: 3PERIPHERAL_SIMULATOR: 4PROCESSOR_SIMULATOR: 5
Specifies the environment the SDK will run in, i.e. whether it will process real or simulated payments. MIDDLEWARE_SIMULATOR is the default, which will connect to the DotDashPay Middleware Simulator instead of a real local instance MIDDLEWARE_SIMULATOR
 simulatorConfiguration
Object: {  
  // Provide this token if you’re trying out the SDK at https://connect.dotdashpay.com, and environment is MIDDLEWARE_SIMULATOR (the default)
  api_token [string]
}
Specifies the environment the SDK will run in, i.e. whether it will process real or simulated payments. MIDDLEWARE_SIMULATOR is the default, which will connect to the DotDashPay Middleware Simulator instead of a real local instance None
 connectionRetries
int32
Represents the number of times the SDK will retry a failed request to the DotDashPay platform before giving up. 6000

denotes a required field

Responses

Platform.Initialized

Indicates that the SDK has connected to the DotDashPay middleware and is ready to listen for payment peripheral interactions and take real (or simulated) payments.

Parameter Description

ListenForInteraction

ListenForInteraction is the starting point of every transaction.

For a loyalty only transaction, i.e. when transaction_mode=‘IDENTIFY’, this request will prompt the hardware that is connected to the DotDashPay Platform to start listening for a loyalty transaction from a mobile device. If the customer is already enrolled in the loyalty program, then the customer’s loyalty profile will be returned. If the customer is not enrolled in the loyalty program, then the customer will receive a push notification that will guide them through a native loyalty enrollment flow.

For a payment transaction, this request will listen for a user interaction (e.g. swipe or tap) from all payment peripheral hardware connected to the DotDashPay Platform.

If you make a second ListenForInteraction request while there is an outstanding ListenForInteraction request, then the first ListenForInteraction request will be cancelled and will return a “User Cancelled” error, and the second request will begin listening for an interaction.

Platform.ListenForInteractionArgs

var args = {
  useExistingData: false,
  amount: 128,
  currency: "USD",
  transactionMode: "PAYMENT",
};

dotdashpay.platform.listenForInteraction(args)
  .onStartedListeningForInteraction(function(response) {
    console.log("Received onStartedListeningForInteraction response", JSON.stringify(response, null, 2));
    var peripheralId = response.peripheralId; // e.g. "IDTechKioskIII"
  })
  .onStartedInteraction(function(response) {
    console.log("Received onStartedInteraction response", JSON.stringify(response, null, 2));
    var peripheralId = response.peripheralId; // e.g. "IDTechKioskIII"
  })
  .onGotInteraction(function(response) {
    console.log("Received onGotInteraction response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
    var peripheralId = response.peripheralId; // e.g. "IDTechKioskIII"
    var customerProfile = response.customerProfile; // e.g. {'phoneNumber': '5555555555', 'familyName': 'Customer', 'postalCode': '94609', 'givenName': 'Mimir T.', 'fullName': 'Mimir T. Customer', 'id': 'an-id'}
  })
  .onListenForInteractionError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default
 useExistingData
bool
Setting this to true will return data that had been read by a connected peripheral before calling ListenForInteraction, e.g. a card swipe that occurred before a total was known. By default, ListenForInteraction will only return new data through connected peripherals. false
 amount
uint32
Amount is the smallest unit of currency for a given currency, e.g. cents in USD. Some payment methods (e.g. Apple Pay) require you to specify the charge amount before taking the payment, rather than the typical approach of specifying it in Payment.Settle or Payment.PreAuthorize. If you specify an amount here, the amount/currency you pass to Payment.PreAuthorize and Payment.Settle MUST agree with this amount/currency. None
 currency
enum Currency:
UNKNOWN_CURRENCY: 0USD: 1
If the payment method requires setting the amount field, you must also set the currency field (if not USD). USD
 transactionMode
enum TransactionMode:
UNKNOWN_TRANSACTION_MODE: 0IDENTIFY: 1PAYMENT: 2IDENTIFY_AND_PAYMENT: 3
The type of transaction to perform: IDENTIFY: Only perform a identify interaction with the payee. This will cause the InteractionResponse to contain a customer_profile_data field, which will contain information about the payee if they have a profile (e.g. if they are enrolled in your loyalty program). PAYMENT: Only perform a payment interaction with the payee. IDENTIFY_AND_PAYMENT: Perform a identify both payment interaction with the payee (both). This will cause the InteractionResponse to contain a customer_profile_data field, which will contain information about the payee if they have a profile (e.g. if they are enrolled in your loyalty program). PAYMENT

Responses

Platform.StartedListeningForInteraction

Response when the hardware peripheral is ready to accept an interaction from the customer, i.e. it is listening for an interaction from the customer.

Parameter Description
 peripheralId
enum PeripheralId:
UnknownPeripheralId: 0TestPaymentDevice: 1SimulatedViaTimeout: 2SimulatedViaFTDI: 3IDTechSpectrumPro: 5IDTechSecureMoir: 6IDTechKioskIII: 7IDTechSecuRED: 8NFC: 9
Denotes which payment hardware is receiving data.

denotes a required field

Platform.StartedInteraction

Response when any connected payment peripheral begins receiving payment data (e.g. when a magnetic-stripe reader starts reading data from a magnetic stripe card).

Parameter Description
 peripheralId
enum PeripheralId:
UnknownPeripheralId: 0TestPaymentDevice: 1SimulatedViaTimeout: 2SimulatedViaFTDI: 3IDTechSpectrumPro: 5IDTechSecureMoir: 6IDTechKioskIII: 7IDTechSecuRED: 8NFC: 9
Denotes which payment hardware is receiving data.

denotes a required field

Platform.GotInteraction

Response when any payment peripheral finishes reading payment data.

Platform.GotInteraction.transactionChainId is returned and unique to this payment interaction. You will pass this token to every subsequent payment request (e.g. Payment.PreAuthorize), and you should store it if you want to retrieve/reconcile this transaction with DotDashPay at a later time (using Payment.GetTransaction).

Parameter Description
 transactionChainId
string
A unique identifier that represents the payment data that was received. Note that this changes each time a payment peripheral reads a card, i.e. for each transaction, even if the payment method is the same. It is used in subsequent SDK requests (e.g. Payment.Settle) to refer to the payment data in a secure way.
 peripheralId
enum PeripheralId:
UnknownPeripheralId: 0TestPaymentDevice: 1SimulatedViaTimeout: 2SimulatedViaFTDI: 3IDTechSpectrumPro: 5IDTechSecureMoir: 6IDTechKioskIII: 7IDTechSecuRED: 8NFC: 9
Denotes which payment hardware received data.
 customerProfile
Object: {  
  // The unique ID of the customer
  id [string]
,
  // The customer’s full name
  full_name [string]
,
  // The customer’s family/last name
  family_name [string]
,
  // The customer’s given/first name
  given_name [string]
,
  // The phone number of the customer
  phone_number [string]
,
  // The zipcode of the customer
  postal_code [string]
}
This field will contain personalized customer information when the following criteria are met: (1) Platform.ListenForInteraction is called with with the IDENTIFY or IDENTIFY_AND_PAYMENT environment. (2) The customer uses a mobile wallet loyalty pass for the transaction.

denotes a required field

WaitForCustomerEnrollment

After receiving an interaction for a IDENTIFY or IDENTIFY_AND_PAYMENT transaction, you can wait for a customer to enroll in the associated loyalty pass. If the customer enrolls before the given timeout, a customer_profile will be returned. Otherwise, a timeout error will be returned.

The customer_profile will contain an id that can be matched against later. If your loyalty pass is personalizable and the customer chose to provide the requested information, that data will be returned in the customer_profile.

NOTE: this request will timeout if the customer enrolled before the request was issued. In this case, you should use Payment.GetTransaction to obtain the customer profile and associated transaction information.

Platform.WaitForCustomerEnrollmentArgs

var args = {
  transactionChainId: "iPqy9F82v5qexbtz",
  timeoutSeconds: 180,
};

dotdashpay.platform.waitForCustomerEnrollment(args)
  .onCustomerEnrolled(function(response) {
    console.log("Received onCustomerEnrolled response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
    var customerProfile = response.customerProfile; // e.g. {'phoneNumber': '5555555555', 'familyName': 'Customer', 'postalCode': '94609', 'givenName': 'Mimir T.', 'fullName': 'Mimir T. Customer', 'id': 'an-id'}
  })
  .onWaitForCustomerEnrollmentError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default
 transactionChainId
string
The transaction_chain_id for the transaction that initiated the customer to enroll in a loyalty pass. None
 timeoutSeconds
int32
If the customer does not enroll within this amount of time, the onWaitForCustomerEnrollmentError handler is triggered with a timeout error. 300

denotes a required field

Responses

Platform.CustomerEnrolled

Parameter Description
 transactionChainId
string
The transaction_chain_id for the transaction that initiated the customer to enroll in a loyalty pass
 customerProfile
Object: CustomerEnrolled.CustomerProfile
Information about the customer that just enrolled in a loyalty pass. If the pass was personalizable, and the customer chose to give the requested information, it will be filled in here

denotes a required field

GetConnectedHardware

Returns a list of all attached hardware peripherals to the DotDashPay Platform.

Platform.GetConnectedHardwareArgs

var args = {};

dotdashpay.platform.getConnectedHardware(args)
  .onGotConnectedHardware(function(response) {
    console.log("Received onGotConnectedHardware response", JSON.stringify(response, null, 2));
    var peripheralIds = response.peripheralIds; // e.g. [['IDTechKioskIII']]
  })
  .onGetConnectedHardwareError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default

Responses

Platform.GotConnectedHardware

Response indicating the set of hardware peripherals that are connected to the DotDashPay Platform.

Parameter Description
 peripheralIds
[Array] enum PeripheralId:
UnknownPeripheralId: 0TestPaymentDevice: 1SimulatedViaTimeout: 2SimulatedViaFTDI: 3IDTechSpectrumPro: 5IDTechSecureMoir: 6IDTechKioskIII: 7IDTechSecuRED: 8NFC: 9
An array of attached peripherals.

Payment

PreAuthorize

PreAuthorize a payment, i.e. verify that the payment_info is accurate and that the desired funds can be withdrawn. A PreAuthorize transaction places a hold on the customer’s account for the transaction amount for a limited time; depending on the cardholder’s bank, the reserve can be in place for 2-10 days.

This request does not charge a payer. You will have to call Payment.Settle later. Alternatively, if you wish to void this authorization, which you should do if you do not plan to settle it, you should call Payment.VoidPreAuthorize.

Payment.PreAuthorizeArgs

var args = {
  transactionChainId: "iPqy9F82v5qexbtz",
  amount: 128,
  currency: "USD",
};

dotdashpay.payment.preAuthorize(args)
  .onStartedPreAuthorizing(function(response) {
    console.log("Received onStartedPreAuthorizing response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onPreAuthorized(function(response) {
    console.log("Received onPreAuthorized response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onPreAuthorizeError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default
 transactionChainId
string
The ID associated with the data returned from Platform.ListenForInteraction. None
 amount
uint32
Amount is the smallest unit of currency for a given currency, e.g. cents in USD. None
 currency
enum Currency:
UNKNOWN_CURRENCY: 0USD: 1
Currency of amount (only USD currently supported). USD

denotes a required field

Responses

Payment.StartedPreAuthorizing

Response when a pre-authorization request is valid and has been sent to the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.PreAuthorize request.

Payment.PreAuthorized

Response when a successful pre-authorization response is returned from the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.PreAuthorize request.

Settle

Settles a payment, which is equivalent to initiating a transfer of money from the payer’s bank to your bank.

You may call this function after receiving data from calling Platform.ListenForInteraction or after receiving data from calling Payment.PreAuthorize.

If called directly after receiving payment data from the platform, then you must include a transaction amount and this request will immediately charge the payer.

If called after authorizing the payment, then supplying the transaction amount is optional (it defaults to the amount specified in Payment.PreAuthorize); a provided transaction amount must be less than or equal to the amount in the PreAuthorization. If Settle is called after Payment.PreAuthorize, then this request will finalize the transaction and the transaction cannot be voided, it must be refunded using Payment.Refund.

Payment.SettleArgs

var args = {
  transactionChainId: "iPqy9F82v5qexbtz",
  amount: 128,
  currency: "USD",
};

dotdashpay.payment.settle(args)
  .onStartedSettling(function(response) {
    console.log("Received onStartedSettling response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onSettled(function(response) {
    console.log("Received onSettled response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onSettleError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default
 transactionChainId
string
The ID associated with the data returned from Platform.ListenForInteraction or Payment.PreAuthorize. None
 amount
uint32
Amount is the smallest unit of currency for a given currency, e.g. cents in USD. If you’re settling after successfuly calling Payment.PreAuthorize, then you may omit the amount to settle for the full amount that you pre-authorized, or set it to be less than or equal to the PreAuthorized amount. None
 currency
enum Currency:
UNKNOWN_CURRENCY: 0USD: 1
Currency of amount (only USD currently supported). USD

denotes a required field

Responses

Payment.StartedSettling

Response when a settle request is valid and has been sent to the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.Settle request.

Payment.Settled

Response when a successful Settle response returns from the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.Settle request.

VoidPreAuthorize

Void an authorized payment. You can only call this function for a payment that was successfully authorized via Payment.PreAuthorize but has not yet been settled.

You cannot use this function if the payment was already settled. If it was settled, you must call Payment.Refund instead.

Payment.VoidPreAuthorizeArgs

var args = {
  transactionChainId: "iPqy9F82v5qexbtz",
};

dotdashpay.payment.voidPreAuthorize(args)
  .onStartedVoidingPreAuthorize(function(response) {
    console.log("Received onStartedVoidingPreAuthorize response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onVoidedPreAuthorize(function(response) {
    console.log("Received onVoidedPreAuthorize response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onVoidPreAuthorizeError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default
 transactionChainId
string
The ID associated with the data returned from Platform.ListenForInteraction or Payment.PreAuthorize. None

denotes a required field

Responses

Payment.StartedVoidingPreAuthorize

Response when a void pre-authorization request is valid and has sent to the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.VoidPreAuthorize request.

Payment.VoidedPreAuthorize

Response when a successful void pre-authorization response is returned from the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.VoidPreAuthorize request.

Refund

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

Refunds will be processed as efficiently as possible for each processor to avoid potentionally costly actions (such as chargebacks), though this will not always be possible.

If a refund succeeds, funds have been returned, one way or another.

Payment.RefundArgs

var args = {
  transactionChainId: "iPqy9F82v5qexbtz",
};

dotdashpay.payment.refund(args)
  .onStartedRefunding(function(response) {
    console.log("Received onStartedRefunding response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onRefunded(function(response) {
    console.log("Received onRefunded response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onRefundError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default
 transactionChainId
string
The ID associated with the data returned from Platform.ListenForInteraction or Payment.Settle. None

denotes a required field

Responses

Payment.StartedRefunding

Response when a refund request is valid and has been sent to the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.Refund request.

Payment.Refunded

Response when a successful refund response is returned from the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.Refund request.

ListenForInteractionThenSettle

This is a convenience request that combines Platform.ListenForInteraction and Payment.Settle into a single request.

Once a payer interacts with a payment peripheral, they are immediately charged for the amount specified in this request.

Payment.ListenForInteractionThenSettleArgs

var args = {
  useExistingData: false,
  existingDataTtlSeconds: 5,
  amount: 128,
  currency: "USD",
  transactionMode: "PAYMENT",
};

dotdashpay.payment.listenForInteractionThenSettle(args)
  .onStartedListeningForInteraction(function(response) {
    console.log("Received onStartedListeningForInteraction response", JSON.stringify(response, null, 2));
    var peripheralId = response.peripheralId; // e.g. "IDTechKioskIII"
  })
  .onStartedInteraction(function(response) {
    console.log("Received onStartedInteraction response", JSON.stringify(response, null, 2));
    var peripheralId = response.peripheralId; // e.g. "IDTechKioskIII"
  })
  .onGotInteraction(function(response) {
    console.log("Received onGotInteraction response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
    var peripheralId = response.peripheralId; // e.g. "IDTechKioskIII"
    var customerProfile = response.customerProfile; // e.g. {'phoneNumber': '5555555555', 'familyName': 'Customer', 'postalCode': '94609', 'givenName': 'Mimir T.', 'fullName': 'Mimir T. Customer', 'id': 'an-id'}
  })
  .onStartedSettling(function(response) {
    console.log("Received onStartedSettling response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onSettled(function(response) {
    console.log("Received onSettled response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onListenForInteractionError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .onSettleError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default
 amount
uint32
Amount is the smallest unit of currency for a given currency, e.g. cents in USD. None
 useExistingData
bool
Setting this to true will return data that had been read by a connected peripheral before calling ListenForInteraction, e.g. a card swipe that occurred before a total was known. By default, ListenForInteraction will only return new data through connected peripherals. false
 existingDataTtlSeconds
uint32
When use_existing_data is true, this determines how long a data will be stored for use. Keep the number relatively low so you don’t accidentally use a previous customer’s data. 20
 currency
enum Currency:
UNKNOWN_CURRENCY: 0USD: 1
Currency of amount (only USD currently supported). USD
 transactionMode
enum TransactionMode:
UNKNOWN_TRANSACTION_MODE: 0IDENTIFY: 1PAYMENT: 2IDENTIFY_AND_PAYMENT: 3
The type of transaction to perform PAYMENT

denotes a required field

Responses

Platform.StartedListeningForInteraction

Response when the hardware peripheral is ready to accept an interaction from the customer, i.e. it is listening for an interaction from the customer.

Parameter Description
 peripheralId
enum PeripheralId:
UnknownPeripheralId: 0TestPaymentDevice: 1SimulatedViaTimeout: 2SimulatedViaFTDI: 3IDTechSpectrumPro: 5IDTechSecureMoir: 6IDTechKioskIII: 7IDTechSecuRED: 8NFC: 9
Denotes which payment hardware is receiving data.

denotes a required field

Platform.StartedInteraction

Response when any connected payment peripheral begins receiving payment data (e.g. when a magnetic-stripe reader starts reading data from a magnetic stripe card).

Parameter Description
 peripheralId
enum PeripheralId:
UnknownPeripheralId: 0TestPaymentDevice: 1SimulatedViaTimeout: 2SimulatedViaFTDI: 3IDTechSpectrumPro: 5IDTechSecureMoir: 6IDTechKioskIII: 7IDTechSecuRED: 8NFC: 9
Denotes which payment hardware is receiving data.

denotes a required field

Platform.GotInteraction

Response when any payment peripheral finishes reading payment data.

Platform.GotInteraction.transactionChainId is returned and unique to this payment interaction. You will pass this token to every subsequent payment request (e.g. Payment.PreAuthorize), and you should store it if you want to retrieve/reconcile this transaction with DotDashPay at a later time (using Payment.GetTransaction).

Parameter Description
 transactionChainId
string
A unique identifier that represents the payment data that was received. Note that this changes each time a payment peripheral reads a card, i.e. for each transaction, even if the payment method is the same. It is used in subsequent SDK requests (e.g. Payment.Settle) to refer to the payment data in a secure way.
 peripheralId
enum PeripheralId:
UnknownPeripheralId: 0TestPaymentDevice: 1SimulatedViaTimeout: 2SimulatedViaFTDI: 3IDTechSpectrumPro: 5IDTechSecureMoir: 6IDTechKioskIII: 7IDTechSecuRED: 8NFC: 9
Denotes which payment hardware received data.
 customerProfile
Object: {  
  // The unique ID of the customer
  id [string]
,
  // The customer’s full name
  full_name [string]
,
  // The customer’s family/last name
  family_name [string]
,
  // The customer’s given/first name
  given_name [string]
,
  // The phone number of the customer
  phone_number [string]
,
  // The zipcode of the customer
  postal_code [string]
}
This field will contain personalized customer information when the following criteria are met: (1) Platform.ListenForInteraction is called with with the IDENTIFY or IDENTIFY_AND_PAYMENT environment. (2) The customer uses a mobile wallet loyalty pass for the transaction.

denotes a required field

Payment.StartedSettling

Response when a settle request is valid and has been sent to the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.Settle request.

Payment.Settled

Response when a successful Settle response returns from the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.Settle request.

ListenForInteractionThenPreAuthorize

This is a convenience request that combines Platform.ListenForInteraction and Payment.PreAuthorize into a single request.

Once a payer interacts with a payment peripheral, they are immediately PreAuthorized for the amount specified in this request.

Payment.ListenForInteractionThenPreAuthorizeArgs

var args = {
  useExistingData: false,
  existingDataTtlSeconds: 5,
  amount: 128,
  currency: "USD",
  transactionMode: "PAYMENT",
};

dotdashpay.payment.listenForInteractionThenPreAuthorize(args)
  .onStartedListeningForInteraction(function(response) {
    console.log("Received onStartedListeningForInteraction response", JSON.stringify(response, null, 2));
    var peripheralId = response.peripheralId; // e.g. "IDTechKioskIII"
  })
  .onStartedInteraction(function(response) {
    console.log("Received onStartedInteraction response", JSON.stringify(response, null, 2));
    var peripheralId = response.peripheralId; // e.g. "IDTechKioskIII"
  })
  .onGotInteraction(function(response) {
    console.log("Received onGotInteraction response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
    var peripheralId = response.peripheralId; // e.g. "IDTechKioskIII"
    var customerProfile = response.customerProfile; // e.g. {'phoneNumber': '5555555555', 'familyName': 'Customer', 'postalCode': '94609', 'givenName': 'Mimir T.', 'fullName': 'Mimir T. Customer', 'id': 'an-id'}
  })
  .onStartedPreAuthorizing(function(response) {
    console.log("Received onStartedPreAuthorizing response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onPreAuthorized(function(response) {
    console.log("Received onPreAuthorized response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onListenForInteractionError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .onPreAuthorizeError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default
 amount
uint32
Amount is the smallest unit of currency for a given currency, e.g. cents in USD. None
 useExistingData
bool
Setting this to true will return data that had been read by a connected peripheral before calling ListenForInteraction, e.g. a card swipe that occurred before a total was known. By default, ListenForInteraction will only return new data through connected peripherals. false
 existingDataTtlSeconds
uint32
When use_existing_data is true, this determines how long a data will be stored for use. Keep the number relatively low so you don’t accidentally use a previous customer’s data. 20
 currency
enum Currency:
UNKNOWN_CURRENCY: 0USD: 1
Currency of amount (only USD currently supported). USD
 transactionMode
enum TransactionMode:
UNKNOWN_TRANSACTION_MODE: 0IDENTIFY: 1PAYMENT: 2IDENTIFY_AND_PAYMENT: 3
The type of transaction to perform PAYMENT

denotes a required field

Responses

Platform.StartedListeningForInteraction

Response when the hardware peripheral is ready to accept an interaction from the customer, i.e. it is listening for an interaction from the customer.

Parameter Description
 peripheralId
enum PeripheralId:
UnknownPeripheralId: 0TestPaymentDevice: 1SimulatedViaTimeout: 2SimulatedViaFTDI: 3IDTechSpectrumPro: 5IDTechSecureMoir: 6IDTechKioskIII: 7IDTechSecuRED: 8NFC: 9
Denotes which payment hardware is receiving data.

denotes a required field

Platform.StartedInteraction

Response when any connected payment peripheral begins receiving payment data (e.g. when a magnetic-stripe reader starts reading data from a magnetic stripe card).

Parameter Description
 peripheralId
enum PeripheralId:
UnknownPeripheralId: 0TestPaymentDevice: 1SimulatedViaTimeout: 2SimulatedViaFTDI: 3IDTechSpectrumPro: 5IDTechSecureMoir: 6IDTechKioskIII: 7IDTechSecuRED: 8NFC: 9
Denotes which payment hardware is receiving data.

denotes a required field

Platform.GotInteraction

Response when any payment peripheral finishes reading payment data.

Platform.GotInteraction.transactionChainId is returned and unique to this payment interaction. You will pass this token to every subsequent payment request (e.g. Payment.PreAuthorize), and you should store it if you want to retrieve/reconcile this transaction with DotDashPay at a later time (using Payment.GetTransaction).

Parameter Description
 transactionChainId
string
A unique identifier that represents the payment data that was received. Note that this changes each time a payment peripheral reads a card, i.e. for each transaction, even if the payment method is the same. It is used in subsequent SDK requests (e.g. Payment.Settle) to refer to the payment data in a secure way.
 peripheralId
enum PeripheralId:
UnknownPeripheralId: 0TestPaymentDevice: 1SimulatedViaTimeout: 2SimulatedViaFTDI: 3IDTechSpectrumPro: 5IDTechSecureMoir: 6IDTechKioskIII: 7IDTechSecuRED: 8NFC: 9
Denotes which payment hardware received data.
 customerProfile
Object: {  
  // The unique ID of the customer
  id [string]
,
  // The customer’s full name
  full_name [string]
,
  // The customer’s family/last name
  family_name [string]
,
  // The customer’s given/first name
  given_name [string]
,
  // The phone number of the customer
  phone_number [string]
,
  // The zipcode of the customer
  postal_code [string]
}
This field will contain personalized customer information when the following criteria are met: (1) Platform.ListenForInteraction is called with with the IDENTIFY or IDENTIFY_AND_PAYMENT environment. (2) The customer uses a mobile wallet loyalty pass for the transaction.

denotes a required field

Payment.StartedPreAuthorizing

Response when a pre-authorization request is valid and has been sent to the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.PreAuthorize request.

Payment.PreAuthorized

Response when a successful pre-authorization response is returned from the payment processor.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.PreAuthorize request.

GetTransaction

Returns information about a previous transaction (composed of a sequence of one or more individual requests). The information is up-to-date as of the time it was requested; it’s possible that it could change if more requests are made against it (e.g. a refund).

Payment.GetTransactionArgs

var args = {
  transactionChainId: "iPqy9F82v5qexbtz",
};

dotdashpay.payment.getTransaction(args)
  .onStartedGettingTransaction(function(response) {
    console.log("Received onStartedGettingTransaction response", JSON.stringify(response, null, 2));
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
  })
  .onGotTransaction(function(response) {
    console.log("Received onGotTransaction response", JSON.stringify(response, null, 2));
    var created = response.created; // e.g. {'seconds': 10000000, 'nanos': 1}
    var transactionChainId = response.transactionChainId; // e.g. "iPqy9F82v5qexbtz"
    var deviceId = response.deviceId; // e.g. "cj8lxcbku3"
    var environment = response.environment; // e.g. "MIDDLEWARE_SIMULATOR"
    var processor = response.processor; // e.g. "MERCURY"
    var merchantAccountId = response.merchantAccountId; // e.g. "17384922341"
    var interaction = response.interaction; // e.g. {'request': {'currency': 'USD', 'amount': 101, 'created': {'seconds': 10000000, 'nanos': 1}}, 'response': {'cardData': {'cardType': 'VISA', 'last4': '5678', 'expirationDate': {'month': 10, 'year': 2016}, 'maskedData': '1234*******5678', 'peripheralId': 'IDTechKioskIII'}, 'customerProfile': {'phoneNumber': '5555555555', 'familyName': 'Customer', 'postalCode': '94609', 'givenName': 'Mimir T.', 'fullName': 'Mimir T. Customer', 'id': 'an-id'}, 'created': {'seconds': 10000000, 'nanos': 1}}}
    var preAuthorize = response.preAuthorize; // e.g. {'request': {'currency': 'USD', 'amount': 101, 'created': {'seconds': 10000000, 'nanos': 1}}, 'response': {'created': {'seconds': 10000000, 'nanos': 1}}}
    var voidPreAuthorize = response.voidPreAuthorize; // e.g. {'request': {'created': {'seconds': 10000000, 'nanos': 1}}, 'response': {'created': {'seconds': 10000000, 'nanos': 1}}}
    var settle = response.settle; // e.g. {'request': {'currency': 'USD', 'amount': 101, 'created': {'seconds': 10000000, 'nanos': 1}}, 'response': {'created': {'seconds': 10000000, 'nanos': 1}}}
    var refund = response.refund; // e.g. {'request': {'created': {'seconds': 10000000, 'nanos': 1}}, 'response': {'created': {'seconds': 10000000, 'nanos': 1}}}
  })
  .onGetTransactionError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
Parameter Description Default
 transactionChainId
string
The transaction being requested. None

denotes a required field

Responses

Payment.StartedGettingTransaction

Response when a request to get a transaction is valid and has been sent to DotDashPay.

Parameter Description
 transactionChainId
string
The ID associated with the Payment.GetTransaction request.

denotes a required field

Payment.GotTransaction

Response contains detailed information about every step of a payment transaction given Platform.GotTransaction.transactionChainId returned from Platform.StartedInteraction.

The data is stored on DotDashPay servers and can be queried at any time.

Given a sequence of transactions for a particular payment, e.g. Platform.ListenForInteraction, Payment.PreAuthorize, Payment.Settle, Payment.Refund, each request uses the same Platform.GotTransaction.transactionChainId, and request/response information for each request is returned (e.g. so you can determine the amount you pre-authorized and the amount you settled).

Parameter Description
 created
Object: {  
  // Number of seconds since UNIX epoch
  seconds [int64]
,
  // Number of additional nanoseconds from seconds for higher time resolution
  nanos [int32]
}
When the response was received.
 transactionChainId
string
The transaction ID that was requested.
 deviceId
string
The device that created the transaction. NOTE: For security reasons, transactions must be queried on the device that created them. Contact us if you need the ability to query transactions from a different device
 environment
enum Environment:
UNKNOWN_ENVIRONMENT: 0PRODUCTION: 1DEVELOPMENT: 2MIDDLEWARE_SIMULATOR: 3PERIPHERAL_SIMULATOR: 4PROCESSOR_SIMULATOR: 5
Environment configured by the SDK.
 processor
enum Processor:
UNKNOWN_PROCESSOR: 0SIMULATOR: 1BRAINTREE: 2MERCURY: 3
Processor the device was configured to use.
 merchantAccountId
string
Processor’s merchant ID associated with transaction.
 interaction
Object: {  
  request: {    
    created: {      
      // Number of seconds since UNIX epoch
      seconds [int64]
,
      // Number of additional nanoseconds from seconds for higher time resolution
      nanos [int32]
    },
    // Total amount expressed in smallest currency unit (e.g. cents for USD)
    amount [uint32]
,
    // The currency used from the set ['USD’]
    currency
  },
  response: {    
    created: {      
      // Number of seconds since UNIX epoch
      seconds [int64]
,
      // Number of additional nanoseconds from seconds for higher time resolution
      nanos [int32]
    },
    card_data: {      
      // A unique identifier that describes the peripheral that processed the interaction from the set ['UnknownPeripheralId’, 'TestPaymentDevice’, 'SimulatedViaTimeout’, 'SimulatedViaFTDI’, 'MagTekSureSwipe21040145’, 'IDTechSpectrumPro’, 'IDTechSecureMoir’, 'IDTechKioskIII’, 'IDTechSecuRED’, 'IDTech4880NFC’]
      peripheral_id
,
      // The type of card from the set ['VISA’, AMERICAN_'EXPRESS’, 'MASTERCARD’, 'DISCOVER’]
      card_type
,
      // The last four digits of the card used in the transaction
      last4 [string]
,
      expiration_date: {        
        // The month the card expires expressed as two numerals
        month [uint32]
,
        // The year the card expires expressed as four numerals
        year [uint32]
      },
      // A masked version of the PAN of the card used in the transaction
      masked_data [string]
    },
    customer_profile: {      
      // The unique ID of the customer
      id [string]
,
      // The customer’s full name
      full_name [string]
,
      // The customer’s family/last name
      family_name [string]
,
      // The customer’s given/first name
      given_name [string]
,
      // The phone number of the customer
      phone_number [string]
,
      // The zipcode of the customer
      postal_code [string]
    }
  }
}
The interaction request and response associated with a Platform.ListenForInteraction request
 preAuthorize
Object: {  
  request: {    
    created: {      
      // Number of seconds since UNIX epoch
      seconds [int64]
,
      // Number of additional nanoseconds from seconds for higher time resolution
      nanos [int32]
    },
    // Total amount expressed in smallest currency unit (e.g. cents for USD)
    amount [uint32]
,
    // The currency used from the set ['USD’]
    currency
  },
  response: {    
    created: {      
      // Number of seconds since UNIX epoch
      seconds [int64]
,
      // Number of additional nanoseconds from seconds for higher time resolution
      nanos [int32]
    }
  }
}
The interaction request and response associated with a Payment.PreAuthorize request
 voidPreAuthorize
Object: {  
  request: {    
    created: {      
      // Number of seconds since UNIX epoch
      seconds [int64]
,
      // Number of additional nanoseconds from seconds for higher time resolution
      nanos [int32]
    }
  },
  response: {    
    created: {      
      // Number of seconds since UNIX epoch
      seconds [int64]
,
      // Number of additional nanoseconds from seconds for higher time resolution
      nanos [int32]
    }
  }
}
The interaction request and response associated with a Payment.VoidPreAuthorize request
 settle
Object: {  
  request: {    
    created: {      
      // Number of seconds since UNIX epoch
      seconds [int64]
,
      // Number of additional nanoseconds from seconds for higher time resolution
      nanos [int32]
    },
    // Total amount expressed in smallest currency unit (e.g. cents for USD)
    amount [uint32]
,
    // The currency used from the set ['USD’]
    currency
  },
  response: {    
    created: {      
      // Number of seconds since UNIX epoch
      seconds [int64]
,
      // Number of additional nanoseconds from seconds for higher time resolution
      nanos [int32]
    }
  }
}
The interaction request and response associated with a Payment.Settle request
 refund
Object: {  
  request: {    
    created: {      
      // Number of seconds since UNIX epoch
      seconds [int64]
,
      // Number of additional nanoseconds from seconds for higher time resolution
      nanos [int32]
    }
  },
  response: {    
    created: {      
      // Number of seconds since UNIX epoch
      seconds [int64]
,
      // Number of additional nanoseconds from seconds for higher time resolution
      nanos [int32]
    }
  }
}
The interaction request and response associated with a Payment.Refund request

denotes a required field

Errors

SdkError

SdkError is a response from any SDK request that does not succeed. It is non-recoverable and always a completion event, i.e. no other responses will ever come after it.

Errors occur in normal operation and may be as innocuous as being unable to read a card (necessitating swiping again), to an internal error in the DotDashPay middleware or a non-responsive payment peripheral.

While some errors may be temporary (e.g. connectivity problems or a card declined for potential fraud,), the SDK will have already made multiple attempts to fulfill your request and will not allow you to retry a request without starting a new transaction (i.e. another card swipe).

Some errors cannot be fixed without automated maintenance or human intervention (e.g. restarting the machine, reconnecting to the internet, updating software, or replacing damaged hardware).

Parameter Description
 code
enum SdkErrorCode:
UNKNOWN_INTERNAL_ERROR: 0PROCESSING_CONNECTION_ERROR: 1000PROCESSING_CONNECTION_TIMEOUT: 1001PROCESSING_NO_PAY_DATA: 1011PROCESSING_UNSUCCESSFUL: 1021PROCESSING_RESPONSE_MALFORMED: 1022PROCESSING_UNSUPPORTED_PERIPH: 1030PROCESSING_UNSUPPORTED: 1100HARDWARE_PERIPH_NOT_SUPPORTED: 2000HARDWARE_PERIPH_NO_CONN: 2101HARDWARE_PERIPH_NO_RESP: 2102HARDWARE_PERIPH_REQUIRES_AMOUNT: 2103HARDWARE_PERIPH_MALFORMED_DATA: 2104HARDWARE_PERIPH_DISCONNECTED: 2105HARDWARE_PERIPH_COMM_ERROR: 2106HARDWARE_VAS_ERROR: 2107COMM_UNABLE_TO_FIND_CORRESPONDING_REQUEST: 3000MISC_UNKNOWN: 9000MISC_UNDETERMINED: 9001MISC_UNIMPLEMENTED: 9002MISC_UNSUPPORTED: 9003MISC_UNREACHABLE: 9004MISC_NO_CREDENTIALS: 9005MISC_BAD_CONFIG: 9006MISC_BAD_INITIALIZATION: 9100MISC_MALFORMED_REQUEST: 9200MISC_MISSING_NEEDED_DATA: 9201
code is used to identify the type of error
 message
string
message is a human-readable description of the error. This should be used for logging and debugging only.
 relatedMessage
string
A human-readable related reason that the error occurred. If specified, it will provide additional information that should be used for logging and debugging only.
 errorId
string
A unique ID for this error: provide this ID to DDP technical support in when submitting an issue

denotes a required field