Skip to content
This repository has been archived by the owner on Mar 11, 2024. It is now read-only.

CoinifySoftware/isignthis-psp

Repository files navigation

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);