@dadesystems/dademobile

DadeMobile.js

JavaScript library for Dade Mobile API. This library provides convenient access to the Dade Mobile API from applications written in JavaScript.

Sample App

Apache Cordova sample app demonstrating the use of DadeMobile.js: https://github.com/DadeSystems/CordovaSample

Installation

Install the package with npm:

npm install @dadesystems/dademobile --save

Or using yarn:

yarn add @dadesystems/dademobile

Usage

The general workflow for capturing payments is as follows:

• Initialize DadeMobile with provided API Key and API URL.
• Use instance of DadeMobile to stage, update, and confirm a payment.

Initialization

The first step is to initialize DadeMobile with provided API Key and API URL:

CommonJS:

const { DadeMobile } = require('@dadesystems/dademobile');

Or using ES modules:

import { DadeMobile } from '@dadesystems/dademobile';

Initialize

const dadeMobile = new DadeMobile(API_KEY, API_URL);

Stage Payment

After initialization, the next step is to stage a payment. The payment amount can be set when staging a payment, or after a payment has already been staged, depending on your workflow. If a payment was previously staged but not confirmed, then it will be resumed.

Params

• external_user_id: Unique identifer for your user making the payment.
• external_reference: (Optional) your reference for the payment.
• amount: (Optional) payment amount. This can be set after staging the payment.

Example

dadeMobile
  .stagePayment({ 
    external_user_id: '123',
    external_reference: '321',
    amount: 5.00
  })
  .then((payment) => {
    // Payment successfully staged
  })
  .catch((error) => {
    // Failed to stage payment
  });

Set Amount

Set the amount of a staged payment.

Params

• payment: The staged payment.
• amount: Payment amount.

Example

dadeMobile
  .setAmount(payment, 15.00)
  .then((payment) => {
    // Payment amount updated successfully
  })
  .catch((error) => {
    // Failed to update payment amount
  });

Upload Image

Upload image for a staged payment.

Params

• payment: The staged payment.
• imageType: The type of image being uploaded (checkfront or checkrear).
• encodedImage: Base64 encoding of the image data.

Example

dadeMobile
  .uploadImage(payment, 'checkfront', encodedImage)
  .then((payment) => {
    // Image uploaded successfully
  })
  .catch((error) => {
    // Failed to upload image
  });

Confirm Payment

Once a payment is staged and all properties have been set, the final step is to confirm the payment. If the payment fails validation, then validation errors will be returned. See the next section for error codes.

Params

• payment: The staged payment.

Example

dadeMobile
  .confirmPayment(payment)
  .then((payment) => {
    // Payment confirmed successfully
  })
  .catch((error) => {
    // Failed to confirm payment
    // Handle validation errors if present
    const { errors } = error;
  });

Success Response

Example payment data returned upon successful confirmation of a payment:

{
  id: 1001,
  type: "Check Payment",
  status: "Completed",
  amount: 5.0,
  external_user_id: "123",
  external_reference: "321",
  date: "2019-02-12",
  check_routing_number: "123456789",
  check_account_number: "987654321",
  check_number: "2808"
}

Validation Errors

Validation errors are returned as an array of error objects containing the error code and error message, example:

[
  {
    error_code: 2001,
    error_message: 'Front image required'
  }
]

The following is a list of validation error codes and descriptions:

2000: Check amount required
2001: Check front image required
2002: Check rear image required
2003: Check image still processing
2004: Check IQA failed
2005: Check duplicate found
2006: Check amount mismatch

Check Amount Mismatch

When check read amount validation is enabled, and the amount set for the payment does not match the amount read from the check, a check amount mismatch validation error will be returned containing the amount read, example:

[
  {
    error_code: 2006,
    error_message: 'Check amount mismatch',
    error_data: {
      read_amount: 10.0
    }
  }
]

This can be resolved by updating the payment with the correct amount before resubmitting. If the amount was read incorrectly, you can ignore the amount mismatch when resubmitting, example:

dadeMobile
  .confirmPayment(payment, { 
    ignore_check_amount_mismatch: true 
  })

Using Promises

Every method returns a chainable promise:

dadeMobile
  .stagePayment({ 
    external_user_id: '123',
    external_reference: '321',
    amount: 5.00
  })
  .then((payment) => {
    return dadeMobile.setAmount(payment, 10.00);
  })
  .then((payment) => {
    return dadeMobile.uploadImage(payment, 'checkfront' encodedImage);
  })
  .then((payment) => {
    return dadeMobile.uploadImage(payment, 'checkrear' encodedImage);
  })
  .then((payment) => {
    return dadeMobile.confirmPayment(payment);
  })
  .then((payment) => {
    console.log(payment);
  })
  .catch((error) => {
    console.log(error);
  });