NAV
iOS (Objective-C) Node.js (Javascript) C#

Payment

PreAuthorize

Payment.PreAuthorizeArgs

DDPPreAuthorizeArgs* args = [[DDPPreAuthorizeArgs alloc] init];
args.paymentDataId = @"pdid-iPqy9F82v5qexbtz";
args.cents = 128;
args.currency = @"USD";

[DotDashPayAPI.payment preAuthorize:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onStartedPreAuthorizing:^(DDPStartedPreAuthorizing* response) {
    LOG(INFO, @"@Received onStartedPreAuthorizing response: %@", response);
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    uint32_t cents = response.cents; // e.g. 128
    NSString* currency = response.currency; // e.g. @"USD"
    BOOL livemode = response.livemode; // e.g. NO
} onPreAuthorized:^(DDPPreAuthorized* response) {
    LOG(INFO, @"@Received onPreAuthorized response: %@", response);
    int32_t status = response.status; // e.g. DDPPaymentStatus_Success
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    NSString* preauthId = response.preauthId; // e.g. @"paut-Eo9YqkOTnmxt6EcL"
    NSString* info = response.info; // e.g. @"Human-readable description"
    NSString* customerId = response.customerId; // e.g. @"2DAuJMBrMyaC"
    NSString* merchantAccountId = response.merchantAccountId; // e.g. @"merchantAccountNumber"
    NSString* cardType = response.cardType; // e.g. @"Visa"
    NSString* last4 = response.last4; // e.g. @"0000"
    NSString* createdAt = response.createdAt; // e.g. @"915148799.75"
    uint32_t cents = response.cents; // e.g. 128
    NSString* currency = response.currency; // e.g. @"USD"
    BOOL livemode = response.livemode; // e.g. NO
    int32_t paymentType = response.paymentType; // e.g. DDPPaymentType_Card
    NSString* rawResponse = response.rawResponse; // e.g. @"Typically json data from processor"
}];
var args = {
  paymentDataId: "pdid-iPqy9F82v5qexbtz",
  cents: 128,
  currency: "USD",
};

