WooCommerce v2

Overview

This documentation covers version 2 of the Acquired WooCommerce Plugin — a complete rewrite of the original integration. It now uses the Acquired REST API and delivers a fully hosted checkout experience.

v2 Highlights:

• Significantly improved performance and reliability.
• Enhanced security, including mandatory 3-D Secure for applicable regions.
• Greater flexibility and configurability.

📘

Important

v2 must be installed separately from the legacy plugin. They cannot run side-by-side.

Key Differences from the Legacy Plugin

1. Separate Installation: Deactivate and remove the legacy plugin before installing v2.
2. Legacy Payments: Transactions via the old HPP integration remain on the legacy API and cannot be
   refunded or modified by v2.
3. Manual Configuration: No automatic migration; you must manually set up credentials and webhooks for v2.
4. New API & Hosted Checkout: v2 uses our RESTful API plus a fully hosted checkout, replacing the legacy HPP flow.

---

Compatibility & Migration Notes

1. Uninstall Legacy Plugin:
   1. Log in to WordPress Admin → Plugins.
   2. Deactivate and delete Acquired WooCommerce Plugin (legacy).
2. Existing Payments:
   1. Historical transactions remain on the legacy system.
   2. To refund or void, log in to the Acquired Hub (hub.acquired.com) and process
      refunds there.
3. Sandbox vs Production Credentials:
   1. Acquire separate Company-Id, App ID, and App Key for sandbox (qahub.acquired.com) and production (hub.acquired.com).

---

Upgrade Path for Existing Merchants

If you already have our legacy Acquired plugin installed and active, follow these pre-activation upgrade steps to minimise downtime (~10 seconds):

1. Add New Plugin (Do Not Activate):
   1. Download the Plug-in Zip file acquired-com-for-woocommerce.zip from:
      https://github.com/acquiredcom/acquired-payments-woocommerce/releases/tag/2.0.0-beta.4
   2. In WooCommerce go to Plugins > Add New > Upload plug-in
   3. Do not activate the new plugin yet.
2. Configure Hosted Checkout:
   1. In your Acquired Hub, complete the Hosted Checkout setup as detailed here.
3. Configure New Plugin Settings:
   1. In WooCommerce Admin → Acquired.com Gateway settings, enter your Company‑Id, App ID, App Key, and other required settings as outlined here.
4. Switch Plugins:
   1. Deactivate the legacy Acquired plugin.
   2. Activate the Acquired WooCommerce Plugin v2. This transition will cause a brief downtime of approximately 10 seconds.

---

Installation

Download & Install

1. Download the plug-in zip file ‘acquired-com-for-woocommerce.zip’ from:
   https://github.com/acquiredcom/acquired-payments-woocommerce/releases/tag/2.0.0-beta.4
2. In WooCommerce go to Plugins > Add New > Upload Plug-in

Activate Plug-in

1. In WordPress Admin, navigate to Plugins.
2. Click Activate under Acquired WooCommerce - Version 2.0.0-beta.4.

---

Configuration

Configuration is split between the Plugin Settings in WooCommerce and your Acquired.com Hub Settings.

Plugin Settings (WooCommerce Admin)

1. Enable Acquired.com Gateway
   1. Tick to enable or disable the payment gateway.
2. Title & Description
   1. Title: Displayed option name at checkout (e.g.,“Credit Card, Apple Pay”).
   2. Description: Shown under the title and in order confirmation emails.
3. Environment
   1. Staging: For QA/Sandbox testing (qahub.acquired.com).
   2. Production: For live transactions (hub.acquired.com).
4. Company-Id
   1. Retrieve from the Acquired.com Hub → Settings → Reference IDs → Company-Id.
   2. Use the correct ID matching your environment.
5. API Credentials
   1. In theAcquired.com Hub → Settings → API Access, copy your App ID and App Key for
      each environment.
6. Transaction Type
   1. Capture: Charge immediately.
   2. Authorise: Place a hold without immediate capture.
7. Payment Reference
   1. Enter your website name (alphanumeric, no special characters).
8. Debug Log
   1. Enable for detailed request/response logging.
   2. Disable in production to conserve server resources.
9. Save Payment Methods
   1. Allows customers to save cards for future purchases.
   2. Also enable Save Cards in the Acquired.com Hub → Hosted Checkout → Cards →
      Settings.
10. 3-D Secure
    1. Mandatory for UK/Europe in production.
    2. Ensure this toggle is ON to avoid failed transactions.
11. Challenge Preferences
    1. Set your 3DSv2 challenge preference; note that issuing banks may override.
12. Contact URL
    1. URL for customer support or “Need help?” links during checkout.
13. Submit Type
    1. Customise the label on the hosted checkout’s submit button (e.g.,“Pay Now”).
14. Update Card Webhook
    1. For Account Updater or Network Tokens:
       1. In the Acquired.com Hub → Hosted Checkout → Cards → Settings, enable Save Cards.
       2. Copy the provided webhook URL into this plugin field.

Acquired.com Hub Settings

1. Hosted Checkout Configuration
   1. Follow the step-by-step guide here.
2. Webhook Setup
   1. Go to the Hub → Settings → Webhooks, add your endpoint URL.
   2. Verify it responds with HTTP 200.
3. IP Whitelisting
   1. Whitelist your WooCommerce server IPs in the Hub to ensure webhook events
      are not blocked.

Order Settings (Plugin)

Cancel Refunded Orders

Automatically mark orders as Canceled in WooCommerce when a refund occurs.

📘

Required

Enable this if you support lottery products.

Wallet for Failed Orders

Allows customers to retry payments on failed orders.

📘

Required

Enable this if you support lottery products.

---

Checkout Flow

1. Customer chooses Acquired Hosted Checkout at WooCommerce checkout.
2. Redirected to the hosted page for payment details.
3. After successful payment, customer returns to the WooCommerce confirmation page.
4. Order status updates automatically via webhooks (processing, completed, etc.).

---

Testing

1. In plugin settings, turn on Staging Mode.
2. Use test card numbers from your Acquired QA dashboard.
3. Inspect logs under WooCommerce → Status → Logs and select acquired_gateway.

---

Troubleshooting

1. Webhook Failures:

• Confirm your endpoint is accessible publicly and returns HTTP 200.

2. Signature Mismatch:

• Verify the webhook secret in the plugin matches Acquired Hub.

3. Payment Declines:

• Check your debug log for provider-specific error codes.