Class: Transpayrent

Transpayrent(url, config)

The Transpayrent SDK simplifies the strong consumer authentication (SCA), payment authorization and secure card storage using tokenization through the consumer's browser while handling PCI DSS compliance. The SDK handles the secure communication with Transpayrent's Payment Gateway including automatically retrying requests in case of communication failures and orchestrates the integration into 3 simple steps for the scenarios summarized in the table below.

Authorize Payment Store Payment Card 3rd Party Wallet
The payment maybe be authorized for a payment transaction using the card details entered by the consumer in the following simple steps:
  1. Create a new payment transaction
  2. Authenticate the consumer using 3D Secure or equivalent
  3. Authorize the payment for the payment transaction
 The consumer's payment card may be securely stored in Transpayrent's Secure Vault and added to the consumer's wallet in the following simple steps:
  1. Create a new payment transaction
  2. Authenticate the consumer using 3D Secure or equivalent
  3. Save the consumer's payment card
 The payment maybe be authorized for a payment transaction using a 3rd party wallet such as Apple Pay, Google Pay or MobilePay Online in the following simple steps:
  1. Create a new payment transaction
  2. Initialize Payment with 3rd party
  3. Authorize the payment for the payment transaction

Please note that the SDK is intended to communicate directly with Transpayrent's Payment Gateway to handle PCI DSS compliance for authentication and authorization.

The SDK handles the authentication by orchestrating the calls to several methods internally and automatically performing the following actions if required:

The look'n'feel of the Lightbox for the authentication challenge and payment initialization flow may be fully customized using CSS simply by passing the appropriate iframe configuration when invoking the SDK's authenticate or initialize methods.
The SDK includes methods for performing each part (initialization, authentication and verification) of the strong consumer authentication process but it's strongly recommended to use the authenticate to orchestrate the process.

Additionally the SDK provides several helper methods, which may be used to streamline the user experience for the following scenarios:

