<?php
|
namespace JVBase\integrations;
|
|
use Exception;
|
use WP_Error;
|
use WP_Post;
|
use JVBase\ui\Checkout;
|
use JVBase\managers\queue\TypeConfig;
|
use JVBase\managers\queue\executors\IntegrationExecutor;
|
|
if (!defined('ABSPATH')) {
|
exit;
|
}
|
|
/**
|
* Helcim Integration Class
|
*
|
* Handles HelcimPay.js checkout, invoice retrieval, customer/card management,
|
* and bidirectional product sync via API token authentication.
|
*
|
* Helcim is the source of truth for invoices and orders.
|
* Products sync bidirectionally through the standard integration field flow.
|
*
|
* @since 1.0.0
|
*/
|
class Helcim extends Integrations
|
{
|
protected string $service_name = 'helcim';
|
protected string|array $apiBase = 'https://api.helcim.com/v2';
|
|
protected bool $isOAuthService = false;
|
|
/**
|
* Helcim API rate limits
|
* @see https://devdocs.helcim.com/docs/api-rate-limits
|
*/
|
protected array $rate_limits = [
|
'per_second' => 5,
|
'per_minute' => 60,
|
'per_hour' => 1000
|
];
|
|
public function __construct(?int $userID = null)
|
{
|
$this->title = 'Helcim';
|
$this->icon = 'credit-card';
|
|
$this->fields = [
|
'api_token' => [
|
'type' => 'text',
|
'subtype' => 'password',
|
'label' => 'API Token',
|
'hint' => 'Found in Helcim Dashboard → Settings → API Access',
|
'required' => true,
|
],
|
'currency' => [
|
'type' => 'select',
|
'label' => 'Currency',
|
'options' => [
|
'CAD' => 'CAD',
|
'USD' => 'USD',
|
],
|
'default' => 'CAD',
|
],
|
];
|
|
$this->advanced = [
|
'fee_saver' => [
|
'type' => 'true_false',
|
'label' => 'Fee Saver',
|
'hint' => 'Pass processing fees to customers (not compatible with Google Pay)',
|
],
|
'allow_ach' => [
|
'type' => 'true_false',
|
'label' => 'Allow ACH/Bank Payments',
|
'hint' => 'Enable bank account payments alongside credit card',
|
],
|
];
|
|
$this->instructions = [
|
'Go to <a href="https://my.helcim.com" target="_blank">Helcim Dashboard</a>',
|
'Navigate to Settings → API Access',
|
'Create a new API Access Configuration',
|
'Enable permissions: General (Customers, Invoices, Products), Transaction Processing',
|
'Copy the API Token and paste it below',
|
];
|
|
$this->canSync = [
|
'create' => true,
|
'update' => true,
|
'delete' => false,
|
];
|
|
$this->handleWebhooks = false;
|
|
parent::__construct($userID);
|
|
// Helcim-specific actions (processAction dispatches these)
|
$this->actions = array_merge($this->actions, [
|
'initialize_checkout' => 'initializeCheckout',
|
'get_invoices' => 'handleGetInvoices',
|
'get_invoice' => 'handleGetInvoice',
|
'get_customer_cards' => 'handleGetCustomerCards',
|
]);
|
|
$this->buttons = array_merge($this->buttons, [
|
'import_from_helcim' => 'Import Products from Helcim',
|
'sync_to_helcim' => 'Sync Site to Helcim',
|
]);
|
}
|
|
/*****************************************************************
|
* ABSTRACT IMPLEMENTATIONS
|
*****************************************************************/
|
|
protected function initialize(): void
|
{
|
if (empty($this->credentials)) {
|
$this->loadCredentials();
|
}
|
|
$this->apiEndpoints = [
|
'connection-test',
|
'helcim-pay/initialize',
|
'invoices',
|
'customers',
|
'payment/purchase',
|
'payment/preauth',
|
'payment/capture',
|
'payment/refund',
|
'payment/verify',
|
'card-transactions',
|
'card-batches',
|
];
|
}
|
|
protected function getRequestHeaders(): array
|
{
|
return [
|
'api-token' => $this->credentials['api_token'] ?? '',
|
'Content-Type' => 'application/json',
|
'Accept' => 'application/json',
|
];
|
}
|
|
protected function performConnectionTest(): bool
|
{
|
try {
|
$response = $this->getRequest('connection-test', [], null, 'none', true);
|
return !is_wp_error($response) && !$this->isErrorResponse($response ?? []);
|
} catch (Exception $e) {
|
$this->logError('Connection test failed', ['error' => $e->getMessage()]);
|
return false;
|
}
|
}
|
|
/*****************************************************************
|
* CONTENT TYPES — product field definitions
|
*****************************************************************/
|
|
protected function setContentTypes(): void
|
{
|
$this->has_content = true;
|
$this->defaultContent = 'REGULAR';
|
$types = ['REGULAR', 'SERVICE', 'DIGITAL', 'FOOD_AND_BEV', 'EVENT', 'SUBSCRIPTION', 'DONATION'];
|
|
foreach ($types as $type) {
|
$t = $type === 'REGULAR' ? null : $type;
|
$this->contentTypes[$type] = $this->getHelcimMeta($t);
|
}
|
}
|
|
public function getAdditionalFields(?string $content_type = null):array
|
{
|
return array_combine(
|
array_map(fn($k) => 'hc_' . $k, array_keys($this->getHelcimMeta($content_type))),
|
$this->getHelcimMeta($content_type)
|
);
|
}
|
|
/**
|
* Get Helcim product meta fields by type.
|
*
|
* Used by Registrar.php when helcim is configured
|
*/
|
public function getHelcimMeta(?string $type = null): array
|
{
|
$fields = [
|
// Basic Product Fields
|
'price' => [
|
'type' => 'number',
|
'bulkEdit' => true,
|
'label' => 'Price',
|
'step' => 0.01,
|
'max' => 99999,
|
'description' => 'Product price'
|
],
|
|
'product_type' => [
|
'type' => 'select',
|
'label' => 'Product Type',
|
'options' => [
|
'REGULAR' => 'Regular Product',
|
'SERVICE' => 'Service',
|
'DIGITAL' => 'Digital Product',
|
'FOOD_AND_BEV' => 'Food & Beverage',
|
'EVENT' => 'Event/Ticket',
|
'SUBSCRIPTION' => 'Subscription',
|
'DONATION' => 'Donation'
|
],
|
'default' => $type ?? 'REGULAR'
|
],
|
|
'cart_quantity' => [
|
'type' => 'number',
|
'label' => 'Quantity',
|
'hidden' => true,
|
],
|
|
// Tax & Shipping
|
'tax_exempt' => [
|
'type' => 'true_false',
|
'label' => 'Tax Exempt',
|
'section' => 'helcim-tax'
|
],
|
|
'shipping_required' => [
|
'type' => 'true_false',
|
'label' => 'Shipping Required',
|
'section' => 'helcim-shipping'
|
],
|
|
'shipping_weight' => [
|
'type' => 'number',
|
'label' => 'Shipping Weight (kg)',
|
'step' => 0.01,
|
'section' => 'helcim-shipping',
|
'condition' => [
|
'field' => 'shipping_required',
|
'operator' => '==',
|
'value' => true
|
]
|
],
|
|
// Availability
|
'available_online' => [
|
'type' => 'true_false',
|
'label' => 'Available Online',
|
'section' => 'helcim-availability',
|
'default' => true
|
],
|
|
'available_for_pickup' => [
|
'type' => 'true_false',
|
'label' => 'Available for Pickup',
|
'section' => 'helcim-availability',
|
'default' => true
|
],
|
|
'available_for_delivery' => [
|
'type' => 'true_false',
|
'label' => 'Available for Delivery',
|
'section' => 'helcim-availability',
|
'default' => false
|
],
|
|
'_helcim_sku' => [
|
'type' => 'text',
|
'label' => 'SKU',
|
'description' => 'Stock keeping unit',
|
'section' => 'helcim-config'
|
],
|
|
// Product Variations
|
'product_variations' => [
|
'type' => 'repeater',
|
'label' => 'Product Variations',
|
'description' => 'Different versions of this product',
|
'add_label' => 'Add Variation',
|
'section' => 'variations',
|
'fields' => $this->getHelcimVariationMeta($type)
|
],
|
|
// Product Options
|
'options' => [
|
'type' => 'group',
|
'label' => 'Product Options',
|
'section'=> 'helcim-options',
|
'fields' => [
|
'max_order' => [
|
'type' => 'number',
|
'label' => 'Maximum per order',
|
'default' => 50
|
],
|
'min_order' => [
|
'type' => 'number',
|
'label' => 'Minimum per order',
|
'default' => 0,
|
],
|
'step' => [
|
'type' => 'number',
|
'label' => 'Order increment',
|
'default' => 1,
|
],
|
'preparation_time' => [
|
'type' => 'number',
|
'label' => 'Preparation time (minutes)',
|
'description' => 'Time needed to prepare this item',
|
'condition' => [
|
'field' => 'product_type',
|
'operator' => 'in',
|
'value' => ['FOOD_AND_BEV', 'SERVICE']
|
]
|
]
|
]
|
],
|
|
// Subscription Fields
|
'subscription_settings' => [
|
'type' => 'group',
|
'label' => 'Subscription Settings',
|
'section' => 'helcim-subscription',
|
'condition' => [
|
'field' => 'product_type',
|
'operator' => '==',
|
'value' => 'SUBSCRIPTION'
|
],
|
'fields' => [
|
'billing_cycle' => [
|
'type' => 'select',
|
'label' => 'Billing Cycle',
|
'options' => [
|
'daily' => 'Daily',
|
'weekly' => 'Weekly',
|
'monthly' => 'Monthly',
|
'quarterly' => 'Quarterly',
|
'yearly' => 'Yearly'
|
],
|
'default' => 'monthly'
|
],
|
'trial_period' => [
|
'type' => 'number',
|
'label' => 'Trial Period (days)',
|
'description' => 'Free trial period before billing starts',
|
'default' => 0
|
],
|
'setup_fee' => [
|
'type' => 'number',
|
'label' => 'Setup Fee',
|
'step' => 0.01,
|
'description' => 'One-time setup fee'
|
]
|
]
|
],
|
|
// Food & Beverage Specific
|
'food_settings' => [
|
'type' => 'group',
|
'label' => 'Food & Beverage Settings',
|
'section' => 'helcim-food',
|
'condition' => [
|
'field' => 'product_type',
|
'operator' => '==',
|
'value' => 'FOOD_AND_BEV'
|
],
|
'fields' => [
|
'ingredients' => [
|
'type' => 'textarea',
|
'label' => 'Ingredients',
|
'description' => 'List ingredients (comma separated)'
|
],
|
'allergens' => [
|
'type' => 'checkbox_list',
|
'label' => 'Allergens',
|
'options' => [
|
'gluten' => 'Contains Gluten',
|
'dairy' => 'Contains Dairy',
|
'nuts' => 'Contains Nuts',
|
'soy' => 'Contains Soy',
|
'eggs' => 'Contains Eggs',
|
'seafood' => 'Contains Seafood'
|
]
|
],
|
'dietary_options' => [
|
'type' => 'checkbox_list',
|
'label' => 'Dietary Options',
|
'options' => [
|
'vegetarian' => 'Vegetarian',
|
'vegan' => 'Vegan',
|
'gluten_free' => 'Gluten Free',
|
'dairy_free' => 'Dairy Free',
|
'keto' => 'Keto Friendly',
|
'halal' => 'Halal',
|
'kosher' => 'Kosher'
|
]
|
],
|
'spice_level' => [
|
'type' => 'range',
|
'label' => 'Spice Level',
|
'min' => 0,
|
'max' => 5,
|
'default' => 0
|
],
|
'serving_size' => [
|
'type' => 'text',
|
'label' => 'Serving Size',
|
'description' => 'e.g., "Serves 2-3"'
|
]
|
]
|
],
|
|
// Service Specific
|
'service_settings' => [
|
'type' => 'group',
|
'label' => 'Service Settings',
|
'section' => 'helcim-service',
|
'condition' => [
|
'field' => 'product_type',
|
'operator' => '==',
|
'value' => 'SERVICE'
|
],
|
'fields' => [
|
'service_duration' => [
|
'type' => 'number',
|
'label' => 'Duration (minutes)',
|
'description' => 'Service duration in minutes'
|
],
|
'booking_required' => [
|
'type' => 'true_false',
|
'label' => 'Booking Required'
|
],
|
'capacity' => [
|
'type' => 'number',
|
'label' => 'Service Capacity',
|
'description' => 'Maximum number of customers per service'
|
],
|
'staff_required' => [
|
'type' => 'number',
|
'label' => 'Staff Required',
|
'description' => 'Number of staff needed',
|
'default' => 1
|
]
|
]
|
],
|
|
// Event Specific
|
'event_settings' => [
|
'type' => 'group',
|
'label' => 'Event Settings',
|
'section' => 'helcim-event',
|
'condition' => [
|
'field' => 'product_type',
|
'operator' => '==',
|
'value' => 'EVENT'
|
],
|
'fields' => [
|
'event_date' => [
|
'type' => 'datetime',
|
'label' => 'Event Date & Time'
|
],
|
'event_location' => [
|
'type' => 'text',
|
'label' => 'Event Location'
|
],
|
'max_attendees' => [
|
'type' => 'number',
|
'label' => 'Maximum Attendees'
|
],
|
'early_bird_price' => [
|
'type' => 'number',
|
'label' => 'Early Bird Price',
|
'step' => 0.01,
|
'description' => 'Discounted price for early registrations'
|
],
|
'early_bird_deadline' => [
|
'type' => 'date',
|
'label' => 'Early Bird Deadline'
|
]
|
]
|
]
|
];
|
|
// Add inventory fields if configured
|
if ($config['hasInventory'] ?? false) {
|
$fields['_helcim_inventory'] = [
|
'type' => 'number',
|
'label' => 'Inventory',
|
'bulkEdit' => true,
|
'section' => 'inventory'
|
];
|
|
$fields['track_inventory'] = [
|
'type' => 'true_false',
|
'label' => 'Track Inventory',
|
'section' => 'inventory',
|
'default' => true
|
];
|
|
$fields['low_stock_threshold'] = [
|
'type' => 'number',
|
'label' => 'Low Stock Alert',
|
'description' => 'Alert when stock falls below this level',
|
'section' => 'inventory',
|
'default' => 5
|
];
|
|
$fields['product_variations']['fields']['inventory'] = [
|
'type' => 'number',
|
'label' => 'Stock Quantity',
|
'description' => 'Current stock for this variation'
|
];
|
}
|
|
return $fields;
|
}
|
|
public function getHelcimVariationMeta(?string $type = null):array
|
{
|
|
$base = [
|
'name' => [
|
'type' => 'text',
|
'label' => 'Variation Name',
|
'description' => 'e.g., "Small", "Large", "Red"'
|
],
|
'price' => [
|
'type' => 'number',
|
'label' => 'Price',
|
'step' => 0.01,
|
'max' => 99999,
|
'description' => 'Price for this variation'
|
],
|
'sku' => [
|
'type' => 'text',
|
'label' => 'SKU',
|
'description' => 'Stock keeping unit for this variation'
|
],
|
'track_inventory' => [
|
'type' => 'true_false',
|
'label' => 'Track Inventory',
|
],
|
'_helcim_variation_id' => [
|
'type' => 'text',
|
'label' => 'Helcim Variation ID',
|
'description' => 'Helcim ID for this variation',
|
'hidden' => true
|
],
|
'_helcim_last_sync' => [
|
'type' => 'datetime',
|
'label' => 'Last Sync',
|
'hidden' => true
|
],
|
'options' => [
|
'type' => 'group',
|
'label' => 'Variation Options',
|
'collapsible' => true,
|
'fields' => [
|
'color' => [
|
'type' => 'color',
|
'label' => 'Color',
|
'description' => 'Visual color for this variation'
|
],
|
'size' => [
|
'type' => 'select',
|
'label' => 'Size',
|
'options' => [
|
'' => 'N/A',
|
'xs' => 'Extra Small',
|
's' => 'Small',
|
'm' => 'Medium',
|
'l' => 'Large',
|
'xl' => 'Extra Large',
|
'xxl' => '2X Large',
|
'custom'=> 'Custom'
|
]
|
],
|
'custom_size' => [
|
'type' => 'text',
|
'label' => 'Custom Size',
|
'condition' => [
|
'field' => 'size',
|
'operator' => '==',
|
'value' => 'custom'
|
]
|
],
|
'weight' => [
|
'type' => 'number',
|
'label' => 'Weight (kg)',
|
'step' => 0.01,
|
'description' => 'Weight of this variation'
|
],
|
'dimensions' => [
|
'type' => 'group',
|
'label' => 'Dimensions',
|
'fields' => [
|
'length' => [
|
'type' => 'number',
|
'label' => 'Length (cm)',
|
'step' => 0.1
|
],
|
'width' => [
|
'type' => 'number',
|
'label' => 'Width (cm)',
|
'step' => 0.1
|
],
|
'height' => [
|
'type' => 'number',
|
'label' => 'Height (cm)',
|
'step' => 0.1
|
]
|
]
|
]
|
]
|
]
|
];
|
|
$extras = [
|
'SERVICE' => [
|
'service_duration' => [
|
'type' => 'number',
|
'label' => 'Duration (minutes)',
|
'description' => 'Duration for this service variation'
|
],
|
'available_for_booking' => [
|
'type' => 'true_false',
|
'label' => 'Available for Booking'
|
]
|
],
|
|
'FOOD_AND_BEV' => [
|
'portion_size' => [
|
'type' => 'select',
|
'label' => 'Portion Size',
|
'options' => [
|
'small' => 'Small',
|
'regular' => 'Regular',
|
'large' => 'Large',
|
'family' => 'Family Size'
|
]
|
],
|
'calories' => [
|
'type' => 'number',
|
'label' => 'Calories',
|
'description' => 'Calorie count for this variation'
|
]
|
],
|
|
'DIGITAL' => [
|
'download_limit' => [
|
'type' => 'number',
|
'label' => 'Download Limit',
|
'description' => 'Maximum number of downloads',
|
'default' => -1
|
],
|
'expiry_days' => [
|
'type' => 'number',
|
'label' => 'Access Duration (days)',
|
'description' => 'Days until download expires',
|
'default' => 0
|
]
|
]
|
];
|
if ($type && array_key_exists($type, $extras)){
|
$base = array_merge($base, $extras[$type]);
|
}
|
return $base;
|
}
|
|
/*****************************************************************
|
* HELCIMPAY.JS — Frontend Scripts & Checkout Initialization
|
*****************************************************************/
|
|
protected function registerAdditionalHooks(): void
|
{
|
if (!$this->isSetUp()) {
|
return;
|
}
|
|
add_action('wp_enqueue_scripts', [$this, 'enqueueScripts']);
|
|
// Shared checkout UI (replaces provider-specific outputCheckout)
|
add_filter('jvbAdditionalActions', [Checkout::class, 'render']);
|
|
// Checkout description filter
|
add_filter('jvb_checkout_description', function (string $desc, string $provider) {
|
if ($provider === 'helcim') {
|
return 'Securely checkout with your name, email, and payments processed by Helcim.';
|
}
|
return $desc;
|
}, 10, 2);
|
|
// Register queue operation types with IntegrationExecutor
|
$this->registerQueueTypes();
|
|
// Register webhook endpoint (handled by parent)
|
$this->registerWebhookEndpoint();
|
}
|
|
public function enqueueScripts(): void
|
{
|
// HelcimPay.js SDK
|
wp_enqueue_script(
|
'helcim-pay-sdk',
|
'https://secure.helcim.app/helcim-pay/services/start.js',
|
[],
|
null,
|
true
|
);
|
|
// Base cart checkout (shared with Square)
|
wp_register_script(
|
'jvb-checkout',
|
JVB_URL . 'assets/js/min/checkout.min.js',
|
['jvb-utility', 'jvb-queue', 'jvb-a11y', 'jvb-cache', 'jvb-tabs', 'jvb-popup'],
|
'1.1.31',
|
true
|
);
|
|
// Helcim checkout (extends CartCheckout)
|
wp_register_script(
|
'jvb-helcim-checkout',
|
JVB_URL . 'assets/js/min/helcim.min.js',
|
['jvb-checkout', 'helcim-pay-sdk'],
|
'1.1.31',
|
true
|
);
|
|
wp_localize_script('jvb-helcim-checkout', 'helcimConfig', [
|
'api_url' => rest_url('jvb/v1/helcim/'),
|
'nonce' => wp_create_nonce('wp_rest'),
|
'currency' => $this->credentials['currency'] ?? 'CAD',
|
'is_logged_in' => is_user_logged_in(),
|
'user_email' => is_user_logged_in() ? wp_get_current_user()->user_email : '',
|
'isOpen' => apply_filters('jvb_store_is_open', '1'),
|
]);
|
|
wp_enqueue_script('jvb-helcim-checkout');
|
}
|
|
|
protected function registerQueueTypes(): void
|
{
|
$queue = JVB()->queue();
|
$executor = new IntegrationExecutor();
|
|
$queue->registry()->register('helcim_sync_to', new TypeConfig(
|
executor: $executor,
|
chunkKey: 'items',
|
chunkSize: 10,
|
maxRetries: 3
|
));
|
|
$queue->registry()->register('helcim_sync_from', new TypeConfig(
|
executor: $executor,
|
chunkKey: 'items',
|
chunkSize: 10,
|
maxRetries: 3
|
));
|
|
$queue->registry()->register('helcim_delete_from', new TypeConfig(
|
executor: $executor,
|
chunkKey: 'external_ids',
|
chunkSize: 20,
|
maxRetries: 2
|
));
|
|
$queue->registry()->register('helcim_import', new TypeConfig(
|
executor: $executor,
|
maxRetries: 3
|
));
|
|
$queue->registry()->register('helcim_sync_customer', new TypeConfig(
|
executor: $executor,
|
maxRetries: 2
|
));
|
}
|
|
/**
|
* Initialize a HelcimPay.js checkout session.
|
*
|
* Server-side: POST /helcim-pay/initialize → returns checkoutToken + secretToken.
|
* Client-side: appendHelcimPayIframe(checkoutToken) renders the payment modal.
|
* Tokens are valid for 60 minutes.
|
*
|
* @param array $data [
|
* 'amount' => float, // Required
|
* 'invoiceId' => string, // Optional — pay a specific invoice
|
* 'customerId' => int, // Optional — associate with Helcim customer
|
* 'paymentType' => string, // purchase|preauth|verify (default: purchase)
|
* ]
|
*/
|
public function initializeCheckout(array $data): array
|
{
|
if (empty($data['amount']) || (float) $data['amount'] <= 0) {
|
return ['success' => false, 'message' => 'Invalid amount'];
|
}
|
|
$paymentMethod = !empty($this->credentials['allow_ach']) ? 'cc-ach' : 'cc';
|
|
$body = [
|
'paymentType' => $data['paymentType'] ?? 'purchase',
|
'amount' => (float) $data['amount'],
|
'currency' => $this->credentials['currency'] ?? 'CAD',
|
'paymentMethod' => $paymentMethod,
|
];
|
|
if (!empty($data['invoiceId'])) {
|
$body['invoiceNumber'] = $data['invoiceId'];
|
}
|
|
if (!empty($data['customerId'])) {
|
$body['customerId'] = (int) $data['customerId'];
|
}
|
|
if (!empty($this->credentials['fee_saver'])) {
|
$body['hasConvenienceFee'] = true;
|
}
|
|
$response = $this->postRequest('helcim-pay/initialize', $body);
|
|
if (is_wp_error($response)) {
|
return ['success' => false, 'message' => $response->get_error_message()];
|
}
|
|
if (empty($response['checkoutToken'])) {
|
return ['success' => false, 'message' => 'Failed to initialize checkout'];
|
}
|
|
return [
|
'success' => true,
|
'checkoutToken' => $response['checkoutToken'],
|
'secretToken' => $response['secretToken'] ?? '',
|
];
|
}
|
|
/*****************************************************************
|
* INVOICES — Helcim is source of truth
|
*****************************************************************/
|
|
/**
|
* Get invoices for a customer.
|
*
|
* @param array $data ['email' => string] or ['customerId' => int]
|
*/
|
public function handleGetInvoices(array $data): array
|
{
|
$customerId = $data['customerId'] ?? null;
|
|
if (empty($customerId) && !empty($data['email'])) {
|
$customerId = $this->getCustomerIdByEmail($data['email']);
|
}
|
|
if (!$customerId) {
|
return ['success' => true, 'invoices' => []];
|
}
|
|
$response = $this->getRequest('invoices', ['customerId' => $customerId], null, 'minimal');
|
|
if (is_wp_error($response) || !is_array($response)) {
|
return ['success' => false, 'message' => 'Failed to fetch invoices'];
|
}
|
|
return ['success' => true, 'invoices' => $response];
|
}
|
|
/**
|
* Get a single invoice by ID.
|
*/
|
public function handleGetInvoice(array $data): array
|
{
|
$invoiceId = $data['invoiceId'] ?? null;
|
|
if (!$invoiceId) {
|
return ['success' => false, 'message' => 'Invoice ID required'];
|
}
|
|
$response = $this->getRequest("invoices/{$invoiceId}", [], null, 'minimal');
|
|
if (is_wp_error($response) || !is_array($response)) {
|
return ['success' => false, 'message' => 'Failed to fetch invoice'];
|
}
|
|
return ['success' => true, 'invoice' => $response];
|
}
|
|
/*****************************************************************
|
* CUSTOMERS & CARDS
|
*****************************************************************/
|
|
/**
|
* Find Helcim customer ID by email.
|
*/
|
public function getCustomerIdByEmail(string $email): ?int
|
{
|
$cacheKey = 'customer_email_' . md5($email);
|
$cached = $this->cache->get($cacheKey);
|
|
if ($cached !== false) {
|
return (int) $cached;
|
}
|
|
$response = $this->getRequest('customers', ['search' => $email], null, 'none', true);
|
|
if (is_wp_error($response) || empty($response)) {
|
return null;
|
}
|
|
$customers = is_array($response) ? $response : [];
|
$emailLower = strtolower($email);
|
|
foreach ($customers as $customer) {
|
$contactEmail = strtolower($customer['contactEmail'] ?? $customer['email'] ?? '');
|
if ($contactEmail === $emailLower) {
|
$this->cache->set($cacheKey, $customer['id'], $this->cacheStrategy['aggressive']);
|
return (int) $customer['id'];
|
}
|
}
|
|
return null;
|
}
|
|
/**
|
* Get or create a Helcim customer.
|
*/
|
public function getOrCreateCustomer(array $info): ?int
|
{
|
if (empty($info['email'])) {
|
return null;
|
}
|
|
$existing = $this->getCustomerIdByEmail($info['email']);
|
if ($existing) {
|
return $existing;
|
}
|
|
$response = $this->postRequest('customers', [
|
'contactName' => $info['name'] ?? '',
|
'contactEmail' => $info['email'],
|
'cellphone' => $info['phone'] ?? '',
|
]);
|
|
if (is_wp_error($response) || empty($response['id'])) {
|
return null;
|
}
|
|
return (int) $response['id'];
|
}
|
|
/**
|
* Get saved cards for a customer.
|
*/
|
public function handleGetCustomerCards(array $data): array
|
{
|
$customerId = $data['customerId'] ?? null;
|
|
if (empty($customerId) && !empty($data['email'])) {
|
$customerId = $this->getCustomerIdByEmail($data['email']);
|
}
|
|
if (!$customerId) {
|
return ['success' => true, 'cards' => []];
|
}
|
|
$response = $this->getRequest("customers/{$customerId}/cards", [], null, 'moderate');
|
|
if (is_wp_error($response) || !is_array($response)) {
|
return ['success' => false, 'message' => 'Failed to fetch cards'];
|
}
|
|
return ['success' => true, 'cards' => $response];
|
}
|
|
/**
|
* Get bank accounts for a customer.
|
*/
|
public function getCustomerBankAccounts(int $customerId): array
|
{
|
$response = $this->getRequest("customers/{$customerId}/bank-accounts", [], null, 'moderate');
|
return (!is_wp_error($response) && is_array($response)) ? $response : [];
|
}
|
|
/*****************************************************************
|
* TRANSACTIONS
|
*****************************************************************/
|
|
public function getTransactions(array $params = []): array
|
{
|
$response = $this->getRequest('card-transactions', $params, null, 'minimal');
|
return (!is_wp_error($response) && is_array($response)) ? $response : [];
|
}
|
|
public function refundPayment(array $data): array
|
{
|
$response = $this->postRequest('payment/refund', $data);
|
|
if (is_wp_error($response)) {
|
return ['success' => false, 'message' => $response->get_error_message()];
|
}
|
|
return ['success' => true, 'transaction' => $response];
|
}
|
|
/*****************************************************************
|
* PRODUCT SYNC
|
*****************************************************************/
|
|
protected function handleTheSavePost(int $postID, \WP_Post $post, bool $update, array $settings): void
|
{
|
$fields = $this->getSyncFields($postID, 'post', ['share_to_helcim', 'schedule_helcim']);
|
|
if (empty($fields['share_to_helcim'])) {
|
return;
|
}
|
|
// Uses IntegrationExecutor via TypeRegistry instead of FilteredExecutor
|
$this->queueOperation('sync_to', [
|
'items' => [$postID],
|
'user_id' => $this->userID,
|
], [
|
'priority' => 'high',
|
'delay' => 30,
|
]);
|
|
update_post_meta($postID, BASE . '_helcim_sync_status', 'queued');
|
}
|
|
protected function handleImportFromHelcim(): array
|
{
|
$this->queueOperation('import_products', [
|
'user_id' => $this->userID,
|
], ['priority' => 'normal']);
|
|
return ['success' => true, 'message' => 'Import from Helcim queued'];
|
}
|
|
/*****************************************************************
|
* USER ↔ CUSTOMER LINKING
|
*****************************************************************/
|
|
public function linkUserToCustomer(int $userId, int $helcimCustomerId): void
|
{
|
update_user_meta($userId, BASE . '_helcim_customer_id', $helcimCustomerId);
|
}
|
|
public function getUserCustomerId(int $userId): ?int
|
{
|
$id = get_user_meta($userId, BASE . '_helcim_customer_id', true);
|
return $id ? (int) $id : null;
|
}
|
|
/**
|
* Resolve customer ID from user meta, falling back to email lookup + auto-link.
|
*/
|
public function resolveCustomerId(int $userId): ?int
|
{
|
$id = $this->getUserCustomerId($userId);
|
if ($id) {
|
return $id;
|
}
|
|
$user = get_userdata($userId);
|
if (!$user || empty($user->user_email)) {
|
return null;
|
}
|
|
$id = $this->getCustomerIdByEmail($user->user_email);
|
if ($id) {
|
$this->linkUserToCustomer($userId, $id);
|
}
|
|
return $id;
|
}
|
|
/*****************************************************************
|
* VALIDATION
|
*****************************************************************/
|
|
/**
|
* Validate a HelcimPay.js transaction using the secret token.
|
*
|
* After the frontend receives a SUCCESS message event, call this
|
* server-side to verify the transaction hash.
|
*/
|
public function validateTransaction(string $secretToken, array $transactionData): bool
|
{
|
$hash = hash('sha256', $secretToken . json_encode($transactionData));
|
return hash_equals($hash, $transactionData['hash'] ?? '');
|
}
|
/*******************************************************************
|
* WEBHOOKS
|
*******************************************************************/
|
/**
|
* Validate Helcim webhook signature.
|
*
|
* Helcim signs webhooks with HMAC-SHA256 using:
|
* signedContent = "{webhook-id}.{webhook-timestamp}.{body}"
|
* key = base64_decode(verifierToken)
|
*
|
* Headers: webhook-id, webhook-timestamp, webhook-signature (v1,{base64hash})
|
*
|
* @see https://devdocs.helcim.com/docs/enabling-webhooks-for-transactions
|
*/
|
protected function validateWebhook(array $payload): bool
|
{
|
$headers = $payload['_headers'] ?? [];
|
|
$webhookId = $headers['webhook_id'][0] ?? $headers['webhook-id'] ?? '';
|
$webhookTimestamp = $headers['webhook_timestamp'][0] ?? $headers['webhook-timestamp'] ?? '';
|
$webhookSignature = $headers['webhook_signature'][0] ?? $headers['webhook-signature'] ?? '';
|
|
if (empty($webhookId) || empty($webhookTimestamp) || empty($webhookSignature)) {
|
$this->logError('Webhook missing required headers', [], 'warning');
|
return false;
|
}
|
|
// Verify timestamp is within 5 minutes (prevent replay attacks)
|
$now = time();
|
if (abs($now - (int)$webhookTimestamp) > 300) {
|
$this->logError('Webhook timestamp too old', [
|
'webhook_timestamp' => $webhookTimestamp,
|
'server_time' => $now,
|
], 'warning');
|
return false;
|
}
|
|
$secret = $this->getAdvancedSetting('webhook_signature_key');
|
if (empty($secret)) {
|
// If no signature key configured, allow webhook but log warning
|
$this->logDebug('No webhook signature key configured — skipping verification');
|
return true;
|
}
|
|
// Reconstruct the raw body from the payload (minus our injected _headers)
|
$body = $payload['_raw_body'] ?? json_encode(
|
array_diff_key($payload, ['_headers' => 1, '_raw_body' => 1])
|
);
|
|
$signedContent = "{$webhookId}.{$webhookTimestamp}.{$body}";
|
$secretBytes = base64_decode($secret);
|
$expectedHash = base64_encode(
|
hash_hmac('sha256', $signedContent, $secretBytes, true)
|
);
|
|
// webhook-signature may contain multiple signatures: "v1,hash1 v2,hash2"
|
$signatures = explode(' ', $webhookSignature);
|
foreach ($signatures as $sig) {
|
$parts = explode(',', $sig, 2);
|
if (count($parts) === 2 && hash_equals($expectedHash, $parts[1])) {
|
return true;
|
}
|
}
|
|
$this->logError('Webhook signature mismatch', [
|
'webhook_id' => $webhookId,
|
], 'warning');
|
|
return false;
|
}
|
|
/**
|
* Process a validated Helcim webhook event.
|
*
|
* Helcim sends minimal payloads: {"id": "12345", "type": "cardTransaction"}
|
* We fetch the full transaction details from the API.
|
*/
|
protected function processWebhook(array $payload): bool
|
{
|
$type = $payload['type'] ?? '';
|
$id = $payload['id'] ?? '';
|
|
if (empty($type) || empty($id)) {
|
$this->logError('Webhook missing type or id', $payload, 'warning');
|
return false;
|
}
|
|
return match ($type) {
|
'cardTransaction' => $this->handleTransactionWebhook($id),
|
'terminalCancel' => $this->handleTerminalCancelWebhook($payload),
|
default => $this->handleUnknownWebhook($type, $id),
|
};
|
}
|
|
/**
|
* Handle a cardTransaction webhook — fetch full transaction, update records.
|
*/
|
protected function handleTransactionWebhook(string $transactionId): bool
|
{
|
// Fetch full transaction from Helcim API
|
$transaction = $this->getRequest("card-transactions/{$transactionId}");
|
|
if (is_wp_error($transaction) || empty($transaction)) {
|
$this->logError('Failed to fetch transaction for webhook', [
|
'transaction_id' => $transactionId,
|
]);
|
return false;
|
}
|
|
$status = $transaction['status'] ?? '';
|
|
// Fire action for other parts of the system to react
|
do_action('jvb_helcim_transaction', $transaction, $status);
|
|
// If linked to an invoice, update invoice cache
|
$invoiceNumber = $transaction['invoiceNumber'] ?? '';
|
if (!empty($invoiceNumber)) {
|
$this->cache->delete("invoice_{$invoiceNumber}");
|
do_action('jvb_helcim_invoice_updated', $invoiceNumber, $transaction);
|
}
|
|
// Log for debugging
|
$this->logDebug('Transaction webhook processed', [
|
'transaction_id' => $transactionId,
|
'status' => $status,
|
'amount' => $transaction['amount'] ?? 0,
|
'type' => $transaction['type'] ?? '',
|
]);
|
|
return true;
|
}
|
|
/**
|
* Handle Smart Terminal cancel webhook
|
*/
|
protected function handleTerminalCancelWebhook(array $payload): bool
|
{
|
do_action('jvb_helcim_terminal_cancel', $payload);
|
|
$this->logDebug('Terminal cancel webhook processed', [
|
'payload' => $payload,
|
]);
|
|
return true;
|
}
|
|
/**
|
* Handle unknown webhook types (future-proofing)
|
*/
|
protected function handleUnknownWebhook(string $type, string $id): bool
|
{
|
$this->logDebug('Unknown webhook type received', [
|
'type' => $type,
|
'id' => $id,
|
]);
|
|
do_action("jvb_helcim_webhook_{$type}", $id);
|
return true;
|
}
|
|
/**
|
* Extract unique webhook ID for deduplication
|
*/
|
protected function extractWebhookId(array $payload): ?string
|
{
|
$headers = $payload['_headers'] ?? [];
|
return $headers['webhook_id'][0] ?? $headers['webhook-id'] ?? $payload['id'] ?? null;
|
}
|
|
/**
|
* Override the webhook request handler to capture raw body for signature verification
|
*/
|
public function handleWebhookRequest(\WP_REST_Request $request): \WP_REST_Response
|
{
|
$payload = $request->get_params();
|
$payload['_headers'] = $request->get_headers();
|
$payload['_raw_body'] = $request->get_body();
|
|
$success = $this->handleWebhook($payload);
|
|
return new \WP_REST_Response([
|
'success' => $success,
|
], $success ? 200 : 400);
|
}
|
/***********************************************************************
|
* POST HOOKS
|
***********************************************************************/
|
/**
|
* Sync a WordPress post to Helcim as a product.
|
* Called by IntegrationExecutor::processSyncTo()
|
*/
|
public function syncPostToService(int $postID): array|\WP_Error
|
{
|
$post = get_post($postID);
|
if (!$post) {
|
return new \WP_Error('not_found', "Post {$postID} not found");
|
}
|
|
$helcimProductId = get_post_meta($postID, BASE . '_helcim_item_id', true);
|
$productData = $this->buildProductPayload($postID);
|
|
if (is_wp_error($productData)) {
|
return $productData;
|
}
|
|
if ($helcimProductId) {
|
// Update existing
|
$response = $this->patchRequest("products/{$helcimProductId}", $productData);
|
} else {
|
// Create new
|
$response = $this->postRequest('products', $productData);
|
}
|
|
if (is_wp_error($response)) {
|
update_post_meta($postID, BASE . '_helcim_sync_status', 'error');
|
return $response;
|
}
|
|
// Store Helcim product ID
|
$newId = $response['id'] ?? $response['productId'] ?? $helcimProductId;
|
update_post_meta($postID, BASE . '_helcim_item_id', $newId);
|
update_post_meta($postID, BASE . '_helcim_sync_status', 'synced');
|
update_post_meta($postID, BASE . '_helcim_last_sync', current_time('mysql'));
|
|
return ['success' => true, 'helcim_id' => $newId];
|
}
|
|
/**
|
* Delete a product from Helcim.
|
* Called by IntegrationExecutor::processDeleteFrom()
|
*/
|
public function deleteFromService(string $externalId): array|\WP_Error
|
{
|
$response = $this->deleteRequest("products/{$externalId}");
|
|
if (is_wp_error($response)) {
|
return $response;
|
}
|
|
return ['success' => true, 'deleted' => $externalId];
|
}
|
|
/**
|
* Build Helcim product payload from a WordPress post.
|
*/
|
protected function buildProductPayload(int $postID): array|\WP_Error
|
{
|
$meta = \JVBase\meta\Meta::forPost($postID);
|
$post = get_post($postID);
|
|
$price = $meta->get('price');
|
if (empty($price) || !is_numeric($price)) {
|
return new \WP_Error('invalid_price', "Post {$postID} has no valid price");
|
}
|
|
return [
|
'name' => $post->post_title,
|
'description' => wp_strip_all_tags($post->post_content),
|
'sku' => $meta->get('sku') ?: "wp-{$postID}",
|
'price' => (float) $price,
|
'taxExempt' => (bool) $meta->get('tax_exempt'),
|
];
|
}
|
}
|