args.paymentDataId = dataId;
dotdashpay.payment.preAuthorize(args)
  .onStartedPreAuthorizing(function(response) {
    console.log("Received onStartedPreAuthorizing response", JSON.stringify(response, null, 2));
    var paymentDataId = response.paymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    var cents = response.cents; // 128
    var currency = response.currency; // "USD"
    var livemode = response.livemode; // false
  })
  .onPreAuthorized(function(response) {
    console.log("Received onPreAuthorized response", JSON.stringify(response, null, 2));
    var status = response.status; // e.g. "SUCCESS"
    var paymentDataId = response.paymentDataId; // "pdid-iPqy9F82v5qexbtz"
    var preauthId = response.preauthId; // "paut-Eo9YqkOTnmxt6EcL"
    var info = response.info; // "Human-readable description"
    var customerId = response.customerId; // "2DAuJMBrMyaC"
    var merchantAccountId = response.merchantAccountId; // "merchantAccountNumber"
    var cardType = response.cardType; // "Visa"
    var last4 = response.last4; // "0000"
    var createdAt = response.createdAt; // "915148799.75"
    var cents = response.cents; // 128
    var currency = response.currency; // "USD"
    var livemode = response.livemode; // false
    var paymentType = response.paymentType; // "CARD"
    var rawResponse = response.rawResponse; // "Typically json data from processor"
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.PreAuthorizeArgs{
  PaymentDataId = "pdid-iPqy9F82v5qexbtz",
  Cents = 128,
  Currency = "USD",
};

bool successful = await DotDashPay.Payment.PreAuthorize(reqArgs,
  onStartedPreAuthorizing: response => {
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    uint cents = response.Cents; // e.g. 128
    string currency = response.Currency; // e.g. "USD"
    bool livemode = response.Livemode; // e.g. false
  },
  onPreAuthorized: response => {
    var status = response.Status; // e.g. "SUCCESS"
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    string preauthId = response.PreauthId; // e.g. "paut-Eo9YqkOTnmxt6EcL"
    string info = response.Info; // e.g. "Human-readable description"
    string customerId = response.CustomerId; // e.g. "2DAuJMBrMyaC"
    string merchantAccountId = response.MerchantAccountId; // e.g. "merchantAccountNumber"
    string cardType = response.CardType; // e.g. "Visa"
    string last4 = response.Last4; // e.g. "0000"
    string createdAt = response.CreatedAt; // e.g. "915148799.75"
    uint cents = response.Cents; // e.g. 128
    string currency = response.Currency; // e.g. "USD"
    bool livemode = response.Livemode; // e.g. false
    var paymentType = response.PaymentType; // e.g. "CARD"
    string rawResponse = response.RawResponse; // e.g. "Typically json data from processor"
  },
  onError: err => {
    // Handle errors here
});

Authorize a payment, i.e. verify that the payment_info is accurate and that the desired funds can be withdrawn. A Pre-Auth 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-3 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.

Parameter Description Default
paymentDataIdpaymentDataIdPaymentDataId
string
the id associated with the payment data returned from Hardware.ReceivePaymentData None
centscentsCents
uint32
the number of cents to charge 0
currencycurrencyCurrency
string
currency of the amount to charge (cents field) (only USD currently supported) “USD”

denotes a required field

Payment.StartedPreAuthorizing

Response when the pre authorization starts via the payment processor.

Parameter Description Default
paymentDataIdpaymentDataIdPaymentDataId
string
the id from Hardware.ReceivePaymentData now being used to PreAuthorize the payment None
centscentsCents
uint32
number of cents in the PreAuthorize 0
currencycurrencyCurrency
string
currency of the PreAuthorize (cents field) “USD”
livemodelivemodeLivemode
bool
is false when the request will not actually PreAuthorize funds i.e. it will be a ‘test’ PreAuthorization. livemode is true when funds will be actually PreAuthorized. false

Payment.PreAuthorized

Response when the payment PreAuthorization returns from the payment processor.

Parameter Description Default
statusstatusStatus
enum PaymentStatus:
SUCCESS: 0FAIL: 1UNKNOWN: 2
an enum indicating the status of the PreAuthorize request None
paymentDataIdpaymentDataIdPaymentDataId
string
the id from Hardware.ReceivePaymentData used to get the payment data None
preauthIdpreauthIdPreauthId
string
a unique id associated with the PreAuthorized payment, which can be used to Payment.Settle or Payment.VoidPreAuthorize None
infoinfoInfo
string
a general purpose information string, e.g. if a call to Payment.PreAuthorize was unsuccessful then this field is populated with an explanation None
customerIdcustomerIdCustomerId
string
the unique customer id associated with the payment device, e.g. the customer’s credit card None
merchantAccountIdmerchantAccountIdMerchantAccountId
string
the id of the merchant account used to process the payment None
cardTypecardTypeCardType
string
the type of card used (if applicable/available), e.g. “Visa” None
last4last4Last4
string
the last four digits of the card used (if applicable/available) None
createdAtcreatedAtCreatedAt
string
indicates the time the PreAuthorization was created None
centscentsCents
uint32
number of cents PreAuthorized 0
currencycurrencyCurrency
string
currency of the transaction amount (cents field) “USD”
livemodelivemodeLivemode
bool
false when the request did not actually PreAuthorize funds with the customer’s bank, i.e. it was a 'test’ PreAuthorization. true when funds were actually PreAuthorized false
paymentTypepaymentTypePaymentType
enum PaymentType:
CARD: 0APPLEPAY: 1ANDROIDPAY: 2BITCOIN: 3THIRDPARTY: 4
specifies the type of payment object used to PreAuthorize the payment, i.e. a credit/debit card, apple pay, android pay, bitcoin, or a third party app/service CARD
rawResponserawResponseRawResponse
string
the raw response from the payment processor (typically used for debugging) None

Settle

Payment.SettleArgs

DDPSettleArgs* args = [[DDPSettleArgs alloc] init];
args.paymentDataId = @"pdid-iPqy9F82v5qexbtz";
args.preauthId = @"paut-Eo9YqkOTnmxt6EcL";
args.cents = 128;
args.currency = @"USD";

[DotDashPayAPI.payment settle:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onStartedSettling:^(DDPStartedSettling* response) {
    LOG(INFO, @"@Received onStartedSettling response: %@", response);
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    NSString* preauthId = response.preauthId; // e.g. @"paut-Eo9YqkOTnmxt6EcL"
    uint32_t cents = response.cents; // e.g. 128
    NSString* currency = response.currency; // e.g. @"USD"
    BOOL livemode = response.livemode; // e.g. NO
} onSettled:^(DDPSettled* response) {
    LOG(INFO, @"@Received onSettled response: %@", response);
    int32_t status = response.status; // e.g. DDPPaymentStatus_Success
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    NSString* preauthId = response.preauthId; // e.g. @"paut-Eo9YqkOTnmxt6EcL"
    NSString* settleId = response.settleId; // e.g. @"txn-NG9jR86SC3hjzQHA8h5X3pwz"
    NSString* info = response.info; // e.g. @"Human-readable description"
    NSString* customerId = response.customerId; // e.g. @"2DAuJMBrMyaC"
    NSString* merchantAccountId = response.merchantAccountId; // e.g. @"merchantAccountNumber"
    NSString* cardType = response.cardType; // e.g. @"Visa"
    NSString* last4 = response.last4; // e.g. @"0000"
    NSString* createdAt = response.createdAt; // e.g. @"915148799.75"
    uint32_t cents = response.cents; // e.g. 128
    NSString* currency = response.currency; // e.g. @"USD"
    BOOL livemode = response.livemode; // e.g. NO
    int32_t paymentType = response.paymentType; // e.g. DDPPaymentType_Card
    NSString* rawResponse = response.rawResponse; // e.g. @"Typically json data from processor"
}];
var args = {
  paymentDataId: "pdid-iPqy9F82v5qexbtz",
  preauthId: "paut-Eo9YqkOTnmxt6EcL",
  cents: 128,
  currency: "USD",
};

args.paymentDataId = dataId;
dotdashpay.payment.settle(args)
  .onStartedSettling(function(response) {
    console.log("Received onStartedSettling response", JSON.stringify(response, null, 2));
    var paymentDataId = response.paymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    var preauthId = response.preauthId; // "paut-Eo9YqkOTnmxt6EcL"
    var cents = response.cents; // 128
    var currency = response.currency; // "USD"
    var livemode = response.livemode; // false
  })
  .onSettled(function(response) {
    console.log("Received onSettled response", JSON.stringify(response, null, 2));
    var status = response.status; // e.g. "SUCCESS"
    var paymentDataId = response.paymentDataId; // "pdid-iPqy9F82v5qexbtz"
    var preauthId = response.preauthId; // "paut-Eo9YqkOTnmxt6EcL"
    var settleId = response.settleId; // "txn-NG9jR86SC3hjzQHA8h5X3pwz"
    var info = response.info; // "Human-readable description"
    var customerId = response.customerId; // "2DAuJMBrMyaC"
    var merchantAccountId = response.merchantAccountId; // "merchantAccountNumber"
    var cardType = response.cardType; // "Visa"
    var last4 = response.last4; // "0000"
    var createdAt = response.createdAt; // "915148799.75"
    var cents = response.cents; // 128
    var currency = response.currency; // "USD"
    var livemode = response.livemode; // false
    var paymentType = response.paymentType; // "CARD"
    var rawResponse = response.rawResponse; // "Typically json data from processor"
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.SettleArgs{
  PaymentDataId = "pdid-iPqy9F82v5qexbtz",
  PreauthId = "paut-Eo9YqkOTnmxt6EcL",
  Cents = 128,
  Currency = "USD",
};

bool successful = await DotDashPay.Payment.Settle(reqArgs,
  onStartedSettling: response => {
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    string preauthId = response.PreauthId; // e.g. "paut-Eo9YqkOTnmxt6EcL"
    uint cents = response.Cents; // e.g. 128
    string currency = response.Currency; // e.g. "USD"
    bool livemode = response.Livemode; // e.g. false
  },
  onSettled: response => {
    var status = response.Status; // e.g. "SUCCESS"
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    string preauthId = response.PreauthId; // e.g. "paut-Eo9YqkOTnmxt6EcL"
    string settleId = response.SettleId; // e.g. "txn-NG9jR86SC3hjzQHA8h5X3pwz"
    string info = response.Info; // e.g. "Human-readable description"
    string customerId = response.CustomerId; // e.g. "2DAuJMBrMyaC"
    string merchantAccountId = response.MerchantAccountId; // e.g. "merchantAccountNumber"
    string cardType = response.CardType; // e.g. "Visa"
    string last4 = response.Last4; // e.g. "0000"
    string createdAt = response.CreatedAt; // e.g. "915148799.75"
    uint cents = response.Cents; // e.g. 128
    string currency = response.Currency; // e.g. "USD"
    bool livemode = response.Livemode; // e.g. false
    var paymentType = response.PaymentType; // e.g. "CARD"
    string rawResponse = response.RawResponse; // e.g. "Typically json data from processor"
  },
  onError: err => {
    // Handle errors here
});

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 either after receiving data from calling Hardware.ReceivePaymentData or after receiving data from calling Payment.PreAuthorize.

If called directly after receiving payment data from the hardware, 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 options (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 later on; it must be refunded.

Parameter Description Default
centscentsCents
uint32
the settle amount, i.e. number of cents to settle for. If directly calling this request after Hardware.ReceivePaymentData, then this field is required and can be for any amount. If calling this request after Payment.PreAuthorize, then this field is optional, as it defaults to the PreAuthorized amount, and if included, must be less than or equal to the PreAuthorized amount. 0
paymentDataIdpaymentDataIdPaymentDataId
string
the id from Hardware.ReceivePaymentData if you are settling a payment directly from data read via a payment peripheral None
preauthIdpreauthIdPreauthId
string
the id from Payment.PreAuthorize if you are settling a payment from a pre-authorization None
currencycurrencyCurrency
string
currency of the amount to settle (the cents field) (only USD currently supported) “USD”

denotes a required field

Payment.StartedSettling

Response when the settle payment initially starts settling the payment with the processor.

Parameter Description Default
paymentDataIdpaymentDataIdPaymentDataId
string
the id from Hardware.ReceivePaymentData if you are settling a payment directly from data read via a payment peripheral None
preauthIdpreauthIdPreauthId
string
the id from Payment.PreAuthorize if you are settling a payment from a pre-authorization None
centscentsCents
uint32
number of cents in the settlement 0
currencycurrencyCurrency
string
currency of the settlement (cents field) “USD”
livemodelivemodeLivemode
bool
false when the request will not actually transfer funds between accounts (settle the payment), i.e. it will be a 'test’ settlement. true when funds will be actually settled. false

Payment.Settled

Response when the Payment.Settle payment request returns from the payment processor.

Parameter Description Default
statusstatusStatus
enum PaymentStatus:
SUCCESS: 0FAIL: 1UNKNOWN: 2
an enum indicating the status of the Settle None
paymentDataIdpaymentDataIdPaymentDataId
string
the id from Hardware.ReceivePaymentData if you are settling a payment directly from data read via a payment peripheral None
preauthIdpreauthIdPreauthId
string
the id from Payment.PreAuthorize if you are settling a payment from a pre-authorization None
settleIdsettleIdSettleId
string
the unique id of the settled payment (you can use this id to Payment.Refund the settled payment later) None
infoinfoInfo
string
a general purpose information string, e.g. if a call to Payment.Settle was unsuccessful, this field is populated with an explanation for why it was unsuccessful, None
customerIdcustomerIdCustomerId
string
the unique customer id associated with the payment device, e.g. the customer’s credit card None
merchantAccountIdmerchantAccountIdMerchantAccountId
string
the id of the merchant account used to settle the payment None
cardTypecardTypeCardType
string
the type of card used (if applicable/available), e.g. “Visa” None
last4last4Last4
string
the last four digits of the card used (if applicable/available) None
createdAtcreatedAtCreatedAt
string
indicates the time the settlement was created None
centscentsCents
uint32
number of cents in the settlement 0
currencycurrencyCurrency
string
currency of the settlement (cents field) “USD”
livemodelivemodeLivemode
bool
false when the request did not actually transfer funds between accounts (settle the payment), i.e. it was a 'test’ settlement. true when funds were really settled. false
paymentTypepaymentTypePaymentType
enum PaymentType:
CARD: 0APPLEPAY: 1ANDROIDPAY: 2BITCOIN: 3THIRDPARTY: 4
specifies the type of payment object used to complete the payment, i.e. a credit/debit card, apple pay, android pay, bitcoin, or a third party app or service CARD
rawResponserawResponseRawResponse
string
the raw response from the payment processor (typically used for debugging) None

VoidPreAuthorize

Payment.VoidPreAuthorizeArgs

DDPVoidPreAuthorizeArgs* args = [[DDPVoidPreAuthorizeArgs alloc] init];
args.preauthId = @"paut-Eo9YqkOTnmxt6EcL";

[DotDashPayAPI.payment voidPreAuthorize:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onVoidedPreAuthorize:^(DDPVoidedPreAuthorize* response) {
    LOG(INFO, @"@Received onVoidedPreAuthorize response: %@", response);
    int32_t status = response.status; // e.g. DDPPaymentStatus_Success
    NSString* voidId = response.voidId; // e.g. @"void-QTKL0uLZuO1gFaFm"
    NSString* info = response.info; // e.g. @"Human-readable description"
    NSString* preauthId = response.preauthId; // e.g. @"paut-Eo9YqkOTnmxt6EcL"
    NSString* customerId = response.customerId; // e.g. @"2DAuJMBrMyaC"
    NSString* merchantAccountId = response.merchantAccountId; // e.g. @"merchantAccountNumber"
    NSString* cardType = response.cardType; // e.g. @"Visa"
    NSString* last4 = response.last4; // e.g. @"0000"
    NSString* createdAt = response.createdAt; // e.g. @"915148799.75"
    uint32_t cents = response.cents; // e.g. 128
    NSString* currency = response.currency; // e.g. @"USD"
    BOOL livemode = response.livemode; // e.g. NO
    int32_t paymentType = response.paymentType; // e.g. DDPPaymentType_Card
    NSString* rawResponse = response.rawResponse; // e.g. @"Typically json data from processor"
}];
var args = {
  preauthId: "paut-Eo9YqkOTnmxt6EcL",
};

dotdashpay.payment.voidPreAuthorize(args)
  .onVoidedPreAuthorize(function(response) {
    console.log("Received onVoidedPreAuthorize response", JSON.stringify(response, null, 2));
    var status = response.status; // e.g. "SUCCESS"
    var voidId = response.voidId; // "void-QTKL0uLZuO1gFaFm"
    var info = response.info; // "Human-readable description"
    var preauthId = response.preauthId; // "paut-Eo9YqkOTnmxt6EcL"
    var customerId = response.customerId; // "2DAuJMBrMyaC"
    var merchantAccountId = response.merchantAccountId; // "merchantAccountNumber"
    var cardType = response.cardType; // "Visa"
    var last4 = response.last4; // "0000"
    var createdAt = response.createdAt; // "915148799.75"
    var cents = response.cents; // 128
    var currency = response.currency; // "USD"
    var livemode = response.livemode; // false
    var paymentType = response.paymentType; // "CARD"
    var rawResponse = response.rawResponse; // "Typically json data from processor"
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.VoidPreAuthorizeArgs{
  PreauthId = "paut-Eo9YqkOTnmxt6EcL",
};

bool successful = await DotDashPay.Payment.VoidPreAuthorize(reqArgs,
  onVoidedPreAuthorize: response => {
    var status = response.Status; // e.g. "SUCCESS"
    string voidId = response.VoidId; // e.g. "void-QTKL0uLZuO1gFaFm"
    string info = response.Info; // e.g. "Human-readable description"
    string preauthId = response.PreauthId; // e.g. "paut-Eo9YqkOTnmxt6EcL"
    string customerId = response.CustomerId; // e.g. "2DAuJMBrMyaC"
    string merchantAccountId = response.MerchantAccountId; // e.g. "merchantAccountNumber"
    string cardType = response.CardType; // e.g. "Visa"
    string last4 = response.Last4; // e.g. "0000"
    string createdAt = response.CreatedAt; // e.g. "915148799.75"
    uint cents = response.Cents; // e.g. 128
    string currency = response.Currency; // e.g. "USD"
    bool livemode = response.Livemode; // e.g. false
    var paymentType = response.PaymentType; // e.g. "CARD"
    string rawResponse = response.RawResponse; // e.g. "Typically json data from processor"
  },
  onError: err => {
    // Handle errors here
});

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 should not use this function for if the payment was already settled. If it was settled, you should call Payment.Refund instead.

Parameter Description Default
preauthIdpreauthIdPreauthId
string
the id returned from the payment processor after Payment.PreAuthorize None

denotes a required field

Payment.VoidedPreAuthorize

Response when a void preauthorization response is returned from the payment processor.

Parameter Description Default
statusstatusStatus
enum PaymentStatus:
SUCCESS: 0FAIL: 1UNKNOWN: 2
an enum indicating the status of the void request None
voidIdvoidIdVoidId
string
a unique id that can be used to identify the void None
infoinfoInfo
string
an optional string given by the payment processor that provides additional information about the void None
preauthIdpreauthIdPreauthId
string
the id from Payment.PreAuthorize that was voided by this request None
customerIdcustomerIdCustomerId
string
the unique customer id associated with the payment device, e.g. the customer’s credit card None
merchantAccountIdmerchantAccountIdMerchantAccountId
string
the id of the merchant account used to Void the PreAuthorization None
cardTypecardTypeCardType
string
the type of card used in the PreAuthorize (if applicable/available), e.g. “Visa” None
last4last4Last4
string
the last four digits of the card used (if applicable/available) None
createdAtcreatedAtCreatedAt
string
indicates the time the Void PreAuthorize was created None
centscentsCents
uint32
number of cents voided in the PreAuthorize 0
currencycurrencyCurrency
string
currency of the PreAuthorize amount (cents field) “USD”
livemodelivemodeLivemode
bool
false when the void did not void a real PreAuthorize i.e. it was a 'test’ void. true when a PreAuthorize was actually voided. false
paymentTypepaymentTypePaymentType
enum PaymentType:
CARD: 0APPLEPAY: 1ANDROIDPAY: 2BITCOIN: 3THIRDPARTY: 4
specifies the type of payment object used to PreAuthorize the payment, i.e. a credit/debit card, apple pay, android pay, bitcoin, or a third party app/service CARD
rawResponserawResponseRawResponse
string
the raw response from the payment processor (typically used for debugging) None

Refund

Payment.RefundArgs

DDPRefundArgs* args = [[DDPRefundArgs alloc] init];
args.settleId = @"txn-NG9jR86SC3hjzQHA8h5X3pwz";

[DotDashPayAPI.payment refund:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onRefunded:^(DDPRefunded* response) {
    LOG(INFO, @"@Received onRefunded response: %@", response);
    int32_t status = response.status; // e.g. DDPPaymentStatus_Success
    NSString* refundId = response.refundId; // e.g. @"rfnd-PFuJxu7hpWKcMsgs"
    NSString* info = response.info; // e.g. @"Human-readable description"
    NSString* settleId = response.settleId; // e.g. @"txn-NG9jR86SC3hjzQHA8h5X3pwz"
    NSString* customerId = response.customerId; // e.g. @"2DAuJMBrMyaC"
    NSString* merchantAccountId = response.merchantAccountId; // e.g. @"merchantAccountNumber"
    NSString* cardType = response.cardType; // e.g. @"Visa"
    NSString* last4 = response.last4; // e.g. @"0000"
    NSString* createdAt = response.createdAt; // e.g. @"915148799.75"
    uint32_t cents = response.cents; // e.g. 128
    NSString* currency = response.currency; // e.g. @"USD"
    BOOL livemode = response.livemode; // e.g. NO
    int32_t paymentType = response.paymentType; // e.g. DDPPaymentType_Card
    NSString* rawResponse = response.rawResponse; // e.g. @"Typically json data from processor"
}];
var args = {
  settleId: "txn-NG9jR86SC3hjzQHA8h5X3pwz",
};

dotdashpay.payment.refund(args)
  .onRefunded(function(response) {
    console.log("Received onRefunded response", JSON.stringify(response, null, 2));
    var status = response.status; // e.g. "SUCCESS"
    var refundId = response.refundId; // "rfnd-PFuJxu7hpWKcMsgs"
    var info = response.info; // "Human-readable description"
    var settleId = response.settleId; // "txn-NG9jR86SC3hjzQHA8h5X3pwz"
    var customerId = response.customerId; // "2DAuJMBrMyaC"
    var merchantAccountId = response.merchantAccountId; // "merchantAccountNumber"
    var cardType = response.cardType; // "Visa"
    var last4 = response.last4; // "0000"
    var createdAt = response.createdAt; // "915148799.75"
    var cents = response.cents; // 128
    var currency = response.currency; // "USD"
    var livemode = response.livemode; // false
    var paymentType = response.paymentType; // "CARD"
    var rawResponse = response.rawResponse; // "Typically json data from processor"
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.RefundArgs{
  SettleId = "txn-NG9jR86SC3hjzQHA8h5X3pwz",
};

bool successful = await DotDashPay.Payment.Refund(reqArgs,
  onRefunded: response => {
    var status = response.Status; // e.g. "SUCCESS"
    string refundId = response.RefundId; // e.g. "rfnd-PFuJxu7hpWKcMsgs"
    string info = response.Info; // e.g. "Human-readable description"
    string settleId = response.SettleId; // e.g. "txn-NG9jR86SC3hjzQHA8h5X3pwz"
    string customerId = response.CustomerId; // e.g. "2DAuJMBrMyaC"
    string merchantAccountId = response.MerchantAccountId; // e.g. "merchantAccountNumber"
    string cardType = response.CardType; // e.g. "Visa"
    string last4 = response.Last4; // e.g. "0000"
    string createdAt = response.CreatedAt; // e.g. "915148799.75"
    uint cents = response.Cents; // e.g. 128
    string currency = response.Currency; // e.g. "USD"
    bool livemode = response.Livemode; // e.g. false
    var paymentType = response.PaymentType; // e.g. "CARD"
    string rawResponse = response.RawResponse; // e.g. "Typically json data from processor"
  },
  onError: err => {
    // Handle errors here
});

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

Parameter Description Default
settleIdsettleIdSettleId
string
the id returned from the payment processor after * Payment.Settle None

denotes a required field

Payment.Refunded

Response when the payment refund returns from the payment processor.

Parameter Description Default
statusstatusStatus
enum PaymentStatus:
SUCCESS: 0FAIL: 1UNKNOWN: 2
an enum indicating the status of the refund None
refundIdrefundIdRefundId
string
a unique id that can be used to identify the refund None
infoinfoInfo
string
an optional string given by the payment processor that provides additional information about the void None
settleIdsettleIdSettleId
string
the id returned from the payment processor after Payment.Settle None
customerIdcustomerIdCustomerId
string
the unique customer id associated with the payment device, e.g. the customer’s credit card None
merchantAccountIdmerchantAccountIdMerchantAccountId
string
the id of the merchant account used to refund the payment None
cardTypecardTypeCardType
string
the type of card used in the associated settle (if applicable/available), e.g. “Visa” None
last4last4Last4
string
the last four digits of the card used (if applicable/available) None
createdAtcreatedAtCreatedAt
string
indicates the time the Refund was created None
centscentsCents
uint32
number of cents in the refunded from the associated Settle 0
currencycurrencyCurrency
string
currency of the Settle amount (cents field) “USD”
livemodelivemodeLivemode
bool
false when the void did not refund a transaction i.e. it was a 'test’ refund. true when a transaction was actually refunded. false
paymentTypepaymentTypePaymentType
enum PaymentType:
CARD: 0APPLEPAY: 1ANDROIDPAY: 2BITCOIN: 3THIRDPARTY: 4
specifies the type of payment object used to Settle the payment, i.e. a credit/debit card, apple pay, android pay, bitcoin, or a third party app/service CARD
rawResponserawResponseRawResponse
string
the raw response from the payment processor (typically used for debugging) None

ReceivePaymentDataThenSettle

Payment.ReceivePaymentDataThenSettleArgs

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);
    NSString* peripheralName = response.peripheralName; // e.g. @"MagTekSureSwipe21040145"
} onReceivedPaymentData:^(DDPReceivedPaymentData* response) {
    LOG(INFO, @"@Received onReceivedPaymentData response: %@", response);
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    NSString* token = response.token; // e.g. @"aeac1bc8f0735e4283305652ab"
    NSString* peripheralName = response.peripheralName; // e.g. @"MagTekSureSwipe21040145"
} onStartedSettling:^(DDPStartedSettling* response) {
    LOG(INFO, @"@Received onStartedSettling response: %@", response);
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    NSString* preauthId = response.preauthId; // e.g. @"paut-Eo9YqkOTnmxt6EcL"
    uint32_t cents = response.cents; // e.g. 128
    NSString* currency = response.currency; // e.g. @"USD"
    BOOL livemode = response.livemode; // e.g. NO
} onSettled:^(DDPSettled* response) {
    LOG(INFO, @"@Received onSettled response: %@", response);
    int32_t status = response.status; // e.g. DDPPaymentStatus_Success
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    NSString* preauthId = response.preauthId; // e.g. @"paut-Eo9YqkOTnmxt6EcL"
    NSString* settleId = response.settleId; // e.g. @"txn-NG9jR86SC3hjzQHA8h5X3pwz"
    NSString* info = response.info; // e.g. @"Human-readable description"
    NSString* customerId = response.customerId; // e.g. @"2DAuJMBrMyaC"
    NSString* merchantAccountId = response.merchantAccountId; // e.g. @"merchantAccountNumber"
    NSString* cardType = response.cardType; // e.g. @"Visa"
    NSString* last4 = response.last4; // e.g. @"0000"
    NSString* createdAt = response.createdAt; // e.g. @"915148799.75"
    uint32_t cents = response.cents; // e.g. 128
    NSString* currency = response.currency; // e.g. @"USD"
    BOOL livemode = response.livemode; // e.g. NO
    int32_t paymentType = response.paymentType; // e.g. DDPPaymentType_Card
    NSString* rawResponse = response.rawResponse; // e.g. @"Typically json data from processor"
}];
var args = {
  cents: 128,
  currency: "USD",
  useExistingData: false,
  useExistingDataSecondsWindow: 5,
};

dotdashpay.payment.receivePaymentDataThenSettle(args)
  .onStartedReceivingPaymentData(function(response) {
    console.log("Received onStartedReceivingPaymentData response", JSON.stringify(response, null, 2));
    var peripheralName = response.peripheralName; // e.g. "MagTekSureSwipe21040145"
  })
  .onReceivedPaymentData(function(response) {
    console.log("Received onReceivedPaymentData response", JSON.stringify(response, null, 2));
    var paymentDataId = response.paymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    var token = response.token; // "aeac1bc8f0735e4283305652ab"
    var peripheralName = response.peripheralName; // "MagTekSureSwipe21040145"
  })
  .onStartedSettling(function(response) {
    console.log("Received onStartedSettling response", JSON.stringify(response, null, 2));
    var paymentDataId = response.paymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    var preauthId = response.preauthId; // "paut-Eo9YqkOTnmxt6EcL"
    var cents = response.cents; // 128
    var currency = response.currency; // "USD"
    var livemode = response.livemode; // false
  })
  .onSettled(function(response) {
    console.log("Received onSettled response", JSON.stringify(response, null, 2));
    var status = response.status; // e.g. "SUCCESS"
    var paymentDataId = response.paymentDataId; // "pdid-iPqy9F82v5qexbtz"
    var preauthId = response.preauthId; // "paut-Eo9YqkOTnmxt6EcL"
    var settleId = response.settleId; // "txn-NG9jR86SC3hjzQHA8h5X3pwz"
    var info = response.info; // "Human-readable description"
    var customerId = response.customerId; // "2DAuJMBrMyaC"
    var merchantAccountId = response.merchantAccountId; // "merchantAccountNumber"
    var cardType = response.cardType; // "Visa"
    var last4 = response.last4; // "0000"
    var createdAt = response.createdAt; // "915148799.75"
    var cents = response.cents; // 128
    var currency = response.currency; // "USD"
    var livemode = response.livemode; // false
    var paymentType = response.paymentType; // "CARD"
    var rawResponse = response.rawResponse; // "Typically json data from processor"
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.ReceivePaymentDataThenSettleArgs{
  Cents = 128,
  Currency = "USD",
  UseExistingData = false,
  UseExistingDataSecondsWindow = 5,
};

bool successful = await DotDashPay.Payment.ReceivePaymentDataThenSettle(reqArgs,
  onStartedReceivingPaymentData: response => {
    string peripheralName = response.PeripheralName; // e.g. "MagTekSureSwipe21040145"
  },
  onReceivedPaymentData: response => {
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    string token = response.Token; // e.g. "aeac1bc8f0735e4283305652ab"
    string peripheralName = response.PeripheralName; // e.g. "MagTekSureSwipe21040145"
  },
  onStartedSettling: response => {
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    string preauthId = response.PreauthId; // e.g. "paut-Eo9YqkOTnmxt6EcL"
    uint cents = response.Cents; // e.g. 128
    string currency = response.Currency; // e.g. "USD"
    bool livemode = response.Livemode; // e.g. false
  },
  onSettled: response => {
    var status = response.Status; // e.g. "SUCCESS"
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    string preauthId = response.PreauthId; // e.g. "paut-Eo9YqkOTnmxt6EcL"
    string settleId = response.SettleId; // e.g. "txn-NG9jR86SC3hjzQHA8h5X3pwz"
    string info = response.Info; // e.g. "Human-readable description"
    string customerId = response.CustomerId; // e.g. "2DAuJMBrMyaC"
    string merchantAccountId = response.MerchantAccountId; // e.g. "merchantAccountNumber"
    string cardType = response.CardType; // e.g. "Visa"
    string last4 = response.Last4; // e.g. "0000"
    string createdAt = response.CreatedAt; // e.g. "915148799.75"
    uint cents = response.Cents; // e.g. 128
    string currency = response.Currency; // e.g. "USD"
    bool livemode = response.Livemode; // e.g. false
    var paymentType = response.PaymentType; // e.g. "CARD"
    string rawResponse = response.RawResponse; // e.g. "Typically json data from processor"
  },
  onError: err => {
    // Handle errors here
});

This is a convenience request that combines Hardware.ReceivePaymentData 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. Generally, this is quicker than calling Hardware.ReceivePaymentData followed by Payment.Settle yourself.

Parameter Description Default
centscentsCents
uint32
number of cents to settle in the transaction 0
currencycurrencyCurrency
string
currency of the settle amount (the cents field) (only USD currently supported) “USD”
useExistingDatauseExistingDataUseExistingData
bool
true when we want to use data that has recently gone through payment peripherals, e.g. a card swipe that occured shortly before this request; if it is false, it will only return new data through the hardware peripherals. false
useExistingDataSecondsWindowuseExistingDataSecondsWindowUseExistingDataSecondsWindow
uint32
when use_existing_data is true, this determines how recently we should use existing data going through the payments peripherals. 20

denotes a required field

Hardware.StartedReceivingPaymentData

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

Parameter Description Default
peripheralNameperipheralNamePeripheralName
string
denotes which payment hardware started to receive data. The possible values are the same as those returned by Hardware.GetConnectedPeripherals. None

Hardware.ReceivedPaymentData

Response when any payment peripheral finishes reading payment data from a magnetic stripe card.

Parameter Description Default
paymentDataIdpaymentDataIdPaymentDataId
string
a unique per-transaction id that represents the payment data that was received. Note that this changes for each transaction even if the payment method is the exact same. It can be used in other API requests to easily refer to payment data in a secure way (e.g. Payment.Settle) None
tokentokenToken
string
a unique and secure token that can be used to identify the payment method that was used. E.g. for magnetic stripe cards, this can be used as a proxy representation of a credit card PAN. None
peripheralNameperipheralNamePeripheralName
string
denotes which payment hardware received data. The possible values are the same as those returned by Hardware.GetConnectedPeripherals. None

Payment.StartedSettling

Response when the settle payment initially starts settling the payment with the processor.

Parameter Description Default
paymentDataIdpaymentDataIdPaymentDataId
string
the id from Hardware.ReceivePaymentData if you are settling a payment directly from data read via a payment peripheral None
preauthIdpreauthIdPreauthId
string
the id from Payment.PreAuthorize if you are settling a payment from a pre-authorization None
centscentsCents
uint32
number of cents in the settlement 0
currencycurrencyCurrency
string
currency of the settlement (cents field) “USD”
livemodelivemodeLivemode
bool
false when the request will not actually transfer funds between accounts (settle the payment), i.e. it will be a 'test’ settlement. true when funds will be actually settled. false

Payment.Settled

Response when the Payment.Settle payment request returns from the payment processor.

Parameter Description Default
statusstatusStatus
enum PaymentStatus:
SUCCESS: 0FAIL: 1UNKNOWN: 2
an enum indicating the status of the Settle None
paymentDataIdpaymentDataIdPaymentDataId
string
the id from Hardware.ReceivePaymentData if you are settling a payment directly from data read via a payment peripheral None
preauthIdpreauthIdPreauthId
string
the id from Payment.PreAuthorize if you are settling a payment from a pre-authorization None
settleIdsettleIdSettleId
string
the unique id of the settled payment (you can use this id to Payment.Refund the settled payment later) None
infoinfoInfo
string
a general purpose information string, e.g. if a call to Payment.Settle was unsuccessful, this field is populated with an explanation for why it was unsuccessful, None
customerIdcustomerIdCustomerId
string
the unique customer id associated with the payment device, e.g. the customer’s credit card None
merchantAccountIdmerchantAccountIdMerchantAccountId
string
the id of the merchant account used to settle the payment None
cardTypecardTypeCardType
string
the type of card used (if applicable/available), e.g. “Visa” None
last4last4Last4
string
the last four digits of the card used (if applicable/available) None
createdAtcreatedAtCreatedAt
string
indicates the time the settlement was created None
centscentsCents
uint32
number of cents in the settlement 0
currencycurrencyCurrency
string
currency of the settlement (cents field) “USD”
livemodelivemodeLivemode
bool
false when the request did not actually transfer funds between accounts (settle the payment), i.e. it was a 'test’ settlement. true when funds were really settled. false
paymentTypepaymentTypePaymentType
enum PaymentType:
CARD: 0APPLEPAY: 1ANDROIDPAY: 2BITCOIN: 3THIRDPARTY: 4
specifies the type of payment object used to complete the payment, i.e. a credit/debit card, apple pay, android pay, bitcoin, or a third party app or service CARD
rawResponserawResponseRawResponse
string
the raw response from the payment processor (typically used for debugging) None

ReceivePaymentDataThenPreAuthorize

Payment.ReceivePaymentDataThenPreAuthorizeArgs

DDPReceivePaymentDataThenPreAuthorizeArgs* args = [[DDPReceivePaymentDataThenPreAuthorizeArgs alloc] init];
args.cents = 128;
args.currency = @"USD";
args.useExistingData = NO;
args.useExistingDataSecondsWindow = 5;

[DotDashPayAPI.payment receivePaymentDataThenPreAuthorize:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onStartedReceivingPaymentData:^(DDPStartedReceivingPaymentData* response) {
    LOG(INFO, @"@Received onStartedReceivingPaymentData response: %@", response);
    NSString* peripheralName = response.peripheralName; // e.g. @"MagTekSureSwipe21040145"
} onReceivedPaymentData:^(DDPReceivedPaymentData* response) {
    LOG(INFO, @"@Received onReceivedPaymentData response: %@", response);
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    NSString* token = response.token; // e.g. @"aeac1bc8f0735e4283305652ab"
    NSString* peripheralName = response.peripheralName; // e.g. @"MagTekSureSwipe21040145"
} onStartedPreAuthorizing:^(DDPStartedPreAuthorizing* response) {
    LOG(INFO, @"@Received onStartedPreAuthorizing response: %@", response);
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    uint32_t cents = response.cents; // e.g. 128
    NSString* currency = response.currency; // e.g. @"USD"
    BOOL livemode = response.livemode; // e.g. NO
} onPreAuthorized:^(DDPPreAuthorized* response) {
    LOG(INFO, @"@Received onPreAuthorized response: %@", response);
    int32_t status = response.status; // e.g. DDPPaymentStatus_Success
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    NSString* preauthId = response.preauthId; // e.g. @"paut-Eo9YqkOTnmxt6EcL"
    NSString* info = response.info; // e.g. @"Human-readable description"
    NSString* customerId = response.customerId; // e.g. @"2DAuJMBrMyaC"
    NSString* merchantAccountId = response.merchantAccountId; // e.g. @"merchantAccountNumber"
    NSString* cardType = response.cardType; // e.g. @"Visa"
    NSString* last4 = response.last4; // e.g. @"0000"
    NSString* createdAt = response.createdAt; // e.g. @"915148799.75"
    uint32_t cents = response.cents; // e.g. 128
    NSString* currency = response.currency; // e.g. @"USD"
    BOOL livemode = response.livemode; // e.g. NO
    int32_t paymentType = response.paymentType; // e.g. DDPPaymentType_Card
    NSString* rawResponse = response.rawResponse; // e.g. @"Typically json data from processor"
}];
var args = {
  cents: 128,
  currency: "USD",
  useExistingData: false,
  useExistingDataSecondsWindow: 5,
};

dotdashpay.payment.receivePaymentDataThenPreAuthorize(args)
  .onStartedReceivingPaymentData(function(response) {
    console.log("Received onStartedReceivingPaymentData response", JSON.stringify(response, null, 2));
    var peripheralName = response.peripheralName; // e.g. "MagTekSureSwipe21040145"
  })
  .onReceivedPaymentData(function(response) {
    console.log("Received onReceivedPaymentData response", JSON.stringify(response, null, 2));
    var paymentDataId = response.paymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    var token = response.token; // "aeac1bc8f0735e4283305652ab"
    var peripheralName = response.peripheralName; // "MagTekSureSwipe21040145"
  })
  .onStartedPreAuthorizing(function(response) {
    console.log("Received onStartedPreAuthorizing response", JSON.stringify(response, null, 2));
    var paymentDataId = response.paymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    var cents = response.cents; // 128
    var currency = response.currency; // "USD"
    var livemode = response.livemode; // false
  })
  .onPreAuthorized(function(response) {
    console.log("Received onPreAuthorized response", JSON.stringify(response, null, 2));
    var status = response.status; // e.g. "SUCCESS"
    var paymentDataId = response.paymentDataId; // "pdid-iPqy9F82v5qexbtz"
    var preauthId = response.preauthId; // "paut-Eo9YqkOTnmxt6EcL"
    var info = response.info; // "Human-readable description"
    var customerId = response.customerId; // "2DAuJMBrMyaC"
    var merchantAccountId = response.merchantAccountId; // "merchantAccountNumber"
    var cardType = response.cardType; // "Visa"
    var last4 = response.last4; // "0000"
    var createdAt = response.createdAt; // "915148799.75"
    var cents = response.cents; // 128
    var currency = response.currency; // "USD"
    var livemode = response.livemode; // false
    var paymentType = response.paymentType; // "CARD"
    var rawResponse = response.rawResponse; // "Typically json data from processor"
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.ReceivePaymentDataThenPreAuthorizeArgs{
  Cents = 128,
  Currency = "USD",
  UseExistingData = false,
  UseExistingDataSecondsWindow = 5,
};

bool successful = await DotDashPay.Payment.ReceivePaymentDataThenPreAuthorize(reqArgs,
  onStartedReceivingPaymentData: response => {
    string peripheralName = response.PeripheralName; // e.g. "MagTekSureSwipe21040145"
  },
  onReceivedPaymentData: response => {
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    string token = response.Token; // e.g. "aeac1bc8f0735e4283305652ab"
    string peripheralName = response.PeripheralName; // e.g. "MagTekSureSwipe21040145"
  },
  onStartedPreAuthorizing: response => {
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    uint cents = response.Cents; // e.g. 128
    string currency = response.Currency; // e.g. "USD"
    bool livemode = response.Livemode; // e.g. false
  },
  onPreAuthorized: response => {
    var status = response.Status; // e.g. "SUCCESS"
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    string preauthId = response.PreauthId; // e.g. "paut-Eo9YqkOTnmxt6EcL"
    string info = response.Info; // e.g. "Human-readable description"
    string customerId = response.CustomerId; // e.g. "2DAuJMBrMyaC"
    string merchantAccountId = response.MerchantAccountId; // e.g. "merchantAccountNumber"
    string cardType = response.CardType; // e.g. "Visa"
    string last4 = response.Last4; // e.g. "0000"
    string createdAt = response.CreatedAt; // e.g. "915148799.75"
    uint cents = response.Cents; // e.g. 128
    string currency = response.Currency; // e.g. "USD"
    bool livemode = response.Livemode; // e.g. false
    var paymentType = response.PaymentType; // e.g. "CARD"
    string rawResponse = response.RawResponse; // e.g. "Typically json data from processor"
  },
  onError: err => {
    // Handle errors here
});

This is a convenience request that combines Hardware.ReceivePaymentData 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. Generally, this is quicker than calling Hardware.ReceivePaymentData followed by Payment.PreAuthorize yourself.

Parameter Description Default
centscentsCents
uint32
number of cents to PreAuthorize in the transaction 0
currencycurrencyCurrency
string
currency of the PreAuthorize amount (the cents field) (only USD currently supported) “USD”
useExistingDatauseExistingDataUseExistingData
bool
true when we want to use data that has recently gone through payment peripherals, e.g. a card swipe that occured shortly before this request; if it is false, it will only return new data through the hardware peripherals. false
useExistingDataSecondsWindowuseExistingDataSecondsWindowUseExistingDataSecondsWindow
uint32
when use_existing_data is true, this determines how recently we should use existing data going through the payments peripherals. 20

denotes a required field

Hardware.StartedReceivingPaymentData

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

Parameter Description Default
peripheralNameperipheralNamePeripheralName
string
denotes which payment hardware started to receive data. The possible values are the same as those returned by Hardware.GetConnectedPeripherals. None

Hardware.ReceivedPaymentData

Response when any payment peripheral finishes reading payment data from a magnetic stripe card.

Parameter Description Default
paymentDataIdpaymentDataIdPaymentDataId
string
a unique per-transaction id that represents the payment data that was received. Note that this changes for each transaction even if the payment method is the exact same. It can be used in other API requests to easily refer to payment data in a secure way (e.g. Payment.Settle) None
tokentokenToken
string
a unique and secure token that can be used to identify the payment method that was used. E.g. for magnetic stripe cards, this can be used as a proxy representation of a credit card PAN. None
peripheralNameperipheralNamePeripheralName
string
denotes which payment hardware received data. The possible values are the same as those returned by Hardware.GetConnectedPeripherals. None

Payment.StartedPreAuthorizing

Response when the pre authorization starts via the payment processor.

Parameter Description Default
paymentDataIdpaymentDataIdPaymentDataId
string
the id from Hardware.ReceivePaymentData now being used to PreAuthorize the payment None
centscentsCents
uint32
number of cents in the PreAuthorize 0
currencycurrencyCurrency
string
currency of the PreAuthorize (cents field) “USD”
livemodelivemodeLivemode
bool
is false when the request will not actually PreAuthorize funds i.e. it will be a 'test’ PreAuthorization. livemode is true when funds will be actually PreAuthorized. false

Payment.PreAuthorized

Response when the payment PreAuthorization returns from the payment processor.

Parameter Description Default
statusstatusStatus
enum PaymentStatus:
SUCCESS: 0FAIL: 1UNKNOWN: 2
an enum indicating the status of the PreAuthorize request None
paymentDataIdpaymentDataIdPaymentDataId
string
the id from Hardware.ReceivePaymentData used to get the payment data None
preauthIdpreauthIdPreauthId
string
a unique id associated with the PreAuthorized payment, which can be used to Payment.Settle or Payment.VoidPreAuthorize None
infoinfoInfo
string
a general purpose information string, e.g. if a call to Payment.PreAuthorize was unsuccessful then this field is populated with an explanation None
customerIdcustomerIdCustomerId
string
the unique customer id associated with the payment device, e.g. the customer’s credit card None
merchantAccountIdmerchantAccountIdMerchantAccountId
string
the id of the merchant account used to process the payment None
cardTypecardTypeCardType
string
the type of card used (if applicable/available), e.g. “Visa” None
last4last4Last4
string
the last four digits of the card used (if applicable/available) None
createdAtcreatedAtCreatedAt
string
indicates the time the PreAuthorization was created None
centscentsCents
uint32
number of cents PreAuthorized 0
currencycurrencyCurrency
string
currency of the transaction amount (cents field) “USD”
livemodelivemodeLivemode
bool
false when the request did not actually PreAuthorize funds with the customer’s bank, i.e. it was a 'test’ PreAuthorization. true when funds were actually PreAuthorized false
paymentTypepaymentTypePaymentType
enum PaymentType:
CARD: 0APPLEPAY: 1ANDROIDPAY: 2BITCOIN: 3THIRDPARTY: 4
specifies the type of payment object used to PreAuthorize the payment, i.e. a credit/debit card, apple pay, android pay, bitcoin, or a third party app/service CARD
rawResponserawResponseRawResponse
string
the raw response from the payment processor (typically used for debugging) None

Hardware

ReceivePaymentData

Hardware.ReceivePaymentDataArgs

DDPReceivePaymentDataArgs* args = [[DDPReceivePaymentDataArgs alloc] init];
args.useExistingData = NO;
args.useExistingDataSecondsWindow = 5;
args.cents = 128;
args.currency = @"USD";

[DotDashPayAPI.hardware receivePaymentData:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onStartedReceivingPaymentData:^(DDPStartedReceivingPaymentData* response) {
    LOG(INFO, @"@Received onStartedReceivingPaymentData response: %@", response);
    NSString* peripheralName = response.peripheralName; // e.g. @"MagTekSureSwipe21040145"
} onReceivedPaymentData:^(DDPReceivedPaymentData* response) {
    LOG(INFO, @"@Received onReceivedPaymentData response: %@", response);
    NSString* paymentDataId = response.paymentDataId; // e.g. @"pdid-iPqy9F82v5qexbtz"
    NSString* token = response.token; // e.g. @"aeac1bc8f0735e4283305652ab"
    NSString* peripheralName = response.peripheralName; // e.g. @"MagTekSureSwipe21040145"
}];
var args = {
  useExistingData: false,
  useExistingDataSecondsWindow: 5,
  cents: 128,
  currency: "USD",
};

dotdashpay.hardware.receivePaymentData(args)
  .onStartedReceivingPaymentData(function(response) {
    console.log("Received onStartedReceivingPaymentData response", JSON.stringify(response, null, 2));
    var peripheralName = response.peripheralName; // e.g. "MagTekSureSwipe21040145"
  })
  .onReceivedPaymentData(function(response) {
    console.log("Received onReceivedPaymentData response", JSON.stringify(response, null, 2));
    var paymentDataId = response.paymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    var token = response.token; // "aeac1bc8f0735e4283305652ab"
    var peripheralName = response.peripheralName; // "MagTekSureSwipe21040145"
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.ReceivePaymentDataArgs{
  UseExistingData = false,
  UseExistingDataSecondsWindow = 5,
  Cents = 128,
  Currency = "USD",
};

bool successful = await DotDashPay.Hardware.ReceivePaymentData(reqArgs,
  onStartedReceivingPaymentData: response => {
    string peripheralName = response.PeripheralName; // e.g. "MagTekSureSwipe21040145"
  },
  onReceivedPaymentData: response => {
    string paymentDataId = response.PaymentDataId; // e.g. "pdid-iPqy9F82v5qexbtz"
    string token = response.Token; // e.g. "aeac1bc8f0735e4283305652ab"
    string peripheralName = response.PeripheralName; // e.g. "MagTekSureSwipe21040145"
  },
  onError: err => {
    // Handle errors here
});

Listen for payment data from the payment peripheral hardware connected to the DotDashPay Platform.

Parameter Description Default
useExistingDatauseExistingDataUseExistingData
bool
true when we want to use data that has recently gone through payment peripherals, e.g. a card swipe that occured shortly before this request; if it is false, it will only return new data through the hardware peripherals. false
useExistingDataSecondsWindowuseExistingDataSecondsWindowUseExistingDataSecondsWindow
uint32
when use_existing_data is true, this determines how recently we should use existing data going through the payments peripherals. 20
centscentsCents
uint32
for some payment methods (e.g. Apple Pay), you need to specify the charge amount (in cents) via this argument, rather than the typical approach of specifying it in @request(Settle) or @request(PreAuthorize) None
currencycurrencyCurrency
string
if the payment method requires setting the cents field, you should also set the currency field if you do not intend use the default value “USD”

Hardware.StartedReceivingPaymentData

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

Parameter Description Default
peripheralNameperipheralNamePeripheralName
string
denotes which payment hardware started to receive data. The possible values are the same as those returned by Hardware.GetConnectedPeripherals. None

Hardware.ReceivedPaymentData

Response when any payment peripheral finishes reading payment data from a magnetic stripe card.

Parameter Description Default
paymentDataIdpaymentDataIdPaymentDataId
string
a unique per-transaction id that represents the payment data that was received. Note that this changes for each transaction even if the payment method is the exact same. It can be used in other API requests to easily refer to payment data in a secure way (e.g. Payment.Settle) None
tokentokenToken
string
a unique and secure token that can be used to identify the payment method that was used. E.g. for magnetic stripe cards, this can be used as a proxy representation of a credit card PAN. None
peripheralNameperipheralNamePeripheralName
string
denotes which payment hardware received data. The possible values are the same as those returned by Hardware.GetConnectedPeripherals. None

GetInternetStatus

Hardware.GetInternetStatusArgs

DDPGetInternetStatusArgs* args = [[DDPGetInternetStatusArgs alloc] init];

[DotDashPayAPI.hardware getInternetStatus:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onRetrievedInternetStatus:^(DDPRetrievedInternetStatus* response) {
    LOG(INFO, @"@Received onRetrievedInternetStatus response: %@", response);
    BOOL connected = response.connected; // e.g. YES
    NSString* info = response.info; // e.g. @"Human-readable description"
    NSArray* connectedInterfaces = response.connectedInterfacesArray; // e.g. @[[u'wifi', u'...']]
    NSArray* ipAddresses = response.ipAddressesArray; // e.g. @[[u'192.168.1.128', u'...']]
}];
var args = {};

dotdashpay.hardware.getInternetStatus(args)
  .onRetrievedInternetStatus(function(response) {
    console.log("Received onRetrievedInternetStatus response", JSON.stringify(response, null, 2));
    var connected = response.connected; // e.g. true
    var info = response.info; // "Human-readable description"
    var connectedInterfaces = response.connectedInterfaces; // [[u'wifi', u'...']]
    var ipAddresses = response.ipAddresses; // [[u'192.168.1.128', u'...']]
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.GetInternetStatusArgs{
};

bool successful = await DotDashPay.Hardware.GetInternetStatus(reqArgs,
  onRetrievedInternetStatus: response => {
    bool connected = response.Connected; // e.g. true
    string info = response.Info; // e.g. "Human-readable description"
    var connectedInterfaces = response.ConnectedInterfaces; // e.g. [[u'wifi', u'...']]
    var ipAddresses = response.IpAddresses; // e.g. [[u'192.168.1.128', u'...']]
  },
  onError: err => {
    // Handle errors here
});

Returns the status of the DotDashPay DotDashPay Platform’s connection to the Internet.

Parameter Description Default

Hardware.RetrievedInternetStatus

RetrievedInternetStatus contains information related to the status of the DotDashPay Platform’s connection to the Internet (which is required to process payments in 'Online’ mode).

A DDPError will not be returned if the Internet is down. Rather, this resposne will indicate that the Internet is disconnected and will return more information about why that is in the info field.

Parameter Description Default
connectedconnectedConnected
bool
will be true if the DotDashPay Platform is connected to the Internet None
infoinfoInfo
string
provides information of the status of the DotDashPay Platform’s connection to the Internet. None
connectedInterfacesconnectedInterfacesConnectedInterfaces
string [Array]
indicates which interfaces are currently connected to the Internet (e.g. ethernet, wifi, etc.). None
ipAddressesipAddressesIpAddresses
string [Array]
for each connected interface, indicates the IP address of that interface. In some cases this will not be available for security reasons. None

GetConnectedPeripherals

Hardware.GetConnectedPeripheralsArgs

DDPGetConnectedPeripheralsArgs* args = [[DDPGetConnectedPeripheralsArgs alloc] init];

[DotDashPayAPI.hardware getConnectedPeripherals:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onRetrievedConnectedPeripherals:^(DDPRetrievedConnectedPeripherals* response) {
    LOG(INFO, @"@Received onRetrievedConnectedPeripherals response: %@", response);
    NSArray* attachedValidPeriphs = response.attachedValidPeriphsArray; // e.g. @[[u'MagTekSureSwipe21040145', u'...']]
    NSArray* attachedErrorPeriphs = response.attachedErrorPeriphsArray; // e.g. @[[]]
}];
var args = {};

dotdashpay.hardware.getConnectedPeripherals(args)
  .onRetrievedConnectedPeripherals(function(response) {
    console.log("Received onRetrievedConnectedPeripherals response", JSON.stringify(response, null, 2));
    var attachedValidPeriphs = response.attachedValidPeriphs; // e.g. [[u'MagTekSureSwipe21040145', u'...']]
    var attachedErrorPeriphs = response.attachedErrorPeriphs; // [[]]
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.GetConnectedPeripheralsArgs{
};

bool successful = await DotDashPay.Hardware.GetConnectedPeripherals(reqArgs,
  onRetrievedConnectedPeripherals: response => {
    var attachedValidPeriphs = response.AttachedValidPeriphs; // e.g. [[u'MagTekSureSwipe21040145', u'...']]
    var attachedErrorPeriphs = response.AttachedErrorPeriphs; // e.g. [[]]
  },
  onError: err => {
    // Handle errors here
});

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

Parameter Description Default

Hardware.RetrievedConnectedPeripherals

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

Parameter Description Default
attachedValidPeriphsattachedValidPeriphsAttachedValidPeriphs
string [Array]
an array of attach peripherals that are working correctly None
attachedErrorPeriphsattachedErrorPeriphsAttachedErrorPeriphs
string [Array]
an array of attach peripherals that are not working correctly None

Information

GetCustomerId

Information.GetCustomerIdArgs

DDPGetCustomerIdArgs* args = [[DDPGetCustomerIdArgs alloc] init];
args.token = @"aeac1bc8f0735e4283305652ab";

[DotDashPayAPI.information getCustomerId:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onRetrievedCustomerId:^(DDPRetrievedCustomerId* response) {
    LOG(INFO, @"@Received onRetrievedCustomerId response: %@", response);
    NSString* customerId = response.customerId; // e.g. @"2DAuJMBrMyaC"
}];
var args = {
  token: "aeac1bc8f0735e4283305652ab",
};

dotdashpay.information.getCustomerId(args)
  .onRetrievedCustomerId(function(response) {
    console.log("Received onRetrievedCustomerId response", JSON.stringify(response, null, 2));
    var customerId = response.customerId; // e.g. "2DAuJMBrMyaC"
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.GetCustomerIdArgs{
  Token = "aeac1bc8f0735e4283305652ab",
};

bool successful = await DotDashPay.Information.GetCustomerId(reqArgs,
  onRetrievedCustomerId: response => {
    string customerId = response.CustomerId; // e.g. "2DAuJMBrMyaC"
  },
  onError: err => {
    // Handle errors here
});

Returns the customer id associated with a tokenized payment method. The token (if available) is returned by Hardware.ReceivedPaymentData.

Parameter Description Default
tokentokenToken
string
a token returned by Hardware.ReceivedPaymentData “”

denotes a required field

Information.RetrievedCustomerId

Returns a customer id associated with the input token from Hardware.ReceivedPaymentData

Parameter Description Default
customerIdcustomerIdCustomerId
string
the unique customer id. This will be empty if no customer id could be found. None

ReceiveLogs

Information.ReceiveLogsArgs

DDPReceiveLogsArgs* args = [[DDPReceiveLogsArgs alloc] init];
args.level = DDPReceiveLogsLevel_Debug;

[DotDashPayAPI.information receiveLogs:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onReceivedLogs:^(DDPReceivedLogs* response) {
    LOG(INFO, @"@Received onReceivedLogs response: %@", response);
    NSString* logMessage = response.logMessage; // e.g. @"The roof is on fire (you may need some water)."
    int32_t level = response.level; // e.g. DDPReceiveLogsLevel_Debug
}];
var args = {
  level: "DEBUG",
};

dotdashpay.information.receiveLogs(args)
  .onReceivedLogs(function(response) {
    console.log("Received onReceivedLogs response", JSON.stringify(response, null, 2));
    var logMessage = response.logMessage; // e.g. "The roof is on fire (you may need some water)."
    var level = response.level; // "DEBUG"
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.ReceiveLogsArgs{
  Level = "DEBUG",
};

bool successful = await DotDashPay.Information.ReceiveLogs(reqArgs,
  onReceivedLogs: response => {
    string logMessage = response.LogMessage; // e.g. "The roof is on fire (you may need some water)."
    var level = response.Level; // e.g. "DEBUG"
  },
  onError: err => {
    // Handle errors here
});

Returns an informational log from the DotDashPay firmware: use this request to monitor the performance and potential issues with the DotDashPay firmware.

Parameter Description Default
levellevelLevel
enum ReceiveLogsLevel:
FATAL: 0ERROR: 1WARNING: 2INFO: 3DEBUG: 4
defines the logging level at which the DotDashPay firmware will send logs to your software. None

Information.ReceivedLogs

Returns an informational log from the DotDashPay firmware.

Parameter Description Default
logMessagelogMessageLogMessage
string
a string containing information and updates from the DotDashPay firmware. None
levellevelLevel
enum ReceiveLogsLevel:
FATAL: 0ERROR: 1WARNING: 2INFO: 3DEBUG: 4
defines the logging level at which the DotDashPay firmware will send logs to your software. None

Global

Initialize

Global.InitializeArgs

DDPInitializeArgs* args = [[DDPInitializeArgs alloc] init];
args.apiToken = @"abc123";
args.simulate = YES;
args.simulateProcessor = YES;
args.processorSandboxMode = YES;
args.processorSandboxName = @"braintree";
args.processorSandboxPublicKey = @"abc123sanboxkey";
args.processorSandboxPrivateKey = @"privatekey123";
args.processorSandboxMerchantId = @"somemerchantid";
args.useSimulatedCardswipe = YES;
args.simulatedCardswipeDelayMs = 300;
args.networkEssid = @"Network Name";
args.networkPassword = @"wifi_password";
args.networkUsername = @"wifi_username";
args.networkX509Cert = @"308202123082017b02020dfa300d06092a864886f70d010105050030819b310b3009060355040613024a50310e300c06035504081305546f6b796f3110300e060355040713074368756f2d6b753111300f060355040a13084672616e6b34444431183016060355040b130f5765624365727420537570706f7274311830160603550403130f4672616e6b344444205765622043413123302106092a864886f70d0109011614737570706f7274406672616e6b3464642e636f6d301e170d3132303832323035323635345a170d3137303832313035323635345a304a310b3009060355040613024a50310e300c06035504080c05546f6b796f3111300f060355040a0c084672616e6b3444443118301606035504030c0f7777772e6578616d706c652e636f6d305c300d06092a864886f70d0101010500034b0030480241009bfc6690798442bbab13fd2b7bf8de1512e5f193e3068a7bb8b1e19e26bb9501bfe730ed648502dd1569a834b006ec3f353c1e1b2b8ffa8f001bdf07c6ac53070203010001300d06092a864886f70d01010505000381810014b64cbb817933e671a4da516fcb081d8d60ecbc18c7734759b1f22048bb61fafc4dad898dd121ebd5d8e5bad6a636fd745083b60fc71ddf7de52e817f45e09fe23e79eed73031c72072d9582e2afe125a3445a119087c89475f4a95be23214a5372da2a052f2ec970f65bfafddfb431b2c14a9c062543a1e6b41e7f869b16400a";
args.networkStaticIp = @"192.168.1.128";
args.networkStaticSubnetMask = @"255.255.255.0";
args.networkStaticGateway = @"192.168.1.1";
args.networkStaticDns = @"8.8.8.8";
args.networkSaveConfiguration = YES;
args.networkAutoReconnect = YES;

[DotDashPayAPI.global initialize:args onError:^(DDPError* error) {
    LOG(ERROR, @"%@", error.errorMessage);
} onInitialized:^(DDPInitialized* response) {
    LOG(INFO, @"@Received onInitialized response: %@", response);
}];
var args = {
  apiToken: "abc123",
  simulate: true,
  simulateProcessor: true,
  processorSandboxMode: true,
  processorSandboxName: "braintree",
  processorSandboxPublicKey: "abc123sanboxkey",
  processorSandboxPrivateKey: "privatekey123",
  processorSandboxMerchantId: "somemerchantid",
  useSimulatedCardswipe: true,
  simulatedCardswipeDelayMs: 300,
  networkEssid: "Network Name",
  networkPassword: "wifi_password",
  networkUsername: "wifi_username",
  networkX509Cert: "308202123082017b02020dfa300d06092a864886f70d010105050030819b310b3009060355040613024a50310e300c06035504081305546f6b796f3110300e060355040713074368756f2d6b753111300f060355040a13084672616e6b34444431183016060355040b130f5765624365727420537570706f7274311830160603550403130f4672616e6b344444205765622043413123302106092a864886f70d0109011614737570706f7274406672616e6b3464642e636f6d301e170d3132303832323035323635345a170d3137303832313035323635345a304a310b3009060355040613024a50310e300c06035504080c05546f6b796f3111300f060355040a0c084672616e6b3444443118301606035504030c0f7777772e6578616d706c652e636f6d305c300d06092a864886f70d0101010500034b0030480241009bfc6690798442bbab13fd2b7bf8de1512e5f193e3068a7bb8b1e19e26bb9501bfe730ed648502dd1569a834b006ec3f353c1e1b2b8ffa8f001bdf07c6ac53070203010001300d06092a864886f70d01010505000381810014b64cbb817933e671a4da516fcb081d8d60ecbc18c7734759b1f22048bb61fafc4dad898dd121ebd5d8e5bad6a636fd745083b60fc71ddf7de52e817f45e09fe23e79eed73031c72072d9582e2afe125a3445a119087c89475f4a95be23214a5372da2a052f2ec970f65bfafddfb431b2c14a9c062543a1e6b41e7f869b16400a",
  networkStaticIp: "192.168.1.128",
  networkStaticSubnetMask: "255.255.255.0",
  networkStaticGateway: "192.168.1.1",
  networkStaticDns: "8.8.8.8",
  networkSaveConfiguration: true,
  networkAutoReconnect: true,
};

dotdashpay.global.initialize(args)
  .onInitialized(function(response) {
    console.log("Received onInitialized response", JSON.stringify(response, null, 2));
  })
  .onError(function(errorData) {
    console.log("Error", JSON.stringify(errorData, null, 2));
  })
  .execute();
var reqArgs = new DotDashPay.InitializeArgs{
  ApiToken = "abc123",
  Simulate = true,
  SimulateProcessor = true,
  ProcessorSandboxMode = true,
  ProcessorSandboxName = "braintree",
  ProcessorSandboxPublicKey = "abc123sanboxkey",
  ProcessorSandboxPrivateKey = "privatekey123",
  ProcessorSandboxMerchantId = "somemerchantid",
  UseSimulatedCardswipe = true,
  SimulatedCardswipeDelayMs = 300,
  NetworkEssid = "Network Name",
  NetworkPassword = "wifi_password",
  NetworkUsername = "wifi_username",
  NetworkX509Cert = "308202123082017b02020dfa300d06092a864886f70d010105050030819b310b3009060355040613024a50310e300c06035504081305546f6b796f3110300e060355040713074368756f2d6b753111300f060355040a13084672616e6b34444431183016060355040b130f5765624365727420537570706f7274311830160603550403130f4672616e6b344444205765622043413123302106092a864886f70d0109011614737570706f7274406672616e6b3464642e636f6d301e170d3132303832323035323635345a170d3137303832313035323635345a304a310b3009060355040613024a50310e300c06035504080c05546f6b796f3111300f060355040a0c084672616e6b3444443118301606035504030c0f7777772e6578616d706c652e636f6d305c300d06092a864886f70d0101010500034b0030480241009bfc6690798442bbab13fd2b7bf8de1512e5f193e3068a7bb8b1e19e26bb9501bfe730ed648502dd1569a834b006ec3f353c1e1b2b8ffa8f001bdf07c6ac53070203010001300d06092a864886f70d01010505000381810014b64cbb817933e671a4da516fcb081d8d60ecbc18c7734759b1f22048bb61fafc4dad898dd121ebd5d8e5bad6a636fd745083b60fc71ddf7de52e817f45e09fe23e79eed73031c72072d9582e2afe125a3445a119087c89475f4a95be23214a5372da2a052f2ec970f65bfafddfb431b2c14a9c062543a1e6b41e7f869b16400a",
  NetworkStaticIp = "192.168.1.128",
  NetworkStaticSubnetMask = "255.255.255.0",
  NetworkStaticGateway = "192.168.1.1",
  NetworkStaticDns = "8.8.8.8",
  NetworkSaveConfiguration = true,
  NetworkAutoReconnect = true,
};

bool successful = await DotDashPay.Global.Initialize(reqArgs,
  onInitialized: response => {
  },
  onError: err => {
    // Handle errors here
});

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

Parameter Description Default
apiTokenapiTokenApiToken
string
the api token associated with your DotDashPay account. “anonymous”
simulatesimulateSimulate
bool
if true, use the DotDashPay web-based simulator instead of communicating to the actual DotDashPay Platform. true
simulateProcessorsimulateProcessorSimulateProcessor
bool
if true, the DotDashPay Platform uses a built-in payment processor simulator rather than sending to a sanboxed or production level payment processor. This option is ignored when simulate is true. true
processorSandboxModeprocessorSandboxModeProcessorSandboxMode
bool
if true, the payment processor will process payments in sandbox mode, i.e. funds will not be transferred. This option is ignored when simulate is true or simulate_processor is true. true
processorSandboxNameprocessorSandboxNameProcessorSandboxName
string
the name of the payment processor used for processing sandboxed transactions. This option is only used when processor_sandbox_mode is true. Production payment processing credentials must be set through the device management interface None
processorSandboxPublicKeyprocessorSandboxPublicKeyProcessorSandboxPublicKey
string
public key associated with some payment processors, used for sandboxed transactions. This option is only used when processor_sandbox_mode is true. Production payment processing credentials must be set through the device management interface None
processorSandboxPrivateKeyprocessorSandboxPrivateKeyProcessorSandboxPrivateKey
string
private key associated with some payment processors, used for sandboxed transactions. This option is only used when processor_sandbox_mode is true. Production payment processing credentials must be set through the device management interface None
processorSandboxMerchantIdprocessorSandboxMerchantIdProcessorSandboxMerchantId
string
merchant id associated with all payment processors, used for sandboxed transactions. This option is only used when processor_sandbox_mode is true. Production payment processing credentials must be set through the device management interface None
useSimulatedCardswipeuseSimulatedCardswipeUseSimulatedCardswipe
bool
if true, a simulated cardswipe takes place after simulated_cardswipe_delay_ms milliseconds whenever a cardswipe would be applicable, e.g. because Hardware.ReceivePaymentData is called. None
simulatedCardswipeDelayMssimulatedCardswipeDelayMsSimulatedCardswipeDelayMs
uint32
the number of milliseconds to wait before simulating a cardswipe when use_simulated_cardswipe is true 500
networkEssidnetworkEssidNetworkEssid
string
the ESSID of the wireless network to connect to None
networkPasswordnetworkPasswordNetworkPassword
string
the password needed to connect to the wireless network if applicable None
networkUsernamenetworkUsernameNetworkUsername
string
the username needed to connect to the wireless network if applicable None
networkX509CertnetworkX509CertNetworkX509Cert
string
the X.509 certificate needed to connect to the wireless network * if applicable. None
networkStaticIpnetworkStaticIpNetworkStaticIp
string
if set to anything other than “”, this will cause the wireless interface to be configured with a static IP address, subnet mask, and gateway IP address “”
networkStaticSubnetMasknetworkStaticSubnetMaskNetworkStaticSubnetMask
string
if a static IP is set, this should be set to the subnet mask of the network you are connecting to None
networkStaticGatewaynetworkStaticGatewayNetworkStaticGateway
string
if a static IP is set, this should be set to the IP address of the gateway you are connected to None
networkStaticDnsnetworkStaticDnsNetworkStaticDns
string
the IP address of a DNS server to use for resolving hostnames. This can be set even if static_ip is set to “”. None
networkSaveConfigurationnetworkSaveConfigurationNetworkSaveConfiguration
bool
saves the wifi configuration (if successful), so that you don’t have to configure wifi everytime your machine restarts. you do not need to send the network information with requests once it has been set. true
networkAutoReconnectnetworkAutoReconnectNetworkAutoReconnect
bool
if save_configuration is true, setting this to true will cause the DotDashPay Platform to automatically attempt to reconnect to any previously saved wifi configurations true

Global.Initialized

Indicates that the DotDashPay Platform has been initialized. The response itself does not contain any extra data.

Parameter Description Default

Errors

DDPError

A DDPError is a potential response from any request. It is always a completion event; i.e. no other responses will ever come after it.

Every API function call allows you to specify an error callback which takes DDPError as an argument. If this callback is ever invoked, a non-recoverable error has occurred on the DotDashPay Platform. For instance, if you call Hardware.ReceivePaymentData, a payer swipes their magnetic stripe card, and the magnetic card reader fails to extract the payer’s card information, a DDPError will be returned so that you can alert the payer their card did not read and call Hardware.ReceivePaymentData again.

Parameter Description Default
errorCodeerrorCodeErrorCode
enum ErrorCode:
PLATFORM_NO_CONN: 1PLATFORM_NO_RESP: 2PLATFORM_MALFORMED_API_REQUEST: 3PLATFORM_UNHANDLED: 999PROCESSING_NO_RESP_PAY: 1001PROCESSING_NO_RESP_LOG: 1002PROCESSING_NO_RESP_DB: 1003PROCESSING_NO_PAY_DATA: 1011PROCESSING_UNHANDLED: 1099PROCESSING_UNSUCCESSFUL: 1021HARDWARE_NETWORK_NO_INTERNET_WIFI: 2001HARDWARE_NETWORK_NO_INTERNET_CELL: 2002HARDWARE_NETWORK_NO_INTERNET_ETHERNET: 2003HARDWARE_NETWORK_NO_WIFI_CONN: 2020HARDWARE_NETWORK_UNHANDLED: 2099HARDWARE_PERIPH_NO_CONN: 2101HARDWARE_PERIPH_NO_RESP: 2102HARDWARE_PERIPH_REQUIRES_CENTS: 2103HARDWARE_PERIPH_MALFORMED_DATA: 2104HARDWARE_PERIPH_DISCONNECTED: 2105HARDWARE_PERIPH_UNHANDLED: 2199
a semantic code used to identify the error (see Error Codes for a complete list) None
errorMessageerrorMessageErrorMessage
string
a human-readable message associated with the error None