The code sample below provides a complete illustration of how the payment page should use the SDK to create a new payment transaction, authenticate the consumer, securely store the payment card and authorize the payment using the stored card for a payment transaction.
The same flow may also be used to complete the payment for a payment transaction using a 3rd party wallet such as Apple Pay, Google Pay or MobilePay Online.
Please note that the sample assumes a payment session has already been created. 

 <script src="https://storage.googleapis.com/static.[ENVIRONMENT].transpayrent.cloud/v1/swagger-client.js"></script>
 <script src="https://storage.googleapis.com/static.[ENVIRONMENT].transpayrent.cloud/v1/transpayrent.js"></script>
 <script>
     var transpayrentConfig = {
         merchantId: [UNIQUE MERCHANT ID ASSIGNED BY TRANSPAYRENT],
         sessionId: [ID IN THE RESPONSE FROM "Create Payment Session"],
         accessToken: '[x-transpayrent-access-token HTTP HEADER IN THE RESPONSE FROM "Create Payment Session"]'
     };
     var url = 'https://generator.[ENVIRONMENT].transpayrent.cloud/v1/'+ transpayrentConfig.merchantId +'/system/PAYMENT_GATEWAY/sdk/CLIENT';

     var card = { card_number: 4111111111111111,     // Successful Authorization: Manual Challenge with browser fingerprint
                  expiry_month: 9,
                  expiry_year: 22,
                  cvv: 987,
                  card_holder_name: 'John Doe',
                  save: true };
     var address = { street : 'Arne Jacobsens Allé 7',
                     appartment : '5. sal',
                     city : 'Copenhagen S',
                     postal_code : '2300',
                     state : '82',
                     country: 208 };                 // Denmark
     var phone = { international_dialing_code: 45,   // Denmark
                   phone_number: 89671108 };
     var email = 'hello@transpayrent.dk';
 
     var sdk = new Transpayrent(url, transpayrentConfig);
     card.payment_method_id = sdk.getPaymentMethodId(card.card_number);
     var createTransactionRequests = new Array();
     // Card based payment
     createTransactionRequests[card.payment_method_id] = { correlation_id : 'TP-'+ transpayrentConfig.sessionId,
                                                           amount: { currency : 208,          // DKK
                                                                     value : card.save ? 0 : 100 } };
     // Transpayrent - Consumer Wallet
     createTransactionRequests[201] = { correlation_id : 'TP-'+ transpayrentConfig.sessionId,
                                        amount: { currency : 208,          // DKK
                                                  value : 100 } };
     // MobilePay Online
     createTransactionRequests[202] = { correlation_id : 'TP-'+ transpayrentConfig.sessionId,
                                        amount: { currency : 208,          // DKK
                                                  value : 100 } };
     
     var initializePaymentRequests = new Array();
     // Card based payment
     initializePaymentRequests[card.payment_method_id] = { payment_method_id : card.payment_method_id }
     // Consumer Wallet
     initializePaymentRequests[201] = { payment_method_id : 201 }
     // MobilePay Online
     initializePaymentRequests[202] = { payment_method_id : 202,
                                        mobile : phone,
                                        save : false };
     
     var authenticateConsumerRequests = new Array();
     // Card based payment
     authenticateConsumerRequests[card.payment_method_id] = { payment_details : card,
                                                              billing_address : address,
                                                              shipping_address : address,
                                                              contact : { mobile : phone,
                                                                          work : phone,
                                                                          home : phone,
                                                                          email : email } };
     
     var authorizePaymentRequests = new Array();
     // Card based payment
     authorizePaymentRequests[card.payment_method_id] = card;
     // Consumer Wallet
     authorizePaymentRequests[201] = { payment_method_id : 201,
                                       valuable_id : [VALUEABLE ID IN THE RESPONSE FROM "Create Payment Session"],
                                       access_token : '[MERCHANT'S SINGLE SIGN-ON TOKEN FOR AUTHORIZING A PAYMENT WITH THE CONSUMER'S WALLET]' };
     // MobilePay Online
     authorizePaymentRequests[202] = { payment_method_id : 202 };

     var saveCardRequest = { payment_details : card,
                             consumer_id : '[MERCHANT'S CONSUMER ID FROM PAYMENT SESSION]',
                             name : "My VISA Card" }
     
     var paymentMethodId = 202;  // CHANGE THIS TO CONTROL WHICH PAYMENT METHOD IS USED

     // Create payment transaction using the specified payment method
     sdk.createTransaction(paymentMethodId, createTransactionRequests[paymentMethodId])
     .then(
         transaction => {
             // Creation of Payment Transaction failed - Display status message
             if (transaction.status) {
                 alert('API: '+ transaction.api +' failed with HTTP Status Code: '+ transaction.status +' and error: '+ transaction.messages[0].message +'('+ transaction.messages[0].code +')');
                 return Promise.reject(null);
             }
             else {
                 var iframeConfig = { container : document.getElementById('container'),
                                      css: 'initialization',
                                      callback : function (event, iframe) {
                                          switch (event) {
                                              case 'payment-initialization-initiated':
                                                 document.getElementById('loader').style.visibility = 'hidden';
                                                 break;
                                              case 'payment-initialization-completed':
                                                 document.getElementById('loader').style.visibility = 'inherit';
                                                 break;
                                          }
                                       } };
                 return sdk.initialize(transaction.id, initializePaymentRequests[paymentMethodId], iframeConfig);
             }
         })
       .then(
         initialization => {
              // Initialization of Payment Transaction failed - Display status message
             if (initialization.status) {
                 alert('API: '+ initialization.api +' failed with HTTP Status Code: '+ initialization.status +' and error: '+ initialization.messages[0].message +'('+ initialization.messages[0].code +')');
                 return Promise.reject(null);
             }
             // Payment Transaction is exempt from Strong Consumer Authentication (SCA)
             else if (sdk.isSCAExempt(paymentMethodId, createTransactionRequests[paymentMethodId].amount, card.save) ) {
                 return Promise.resolve(initialization);
             }
             else {
                 var iframeConfig = { container : document.getElementById('container'),
                                      css: 'challenge',
                                      callback : function (event, iframe) {
                                          switch (event) {
                                              case 'authentication-challenge-initiated':
                                                 document.getElementById('loader').style.visibility = 'hidden';
                                                 break;
                                              case 'authentication-challenge-completed':
                                                 document.getElementById('loader').style.visibility = 'inherit';
                                                 break;
                                          }
                                      } };
                 return sdk.authenticate(initialization.transaction_id, authenticateConsumerRequests[paymentMethodId], iframeConfig);
             }
     })
     .then(
         authentication => {
             // Consumer Authentication failed
             if (authentication.status) {
                 // Consumer failed authentication challenge
                 if (authentication.status == 511) {
                     alert('Consumer failed authentication challenge for payment transaction: '+ authentication.transaction_id +' with error: '+ sdk.getStatusMessage(authentication.status_code) +' ('+ authentication.status_code +')');
                 }
                 // API request failed - Display status message
                 else {
                     alert('API: '+ authentication.api +' failed with HTTP Status Code: '+ authentication.status +' and error: '+ authentication.messages[0].message +'('+ authentication.messages[0].code +')');
                 }
                 return Promise.reject(null);
             }
             // Payment Transaction is exempt from Strong Consumer Authentication (SCA)
             else if (sdk.isSCAExempt(paymentMethodId, createTransactionRequests[paymentMethodId].amount, card.save) ) {
                 return sdk.authorize(authentication.transaction_id, card);
             }
             // Consumer Authentication succesfully completed: Save Payment Card
             else if (card.save) {
                 saveCardRequest.card.cryptogram = authentication.cryptogram;
                 return sdk.save(authentication.transaction_id, saveCardRequest);
             }
             // Consumer Authentication succesfully completed: Authorize Payment
             else {
                 card.cryptogram = authentication.cryptogram;
                 return sdk.authorize(authentication.transaction_id, card);
             }
         })
     .then(
         save => {
             // Payment Card attempted saved
             if (100 < paymentMethodId && paymentMethodId < 200 && card.save) {
                 // Saving Payment Card failed - Display status message
                 if (save.status) {
                     alert('API: '+ save.api +' failed with HTTP Status Code: '+ save.status +' and error: '+ save.messages[0].message +'('+ save.messages[0].code +')');
                     return Promise.reject(null);
                 }
                 // Payment card succesfully saved and added to the consumer's wallet
                 else {
                     var request = { payment_method_id: 201,            // Consumer Wallet
                                     valuable_id : save.valuable_id,
                                     access_token : authorizePaymentRequests[201].access_token }
                 
                     // Create new transaction for authorizing a payment with the stored card
                     return sdk.createTransaction(request.payment_method_id, createTransactionRequests[request.payment_method_id])
                         .then(
                             transaction => {
                                 // Creation of Payment Transaction failed - Display status message
                                 if (transaction.status) {
                                     alert('API: '+ transaction.api +' failed with HTTP Status Code: '+ transaction.status +' and error: '+ transaction.messages[0].message +'('+ transaction.messages[0].code +')');
                                     return Promise.reject(null);
                                 }
                                 // Authorize the payment for the payment transaction using the consumer's stored card
                                 else {
                                     return sdk.authorize(transaction.id, request);
                                 }
                             });
                 }

             }
             // Payment authorization
             else {
                 return Promise.resolve(save);
             }
         })
     .then(
         authorization => {
             // Payment Authorization failed - Display status message
             if (authorization.status) {
                 alert('API: '+ authorization.api +' failed with HTTP Status Code: '+ authorization.status);
             }
             // Payment Authorization completed - Display success message
             else {
                 alert('Payment transaction: '+ authorization.transaction_id +' successfully authorized');
             }
         })
     .catch(reason => {
         // Low level error - Display error message
         if (reason) {
             console.error(reason);
         }
     });
 </script>

