S4Payments Web SDK

This is the offiically supported Web SDK for integrating with Shift4.

The goal is to provide integrators with a modern, extendable web SDK that allows them to utilize various approaches to integrate Shift4 payments into their solution.

Setup the Client Library

Add the SDK to your project.

npm add @shift4/s4payments-web-sdk

Include it in your code.

const S4Payments = require('@shift4/s4payments-web-sdk')

Create the Config

Create the client config object used for initializing the SDK. See the section called Client Config Object below for additional details.

Modes Available: uat If you remove development object as a whole, it'll default to production.

Example:

config = {
  riskId: '1234567890',
  enabledServices: ['risk', '3ds'],
  appId: 'hik23bf33e2f985fba0d4738c19f24ea',
  development: {
    mode: 'uat'
  },
  events: (payload) => {
    if (payload.event === 'S4PAYMENTS_INITIALIZED') {
      console.log(payload)

      // payload.shift4Session - From the payload
      // payload.riskSessionId - From the payload

    } else if (payload.event === 'THREE_D_SECURE_SUCCESS') {
      console.log('DO something for 3DS Success')
    } else if (payload.event === 'THREE_D_SECURE_FAILURE') {
      console.log("Do something for 3DS Failure")
    } else if (payload.event === 'THREE_D_SECURE_ERROR') {
      console.log("Do something for 3DS Error")
    } else if (payload.event === 'S4PAYMENTS_CLOSED') {
      // If you are integrating 3DS, and your payment screen just hangs for a while, ~10 minutes,
      // the SDK will shut down 3DS and you will be required to re-initialize the SDK.
    }
  }
}

S4Payments.sdk.initialize(config)

Client Config Object

This is used to initialize the client (S4Payments.sdk.initialize(CONFIG)).

config = {
  riskId: '<STRING>',
  debug: '<BOOLEAN>',
  enabledServices: <ARRAY OF STRINGS>,
  appId: '<STRING>',
  events: (payload) => {

  }
}

• riskId: {String} - The Shift4 Risk MID that was supplied by Shift4.
• debug: {Boolean} - Do we want to put this library in Debug mode or not.
• appId: {String} - A Shift4 App ID that was generated by creating your application with Shift4 Payments API. Details above.
• events: {Function} - A callback function that is called from within the SDK for any events that you need to be notified of. You can listen for various events and receive information. Details for payload events can be found below.
• enabledServices: {Array of Strings} - What services do you want to use?
  • 'risk': Enables and collects information for risk assessment.
  • '3ds': Enables and runs 3DS when necessary.

Event Payloads

S4PAYMENTS_INITIALIZED - If you have enabled 'risk' and/or '3ds', this will be called when the SDK has completed its client side data collection. It will provide you with a sessionId that you will pass to the Shift4 API's to complete the risk check. You must wait for this response to use risk and 3DS.

Payload

{
  shift4Session: '<IDENTIFIER>',
  riskSessionId: '<IDENTIFIER>'
}

3DS Payloads

THREE_D_SECURE_SUCCESS -

Payload

