VPCart 9.0 Stripe checkout hosted payment gateway readme

Created : 19 April 2021
Last Modified : 23 May 2022

***********************************************************************************
Contents:

A. SUMMARY
B. FILE STRUCTURE
C. INSTALLATION INSTRUCTION
D. HOW IT WORKS
E. CONFIGURATION SETTINGS
F. DATABASE TABLES MODIFIED
G. LANGUAGE SETTINGS CHANGED
H. CHANGE LOGS
I. TROUBLESHOOTING
J. FAQ
K. COPYRIGHT NOTICE
L. TERMS AND CONDITIONS

***********************************************************************************

A. SUMMARY
==========
This interface is for use with Stripe Checkout Hosted payment gateway.

Features:

Your customers card information is filled on the gatway page.
Support SCA (Strong Customer Authentication)
Refund ability (partial & full refund) via API in VPCart Orders administration
Easy to use & setup with minimal settings in Modules Manager.
Well tested on modern browsers and mobile devices.

Both normal checkout and one-page checkout method are supported by this module.

To use this module, you must register an account first with Stripe.
You can register at https://dashboard.stripe.com/register

IMPORTANT NOTE:
It is strongly recommended to have SSL certificate installed on shopping cart site for security and PCI compliance.

If you do not have any SSL Certificate in your current site, you can purchase SSL from us at:
https://www.vpcart.com/virtprog/instantssl1yr.htm

***********************************************************************************

B. FILE STRUCTURE
===================