Constructor

new Transpayrent(url, config)

Creates a new instance of the Transpayrent SDK, which simplifies the strong consumer authentication (SCA) and payment authorization through the consumer's browser.

Parameters:
Name Type Description
url String

The URL pointing to the Payment Gateway's OpenAPI service definitions.
config BaseConfig

The base configuration for the API requests.
Version:
  • 1.5.2
Copyright:
  • Transpayrent ApS 2022
License:
  • Common Transpayrent API license
Source:
See:
Example

Instantiate the Transpayrent SDK

 <script src="https://storage.googleapis.com/static.[ENVIRONMENT].transpayrent.cloud/v1/swagger-client.js"></script>
 <script src="https://storage.googleapis.com/static.[ENVIRONMENT].transpayrent.cloud/v1/transpayrent.js"></script>
 <script>
     var transpayrentConfig = {
         merchantId: [UNIQUE MERCHANT ID ASSIGNED BY TRANSPAYRENT],
         sessionId: [ID IN THE RESPONSE FROM "Create Payment Session"],
         accessToken: '[x-transpayrent-access-token HTTP HEADER IN THE RESPONSE FROM "Create Payment Session"]'
     };
     var url = 'https://generator.[ENVIRONMENT].transpayrent.cloud/v1/'+ transpayrentConfig.merchantId +'/system/PAYMENT_GATEWAY/sdk/CLIENT';
     var sdk = new Transpayrent(url, transpayrentConfig);
 </script>

Methods

authenticate(transactionId, body, config) → {AuthenticationSuccessResult|AuthenticationFailureResult|Status}

Convenience method for authenticating the consumer of the specified payment transaction through the Transpayrent Payment Gateway using 3D secure or equivalent.
The method orchestrates each part (initialization, authentication and verification) of the strong consumer authentication process by calling several methods internally in the SDK and automatically performs the following actions if required:

The look'n'feel of the authentication challenge may be fully customized using CSS simply by passing the appropriate iframe configuration as the 3rd argument to this method.
This is the 2nd method that should be called by the payment page.
Please note that:

  • Calling createTransaction should be done prior to calling this method to create a new payment transaction and obtain a transaction id
  • Calling this method is the recommended way to complete the strong consumer authentication (SCA) flow
  • The method will register event listeners and listen for the following events:
    • 3DS-authentication-complete
    • 3DS-fingerprint-complete
  • API calls made using this method falls under PCI DSS.
Parameters:
Name Type Description
transactionId Long

The unique id of the payment transaction for which strong consumer authentication using 3D secure or equivalent is required
body AuthenticateConsumerRequest

A representation of the entered payment details required for strong authentication of a payment transaction using 3D Secure or equivalent. Please note that the browser property will be constructed automatically.
config IFrameConfig

The configuration for the iframe which will be constructed in case the consumer needs to be presented with an authentication challenge
Source:
See:
Listens to Events:
  • message:'3DS-fingerprint-complete'
  • message:'3DS-authentication-complete'
Returns:
Type
AuthenticationSuccessResult | AuthenticationFailureResult | Status
Example

