Getting Started with DotDashPay

Step 1: Installation

Step 2: Process a Payment

This is your API token. In order to process payments (simulated or real), you must always setup the API to use this token so we can ensure your account receives those payments:

API Token: aac42010c3661a5de244fc4c20305191

Completely processing a payment can be accomplished via a simple pair of API calls:

Language:Node.jsC#iOS
DDPInitializeArgs* args = [[DDPInitializeArgs alloc] init]; args.apiToken = @"@api-token()"; args.simulate = YES; [DotDashPayAPI.global initialize:args onError:^(DDPError* error) { LOG(ERROR, @"Could not initialize: %@", error); } onInitialized:^(DDPInitialized* response) { LOG(INFO, @"DotDashPay API initialized"); DDPReceivePaymentDataThenSettleArgs* args = [[DDPReceivePaymentDataThenSettleArgs alloc] init]; args.cents = 100; [DotDashPayAPI.payment receivePaymentDataThenSettle:args onError:^(DDPError* error) { LOG(ERROR, @"Error while executing receivePaymentDataThenSettle: %@", error.description); } onSettled:^(DDPSettled* response) { LOG(INFO, @"Settlement finished! Transaction id: %@", response.settleId); }]; }];
var dotdashpay = require("dotdashpay"); dotdashpay.global.initialize({ simulate: true, apiToken: "@api-token()" }) .onInitialized(performTransaction) .onError(handleError) .execute(); function performTransaction() { dotdashpay.payment.receivePaymentDataThenSettle({ cents: 100 }) .onSettled(function(response) { console.log("Settlement finished! Settle response data: ", JSON.stringify(response, null, 2)); process.exit(0); }) .onError(handleError) .execute(); } function handleError(err) { console.error("Error performing transaction: ", err); process.exit(1); }
using System; using System.Threading.Tasks; class DotDashPayShortDemo { static void Main(string[] args) { // Use Task.Run() to call async DotDashPay functions Task.Run(async () => { // Initialization var initArgs = new DotDashPay.InitializeArgs { Simulate = true, ApiToken = "@api-token()" }; // All requests return Task<bool>. // Once all responses for the request are received, the Task<bool> // evaluates to false if there was an error and true otherwise. bool successful = await DotDashPay.Global.Initialize(initArgs, onError: err => Console.Error.WriteLine("Error initializing: {0}", err)); if (!successful) return; // Process a payment var payArgs = new DotDashPay.ReceivePaymentDataThenSettleArgs { Cents = 100 }; successful = await DotDashPay.Payment.ReceivePaymentDataThenSettle(payArgs, onSettled: results => Console.WriteLine("Success! Txn Id: {0}", results.SettleId), onError: err => Console.Error.WriteLine("Error settling payment: {0}", err)); }).Wait(); // Keep the console open to see the printed results Console.ReadLine(); } }
copy

Note that you must call the execute command at the end of each API call. This ensures that the callback functions are registered correctly before actually performing the request.

This API call asks the DotDashPay Platform to listen for any type of payment data coming from the attached payment hardware (magstripe readers, NFC modules, etc), and immediately process the payment for $1.00 once it receives the payment data.

Insert the code block above into your source code and run your application. The ReceivePaymentDataThenSettle code block must be inserted in a place that is going to be run by your application (e.g. in an initialization function or a main method). When this code executes, the simulator notifies our server of the transaction so you will be able to see it in in real-time:

Real-Time Transactions
API Connection Status: Not Connected
ID
Transaction Timestamp
Type
Status
Payment Information
Amount
Note: Wherever you are running the code above must be able to access the Internet for real-time transactions to appear.
 

Step 3: Perfect the Payment Experience

Now that you've successfully processed a simulated payment, let's discuss how the DotDashPay API works in more detail so that you can use it to craft the perfect payment experience.

The DotDashPay API is a simple set of requests to the DotDashPay Platform that you can use to create, settle, refund, void, and tokenize payments. Every request has an associated set of responses from the DotDashPay Platform that you handle by specifying function callbacks when you make the request.

There are two fundamental types of responses that are returned when a request is sent: update responses and completion responses. The only difference between these two is that once a completion response is received, there will be no more responses of any kind; they complete the request. In addition, at any point a DDPError may be returned. A DDPError is always a completion response and will contain data fields indicating what happened.

The API documentation lists the requests and responses in detail. To get a feel for how this works, let's add in all of the response handlers to the ReceivePaymentDataThenSettle request that we used in the above example:

The code below handles these responses by simply assigning each field in the response data to a variable. In a real application, you could use these responses and their associated data to communicate something to your customers (e.g. tell them you're processing their payment), trigger a machine function (e.g. warm up your machine's flux capacitor), etc.

Language:Node.jsC#iOS
DDPInitializeArgs* args = [[DDPInitializeArgs alloc] init]; args.apiToken = @"@api-token()"; args.simulate = YES; [DotDashPayAPI.global initialize:args onError:^(DDPError* error) { LOG(ERROR, @"Could not initialize: %@", error); } onInitialized:^(DDPInitialized* response) { DDPReceivePaymentDataThenSettleArgs* args = [[DDPReceivePaymentDataThenSettleArgs alloc] init]; args.cents = 128; args.currency = @"USD"; args.useExistingData = NO; args.useExistingDataSecondsWindow = 5; [DotDashPayAPI.payment receivePaymentDataThenSettle:args onError:^(DDPError* error) { LOG(ERROR, @"%@", error.errorMessage); } onStartedReceivingPaymentData:^(DDPStartedReceivingPaymentData* response) { LOG(INFO, @"@Received onStartedReceivingPaymentData response: %@", response); } onReceivedPaymentData:^(DDPReceivedPaymentData* response) { LOG(INFO, @"@Received onReceivedPaymentData response: %@", response); } onStartedSettling:^(DDPStartedSettling* response) { LOG(INFO, @"@Received onStartedSettling response: %@", response); } onSettled:^(DDPSettled* response) { LOG(INFO, @"@Received onSettled response: %@", response); }]; }];
var dotdashpay = require("dotdashpay"); dotdashpay.global.initialize({ simulate: true, apiToken: "@api-token()" }) .onInitialized(performTransaction) .onError(handleError) .execute(); // Perform a full end-to-end transaction using ConnectOS // and log all possible responses function performTransaction() { console.log("Successfully initialized ConnectOS: now performing a transaction"); dotdashpay.payment.receivePaymentDataThenSettle({ cents: 128 }) .onStartedReceivingPaymentData(printResponse("onStartedReceivingPaymentData")) .onReceivedPaymentData(printResponse("onReceivedPaymentData")) .onStartedSettling(printResponse("onStartedSettling")) .onSettled(printResponse("onSettled", true)) .onError(handleError) .execute(); } // Simple callback helper functions for printing responses function printResponse(cbName, shouldExit) { return function(response) { console.log("Received " + cbName, JSON.stringify(response, null, 2)); if (shouldExit) { process.exit(0); } } } function handleError(err) { console.error("Error performing transaction: ", err); process.exit(1); }
using System; using System.Threading.Tasks; class DotDashPayExpandedDemo { static void Main(string[] args) { // Use Task.Run() to call async DotDashPay functions Task.Run(async () => { // Initialization var initArgs = new DotDashPay.InitializeArgs { Simulate = true, ApiToken = "@api-token()" }; // All requests return Task<bool>. // Once all responses for the request are received, the Task<bool> // evaluates to false if there was an error and true otherwise. bool successful = await DotDashPay.Global.Initialize(initArgs, onError: err => Console.Error.WriteLine("Error initializing: {0}", err)); if (!successful) return; // Process a payment var payArgs = new DotDashPay.ReceivePaymentDataThenSettleArgs { Cents = 128 }; successful = await DotDashPay.Payment.ReceivePaymentDataThenSettle(payArgs, onStartedReceivingPaymentData: results => Console.WriteLine("(1) Received onStartedReceivingPaymentData: {0}", results), onReceivedPaymentData: results => Console.WriteLine("(2) Received onReceivedPaymentData: {0}", results), onStartedSettling: results => Console.WriteLine("(3) Received onStartedSettling: {0}", results), onSettled: results => Console.WriteLine("(4) Received onSettled: {0}", results), onError: err => Console.Error.WriteLine("Error settling payment: {0}", err)); }).Wait(); // Keep the console open to see the printed results Console.ReadLine(); } }
copy

When you execute this code with the simulator, each callback is logged to our server, and you should see each of the following boxes fill in:

It may take a few seconds for the transactions to hit our servers depending on the quality of your connection.

These simple examples have shown you how to process a payment and handle events from the DotDashPay API. The DotDashPay APIs provide a lot more functionality that you can find in the API Documentation or in one of our helpful guides on Controlling the Simulator and Handling Errors.