isignthis-psp

UPDATE 2.x.x: Node-style callbacks are deprecated, but can still be found in versions 1.x.x

Module for interfacing with iSignThis as a payment service provider (PSP)

Constructor

Module constructor

Arguments

Argument	Type	Default	Description
settings	Object	Required	An object of settings required or supported by the module.

option object

Field	Type	Default	Description
clientCertificate	Buffer	Required	Client certificate used for communication
clientKey	Buffer	Required	Client private key used for communication
merchantId	String	Required	iSignThis merchant identifier
log	Object	console-log-level instance	Bunyan-compatible logger
baseUrl	String	"https://gateway.isignthis.com"	Base URL (without trailing slash) to iSignThis to use instead of default
acquirerId	String	"node-isignthis-psp"	Default acquirer to use if none specified when creating a payment

Example

var fs = require('fs');
var ISignThis = require('isignthis-psp');

var iSignThis = new ISignThis({
  clientCertificate: fs.readFileSync(certFile),
  clientKey: fs.readFileSync(keyFile),
  merchantId: "my_merchant",
  acquirerId: "clearhaus"
});

Payments

Payment object

This section describes the object that is returned on success from createPayment and getPayment.

Field	Type	Description
id	String	PSP-specific identifier for this payment
acquirerId	String	Acquirer used for this payment? (options.acquirerId as passed to the constructor)
state	String	State of the payment. Is one of the following strings: pending - Payment has been initiated, but is waiting for action from the PSP or the end-user. rejected - Payment was rejected before the end-user entered any payment details. declined - Payment was declined after the end-user entered payment details. failed - Payment failed due to an error with the PSP. expired - Payment expired before it was completed. completed - Payment completed successfully.
event	String	The event field describes an event, a system action that has been triggered either automatically or by an operator.
expiryTime	Date	Time when payment expires in ISO-8601 format
redirectUrl	String	URL where the payment is processed by the user.
transactions	Object	Information about the transaction(s) related to the payment
→id	String	Acquirer-specific identifier for this transaction.
→amount	Integer	Amount (denominated in sub-unit of →currency) of this transaction
→currency	String	Currency denominating amount
→identity	Object	Information about the KYC/SCA identity returned with the transaction. If no identity is returned, value will be null
→identity.id	String	Identity ID
→identity.url	String	URL to get provider specific identity information
raw	Object	The payment object from the PSP. The contents of this object will differ between different PSPs, and should be treated as an opaque blob.
card	Object	Information about the card
→token	String	The credit card token to use for a preauthorized card payment
→last4	String	The last four digits of the credit card number
→bin	String	The credit card bin
→brand	String	The credit card brand
→expiryDate	String	The credit card expiry date (e.g. 1217 for Dec, 2017)
→recurringId	String	ID to use for recurring payments.

createPayment: Create payment

Initiate a payment

createPayment(options)

options arguments

Argument	Type	Default	Description
workflow	String	Required	Workflow identifier given by iSignThis.
acquirerId	String	acquirerId from constructor	What acquirer should be used for this payment?
returnUrl	String (URL fragment)	Required	URL to redirect end-user to after a successful payment. Note: The PSP transaction ID will be appended to the URL, so it should be something like https://example.com/payment-complete?transaction_id=
amount	Integer	Required	Amount (denominated in sub-unit of currency) to create a payment for.
currency	String	Required	Currency code denominating amount.
client	Object	Required	Object with information about the client initiating the payment. Only the ip field is required.
initRecurring	Boolean	(Optional)	If payment is the first in a series of recurring payments.
→ip	String	Required	IP address of client
→name	String	null	Full name of client
→dob	String	null	Date of birth of client
→country	String	null	Country code (ISO-3166-1 alpha-2) of country of citizenship of client
→email	String (Email address)	null	Email address of client
→address	String	null	Physical street address of client
account	Object	Required	Object with information about the account (e.g. the internal user or equivalent)
→id	String	Required	Unique identifier for this account (e.g. internal user ID or equivalent)
→secret	String	null	Secret used by iSignThis
→name	String	null	Full name of account owner
transaction	Object	{}	Information about the transaction(s) related to the payment
→id	String	null	Internal reference
→reference	String	null	Internal reference for the transaction(s)

Returns

The function return a Promise which resolves in a payment object.

Example

var options = {
  workflow: 'CORE',
  acquirerId: 'clearhaus',
  returnUrl: 'https://example.com/payment-complete?transaction_id=',
  amount: 5000,
  currency: 'USD', // 50.00 USD
  client: {
    ip: '127.0.0.1',
    userAgent: 'Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531...'
  },
  account: {
    id: 'user-12345'
  }
};

