Class: Transpayrent

Transpayrent(url, config)

The Transpayrent SDK simplifies the strong consumer authentication (SCA) and payment authorization through the consumer's browser while handling PCI DSS compliance. The SDK handles the secure communication with Transpayrent's Payment Gateway and orchestrates the integration into 3 simple steps for the scenarios summarized in the table below.

Authorize Payment Store Payment Card
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

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 authentication challenge may be fully customized using CSS simply by passing the appropriate iframe configuration when invoking the SDK's authenticate method.
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.

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.
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 body = { correlation_id : 'TP-103645',
                  amount: { currency : 208,          // DKK
                            value : 100 } };
     var card = { payment_method_id: 109,            // 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 : 'CO',
                     country: 208 };                 // Denmark
     var phone = { international_dialing_code: 45,   // Denmark
                   phone_number: 12345678 };
     var email = 'hello@transpayrent.dk';
     var save = { card : card,
                  consumer_id : '[MERCHANT'S CONSUMER ID FROM PAYMENT SESSION]',
                  name : "My VISA Card" }
     var ssoToken = '[MERCHANT'S SINGLE SIGN-ON TOKEN FOR AUTHORIZING A PAYMENT WITH THE CONSUMER'S WALLET]';
 
     var sdk = new Transpayrent(url, transpayrentConfig);

     // Create payment transaction for securely storing the consumer's payment card and add the stored card to the consumer's wallet
     sdk.createTransaction(card.payment_method_id, { amount: { currency : 208,   // DKK
                                                               value : 0 } })
     .then(
         transaction => {
             // Creation of Payment Transaction failed - Display status message
             if (transaction.status) {
                 alert('API: '+ transaction.api +' failed with HTTP Status Code: '+ transaction.status);
                 return Promise.reject(null);
             }
             else {
                 var body = { card : 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;
                                          }
                                     } };
                 return sdk.authenticate(transaction.id, body, 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);
                 }
                 // API request failed - Display status message
                 else {
                     alert('API: '+ authentication.api +' failed with HTTP Status Code: '+ authentication.status);
                 }
                 return Promise.reject(null);
             }
             // Consumer Authentication succesfully completed
             else {
                 save.card.cryptogram = authentication.cryptogram;
                 return sdk.save(authentication.transaction_id, save);
             }
         })
     .then(
         save => {
             // Saving Payment Card failed - Display status message
             if (save.status) {
                 alert('API: '+ save.api +' failed with HTTP Status Code: '+ save.status);
                 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 : ssoToken }
                 
                 // Create new transaction for authorizing a payment with the stored card
                 return sdk.createTransaction(request.payment_method_id, body)
                     .then(
                         transaction => {
                             // Creation of Payment Transaction failed - Display status message
                             if (transaction.status) {
                                 alert('API: '+ transaction.api +' failed with HTTP Status Code: '+ transaction.status);
                                 return Promise.reject(null);
                             }
                             // Authorize the payment for the payment transaction using the consumer's stored card
                             else {
                                 return sdk.authorize(transaction.id, request);
                             }
                         });
             }
         })
     .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.0.0
Copyright:
  • Transpayrent ApS 2021
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 : 'CO',
                 country: 208 };                 // Denmark
 var phone = { international_dialing_code: 45,   // Denmark
               phone_number: 12345678 };
 var email = 'hello@transpayrent.dk';
 var body = { card : 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) → {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.
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.
Source:
See:
Returns:
Type
AuthenticationSuccessResult | AuthenticationChallengeResult | AuthenticationFailureResult | Status

authorize(transactionId, card) → {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.
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.
Parameters:
Name Type Description
transactionId Long

The unique id of the payment transaction for which the payment should be authorized
card PaymentCard

A representation of a payment made using a payment card such as a MasterCard credit card or a VISA debit card
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] };
 sdk.authorize(authentication.transaction_id, card)
 .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);
     }
 });

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

Creates a new payment transaction through the Transpayrent Payment Gateway by invoking the Create Payment Transaction API.
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.
Source:
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

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) → {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.
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
Source:
See:
Returns:
Type
AuthenticationSuccessResult | AuthenticationFailureResult | Status

initializeAuthentication(transactionId, body) → {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.
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.
Source:
See:
Returns:
Type
InitializeAuthenticationResponse | Status

save(transactionId, body) → {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 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.
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
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 = { card : 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);
     }
 });