Payment Authentication App Example

Description

The Payment Authentication app is an app that creates a step verification to the checkout process allowing or rejecting an order placement. This repository provides an example on how to accomplish it.

Table of Contents

• Usage
• Responding to checkout
• Checkout Payload
• Injecting external script

Usage

To get started you should edit the manifest.json file to properly select the app name, for this example: example-payment-auth-app. You should also input the correct initial version and, if applicable, change the vendor name.

If you change the app name at manifest.json you also need to change the app name at extension path at pages/pages.json file, for this example: checkout/transactions/example-payment-auth-app. The template of this extension path is checkout/transactions/<app-name-here>.

Create a new workspace and link this app to your store and workspace. Go on to {{your-account}}.vtexcommercestable.com/checkout?workspace={{your-workspace}}, open the browser dev tools then run:

window.transactionAppName = '{{your-app-name}}'

If you follow through the checkout process, you should now see your app running after order confirmation.

PROTIP: vtexcommercestable does not support workspace, so you might need to export your cart to run some tests. To do that, you may go {{your-workspace}}--{{your-store}}.myvtex.com, add products to cart, go to cart, then open your browser DevTools and run:

vtexjs.checkout.orderFormId

You should get the orderFormId and then you may inject that in vtexcommercestable using: {{your-account}}.vtexcommercestable.com/checkout?workspace={{your-workspace}}&orderFormId={{your-orderFormId}}

Responding to checkout

The checkout UI API expects a response from the app through the transactionValidation.vtex event, therefore an approach for responding is:

$(window).trigger('transactionValidation.vtex', [status])

Where status is a boolean and resolves(status == true) or rejects (status == false) order placement. At this point, the checkout UI will validate if the transaction was approved or denied and according to this status if the transaction is approved checkout UI will redirect to the Order Placed page, otherwise will show a warning modal.

Please refer to the response method implementation in this repo for an example on expected response trigger.

Checkout Payload

Checkout should give you a payload via props to better be able to handle the order, to access that you just do:

const { appPayload } = this.props // This appPayload is a serialized JSON (as string).

Injecting external script

In order to be able to run external scripts on your transaction app, you need to inject that script on the head of the checkout html. To do so, you have to do a DOM injection, for that you should do:

const head = document.getElementsByTagName('head')[0]

const js = document.createElement('script')
js.id = {{script-id}}
js.src = {{script-src}}
js.async = true;
js.defer = true;
js.onload = {{callback-onload}}

head.appendChild(js)

There is an example for the script injection here

Do keep in mind that if the external js script handles DOM manipulation, then you should use React's ref to create a div container and hand it over to the library. There's also an example for doing so in this repo.