Authenticate consumer with 3D Secure or equivalent using the Transpayrent SDK

 var card = { payment_method_id: 108,            // VISA
              card_number: 4111111111111111,     // Successful Authorization: Manual Challenge with browser fingerprint
              expiry_month: 9,
              expiry_year: 22,
              cvv: 987,
              card_holder_name: 'John Doe',
              save: true };
 var address = { street : 'Arne Jacobsens Allé 7',
                 appartment : '5. sal',
                 city : 'Copenhagen S',
                 postal_code : '2300',
                 state : '82',
                 country: 208 };                 // Denmark
 var phone = { international_dialing_code: 45,   // Denmark
               phone_number: 12345678 };
 var email = 'hello@transpayrent.dk';
 var body = { payment_details : card,
              billing_address : address,
              shipping_address : address,
              contact : { mobile : phone,
                          work : phone,
                          home : phone,
                          email : email } };
 var iframeConfig = { container : document.body,
                      css: 'challenge',
                      callback : function (event, iframe) {
                          switch (event) {
                              case 'authentication-challenge-initiated':
                                  // DO SOMETHING BEFORE THE AUTHENTICATION CHALLENGE IS DISPLAYED
                                  break;
                              case 'authentication-challenge-completed':
                                  // DO SOMETHING AFTER THE AUTHENTICATION CHALLENGE IS COMPLETE
                                  break;
                          }
                      } };
 sdk.authenticate(transaction.id, body, iframeConfig);
 .then(
     authentication => {
         // Consumer Authentication failed
         if (authentication.status) {
             // Consumer Authentication failure
             if (authentication.status == 511) {
                 // HANDLE AUTHENTICATION FAILURE
                 return Promise.reject(null);
             }
             // API request failed - Display status message
             else {
                 // HANDLE COMMUNICATION ERROR
                 return Promise.reject(null);
             }
         }
         // Consumer Authentication succesfully completed
         else {
             // AUTHORIZE PAYMENT BY INVOKING METHOD: authorize
         }
     })
 .catch(reason => {
     // Low level error - Display error message
     if (reason) {
         console.error('Internal error: '+ reason);
     }
 });

authenticateConsumer(transactionId, body, attempt) → {AuthenticationSuccessResult|AuthenticationChallengeResult|AuthenticationFailureResult|Status}

Authenticates the consumer of the specified payment transaction through the Transpayrent Payment Gateway using 3D secure or equivalent by invoking the Authenticate Consumer API. The method will automatically retry authentication of the consumer for the specified payment transaction up to 5 times in the following scenarios:

  • HTTP Status Code: 409 - Conflict: Cached Payment Transaction not yet updated with authentication data
  • Low level communication error
    Calling this method directly is not recommended, instead call method: Transpayrent#authenticate to orchestrate the complete flow for strong consumer authentication (SCA).
    Please note that API calls made using this method falls under PCI DSS.
Parameters:
Name Type Description
transactionId Long

The unique id of the payment transaction for which strong consumer authentication using 3D secure or equivalent is required
body AuthenticateConsumerRequest

A representation of the entered payment details and details of the consumer's browser attributes required for strong authentication of a payment transaction using 3D Secure or equivalent.
attempt Integer

The current attempt at authenticating the consumer for the specified payment transaction, defaults to 1
Source:
See:
Returns:
Type
AuthenticationSuccessResult | AuthenticationChallengeResult | AuthenticationFailureResult | Status

authorize(transactionId, paymentDetails, attempt) → {AuthorizePaymentResponse|Status}

Authorizes the payment for the specified payment transaction through the Transpayrent Payment Gateway using the provided payment details by invoking the Authorize Payment For Transaction API. The method will automatically retry authorization of the payment for the specified payment transaction up to 5 times in case of communication issues.
This is the 3rd method that should be called by the payment page when authorizing a payment without storing the consumer's payment card.
Please note that:

  • Calling authenticate should be done prior to calling this method to authenticate the consumer and obtain a cryptogram
  • Call save prior to calling this method to securely store the consumer's payment card in Transpayren's Secure Vault and add the stored payment card to the consumer's wallet
  • API calls made using this method falls under PCI DSS when authorizing the payment for the payment transaction using a payment card.
Parameters:
Name Type Description
transactionId Long

The unique id of the payment transaction for which the payment should be authorized
paymentDetails PaymentDetails

A representation of a payment details (card details, wallet details, voucher details etc.), which will be used to authorize the payment for the payment transaction
attempt Integer

The current attempt at authorizing the payment for the specified payment transaction, defaults to 1
Source:
See:
Returns:
Type
AuthorizePaymentResponse | Status
Examples

Authorize payment with payment card details using the Transpayrent SDK

 var card = { payment_method_id: 108,            // VISA
              card_number: 4111111111111111,     // Successful Authorization: Manual Challenge with browser fingerprint
              expiry_month: 9,
              expiry_year: 22,
              cvv: 987,
              card_holder_name: 'John Doe',
              save: true,
              cryptogram : [CRYPTOGRAM RETURNED BY STRONG CONSUMER AUTHENTICATION] };
 var body = { payment_details : card }
 sdk.authorize(authentication.transaction_id, body)
 .then(
     authorization => {
         // Payment Authorization failed - Display status message
         if (authorization.status) {
             // HANDLE AUTHORIZATION FAILURE
         }
         // Payment Authorization completed - Display success message
         else {
             // HANDLE AUTHORIZATION SUCCESS
         }
     })
 .catch(reason => {
     // Low level error - Display error message
     if (reason) {
         console.error('Internal error: '+ reason);
     }
 });

