TABLE OF CONTENTS

Overview

The checkout call is used to process payments and create orders. There are many different endpoints, depending on which application or sale channel is being used.  The driver for selecting  a checkout endpoint should be, “to which sale channel do I want this sale attributed?”

While the checkout object is mostly the same across all sale channels, there are some slight differences depending on the endpoint you use.  This section will provide information specific to each checkout endpoint.


Endpoints


Method

Endpoint

Sale Channel

POST

/v2/b2c/checkout
/v2/b2c/cors/checkout

Online (B2C)

POST

/v2/b2b/orders/checkout

Inside Sales

POST

/v2/b2b/checkout/kiosk
/v2/b2c/checkout/pointofsale

Kiosk
Point of Sale

POST

/v2/b2b/orders/organizations/{organizationId}

Reseller

 

Preventing B2C Credit Card Phishing Attacks

The unauthenticated consumer ticket/membership sales flow for B2C API implementations is regularly subject to attacks from spammers who will try if a card authentication works via a charge and then go on to charge that card found valid into other online stores, or anywhere else.

Those attacks often are caused by bots and end up creating an unnecessary rather large transaction cost, via chargebacks or decline authorizations,  on the merchant of record (MOR), given that attacks happen in bursty large batches. When ACME is the MOR,  and therefore owns the costs, it reserves the right to turn the B2C API traffic to minimize financial losses. When ACME is not the MOR, such as when OTAs call us (they do the payments outside of us) , we want to make sure that our checkout infra provides the ability to protect the MOR via preventing such attacks.

 

One of our many prevention mechanisms is currently based on an invisible CAPTCHA mechanism (Google reCAPTCHA v3) whereby external AI underneath our stack does score a safety number based on the different browser patterns (IP, cookies, etc.)


We require our all API implementations (including our B2C) to insert Google reCAPTCHA into their payment pages and pass the captcha token to our checkout API call.


NEW - required by Feb 28, 2023
In addition to Google reCAPTCHA v3, we also require implementation of the Google reCAPTCHA v2 Checkbox as a strong way to further weed out bot activity from real guest and member purchases.

 

Please use this Google documentation for your JS coding:
https://www.google.com/recaptcha/about/

API Keys & Implementation

  • reCAPTCHA v2 Checkbox: 
    • Generate your Site and Secret Keys via the Google Admin Console ›
    • You will own implementation of this. We recommend displaying and validating the "I am not a robot" checkbox just prior to your final checkout call.
  • reCAPTCHA v3: 
    • Before this functionality can work you will need to email our API support team so that the client facing URL can be safelisted in our infrastructure.
    • Use the ACME Generated Site keys as V3 needs to go through our account to properly manage with the checkout call.
    • Once you get the token from the Google JS, you only need to pass it as an http header called “x-acme-captcha-token” into our checkout API, whether called from the browser or from your server.


IMPORTANT: The Google reCAPTCHA token will expire after some time, which will block a successful checkout. Please refer to Google's documentation for additional information on how to best handle this.


Please note that if you are the merchant of record, you may decide to use your own card phishing prevention mechanism. We do however recommend our fraud prevention system given it collects data for all of our clients at once and leverage the AI algorithms of Google at scale, therefore it should detect attacks on your site much faster thanks to a larger training data set.


Preventing Duplicate Charges

A common issue that developers run into when building custom integrations is with users being charged twice or multiple orders being created at checkout.  We have a couple of best practices to safeguard against this issue and to help avoid the need for emergency code changes in your integration.


Request UUID Header

We strongly recommend generating a UUID for each checkout transaction and sending that via the x-acme-request-uuid header.  If the backend sees two back-to-back checkout attempts with the same UUID, it will reject that transaction as a duplicate and return a DUPLICATE_TRANSACTION error.

x-acme-request-uuid: 8270b929-44ea-46fc-b399-cfe6fa960f24


Front-End Prevention

The other strategy we recommend is to prevent users from creating duplicate transactions via your front end.  Strategies include blocking the “submit” or “checkout” button after it’s been clicked or providing visual feedback to the user that the request is in process.  The most common cause of duplicate orders is users thinking that “nothing’s happening” and clicking the “submit” button multiple times. Providing visual feedback that the click was successful and the order is being processed is very effective in preventing duplicate transactions from being submitted to ACME.


Server-Side Prevention

In addition, ACME fingerprints the card with the amount as an added layer of transaction duplication protection on checkout. If the same card with the exact same amount is used within 5 minutes, error code 16003 will be triggered with the message “Duplicate transaction found” and type “DUPLICATE_TRANSACTION_FOUND”. Should this be intentional (e.g. two subsequent orders for the same amount), the user try again after 5 minutes.


Things to note for Server-Side Prevention: 

  • Timeframes may be modified at the discretion of ACME.
  • Server-Side Prevention is only supported for our clients on our native payment rails. This is not supported for clients on Stripe.