You can review the expected user experience for CIT payments in our User Experience guide here

🚧

Signed-in Mode (Wink Login) or Guest Mode

Wink Payment SDK works in a secure payment mode via Wink Login for both Consumer Initiated (CIT) or Merchant Initiatied/Subscription ( MIT ) type payments. Please see the Integration guide here to integrate Wink Login in your website.

Alternatively, Wink Payment SDK can also be used in Guest Mode but only in CIT Mode.

This page is describing the front end integration for achieving CIT payments

👍

CIT Payments integration does not require you to do any work on the Backend. It is pure front end integration

Front End CIT Integration via Wink Payment SDK

Step 1. Add the Wink Payment component to your webpage or app

The Javascript SDK is meant to be used on your application front end page where you are displaying the option to complete the purchase by clicking on a Payment button

You can include the script either on the index.html of your Single page client application or the home page of Server rendered web applications

For Sandbox and Production use the respective script tag from here

Step 2: Add a Payment button to your application

Normally this button is placed where the user is ready to provide payment information to complete their purchase and the final amount is already available for the purchase ( inclusive of all taxes, discounts and fees ).

With only a few lines of code, you can add a button that automatically configures itself to have the appropriate text, logo, and colors for the sign-in state of the user and the scopes you request.

📘

Button Styling

The Wink Button styling as well as the images can be found here in the public folder and images can be found here under public/assets folder:

Wink button images

Additionally, Wink's button styling examples can be found here:

Wink button styles

<button id="wink-oauth-button" class="wink-oauth-button-light">
  <img src="semicolon-white.svg" /> 
  Payment
</button>

Step 3: Setup the session and initialize the SDK

When the Payment Button is clicked, the onClick function must call the session API and then initiate the SDK. On button click the respective integrationType should be passed to initWinkPay function

The following code shows how to setup the OnClick for the Payment button, call the session API to receive a unique sessionID and configure the SDK with these details.

📘

The code below needs you to select a few information

1. IntegrationMode value: Specifies how Wink Payment SDK appears from your application. 1= Redirect 2= IFrameEmbedded 3=IFrameOverlay
2. integrationType: Must be set to Payment for CIT Payments

<script>
async function initWinkPay(integrationType){
const postData ={
      "customerToken": "string", // add your customer token (Optional)
      "integrationToken": "string", // add integration token
      "paymentId": "string", // add payment Id
      "amount": 0 ,      // add amount in ISO format
      "currencyCode": "USD", // USD currency code
      "integrationMode": 1, // You can use wink payment in any of 3 integration modes. 1= Redirect 2= IFrameEmbedded 3=IFrameOverlay
      "returnUrl": "string", // add returnURL for redirecting user on success
      "cancelUrl": "string", // add returnURL for redirecting user on failure
      "description": "string", // Payment description
      "integrationType": integrationType, // Any one of Payment, Checkout and MIT
      "externalFields": { // (Optional) can be used for sending extra params.  Some examples are bellow.
        "customerEmail": "string",
        "customerFullName": "string"
      },
}
 try {
    const response = await fetch('https://{your-server}/v1/payment/session', {
      method: 'POST',
      headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(postData),
    });
    const result  = await response.json();
    const WinkPaymentJS = window.WinkPaymentJS;
    const params = {
        sessionId: result.sessionId,
        mode: 'redirect', // redirect or embeddediFrame or overlayiFrame, pass one of the value without spacesone of the value without spaces
        env: 'sandbox' // sandbox or live, pass one of the value without spaces
      };
    WinkPaymentJS.init(params);
  } catch (error) {
    console.log(error)
  } 
}
</script>

<button type="button" id="payment" onClick="initWinkPay('Payment')" class="wink-oauth-button wink-oauth-button--primary wink-oauth-button--fit-to-text">
	<img src="https://buttons.winklogin.com/src/images/semicolon-white.svg" alt="payment button" />
	Payment 
</button>

Backend Code

From your servers /your-server/create-session call below api to create session. Use
merchant api key in authorization header

Api url = <https://stagepayments-api.winkapis.com/v1/payment/session>
Return the sessionId received from wink to your UI

👍

Automatic Wink Login Integration - No extra code needed

Note that Wink Login integration works without you having to do anything special. If the user has been logged on your website using Wink Login and then the Wink Payment SDK is called as per above code to launch payment, it will automatically retrieve all card and address data and speed the user through the payment steps. If the user is not logged in, once the payment SDK is called, it will ask the user to either login or skip the login to use the SDK in Guest Mode

Step 4: Retrieving the Transaction Response

On payment completion

For Redirect mode or iFrame mode

• user will be redirected back to your site on the given return URL you specified in the code above
• if you have included wink-payment js on index.html / home page, then on your return page your callback function will be invoked with the following object as input

{
transactionId: transactionId, // transaction id from wink
amount: amount,
currencyCode: currencyCode,
cartId: cartId // cart or quote id which was sent during session creation
}

Use the below code to display transaction data on the return URL page.

function amountInOriginal (amount){
return ( amount/100 );
} 
const queryParam = new URLSearchParams(window.location.search);
   
function onPaymentReturn(transactionData) {
    if (
        transactionData?.transactionId !== null &&
        transactionData?.transactionId !== undefined
    ) {
        // use the received query params as required
        // transactionData.transactionId)
        // amountInOriginal(transactionData.amount)
        // transactionData.currencyCode
    }
}

//Show session expired message

 if (queryParam.get("transactionStatus") == "sessionExpired") {
    //Show session expired message on UI
 }

🚧

Note that the payment session is set to a default value of 5 min. The user must complete the payment within the 5 minutes or the session will be expired.

In case the session is expired the user will receive the transactionStatus = sessionExpired in the URL.

📘

Wink Payment handles all the amount in ISO Format, so you will have to convert the amount into its original format using an amountInOriginal function.