return PSP.createPayment(options)
  .then(payment => {
    // Handle payment creation success
  })
  .catch(err => {
    // Handle error
  });
});

processRecurringPayment: Process recurring payment

Process a recurring payment using a recurringId from a succeded payment with initRecurring: true

processRecurringPayment(options)

options arguments

Argument	Type	Default	Description
workflow	String	Required	Workflow identifier given by iSignThis.
acquirerId	String	acquirerId from constructor	What acquirer should be used for this payment?
recurringId	String	Required	If payment is the first in a series of recurring payments. https://example.com/payment-complete?transaction_id=
client	Object	Required	Object with information about the client initiating the payment. Only the ip field is required.
→ip	String	Required	IP address of client
→name	String	null	Full name of client
→dob	String	null	Date of birth of client
→country	String	null	Country code (ISO-3166-1 alpha-2) of country of citizenship of client
→email	String (Email address)	null	Email address of client
→address	String	null	Physical street address of client
account	Object	Required	Object with information about the account (e.g. the internal user or equivalent)
→id	String	Required	Unique identifier for this account (e.g. internal user ID or equivalent)
→secret	String	null	Secret used by iSignThis
→name	String	null	Full name of account owner
transaction	Object	{}	Information about the transaction(s) related to the payment
→id	String	null	Internal reference
→reference	String	null	Internal reference for the transaction(s)

Returns

The function return a Promise which resolves in a payment object.

Example

const options = {
  acquirerId: 'clearhaus',
  recurringId: 'recurring-id-string',
  client: {
    ip: '127.0.0.1',
    userAgent: 'Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531...'
  },
  account: {
    id: 'user-12345'
  }
};

return PSP.processRecurringPayment(options)
  .then(payment => {
    // Handle payment creation success
  })
  .catch(err => {
    // Handle error
  });
});

getPayment: Read payment

Get updated information about an existing payment

getPayment(paymentId);

Arguments

Argument	Type	Default	Description
paymentId	String	Required	ID of payment to query. Comes from the id property of the payment object.

Returns

The function return a Promise which resolves in a payment object.

Example

const paymentId = '12345678-4321-2345-6543-456787656789';
return PSP.getPayment(paymentId)
  .then(payment => {
    // Handle payment creation success
  })
  .catch(err => {
    // Handle error
  });
});

isCallbackValid: Validate callback

Validate a callback sent from iSignThis.

isCallbackValid(request);

Arguments

Argument	Type	Default	Description
request	Object	Required	Whole request object with headers and body.

Returns

Returns true if callback is valid

Example

const request = {
  headers: {
  	 'content-type': 'application/json',
	  accept: 'application/json',
	  host: 'example.com',
	  authorization: 'Bearer token_value',
	  'content-length': '1297',
	  connection: 'close',
  },
  body: {}
};

// Result is either true or false
const result = isCallbackValid(request);

parsePayment: Read payment

Get updated information about an existing payment

parsePayment(requestBody);

Arguments

Argument	Type	Default	Description
requestBody	Object	Required	Body of the request object. In this case its a payment object from iSignThis.

Result

This function returns a payment object.

Example

const requestBody = {
  id: "c97f0bfc-c1ac-46c3-96d8-6605a63d380d",
  uid: "c97f0bfc-c1ac-46c3-96d8-6605a63d380d",
  secret: "f8fd310d-3755-4e63-ae98-ab3629ef245d",
  mode: "registration",
  original_message: {
    merchant_id: merchantId,
    transaction_id: transactionId,
    reference: transactionReference
  },
  expires_at: "2016-03-06T13:36:59.196Z",
  transactions: [
    {
      acquirer_id: acquirerId,
      bank_id: "2774d451-5499-41a6-a37e-6a90f2b8673c",
      response_code: "20000",
      success: true,
      amount: "0.70",
      currency: "DKK",
      message_class: "authorization-and-capture",
      status_code: "20000"
    },
    {
      acquirer_id: acquirerId,
      bank_id: "73f63c0b-7c59-416f-89e5-17dcc38b64ac",
      response_code: "20000",
      success: true,
      amount: "0.30",
      currency: "DKK",
      message_class: "authorization-and-capture",
      status_code: "20000"
    }
  ],
  state: "PENDING",
  compound_state: "PENDING.AWAIT_SECRET"
}

// result is a payment object
const payment = PSP.parsePayment(requestBody);