Files included in the zip are:
- $READ_ME_FIRST_stripehosted900.HTML
- stripehosted_execute.asp
- stripehosted_process.asp
- stripehostedcallback.asp
- stripehostedcancel.asp
- stripehostedconfig.asp
- stripehostedgateway.asp
- stripehostedresult.asp
- plugins/stripehosted/client.js
- admin/shopa_stripehosted_config.asp
- admin/stripehosted_getrefundamt.asp
- admin/stripehosted_refundvoid.asp
- admin/stripehosted_setup.asp
- admin/stripehosted_setup_config.asp
- admin/stripehosted_setup_process.asp
- admin/stripehosted_subs.asp
- admin/stripehostedconfig.asp
- admin/help/shoph_stripehosted.asp
- admin/js/stripehosted/stripehosted.css
- admin/js/stripehosted/stripehosted.js
- admin/js/stripehosted/striperefund.js
- admin/images/stripehosted/*
- admin/sqlscripts/stripehosted/*

***********************************************************************************

C. INSTALLATION INSTRUCTION
============================

1. Upload the below files and folder to your VPCart 9.00 root folder.
- stripehosted_execute.asp
- stripehosted_process.asp
- stripehostedcallback.asp
- stripehostedcancel.asp
- stripehostedconfig.asp
- stripehostedgateway.asp
- stripehostedresult.asp
- plugins/stripehosted/client.js

2. Upload the below files to your ADMIN folder. If you have renamed your ADMIN folder, then this must be placed in the renamed folder.
- admin/shopa_stripehosted_config.asp
- admin/stripehosted_getrefundamt.asp
- admin/stripehosted_refundvoid.asp
- admin/stripehosted_setup.asp
- admin/stripehosted_setup_config.asp
- admin/stripehosted_setup_process.asp
- admin/stripehosted_subs.asp
- admin/stripehostedconfig.asp
- admin/help/shoph_stripehosted.asp
- admin/js/stripehosted/stripehosted.css
- admin/js/stripehosted/stripehosted.js
- admin/js/stripehosted/striperefund.js
- admin/images/stripehosted/*
- admin/sqlscripts/stripehosted/*

3. Log into super admin and execute page below:
http://www.yourdomain.com/<your admin folder>/stripehosted_setup.asp

Note: Replace the below with your VPCart site
{ www.yourdomain.com } : your site domain
{ your admin folder } : your admin folder

Click Install Now button.

4. After installation completed, click Next button:

5. You will be redirected to Stripe configuration page.

- Do you want to enable Stripe Hosted module?
Set to Yes to enable Stripe Checkout Hosted Payment gateway.
You are required to get Publishable key, Secret key and setup Business account before "Enable" the module.

Please follow below guide to setup Business account:

1. Log in to Stripe with your email address and password.

2. After loggen into the account, click on Settings on the left side.

3. At center panel, click "Account details" under "Business settings".

4. Fill in the information under "Account settings" section, then click "Save" button.

Please refer to below link on how to get Publishable key and Secret key:
https://support.stripe.com/questions/locate-api-keys-in-the-dashboard

- What is gateway Prefix?
Gateway prefix.
Identity of the orders payment method.
You should no update this field.

- Do you want to run in trace mode?
Set to Yes to enable debug trace for developer.

- What is your currency charged by gateway?
Stripe supports many other currencies worldwide. For the list of supported currencies, you can refer at:
https://stripe.com/docs/currencies

- What is your Publishable key?
Please enter your Stripe Publishable key. You can refer to their guide on how to get this Publishable key:
https://support.stripe.com/questions/locate-api-keys-in-the-dashboard

- What is your Secret key?
Please enter your Stripe Secret key. You can refer to their guide on how to get this Secret key:
https://support.stripe.com/questions/locate-api-keys-in-the-dashboard

- What is your Webhooks event key?

It is important and you are REQUIRED to setup on your Stripe panel.

What is Webhooks URL:
We set Webhooks URL on Stripe which the orders payment transaction detail would be returned silently via this URL.
After VPCart receive the notification, VPCart would update these payment information to the specify order.

Please follow below guide to setup Webhooks URL:

1. Log in to Stripe with your email address and password.

2. After loggen into the account, click on Developers, then Webhooks on the left side.

3. Click on button "Add endpoint" on the Endpoints section.

4. Pleae fill in the information for the following fields:
Endpoint URL: The Webhook URL setup on your site. Eg: https://v9deluxesql.cartmonkey.com/stripehostedcallback.asp
where v9deluxesql.cartmonkey.com is your domain and the store folder.
stripehostedcallback.asp is the page URL you must include.

Events to send: You must select "checkout.session.completed" from the Select events dropdown field.

5. Click "Add endpoint" button after all information filled.

6. After Webhook URL created, please click "Click to reveal" button on "Signing secret" section

6. Copy the signing string, and paste to "Webhooks event key" field.

6. Click Update record button.

7. You are done.

8. IMPORTANT NOTICE:

Notes: You are required to going thru the "Activate your account" process before accepting payments with Stripe.

Please follow below guide to Activate your account:

8a. Log in to Stripe with your email address and password.

8b. After loggen into the account, click on "Activate your account" on the left side.

8c. Going thru the steps provided by Stripe and finally your account will be get activated.

***********************************************************************************

D. HOW IT WORKS
===============

When customers do a checkout, simply click the pay with credit card button, and will be redirected to Stripe checkout gateway.

On a success payment, Stripe will return response with Payment ID and Status to your VPCart site.

VPCart will update the following Orders table fields as below eg :
ocardtype : Stripe
oauthorization : Stripe
Payment Intent ID=pi_xxxxxxxxxxxxxxxxxxxx
Status=paid
Currencye=xxx
Amount=xxx

If no Payment ID and succeeded Status returned in the response from Stripe, then it will be marked as Stripe-Declined.

VPCart will update the following Orders table field as below eg :

ocardtype : Stripe-Declined
oauthorization : Declined [reason for the decline]

And redirect customers back to shopcheckout.asp.asp to retry their payment.

Stripe Refund process

You can do refunds for any online purchases paid using Stripe directly from within the VPCart orders administration.

Go to : Store > Orders and locate the column "Payment Status". For any success payment, you can see a link for Refund.

To do a refund for an order, click the Refund link.

It will then take you to the Refund form as shown on screenshot below:

There are two Refund type you can choose:

1) Full refund.

If you choose Full refund, it will send the full order amount to Stripe for the refund.

Example, if the total order amount is $50 then Full refund process will send the total $50 refund request to Stripe.

2) Partial refund.

It's flexible that you can do partial refund to your customers more than once on your liking.

For example, a total order amount is $50, and you wish to do refund in partial eg
First refund $25
Second refund $25

The Partial refund can handle this for you.

Simply choose the Partial option, and you will see the amount textbox. Enter eg 25 into it and click Refund to proceed.

For a success refund, the following Orders table fields will be updated:

ocardtype :
Stripe-Refund (For a full refund)
Stripe-Partial Refund (For a partial refund)

oauthorization : Added the Date and time of the refund, Refund ID, Refunded amount eg
Date=5/23/2020 5:05:33 AM
Refund ID: re_1GlpY9JmLUaK6FGOTkyFWyib : US$20.00

NOTE : If you do more than one refund for an order, then it can be tracked from this oauthorization value eg:

The example above showing that first refund US$41.00 is made and then followed by second refund US$5.50

The following fields in Orders table are used for refund process:

- ostriperefundid (new field) : The latest refund id made for the order
- ostriperefunddatetime (new field) : The last refund process date and time.
- oauthorization : All the refund date, refund id and refund amount in each refund request will be appended to the existing payment status.
- orefundtype : R (full refund) or S (partial refund).

For any successful refund, VPCart will deduct the refunded amount to the total order amount (orderamount field).
Also, in your order details page in administration, merchants able to see the total of refunded amount.

***********************************************************************************

E. CONFIGURATION SETTINGS
=================

Refer to Stripe Hosted configuraiton page

F. DATABASE TABLES MODIFIED
===========================

Orders table, new fields:

- otransid text 50
- occlastdigits text 50
- oauthcode text 50
- orefundtype text 1
- oaddonmodulename text 100
- ostripesessionid text 200
- ostriperefundid text 100
- ostriperefunddatetime text 50

Orders table, existing field size changed:
- oauthorization field size increased to text 4000

G. LANGUAGE SETTINGS CHANGED
============================

New languages for Stripe Hosted

H. CHANGE LOGS
============================

2022.05.23 - stripehosted: Bug fix: Possible no return json response from endpoint

***********************************************************************************

I. TROUBLESHOOTING
============================

Please submit a ticket to our helpdesk at https://helpdesk.vpcart.com and our support team will assist you.

***********************************************************************************

J. FAQ
============================

NONE

***********************************************************************************
K. COPYRIGHT NOTICE
============================

Copyright (c) 1999-2022 Rocksalt International Pty. Ltd.
All rights reserved.

This software and documentation constitute a published work and
contains valuable trade secrets and proprietary information
belonging to Rocksalt International Pty. Ltd. .
None of the foregoing material may be copied,
duplicated or disclosed without the express written permission
of Rocksalt International Pty. Ltd. .

LICENSEE ACCEPTS VP-ASP Shopping Cart "AS IS" "WITH ALL FAULTS",
Rocksalt International Pty. Ltd. accepts no responsibility for the
operation or performance of the VP-ASP Shopping Cart.
The entire risk of use and consequences of use of the
VP-ASP Shopping Cart falls completely on the Licensee
and Rocksalt International Pty. Ltd. shall not be liable in any respect
for any claims, loss or injury alleged to have resulted
from use of or in reliance on VP-ASP Shopping Cart.

Licensee acknowledges that it has read the foregoing
disclaimers of warranty and limitation of liability
and understands that Licensee assumes
the entire risk of using VP-ASP Shopping Cart.

***********************************************************************************

L. TERMS AND CONDITIONS
============================
ROCKSALT INTERNATIONAL GRANTS TO THE LICENSEE A NON-EXCLUSIVE,
NON-SUB LICENSABLE, NONTRANSFERABLE LICENSE
TO INSTALL AND USE THIS APPLICATION ON A SINGLE DOMAIN FOR
A SINGLE SHOP.

THE CODE IN THE APPLICATION MAY BE MODIFIED FOR USE IN
SETTING UP A SINGLE SHOPPING SITE ON THE WORLD WIDE WEB.

LICENSEE MAY MAKE A COPY OF THE APPLICATION FOR
BACK-UP AND ARCHIVAL PURPOSES, PROVIDED THAT ANY COPY
MUST CONTAIN ALL PROPRIETARY NOTICES INCLUDED
WITH THE APPLICATION.

LICENSEE IS PROHIBITED FROM SELLING OR DISTRIBUTING
THE APPLICATION IN ANY MANNER.

LIMITATION OF LIABILITY.

ROCKSALT INTERNATIONAL AND ITS LICENSORS SHALL
NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE OR ANY
THIRD PARTY AS A RESULT OF USING OR DISTRIBUTING THIS
APPLICATION.

IN NO EVENT WILL ROCKSALT INTERNATIONAL OR ITS LICENSORS
BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA,
OR FOR DIRECT, INDIRECT, SPECIAL,
CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES,
HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LI
ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE,
EVEN IF ROCKSALT INTERNATIONAL HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.