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: | 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: | 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:
|
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:
- Fingerprint the consumer's brower in an invisible iframe
- Display an authentication challenge to the consumer in an iframe
- Display the flow for initializing the payment with a 3rd party wallet to the consumer in a Lightbox iframe
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:
- Determine Transpayrent's Payment Method Id using the entered card number
- Validate the entered card number
- Validate the entered expiry date
- Validate the entered Card Verification Value (CVV)
- Determine whether the payment transaction is exempt from Strong Consumer Authentication (SCA) using 3D Secure
- Retrieve Transpayrent's status message for the specified status code
Finally completing the entire payment process may be simplified further by using the Transpayrent UI Helper SDK into the following 3 steps:
- Override UI Helper SDK methods to return the correct request for the specified payment method:
- Construct requests for each operation:
createTransaction,initialize,authenticate,authorizeandsave - 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:
- Merchant back-end creates a new payment session
- Merchant back-end renders the payment page and instantiates the Transpayrent SDK
- The payment page creates a new payment transaction using the SDK
- The payment page authenticates the consumer with 3D Secure or equivalent using the Transpayrent SDK
- 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:
- Merchant back-end creates a new payment session
- Merchant back-end renders the payment page and instantiates the Transpayrent SDK
- The payment page creates a new payment transaction using the Transpayrent SDK
- The payment page authenticates the consumer with 3D Secure or equivalent using the Transpayrent SDK
- 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>