Authorize payment with stored payment card using the Transpayrent SDK

 var request = { payment_method_id: 201,            // Consumer Wallet
                 valuable_id: [VALUABLE ID RETURNED BY SDK METHOD: save] };
 sdk.authorize(save.transaction_id, request)
 .then(
     authorization => {
         // Payment Authorization failed - Display status message
         if (authorization.status) {
             // HANDLE AUTHORIZATION FAILURE
         }
         // Payment Authorization completed - Display success message
         else {
             // HANDLE AUTHORIZATION SUCCESS
         }
     })
 .catch(reason => {
     // Low level error - Display error message
     if (reason) {
         console.error('Internal error: '+ reason);
     }
 });

copyToClipboard(text)

Copies the specified text to the clipboard using the Clipboard API.
The method will gracefully fallback to the deprecated execCommand function.

Parameters:
Name Type Description
text String

The text that will be copied to the clipboard
Source:

createTransaction(paymentMethodId, body, attempt) → {CreatePaymentTransactionResponse|Status}

Creates a new payment transaction through the Transpayrent Payment Gateway by invoking the Create Payment Transaction API. The method will automatically retry creation of the payment transaction up to 5 times in case of communication issues.
This is the 1st method that should be called by the payment page.

Parameters:
Name Type Description
paymentMethodId PAYMENT_METHOD_ID

The unique id of the payment method which will be used to authorize the payment for the payment transaction.
body CreatePaymentTransactionRequest

A representation of the consumer's payment transaction.
attempt Integer

The current attempt at creating the payment transaction, defaults to 1
Source:
See:
  • Transpayrent#sleep
Returns:
Type
CreatePaymentTransactionResponse | Status
Example

Create a new payment transaction using the Transpayrent SDK

 var paymentMethodId = 108;                      // VISA
 var body = { correlation_id : 'TP-103645',
              amount: { currency : 208,          // DKK
                        value : 100 } };
 sdk.createTransaction(paymentMethodId, body)
 .then(
     transaction => {
         // Creation of Payment Transaction failed - Display status message
         if (transaction.status) {
             // HANDLE FAILURE
             return Promise.reject(null);
         }
         else {
             // AUTHENTICATE CONSUMER BY INVOKING METHOD: authenticate
         }
     })
 .catch(reason => {
     // Low level error - Display error message
     if (reason) {
         console.error('Internal error: '+ reason);
     }
 });

displayChallenge(url, data, config) → {HTMLIFrameElement}

Constructs the iframe element for displaying the authentication challenges and attaches it inside the provided container element.

Parameters:
Name Type Description
url String

The URL to the Access Control Server (ACS) will use for the challenge during the strong consumer authentication (SCA) process.
data String

The base64 encoded request data that must be sent to the Access Control Server (ACS). The data will be sent to the ACS in the creq field.
config IFrameConfig

The configuration for the constructed iframe element
Source:
Returns:

The constructed iframe element

Type
HTMLIFrameElement

displayPaymentButton(paymentMethodId, …args)

Displays the payment button for the specified payment method. Clicking the payment will display the payment sheet for a 3rd party wallet such as Apple Pay or Google Pay.

Parameters:
Name Type Attributes Description
paymentMethodId PAYMENT_METHOD_ID

The payment method selected by the consumer
args any <repeatable>

Arguments passed to TranspayrentGooglePayHelper#displayPaymentButton
Source:
Example

Display the "Buy with Google Pay" button using the Transpayrent SDK

 var container = document.getElementById('payment-methods');
 var paymentMethods = new Map([
          [ 203, 'Google Pay'],
          [ 103, 'VISA Dankort'],
          [ 107, 'Maestro'],
          [ 108, 'MasterCard'],
          [ 109, 'VISA'],
          [ 110, 'VISA Electron'] ]);

 // Display the Payment Sheet for Google Pay
 // See: https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
 function onGooglePayLoaded() {
     var config = { buttonColor : 'black',
                    buttonType : 'buy',
                    onClick : () => {
                         const paymentMethodId = 203;                                    // Google Pay
                         var paymentSheetDetails = { merchant_id : transpayrentConfig.merchantId,
                                                     merchant_name : '[MY MERCHANT]',
                                                     country : 208,                      // Denmark
                                                     payment_method_ids : Array.from(paymentMethods.keys() ),
                                                     amount : { currency : 208,          // DKK
                                                                value : 1000 },
                                                     save : false };
                          sdk.displayPaymentSheet(paymentMethodId, paymentSheetDetails)
                             .then(token => completePayment(paymentMethodId) )
                             .catch(reason => {
                                 document.getElementById('container').style.visibility = 'hidden';
                                 alert('API: '+ reason.api +' failed with HTTP Status Code: '+ reason.status +' and error: '+ reason.messages[0].message +'('+ reason.messages[0].code +')');
                             });
                  } };
     sdk.displayPaymentButton(203, container, Array.from(paymentMethods.keys() ), config);
 }

displayPaymentInitialization(paymentMethodId, url, method, data, config) → {HTMLIFrameElement|HTMLDivElement}

Constructs the iframe element for the consumer to initialize the payment for the payment transaction with an upstream 3rd party provider such as Apple Pay, Google Pay or MobilePay Online. The method will trigger a callback to the provided callback if defined sending a payment-initialization-initiated event.

