isignthis-psp

    3.0.4 • Public • Published

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

    Install

    npm i isignthis-psp

    DownloadsWeekly Downloads

    2

    Version

    3.0.4

    License

    MIT

    Unpacked Size

    43.1 kB

    Total Files

    8

    Last publish

    Collaborators

    • coinifyaps