Home

transpayrent

Copyright (c) 2022 Transpayrent ApS.

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 Transpayrent 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 PayTM 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 contact Transpayrent to enable any 3rd party wallet.

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

The Transpayrent SDK handles the authentication and initialization 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 Transpayrent SDK's authenticate or initialize methods.
Communication with Transpayrent's Payment Gateway is done asyncronously using Promises.

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

Finally completing the entire payment process may be simplified further by using the Transpayrent UI Helper SDK into the following 3 steps:

  1. Override UI Helper SDK methods to return the correct request for the specified payment method:
  2. Construct requests for each operation: createTransaction, initialize, authenticate, authorize and save
  3. Complete the payment using the Transpayrent UI Helper SDK's completePayment method

Please note that the default implementation of method: getIFrameConfig will apply a CSS class with the name of the action: consumer-authentication or payment-initialization to the constructed iframe.

The sequence diagram below illustrates the communication flow for authorizing the payment for a payment transaction when using the Transpayrent SDK:
Successfully completing a payment using the Transpayrent SDK takes 5 simple steps:

  1. Merchant back-end creates a new payment session
  2. Merchant back-end renders the payment page and instantiates the Transpayrent SDK
  3. The payment page creates a new payment transaction using the SDK
  4. The payment page authenticates the consumer with 3D Secure or equivalent using the Transpayrent SDK
  5. The payment page authorizes the payment for the payment transaction using the Transpayrent SDK

The sequence diagram below illustrates the communication flow for securely storing the consumer's payment card in Transpayrent's Secure Vault and adding it to the consumer's wallet when using the Transpayrent SDK:
Please note that the communication highlighted with red falls under PCI DSS compliance and must be made directly from the Transpayrent SDK to the Transpayrent Payment Gateway to handle compliance

Securely storing a payment card and adding the stored card to the consumer's wallet takes 5 simple steps using the Transpayrent SDK:

  1. Merchant back-end creates a new payment session
  2. Merchant back-end renders the payment page and instantiates the Transpayrent SDK
  3. The payment page creates a new payment transaction using the Transpayrent SDK
  4. The payment page authenticates the consumer with 3D Secure or equivalent using the Transpayrent SDK
  5. The payment page saves the consumer's payment card using the Transpayrent SDK

The code sample below provides a complete illustration of how the payment page may 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 using the Transpayrent SDK in conjunction with the Transpayrent UI Helper SDK.
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 as outlined in step 1. Merchant back-end creates a new payment session above.

<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 src="https://pay.google.com/gp/p/js/pay.js"></script>
<script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>
<script>
    // Override UI Helper SDK methods to return the correct request for the specified payment method
    TranspayrentUIHelper.prototype.displayAuthenticationFailure = function (result) {
        document.getElementById('container').style.visibility = 'hidden';
        var message = document.createElement('h1');
        message.className = 'failure';
        message.innerHTML = '<img id="loader" src="/failure.png" width="30" height="30" alt="- completed -" />';
        message.innerHTML += ` Consumer failed authentication challenge for payment transaction: ${result.transaction_id} with error: ${this._sdk.getStatusMessage(result.status_code)} (${result.status_code})`;
        document.body.appendChild(message);
    }
    TranspayrentUIHelper.prototype.displayPaymentConfirmation = function (authorization) {
        document.getElementById('container').style.visibility = 'hidden';
        var message = document.createElement('h1');
        message.className = 'success';
        message.innerHTML = '<img id="loader" src="/success.png" width="30" height="30" alt="- completed -" />';
        message.innerHTML += ` Payment transaction: ${authorization.transaction_id} successfully authorized`;
        document.body.appendChild(message);
    }
    TranspayrentUIHelper.prototype.getCreateTransactionRequest = function (paymentMethodId) {
        return createTransactionRequests[paymentMethodId];
    }
    TranspayrentUIHelper.prototype.getInitializePaymentRequest = function (paymentMethodId) {
        return initializePaymentRequests[paymentMethodId];
    }
    TranspayrentUIHelper.prototype.getAuthenticateConsumerRequest = function (paymentMethodId) {
        return authenticateConsumerRequests[paymentMethodId];
    }
    TranspayrentUIHelper.prototype.getAuthorizePaymentRequest = function (paymentMethodId) {
        return authorizePaymentRequests[paymentMethodId];
    }
    TranspayrentUIHelper.prototype.getSaveRequest = function (paymentMethodId) {
        return saveRequests[paymentMethodId];
    }