{
    "event": "THREE_D_SECURE_SUCCESS",
    "sessionId": "d2bd267d446f47bf9940464f27af269f",
    "jwt": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1ZWM3MGQ5ODIzMDFjNzNiZTQ0OWUzZTQiLCJpYXQiOjE2NDU5MzcyODYsImV4cCI6MTY0NTk0NDQ4NiwianRpIjoiYmYzM2UyNGMtYjM2Ni00MWVkLWE3NjEtYzJkMGU4Y2U0ZTE2IiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwXzIyZWYxODNhLWZlYTMtNDIxYS1hNTg2LWZiMzkyMzRlMDc5OCIsIlJlZmVyZW5jZUlkIjoiMF8yMmVmMTgzYS1mZWEzLTQyMWEtYTU4Ni1mYjM5MjM0ZTA3OTgiLCJhdWQiOiIxQ0Y3NzY5Ri1CRjMxLUFGMTMtMDZDMTkzMDU1RTI0RUY4MiIsIlBheWxvYWQiOnsiVmFsaWRhdGVkIjp0cnVlLCJQYXltZW50Ijp7IlR5cGUiOiJDQ0EiLCJQcm9jZXNzb3JUcmFuc2FjdGlvbklkIjoialp4UklQNnZvSWkyaEViaHQxaDAiLCJFeHRlbmRlZERhdGEiOnsiQW1vdW50IjoiNjAwMDEyIiwiQ0FWViI6IkFBQUJBV0ZsbVFBQUFBQmpSV1daRUVGZ0Z6OFx1MDAzZCIsIkN1cnJlbmN5Q29kZSI6Ijg0MCIsIkVDSUZsYWciOiIwNSIsIlhJRCI6ImFscDRVa2xRTm5adlNXa3lhRVZpYUhReGFEQVx1MDAzZCIsIlBBUmVzIjoiZU5yZFdWblBxc2pXdm44VC84Tk9uMHU3bTBGUk9IRy9TVEdLQ0FveTN6RVBJak9DL1BwVCt1NnArK3hPdXIrYmszd214S0pZdFdyTlR5M1k2V2tiUmV3bENvWTJldC9KVWRkNVNmUXBDei8va3J1VEpwNDM5MHJNOEpUejB4NUwwVi9lZDJlZ1JkMkw0RFhhanBIWTZFRWFNZEhnanFSM1hzNWxVWlRNK3RCOWh0VDNxTzJ5cW56SGZrZC94M2ZJMTF1NFVSdWtYdG0vNzd5Z29VWGxIY05YYTJLekpYZklsNG5kTFdwRjlqMk1ZbThvK2gzeWNidER2cTg4RDg5UkI4V2VzdkRkSytxMWNTMVVwWFR2Rit2NjhEZ3o4L2JxNUxIZzh3NTVVdXhDcjQvZWNSVGRvaHVjK0lTdC80MWkvMGJoanEvNVhmMWtCMjdWQUhsdlVCVEZvTHcvenUyZ2lkcW9EQjd2NUJyZElkL3VkdEZVVjJVRUtlQ0NiK01kOGwyODJpdmYwUjkrR0VwaGtEZWMzZW4yKzY3UGJqK0tSVDNGd3JZNzVEVy82M3F2SDdwM1o0ZDhHZTBDNzM1L0J3RFF3T0tMbXdxZXcxeXpMSmZqK0lTZmwxRGRGOGt1Q3JKM2xJQkN3Zi9YS2xBa1ZadjE2ZTBwNmg4bmRzaFRGT1RsMC9mZEpVdEt1RmtiZlpwdVJRazltZlo5L1c4RUdjZng5M0gxZTlVbUNCUVlSVkFLZ1FSaGx5WC8rdVZqVlJTS1pWejlvMldNVjFabEZuaEZObnM5akE0NTZ0TXEvUFJOdHAreDBiVW5Kd3pST09ZM3lPcTNBRnVYdnoxbjBCVkdRSjdJejVuK29ObmYyZVhQd3JhZDkxdVhldGh6Z3o4eGV0OXBVUnc5SXlMNlpHamk1MS8rOVhmU2c4MlNxT3YvTDZKOEZlTkhEbC81bVY0eFJPOUlNYm5OVXZNWXpVSWpoMjB3THVzVWFYbDJVZlh6MTNVZmxEdmttK3hmRlB2dzRnL1craUE4ZXNUanZqVlpVS0dSalZJaE5wMTgzRzh3MjZ0ZDNqVGRvOTRlNkt4RVorVzB6cjJrOXFxckdkNDdZcm1uSE56Q21GZ2QydzZaeU1VYmRRZ0grYmk1S3h4bkxNWHhFTnlPYXRvSWRTNEoyakZ5MVFMQnJ4c3YxMDdhOGZKb2ZaT3VLYmNpTjYyWUFDWVRuV2hlWDVzeGpNK0x0MkYvdTZQOU1qc2o2OHZhT3ZRWGkwd0lkRW1KMm5XSXVIYlNIWlBuK241bHFkTFlDQnRRRTZPbWJqRmhOYXNubGljZnE1cFl5Nkk0TE40YXB4TVM3NGdRbmhHY2FlVkNQVFQ2Qk9yYTFqdzBkTWNyTVNDNE81TVIwWmhzZGhLSzQ1TE1RTWtncE5QR1YydERsSkxtcnRzeVhid1ZQcEhVS3p0MU9KZG5Wd2UwTEpnenhoMFpxaWdvaXl5RW9QU09wMzBBVHNEVURzWG9LZnY1Z1lIUG4zK0lxaStla2FMSGh5ZHNBcVZZci9jK1JwZkJ6Nk9nVnp4WUlaalB4dVhYVHhmOTh5bk5xbDgvSFQvTHNQNVU3YStmVHA4WnJ3MnowaXVZNmdiTEo0eE1wbXJycW4wbEJIeHVmQ1A0QkJqSWcxRytUN0RScmZyMENvVjJoL3g1eTVjTVROVDJXUXhUREJaUGFFQmVtUm1HcHBjSkdFVWFKS0lxbjV0OHFNKzJlUm9tZkNRelBhL1NPQWNLblZ5YjlKb0oxSWpTUU8xNHdOS2tySFlqb3pyczRzMVVWWUViRDZZeGM0WE15QUxBREk1SjVVREYrWWNyRklOalRheVBZNzFySDNMM1FyUCs2akRDS3cyRjR1N25YQ0xUNjllYXhSc3p5YmFCbTNsb0grcHdmMDBjaTdpS25ITDNiYnJ6TEg1d2NHTTZzQ0NqRThXa2dhd0xxSklHTjYzMmIzeW40bFR2VytZRDBpU0xOOGpsRWQ2SzEzNnFEaUorUkIreXpzRkxIV1VXd0l2MlhuUDVhKzRoendhaDZJVW5pNElrYStnb2pBNEw5WUxhc2JUR092Ymg2bGxFNmpNMDUxcllIVnF1ZG5HaUNITE9sT2t2R28rai9GM2pNVkVOUlpjdnhpaCtjSktlbktidm5KNWFXVmdSM0pUaXFXRlEwdmZneHFPZVJRMnlTbzZzK2xxMVo0R3J1QmFCK2l0eFluVndmR3ErZUlQT2ttbU9xanlMbkpnWkhEN3M0ZWlnTUhYb1YxcjhMNTl4UEFBbkJxZ2tlRDVuRWdtT09iQjRRNXNqeGxtTW5CRm9vRnNYV3p0Y1l2VTJQMUNydlc1NDhYaHplWlJlOW81OXpNNDJvRExqQ293VGtMaFVBVms1Mk5yUTk2ZytOL3ZGMjN6SWt1MVNyYVlUNXhLVElQU25uT2lUZGJLcU9XdkRLcDNmblplYnJXRm4zdGFhSkdabVlrSzBpRlVYOExaQ0ZwbGhoMGZwd1hURjR1MGc4bm03WGRhK3I2T0JJaU5iTjFGb1JkSTR2MjYwYmJzRXpiM1oyazJDVzlzMm1GVXNFYmNYM3hmN09SZkVQR0hMUkQxTWlNRVppN2ZOYlhDdGpZZDNoU1NGRmFWTzkvcElOL2U1MFF0clFIVGcrY3VteVlxTkxSNnFyYkxXS0gyK1NJRjhCbWVVZVZ6Y1lYaVlCNS9DaWNXYmZsTUpJWTU5Y1dBMndvbTZKOVcydjlybUVham9vNzlpTlJVZWxqSko2VkZNamwyL2RCaGhrSkZSWklFSzZHb3QwalhMTU1BREk0d0NBRDJyb1RwUTl3Z054Qkd3NFBUMDMxNGxhUkNUSEl4cmhvYVVlL1ZGVjlDME0vTEFFYVhSb1duVjJNTmNGUmltRXhadlFEVjRlb1R4UjZQUENBelpSTFZvK3JLaDFwNkVNZlljQzk0ZDdHc01PUnFheWJhZzBrSDgya25qT0lFRlZwSitSUGJpN2VleFRZY2YxQ1JuNXJRaDgxSmlTUFFwdlU1VnVOZkdVMGJlQTZHdmo1Ynk4Qmxpaml3TWx0SFExcXJqRGNiMmhjb2RreHlWV1p3VVFWMDd1anJKbGpHZVdJQXAraFhtVzVxNUxJY3FscHU1T1hnb0QwcDJiSzBJVmhwclhFZFkycDNWb1pQWjRLWHJoNlljVFRQZEtPbWdwSk9rcFJPT3A5VmdCSTdqZTNzTkRkanFmbHpSclhmQjdzNUtHWStsUXZnV2owR1poQVJXRHFxWGFmSmxKM0ZVSFJtYW1OK3prOTgyV0RHNmF3M1ZsZ0FzdS9WWXg5dlVPc2tNS2pBM1JyZ0FRVmh5QnMwQkdkYW4vUXhDT2xXUzlKclE2VDNsZ1FhZ1Q4Um42cUgzVnM3NXhIbFdtWldjeStOSmRTUkhkRVhnK0d0TjVWUmFWVnVadWNLOEF4YU1jWUVYalp6T0x4eUs2L3NyRWVMY3cxdHB1VytZbURNclhjZ1hEclI2cXM1bTQrVGllTlovVW9WaFJqK2pnQU5zNk8yUExkYUpnMG1hRHlJZUVnT1Rpa0trTEFoY2dXSml5RFpjWDg2bksxajNLQ1ZzZFJLUGNDRmVLdUZnbDJLQ2tGcWRMOTVHVVNPaGNQekFhY2ZwdkM2YU9jRXB2YjFHNWhLOTdKbGxuOW02ZHJncU56VUNQWE82bnVlMVBSdUpDZkxoaGxraWF5V2hseXFxdlhoekRacU54UFVXc1RSOVJ2bFlwb3VZYWRra2VKQ2o3OC9SQm1oTDBaWWVqeFJwVDBpeWllODAxYzBqUmFGMVRockgxWlEyZ3ladFlNM2tiS3RNNXpvSTVjbml0VU8wY2szeVRoZG5mNk1qNS9KK01WMGxUamRXZHhHRmlRS3JNaUQ1b3RWRUxSZFlseUFORnZYNXBMUTBkUEgyWU1wVUc5QUc5MnQyd0h3dUsyOXBneDMwZzJCdWxjME55MVpZZ0oyVG9pbm9pb3REYlM0ZGdhQUdRTHhBL3MvbytUTTQ1UklkSmpsKyt3YW5vYm84NC9ZWnZhZWxpNlJyeVI0SjljeitGRTZKL3hXY2lsK0t3Z3RPdWIrRTB4dDFENWx2VURySk04RGwzUGdqbEw3bWZvRFMvZmhmNExSNCt4RVN1ZWx2QXVJRmxzUGt0ZWJJVGFIdVdncE02K0JXb05HRlR2MmJtanlsRFlTcGhocm1yczVkWlVaODJRQk1zdjhYZHRQaFArNVpDZ1FjdUIvOVQyQ3pZMU4vMUduZkhYb3FTbVpaWEcrMHJWZEJtSmprUHNDaWgzSEdHRXlQSnJQeDZ2NHdrYlE4SDlhR25PUnBjQ3d5aHBjbmhaOHFna2VidnFlalNqMUlRckhoZEd0ekZWZStwbHpGeFp0L2xXZTVtT1F4Rm1Na3lZLzc2U3AyZnJUMHJDTURIbDYxcFhCMUtrMmtaUzdXZVZLZExDM21GdVBNS2Q3NFdZQVBzak1GQjREQ2tnd0tXZ2lGdUtlT0Z3TE5WV3ZBblZPblUxaEUxMEtjT2NjK2N5Vk83cndoU3NrNjFselRBYUhpSk1iNnRCbUtVNWl2N1JVMmhSSk1JZnVrSjRkemlqSVg0YWF6U0J3UW05NHV5MGJndWVpWUtJQUN0NU9GamFvcHd2NEJYNUlpVno2U1NuRlh5ajI2cnM5WVNZNEZSbnF3dU0rOW1lN0JRQkpqUDlqQjQ3aEZCNzRSUkk2TDlXUDJBMndDbHFFaFRsOCtnRWgrQVNUREF1RUpuaUI1SG1Ca3NQNEFQd2dQeUFpZEEzT1B6dW4ySzNTNUxKM0pBcFBZRFIya1JmMzNvT3Z1M2x5WUlVVGg0Tno5cC9Gai9ERkNmNlNCdnZ0S1pSN3VQZ1EwOVVMa3dXMGNwZVFGNlJyTnlLUG9xYkFzb3BNd0EvZHIvbkdGQytPLzBEMHJISFNUUGk3ZUxoZjBjZFJWVkdIQkJ4aXJhNDZIUjh2Z3pBOURhOWwwbWU2MS9ScXdtemxuQ21UZ25mVzRIMSs3NURTZGpId0ZqQTNkd1VLSytxR1g1MWgwSTdEb0RwTmpMVmhyZnIxK0hqUVBVdVdLNlQxUVlHd2ZhUld3U1FKUElaSStPdVJsd084MUxjdEZWMHcrYnFubncrSXROY0tvRkxsVi9aQUVGUUdLUTRyUXdscDYydDRIWUdLMHQ1RUZzZDR2TlFVbXFxUW5XWGJPcTZrVTlPV1IwQ1ZaYVp5MFdkNDZHT09pWCt4OVh5Z254aHpDMVdIR2dwaks5TTAydXZ2ek1BMWxlTDlWaDl1ODRvVE5URzB2ZzlvU21wOHlScmNtdC9INk50YjlrQkQzR3ZwdXFVNStIbHg0WTh1NjkzTjJ2eDVqK2xGU2h6aUpIS0VTSnJiWTcvZUhERHlLUk5FSmFjL1o3VzBJTERYYVh4ejFHSittUzh3UURzSERESVlLWFdjbkswWjg4bS9jdXBYY2lYSEdLYUNpMmIzZHp2RnRiUzJUZ3lRRGl3dkZVNU9ubnNDaUtvWGRiZnNZbVlGdDUrVmNSZkxpYlJ1MW1LUTlTTEk2MGQyaHBwdDA4NkFOaHZNd0xtaDk4VytDQ3J2SklhajAwamRRT1hwc2pvK0V0ZHFYU2NBcm1WZXVwR3orZndvcTgzK0R5dlYvQlNycGwvUGpFMVNjdjdEYnhjY3A5QWtuVUtaL0FDZ1BXaDl2blg3QWpIMTgyTmRScTlEN3pYSytEeExwUTR2UGR3RUFVWXp6dTZZK0Rwd1lFUkk0UmFrdUF2WXhKZmhrT0ExdllUcG8ydVdhUUdyYVBaN1BlQmZCUTZEYnoySjdyWkVZRkJYczBRTGNiZ3JER3Bmai9UZ0lFUy8xdmRsZjJGSkVSS0srMGpKNmpjOTdMQWpBTWQ5RU90VlQvTGcxYjY1SnhHN1FETWZTMkhlU29Pak40ZzBEZnNYMXNCTjNhM1lHR1lrUzNJdzRjbFp1RVNIQUpDa3VUanl5SW5XRHFxY3dPUnNsU2xtM3dZL0NRQlQ3QzdGTnIzcDdTSHdJQlhvZHQ1b3QzQW5GSDViK0kyWWxzTmV2VlNnemxnUkcxcExsZmpvOHdwVS9zenJaY0ZqQldMTXhGZlJWVWRuTlNUT2sySzRDUElRd2pwMnhDNmYyOFd3Vk1VNGR6a2pITkFicXBOVlhRTUhYbzgvK0paalFYNkVFOW1oL0FKTm52L0hSTlVFK1VVMlBvNUJ6c0lOd3ZrYkQrVm1zbjZWYVp0WDFVZWQ2V1pleFoxY0d3ZmRiWDZaWHd0aHFQZGFjenViR0w4ME5DWU12Y2YzRXp2T2ZuKzFmUnczVDUvSmJDSThXRmE2ZHQ1YTdiM09qS1V6RjdaUVZnZ2IwZEIwck51eVFaVXpKaVRUZ0Q0NnNOdzdlMWZSOHdoV1B6TUxEZ2JYQktUdHZhNnhCQWhOcXg0N09xcjJjcE10R1Y2a0dTekFNSXAwSHRQa2E2clhxRHhjMmFqeWpQaVhVd01GZUFUc1V6c3kxd1ZYb21LVTgxK0kyOXJuNmZsKzg0U29YUllXYlc5S2dYR0ZQZWRnd2N5bUcwcEZkM3NRVmVoN1VPWitidTluY0RrTmVlVzRzU1VLOHFucFdiUDJyVGxiMUJUZFlvb0h4cEoxYlRyWlhwZUxObVJuS2dwZGpqVnRRdXIwK1g1V2h2ckVKMDEzdEJ6U3ZnY0F1aThwc081Ym5JNTA5N3FLTkU1M1d4MmhQQ0tmRld5bVl4Tkl5MGJaTHp4Nm1sQWJmanBSWlJWd3JvTVNNa1ZUVGtCY3F1MW1qVHE3Vm41N3RrZTl2N3BCdmIvTyt2K2Q3ZmRGNGZYUjV2b0wvOFdQTWZ3QnBxMVIvIiwiVGhyZWVEU1ZlcnNpb24iOiIxLjAuMiIsIkNhdnZBbGdvcml0aG0iOiIyIiwiUEFSZXNTdGF0dXMiOiJZIiwiU2lnbmF0dXJlVmVyaWZpY2F0aW9uIjoiWSJ9fSwiQWN0aW9uQ29kZSI6IlNVQ0NFU1MiLCJFcnJvck51bWJlciI6MCwiRXJyb3JEZXNjcmlwdGlvbiI6IlN1Y2Nlc3MifX0.af-V588Tn6qLhlXMM4Rp33dJpnmoOhsDrJ2uQ2pTkV0",
    "threeDSecure": {
        "authenticationSource": "2",
        "cryptogram": "AAABAWFlmQAAAABjRWWZEEFgFz8=",
        "ecommIndicator": "05",
        "xid": "alp4UklQNnZvSWkyaEViaHQxaDA=",
        "programProtocol": "1"
    }
}

THREE_D_SECURE_FAILURE -

Payload

{
    "event": "THREE_D_SECURE_FAILURE",
    "sessionId": "d2bd267d446f47bf9940464f27af269f",
    "jwt": "...",
    "extendedData": {
        "CAVV": "AAABAWFlmQAAAABjRWWZEEFgFz8=",
        "ECIFlag": "05",
        "XID": "alp4UklQNnZvSWkyaEViaHQxaDA="
    }
}

THREE_D_SECURE_ERROR -

Payload

{
    "event": "THREE_D_SECURE_ERROR",
    "sessionId": "d2bd267d446f47bf9940464f27af269f",
    "jwt": "...",
    "extendedData": {
        "CAVV": "AAABAWFlmQAAAABjRWWZEEFgFz8=",
        "ECIFlag": "05",
        "XID": "alp4UklQNnZvSWkyaEViaHQxaDA="
    }
}

Risk Assessment

RISK_ASSESSMENT_READY - If risk is used, this will notify the integrator when risk data collection is ready on the client side. Only used when you only use Risk and no 3DS.

Payload

{
  riskSessionId: '<IDENTIFIER>'
}