Parameters:
Name Type Description
paymentMethodId PAYMENT_METHOD_ID

The unique id of the payment method which will be used to initialize the payment for the payment transaction.
url String

The URL to the upstream 3rd party provider with which the consumer must initialize the payment for the payment transaction
method Integer

The HTTP method which is required by the upstream 3rd party provider to initialize the payment for the payment transaction
data String

A map of data which will be sent to the upstream 3rd party provider as name value pairs to initialize the payment for the payment transaction
config IFrameConfig

The configuration for the constructed iframe element
Source:
Returns:

The constructed lightbox element

Type
HTMLIFrameElement | HTMLDivElement

displayPaymentSheet(paymentMethodId, details) → {String}

Displays the payment sheet for the specified payment method using an instance of its helper class.
The payment sheet will allow the consumer to select a payment card from a 3rd party wallet such as Apple Pay or Google Pay.
Please note that 3rd party wallets, such as Apple Pay and Google Pay, that rely on the Payment Request API prohibits the payment sheet from being displayed asynchronously, which requires this method to be called from within an async function using the await operator.

Parameters:
Name Type Description
paymentMethodId PAYMENT_METHOD_ID

The payment method selected by the consumer
details PaymentSheetDetails

The details that will be passed to the 3rd party wallet when displaying the payment sheet
Source:
See:
  • Transpayrent#getHelper
Returns:

The payment token returned by the 3rd party wallet, which should be passed to Transpayrent#authorize

Type
String
Example

Display the Payment Sheet for Apple Pay using the Transpayrent SDK

 var paymentMethods = new Map([
          [ 204, 'Apple Pay'],
          [ 103, 'VISA Dankort'],
          [ 107, 'Maestro'],
          [ 108, 'MasterCard'],
          [ 109, 'VISA'],
          [ 110, 'VISA Electron'] ]);
 const paymentMethodId = 204;                                                // Apple Pay
 var paymentSheetDetails = { merchant_id : transpayrentConfig.merchantId,
                             merchant_name : '[MY MERCHANT]',
                             country : 208,                                  // Denmark
                             payment_method_ids : Array.from(paymentMethods.keys() ),
                             amount : { currency : 208,                      // DKK
                                        value : 1000 },
                             save : false };
sdk.displayPaymentSheet(paymentMethodId, paymentSheetDetails);

fingerprint(url, data) → {HTMLIFrameElement}

Constructs an iframe which sends an HTTP POST request to enable the Access Control Server (ACS) to fingerprint the consumer's browser.

Parameters:
Name Type Description
url String

The URL to the Access Control Server (ACS), which will create a fingerprint of the consumer's browser as part of the 3D Secure process for strong consumer authentication.
data String

The base64 encoded request data that must be sent to the Access Control Server (ACS). The data will be sent to the ACS in the threeDSMethodData field for 3D Secure v2 and in the pareq field for 3D Secure v1.
Source:
Returns:

The constructed iframe element

Type
HTMLIFrameElement

getAuthenticationResult(transactionId, attempt) → {AuthenticationSuccessResult|AuthenticationFailureResult|Status}

Retrieves the strong consumer authentication (SCA) result for the specified payment transaction through the Transpayrent Payment Gateway using 3D secure or equivalent. The method will invoke the Get Authentication Result For Transaction API and automatically retry retrieving the strong consumer authentication (SCA) result for the specified payment transaction up to 5 times in the following scenarios:

  • HTTP Status Code: 409 - Conflict: Cached Payment Transaction not yet updated with authentication data
  • Low level communication error
    Please note that calling this method directly is not recommended, instead call method: Transpayrent#authenticate to orchestrate the complete flow for strong consumer authentication (SCA).
Parameters:
Name Type Description
transactionId Long

The unique id of the payment transaction for which the strong consumer authentication using 3D secure or equivalent is required should be verified
attempt Integer

The current attempt at retrieving the authentication result for the specified payment transaction, defaults to 1
Source:
See:
Returns:
Type
AuthenticationSuccessResult | AuthenticationFailureResult | Status

getLocalizedMessage(message, language, attempt) → {String}

Localizes the specified message using the provided language. The specified message will be localized using the browser's Accept-Language header if a language isn't specified.

Parameters:
Name Type Description
message String

The message that will be localized
language String

The ISO-639-1 code for the language the message should be translated to
attempt Integer

The current attempt at localizing the specified message, defaults to 1
Source:
See:
Returns:

The localized message

Type
String

getLocalizedStatusMessage(statusCode, language, attempt) → {String}

Localizes the message for the specified status code using the provided language. The message for the specified status code will be localized using the browser's Accept-Language header if a language isn't specified.

Parameters:
Name Type Description
statusCode Integer

The status code for which the message will be localized
language String

The ISO-639-1 code for the language the message for the specified status code should be translated to
attempt Integer

The current attempt at localizing the message for the specified status code, defaults to 1
Source:
See:
Returns:

The localized message for the specified status code

Type
String

getPaymentMethodId(cardNumber) → {PAYMENT_METHOD_ID}

Determines the payment method based on the specified {@code cardNumber}. The method may be used to dynamically route the payment transaction to an upstream provider based on the card details entered by the consumer.