</script>
<script>
    // SDK configuration
    const 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"]'
    };
    const url = 'https://generator.[ENVIRONMENT].transpayrent.cloud/v1/'+ transpayrentConfig.merchantId +'/system/PAYMENT_GATEWAY/sdk/CLIENT';

    // Instantiate SDK and UI Helper SDK
    const sdk = new Transpayrent(url, transpayrentConfig);
    const helper = new TranspayrentUIHelper(sdk, document.getElementById('container'), document.getElementById('loader') );
    
    /* ========== COMMON DATA START ========== */
    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 };
    card.payment_method_id = sdk.getPaymentMethodId(card.card_number);
    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 nationalIdentificationNumber = '31892554313';
    /* ========== COMMON DATA END ========== */

    /* ========== CREATE PAYMENT TRANSACTION DATA START ========== */
    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 } };
    // Google Pay
    createTransactionRequests[203] = { correlation_id : 'TP-'+ transpayrentConfig.sessionId,
                                       amount: { currency : 208,          // DKK
                                                 value : 100 } };
    // Apple Pay
    createTransactionRequests[204] = { correlation_id : 'TP-'+ transpayrentConfig.sessionId,
                                       amount: { currency : 208,          // DKK
                                                 value : 100 } };
    // PIX
    createTransactionRequests[301] = { correlation_id : 'TP-'+ transpayrentConfig.sessionId,
                                       amount: { currency : 986,          // BRL
                                                 value : 100 } };
    /* ========== CREATE PAYMENT TRANSACTION DATA END ========== */

    /* ========== INITIALIZE PAYMENT DATA START ========== */
    var initializePaymentRequests = new Array();
    // Card based payment
    initializePaymentRequests[card.payment_method_id] = { payment_method_id : card.payment_method_id,
                                                          save : card.save }
    // Consumer Wallet
    initializePaymentRequests[201] = { payment_method_id : 201 }
    // MobilePay Online
    initializePaymentRequests[202] = { payment_method_id : 202,
                                       mobile : phone,
                                       save : card.save };
    // Google Pay
    initializePaymentRequests[203] = { payment_method_id : 203,
                                       save : card.save }
    // Apple Pay
    initializePaymentRequests[204] = { payment_method_id : 204,
                                       save : card.save }
    // PIX
    initializePaymentRequests[301] = { payment_method_id : 301,
                                       national_identification_number : nationalIdentificationNumber,
                                       contact : { email : email } }
    /* ========== INITIALIZE PAYMENT DATA END ========== */

    /* ========== AUTHENTICATE CONSUMER DATA START ========== */
    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 } };
    // Google Pay
    authenticateConsumerRequests[203] = { payment_details : { payment_method_id : 203,
                                                              token : null },
                                          billing_address : address,
                                          shipping_address : address,
                                          contact : { mobile : phone,
                                                      work : phone,
                                                      home : phone,
                                                      email : email } };
    /* ========== AUTHENTICATE CONSUMER DATA END ========== */

    /* ========== AUTHORIZE PAYMENT DATA START ========== */
    // Card based payment
    authorizePaymentRequests[card.payment_method_id] = { payment_details : card,
                                                         national_identification_number : nationalIdentificationNumber, // Optional: Required in Brazil
                                                         contact : { email : email } };                                 // Optional: Required in Brazil
    // Consumer Wallet
    authorizePaymentRequests[201] = { payment_details : { payment_method_id : 201,
                                                          valuable_id : 3,
                                                          access_token : 'SINGLE SIGN-ON TOKEN' },
                                      national_identification_number : nationalIdentificationNumber,    // Optional: Required in Brazil
                                      contact : { email : email } };                                    // Optional: Required in Brazil
    // MobilePay Online
    authorizePaymentRequests[202] = { payment_details : { payment_method_id : 202 } };
    // Google Pay
    authorizePaymentRequests[203] = { payment_details : { payment_method_id : 203,
                                                          token : null },
                                      national_identification_number : nationalIdentificationNumber,    // Optional: Required in Brazil
                                      contact : { email : email } };                                    // Optional: Required in Brazil
    // Apple Pay
    authorizePaymentRequests[203] = { payment_details : { payment_method_id : 204,
                                                          token : null },
                                      national_identification_number : nationalIdentificationNumber,    // Optional: Required in Brazil
                                      contact : { email : email } };                                    // Optional: Required in Brazil
    // PIX
    authorizePaymentRequests[301] = { payment_details : { payment_method_id : 301 } };
    /* ========== AUTHORIZE PAYMENT DATA END ========== */

    /* ========== SAVE PAYMENT DETAILS START ========== */
    var saveRequests = new Array();
    // Card based payment
    saveRequests[card.payment_method_id] = { payment_details : card,
                                             consumer_id : 'CID-12345',
                                             name : 'My VISA' }
    // Google Pay
    saveRequests[203] = { payment_details : authorizePaymentRequests[203],
                          consumer_id : 'CID-12345',
                          name : 'My Google Pay Card' }
    // Apple Pay
    saveRequests[204] = { payment_details : authorizePaymentRequests[204],
                          consumer_id : 'CID-12345',
                          name : 'My Apple Pay Card' }
    /* ========== SAVE PAYMENT DETAILS END ========== */
    
    /* ========== DISPLAY PAYMENT BUTTONS FOR APPLE PAY AND GOOGLE PAY START ========== */
    // Display the Payment Sheet for Google Pay
    // See: https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions
    var config = { buttonColor : 'black',
                   buttonType : 'buy',
                   onClick : () => {
                        const paymentMethodId = 203;    // Google Pay
                        var data = { merchant_id : transpayrentConfig.merchantId,
                                     merchant_name : '[MY MERCHANT]',
                                     country : 208,
                                     payment_method_ids : Array.from(paymentMethods.keys() ),
                                     amount : createTransactionRequests[paymentMethodId].amount,
                                     save : initializePaymentRequests[paymentMethodId].save };
                        sdk.displayPaymentSheet(paymentMethodId, data)
                            .then(token => helper.completePayment(paymentMethodId, data.save) )
                            .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 +')');
                            });
                    } };
    // Display the "Buy with Google Pay" button
    sdk.displayPaymentButton(203, document.getElementById('container'), Array.from(paymentMethods.keys() ), config);

    // Display the Payment Sheet for Apple Pay
    // See: https://developer.apple.com/documentation/apple_pay_on_the_web/applepaybutton
    var config = { buttonstyle : 'black',
                   type : 'pay',
                   locale : 'en',
                   onClick : () => {
                        const paymentMethodId = 204;    // Apple Pay
                        var data = { merchant_id : transpayrentConfig.merchantId,
                                     merchant_name : '[MY MERCHANT]',
                                     country : 208,
                                     payment_method_ids : Array.from(paymentMethods.keys() ),
                                     amount : createTransactionRequests[paymentMethodId].amount,
                                     save : initializePaymentRequests[paymentMethodId].save };
                        sdk.displayPaymentSheet(paymentMethodId, data)
                            .then(token => helper.completePayment(paymentMethodId, data.save) )
                            .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 +')');
                            });
                    } };
    // Display the "Buy with Apple Pay" button
    sdk.displayPaymentButton(204, document.getElementById('container'), Array.from(paymentMethods.keys() ), config);
    /* ========== DISPLAY PAYMENT BUTTONS FOR APPLE PAY AND GOOGLE PAY END ========== */
</script>