Controlling the DotDashPay Simulator

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

The DotDashPay API provides a set of functions to control how the simulator responds to your API requests, i.e. you can directly control the response data you receive in your callback functions, cause errors to be thrown, etc. To use the simulator, simply specify the simulate option when initializing the DotDashPay API, i.e:

Language:Node.jsC#iOS
DDPInitializeArgs* args = [[DDPInitializeArgs alloc] init]; args.apiToken = @"INSERT-YOUR-TOKEN"; args.simulate = YES; [DotDashPayAPI.global initialize:args onError:^(DDPError* error) { LOG(ERROR, @"Could not initialize: %@", error); } onInitialized:^(DDPInitialized* response) { // do something special }];
var dotdashpay = require("dotdashpay"); var config = { simulate: true, apiToken: "YOUR-API-TOKEN-HERE" }; // Initialize a connection to ConnectOS. dotdashpay.global.initialize(config) .onInitialized(testSimulatedResponse) .onError(handleError) .execute(); function testSimulatedResponse() { // See example below } function handleError(err) { console.error("Error performing transaction: ", err); process.exit(1); }
var initArgs = new DotDashPay.InitializeArgs { Simulate = true, ApiToken = "your-api-token" }; bool successful = await DotDashPay.Global.Initialize(initArgs);
copy

Changing the data of a simulator response

By default the API ships with a default set of response data for all requests, and you can directly manipulate the simulator by explicitly setting response data at runtime. This manipulation happens via a single function call, e.g:

Language:Node.jsC#iOS
[DDPSimulatorManager setResponse:@"Settled" withResponseData:responseData];
dotdashpay.simulator.setResponse("Settled", {"customerId": "custom-id"});
var settled = new DotDashPay.Settled({CustomerId = "custom-id"}); DotDashPay.Simulator.SetResponse(settled);
copy

The simulator knows how to map incoming requests to the associated set of responses that are detailed in the API Reference Documentation. This means that if you set the response data for the Settled response, anytime you issue an API request with a Settled response, then your "onSettled" callback will automatically be called with the response data you set. Note that any fields that you do not set will remain the default response from the simulator. Here's an example:

Language:Node.jsC#iOS
DDPInitializeArgs* args = [[DDPInitializeArgs alloc] init]; args.apiToken = @"INSERT-YOUR-TOKEN"; args.simulate = YES; [DotDashPayAPI.global initialize:args onError:^(DDPError* error) { LOG(ERROR, @"Could not initialize: %@", error); } onInitialized:^(DDPInitialized* response) { DDPSettled* responseData = [[DDPSettled alloc] init]; responseData.settleId = @"sumo"; [DDPSimulatorManager setResponse:@"Settled" withResponseData:responseData]; DDPReceivePaymentDataThenSettleArgs* requestArgs = [[DDPReceivePaymentDataThenSettleArgs alloc] init]; requestArgs.cents = 128; [DotDashPayAPI.payment receivePaymentDataThenSettle:requestArgs onError:^(DDPError* error) { assert(false); } onSettled:^(DDPSettled* responseData) { assert([responseData.settleId isEqualToString:@"sumo"]); }]; }];
function testSimulatedResponse() { var myCustomerId = "some-custom-id"; dotdashpay.simulator.setResponse("Settled", {customerId: myCustomerId}); dotdashpay.payment.receivePaymentDataThenSettle({cents: 500}) .onSettled(function (resp) { if (resp.customerId !== myCustomerId) { throw new Error("Simulator did not overwrite customerId field"); } else { console.log("Simulator set customerId as expected."); } process.exit(0); }) .execute(); }
var initArgs = new DotDashPay.InitializeArgs { Simulate = true, ApiToken = "your-api-token" }; bool successful = await DotDashPay.Global.Initialize(initArgs); var customSettled = new DotDashPay.Settled{CustomerId = "custom-id"}; DotDashPay.Simulator.SetResponse(customSettled); successful = await DotDashPay.Payment.Settle(new DotDashPay.SettleArgs { Cents=100 }, onSettled: results => { if (customSettled.CustomerId != results.CustomerId) { throw new Exception("Customer Ids were not overridden as expected"); } }, onError: err => { throw new Exception("Received an unexpected error: " + err.ToString()); } );
copy

Simulating Errors

Errors work slightly differently in the simulator since every request can, at any time, return an error. Similar to normal responses, you can specify that the simulator should return an error when a particular response would have otherwise been returned. Here's an example; note that because the StartedReceivingPaymentData response occurs before the Settled response, the "onStartedReceivingPaymentData" callback will be called but the "onSettled" callback will not be called because the "onError" response will occur instead:

Language:Node.jsC#iOS
DDPInitializeArgs* args = [[DDPInitializeArgs alloc] init]; args.apiToken = @"INSERT-YOUR-TOKEN"; args.simulate = YES; [DotDashPayAPI.global initialize:args onError:^(DDPError* error) { LOG(ERROR, @"Could not initialize: %@", error); } onInitialized:^(DDPInitialized* response) { DDPError* errorResponse = [[DDPError alloc] init]; errorResponse.errorCode = DDPErrorCode_PlatformUnhandled; errorResponse.errorMessage = @"Did not receive a response from payment processor"; [DDPSimulatorManager setErrorResponse:errorResponse insteadOfResponse:@"Settled"]; DDPReceivePaymentDataThenSettleArgs* requestArgs = [[DDPReceivePaymentDataThenSettleArgs alloc] init]; requestArgs.cents = 128; [DotDashPayAPI.payment receivePaymentDataThenSettle:requestArgs onError:^(DDPError* error) { assert(true); } onStartedReceivingPaymentData:^(DDPStartedReceivingPaymentData* response) { assert(true); } onReceivedPaymentData:^(DDPReceivedPaymentData* response) { assert(true); } onStartedSettling:^(DDPStartedSettling* response) { assert(true); } onSettled:^(DDPSettled* settled) { assert(false); }]; }];
function testSimulatedResponse() { var returnError = true; var errorValues = { "errorCode": 999, "errorMessage": "a custom error message" }; dotdashpay.simulator.setResponse("Settled", errorValues, returnError); dotdashpay.payment.receivePaymentDataThenSettle({cents: 500}) .onStartedReceivingPaymentData(function (resp) { console.log("onStartedReceivingPaymentData will be called"); }) .onSettled(function (resp) { console.log("onSettled will NOT be called because 'Settled' was specified to be an error."); }) .onError(function (resp) { console.log(JSON.stringify(resp)); // {"errorCode": 999, "errorMessage": "a custom error message"} process.exit(0); }) .execute(); }
var initArgs = new DotDashPay.InitializeArgs { Simulate = true, ApiToken = "your-api-token" }; bool successful = await DotDashPay.Global.Initialize(initArgs); var settled = new DotDashPay.Settled(); var setErr = new DotDashPay.DDPError { ErrorCode = DotDashPay.ErrorCode.HardwareNetworkNoInternetCell, ErrorMessage = "TestMessage" }; DotDashPay.Simulator.SetErrorResponse(settled, setErr); successful = await DotDashPay.Payment.Settle(new DotDashPay.SettleArgs { Cents = 100 }, onSettled: results => { throw new Exception("Should not have received Settled event."); }, onError: err => { if (setErr.ErrorCode != err.ErrorCode || setErr.ErrorMessage != err.ErrorMessage) { throw new Exception("Returned error properties did not match"); } } );
copy

Note: error codes can be found in the ErrorResponse codes section.