Parameters:
Name Type Description
cardNumber Long

The card number which should be used to determine the payment method
Source:
See:
Returns:

The payment method that was determined based on the specified {@code cardNumber} or -1 if the payment method could not be determined

Type
PAYMENT_METHOD_ID

getStatusMessage(statusCode) → {String}

Retrieves the status message for the specified status code from the internal cache.

Parameters:
Name Type Description
statusCode Integer

The status code for which the status message will be returned
Source:
See:
Returns:

The status messages for the specified status code

Type
String

getTransaction(transactionId, attempt) → {PaymentTransaction|Status}

Retrieves the specified payment transaction from the Transpayrent Payment Gateway. The method will invoke the Get Transaction API and automatically retry retrieving the specified payment transaction up to 5 times in case of communication issues.

Parameters:
Name Type Description
transactionId Long

The unique id of the payment transaction that will be retrieved
attempt Integer

The current attempt at retrieving the specified payment transaction, defaults to 1
Source:
See:
  • Transpayrent#sleep
Returns:
Type
PaymentTransaction | Status

initialize(transactionId, body, config) → {InitializePaymentResponse|Status}

Initializes the payment for the specified payment transaction with the upstream 3rd party provider through the Transpayrent Payment Gateway by invoking the Initialize Payment For Transaction API.
The method will automatically retry initialization of the payment for the specified payment transaction up to 5 times in case of communication issues.
This is the 2nd method that should be called by the payment page when authorizing a payment using a 3rd party provider such as Apple Pay, Google Pay or MobilePay Online.
Please note that:

  • Calling createTransaction should be done prior to calling this method to create a new payment transaction and obtain a transaction id
  • Calling this method is the recommended way to complete the flow for initializing the payment for a payment transaction using a 3rd party provider such as Apple Pay, Google Pay or MobilePay Online.
  • The method will register event listeners and listen for the following events:
    • payment-initialization-complete
  • 3rd party wallets, such as Apple Pay and Google Pay, that rely on the Payment Request API prohibits the payment sheet from being displayed asynchronously, which requires this method to be called from within an async function using the await operator.
Parameters:
Name Type Description
transactionId Long

The unique id of the payment transaction for which the payment will be initialized
body InitializationDetails

A representation of the initialization details provided by the consumer the selected payment method
config IFrameConfig

The configuration for the iframe which will be constructed in case the consumer needs to complete initialization of the payment for the payment transaction using a lightbox overlay
Source:
See:
Returns:
Type
InitializePaymentResponse | Status
Example

Initialize payment with MobilePay Online using the Transpayrent SDK

 var body = { payment_method_id: 202,            // MobilePay Online
              mobile: { international_dialing_code: 45,
                        phone_number: 89671108 }
              save: false };
 var iframeConfig = { container : document.body,
                      css: 'initialization',
                      callback : function (event, iframe) {
                          switch (event) {
                             case 'payment-initialization-initiated':
                                 // DO SOMETHING BEFORE THE INITIALIZATION OF THE PAYMENT FOR THE PAYMENT TRANSACTION IS DISPLAYED
                                 break;
                             case 'payment-initialization-completed':
                                 // DO SOMETHING AFTER INITIALIZATION OF THE PAYMENT FOR THE PAYMENT TRANSACTION IS COMPLETE
                                 break;
                          }
                      } };
 sdk.initialize(transaction.id, body, iframeConfig)
 .then(
     initialization => {
         // Payment Initialization failed - Display status message
         if (initialization.status) {
             // HANDLE INITIALIZATION FAILURE
         }
         // Payment Initialization completed - Authorize payment
         else {
             // AUTHORIZE PAYMENT BY INVOKING METHOD: authorize
         }
     })
 .catch(reason => {
     // Low level error - Display error message
     if (reason) {
         console.error('Internal error: '+ reason);
     }
 });

initializeAuthentication(transactionId, body, attempt) → {InitializeAuthenticationResponse|Status}

Initializes strong consumer authentication for the specified payment transaction through the Transpayrent Payment Gateway using 3D secure or equivalent by invoking the Initialize Authentication For Transaction API. The method will automatically retry initialization of the strong consumer authentication for the specified payment transaction up to 5 times in case of communication issues.
Calling this method directly is not recommended, instead call method: Transpayrent#authenticate to orchestrate the complete flow for strong consumer authentication (SCA).
Please note that API calls made using this method falls under PCI DSS.

Parameters:
Name Type Description
transactionId Long

The unique id of the payment transaction for which strong consumer authentication using 3D secure or equivalent is required
body InitializeAuthenticationRequest

A representation of the payment details provided by the consumer for strong authentication of a payment transaction using 3D Secure or equivalent.
attempt Integer

The current attempt at initializing strong consumer authentication for the specified payment transaction, defaults to 1
Source:
See:
Returns:
Type
InitializeAuthenticationResponse | Status

initializePayment(transactionId, body, attempt) → {InitializePaymentResponse|Status}

Initializes the payment for the specified payment transaction with the upstream 3rd party provider through the Transpayrent Payment Gateway by invoking the Initialize Payment For Transaction API.
The method will automatically retry initialization of the payment for the specified payment transaction up to 5 times in case of communication issues.
Calling this method directly is not recommended, instead call method: Transpayrent#initialize to orchestrate the complete flow for initializing a payment for the payment transaction.

