Step 6: Receive payment

Integration Details

Once, the user has goes through the Uplift application through the iFrame, there are two potential outcomes:

1. Adverse action (the user has not been approved), in such a case:
   1. The iFrame will display a message to the user suggesting completing the purchase with an alternate payment method.
   2. The payment selector will remain enabled, however the user will be unable to continue with the Uplift application.
   3. The callback handler will not trigger a status change and it will remain as OFFER_AVAILABLE. Due to compliance reasons we are unable to share the specific status of the loan application. An example of an adverse action on the iFrame will look like the image below.

      

      Note: In the image above, for travel partners, if an applicant is declined then they will be prompted with a button to start a fresh application for a new user.

2. Successful application (the user has been approved), in such a case:
   1. The callback handler will fire a TOKEN_AVAILABLE status signaling that a token object (containing the details of Uplift virtual card similar to any bank card) is available for the merchant to process your payment.
      
      
      ⚠️ Make sure to obtain the available token ONLY AFTER the user clicks on the booking/purchase button on your website.

      In order to retrieve the token, you will need to call the window.Uplift.Payments.getToken() method. This method does not take any parameter and makes a request to the Uplift platform to send the token object.

      Uplift and Non Uplift Payments

      Even if Uplift is not selected as payment method, after the user clicks on the booking/purchase button is necessary to execute the orderSubmit method from the Uplift Analytics library as shown below.

      The Uplift.Analytics.orderSubmit(order_info: orderInfo, data: data) method takes two parameters:

      1. An OrderInfo object identical to the one used in Step 3 of the API Integration. Refer to this page for information on the complete schema for the OrderInfo object.
      2. A data object as shown below:

         {
           //user’s mode of payment
           "mode_of_payment": String,
           //user’s available payment options
           "payment_options": [String]
         };
         

      Example of allowed values for mode_of_payment and payment_options

      'full', 'pay monthly', 'deposit', 'hold', 'other'.

   2. Once the token has been sent by Uplift, the callback handler will fire a TOKEN_RETRIEVED status with the token as an attribute of the response. This token object can then be used to process payment similar to any other bank card.
      📘 Detailed attributes of the token and how to get paid using it can be found here.
      ⚠️ Please review the Response Reason Code details if the token value is NULL.

      How to correctly retrieve the billing contact information?

      ⚠️Please make sure to use the data under the token.contact object instead of any other billing information provided by the user.

   Below is an example of the updated callback handler with the above mentioned changes.

   function myOnChangeCallback(response) {
     var statusHandlers = {
       OFFER_AVAILABLE: function(){
         //Uplift Pay Monthly Offer available for this customer.
       },
       TOKEN_AVAILABLE: function(){
         //Uplift application has been completed and ready to pay in full.
         //Retrieve the token ONLY AFTER Purchase/Book button is clicked.
         window.Uplift.Payments.getToken();
       },
       TOKEN_RETRIEVED: function(){
         //Uplift Payment Token successfully retrieved.
         var token = response.token;
         //process payment using token (uplift virtual card).
       },
       OFFER_UNAVAILABLE: function(){
        //Uplift Pay Monthly Offer is not available for this customer.
       },
       SERVICE_UNAVAILABLE: function(){
         //Uplift Payments Service is unavailable.
       }
     };
     statusHandlers[response.status]();
   }
   

Error Reporting

window.Uplift.Payments.error(errorMsg: String, errorType: String)

This method has two parameters, errorMsg representing the message shown to the user and errorType which has three possible values (validation, booking, fatal) corresponding to the type of error.

Some of the examples of the possible scenarios for each value is:

1. validation - due to a field being incorrectly used resulting in the system being unable to process payment e.g. incorrect usage of expiration month etc.
2. booking - due to an error between the user confirming purchase and processing payment e.g. inventory no longer available, payment provider is down etc.
3. fatal - due to an error not mentioned above resulting in customer being unable to book e.g. partner site server timed out etc.

Reporting errors will help Uplift improve and better serve our mutual customers.

Processing Confirmation

For the confirmation process, two steps are needed. The first one is necessary for all the payment methods, but the second one is only required for the Uplift payment.

1. Uplift and Non Uplift Payments
Use the Uplift Analytics orderResponse method to send the order_id and the payment method selected: Uplift.Analytics.orderResponse(data)

The data object should be defined as shown below:

{
  //user’s mode of payment
  "mode_of_payment": String,
  //pass the confirmation number
  "order_id": String
};

Example

Uplift.Analytics.orderResponse({
  "mode_of_payment": "pay monthly",
  "order_id": "ConfirmationID123"
})

2. Uplift Payment

The confirm function should be ONLY executed for Uplift transactions. If the transaction was successfully processed using the Uplift token, the partner confirmation number needs to be sent to Uplift using the predefined method shown below.

window.Uplift.Payments.confirm(order_id: String)

This method informs Uplift that the booking was successful and allows us to provide a better customer experience for our mutual customers, in case they call Uplift.

Example

window.Uplift.Payments.confirm("616783a0")