Parameters:
Name Type Description
transactionId Long

The unique id of the payment transaction for which the payment will be initialized with a 3rd party provider such as Apple Pay, Google Pay or MobilePay Online
body InitializePaymentRequest

A representation of the initialization details provided by the consumer for the selected payment method
attempt Integer

The current attempt at initializing the payment for the specified payment transaction, defaults to 1
Source:
See:
Returns:
Type
InitializePaymentResponse | Status

isCardNumberValid(cardNumber) → {Boolean}

Validates that the specified card number is valid using the following rules:

  • Contains only numbers
  • Does not start with a 0
  • Is 13 to 19 digits
  • Is compliant with the Luhn algorithm
Parameters:
Name Type Description
cardNumber Long

The card number which should be validated
Source:
See:
Returns:

True if the specified card number is valid otherwise false

Type
Boolean

isCVVValid(paymentMethodId, cvv) → {Boolean}

Validates that the specified Card Verification Value (CVV) is valid for the specified card type:

  • CVV must be greater than 0 and less than 10000 for American Express
  • CVV must be greater than 0 and less than 1000 for other card types

Please note that the validation logic relies on the Transpayrent Payment Gateway automatically prefixing the CVV with 0's to provide the correct number of digits for the card type:

  • 4-digits for American Express
  • 3-digits for other card types
Parameters:
Name Type Description
paymentMethodId PAYMENT_METHOD_ID

The payment method for the payment card for which the CVV should be validated
cvv Integer | String

The payment card's Card Verification Value (CVV)
Source:
Returns:

True if the specified Card Verification Value (CVV) is valid otherwise false

Type
Boolean

isExpiryDateValid(expiryMonth, expiryYear) → {Boolean}

Validates that the specified expiry date is valid. That is the specified expiry date is not in the past.

Parameters:
Name Type Description
expiryMonth Integer

The payment card's expiry month expressed as 2-digits, i.e. 01 for January
expiryYear Integer

The payment card's expiry year expressed as 2-digits, i.e. 23 for 2023
Source:
Returns:

True if the specified expiry date is valid otherwise false

Type
Boolean

isSCAExempt(paymentMethodId, amount, save) → {Boolean}

Determines whether the completion of the payment using the specified payment method is exempt from Strong Consumer Authentication (SCA).

Parameters:
Name Type Description
paymentMethodId PAYMENT_METHOD_ID

The payment method selected by the consumer
amount Amount

The payment transaction's amount that will be authorized
save Boolean

Flag indicating whether the consumer has elected to securely store the provided details for the payment method upon successful authorization
Source:
Returns:

True if payment is exempt from Strong Consumer Authentication (SCA) otherwise false.

Type
Boolean

save(transactionId, body, attempt) → {SaveConsumerValuableResponse|Status}

Securely stores the provided payment instrument for the specified payment transaction into Transpayrent's Secure Vault by invoking the Save Consumer Valuable For Transaction API. The method will automatically retry securely storing the provided payment instrument for the specified payment transaction up to 5 times in case of communication issues.
The saved payment instrument is automatically added to the consumer's wallet if a consumerId is provided in the request or was specified for the Payment Session.
This is the 3rd method that should be called by the payment page when storing the consumer's payment card.
Please note that:

  • Calling authenticate should be done prior to calling this method to authenticate the consumer and obtain a cryptogram
  • Merchants can only save a payment instrument for a payment transaction that is part of a payment session owned by the merchant
  • API calls made using this method falls under PCI DSS when saving a payment card.
Parameters:
Name Type Description
transactionId Long

The unique id of the payment transaction for which the payment card was authenicated
body SaveConsumerValuableRequest

The payment details for the payment card which will be securely stored in Transpayrent's Secure Valut and added to the consumer's wallet
attempt Integer

The current attempt at securely storing the provided payment instrument for the specified payment transaction, defaults to 1
Source:
See:
Returns:
Type
SaveConsumerValuableResponse | Status
Example

Save payment instrument using the Transpayrent SDK

 var card = { payment_method_id: 108,            // VISA
              card_number: 4111111111111111,     // Successful Authorization: Manual Challenge with browser fingerprint
              expiry_month: 9,
              expiry_year: 22,
              cvv: 987,
              card_holder_name: 'John Doe',
              cryptogram : [CRYPTOGRAM RETURNED BY STRONG CONSUMER AUTHENTICATION] };
 var body = { payment_details : card,
              consumer_id : "CID-12345",         // Defaults to the Consumer ID from the Payment Session if omitted
              name : "My VISA Card" }
 sdk.save(authentication.transaction_id, body)
 .then(
     save => {
         // Saving payment instrument failed - Display status message
         if (save.status) {
             // HANDLE SAVE FAILURE
         }
         // Payment instrument successfully saved
         else {
             // AUTHORIZE PAYMENT BY INVOKING METHOD: authorize
         }
     })
 .catch(reason => {
     // Low level error - Display error message
     if (reason) {
         console.error('Internal error: '+ reason);
     }
 });