fluentcart-developer 3.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (609) hide show
  1. package/LICENSE.md +26 -26
  2. package/README.md +59 -59
  3. package/dist/cards/fluentcart/templates-native.js +1087 -1087
  4. package/dist/cards/fluentcart/tools.js +2309 -2309
  5. package/dist/skills/fluentcart-developer/SKILL.md +108 -108
  6. package/dist/skills/fluentcart-developer/examples/README.md +30 -30
  7. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  8. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  9. package/dist/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +113 -113
  10. package/dist/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +148 -148
  11. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  12. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/README.md +22 -22
  13. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/sample-plugin-with-licensing-sdk.php +79 -79
  14. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/FluentLicensing.php +303 -303
  15. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/LicenseSettings.php +566 -566
  16. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/PluginUpdater.php +304 -304
  17. package/dist/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +61 -61
  18. package/dist/skills/fluentcart-developer/references/api/authentication.md +452 -452
  19. package/dist/skills/fluentcart-developer/references/api/coupons.md +786 -786
  20. package/dist/skills/fluentcart-developer/references/api/customers.md +889 -889
  21. package/dist/skills/fluentcart-developer/references/api/files.md +609 -609
  22. package/dist/skills/fluentcart-developer/references/api/index.md +432 -432
  23. package/dist/skills/fluentcart-developer/references/api/licensing.md +633 -633
  24. package/dist/skills/fluentcart-developer/references/api/order-bump.md +384 -384
  25. package/dist/skills/fluentcart-developer/references/api/orders.md +814 -814
  26. package/dist/skills/fluentcart-developer/references/api/products.md +866 -866
  27. package/dist/skills/fluentcart-developer/references/api/roles-permissions.md +536 -536
  28. package/dist/skills/fluentcart-developer/references/api/subscriptions.md +827 -827
  29. package/dist/skills/fluentcart-developer/references/database/index.md +44 -44
  30. package/dist/skills/fluentcart-developer/references/database/models/activity.md +178 -178
  31. package/dist/skills/fluentcart-developer/references/database/models/applied-coupon.md +291 -291
  32. package/dist/skills/fluentcart-developer/references/database/models/attribute-group.md +239 -239
  33. package/dist/skills/fluentcart-developer/references/database/models/attribute-relation.md +181 -181
  34. package/dist/skills/fluentcart-developer/references/database/models/attribute-term.md +219 -219
  35. package/dist/skills/fluentcart-developer/references/database/models/cart.md +645 -645
  36. package/dist/skills/fluentcart-developer/references/database/models/coupon.md +427 -427
  37. package/dist/skills/fluentcart-developer/references/database/models/customer-addresses.md +348 -348
  38. package/dist/skills/fluentcart-developer/references/database/models/customer-meta.md +156 -156
  39. package/dist/skills/fluentcart-developer/references/database/models/customer.md +584 -584
  40. package/dist/skills/fluentcart-developer/references/database/models/dynamic-model.md +163 -163
  41. package/dist/skills/fluentcart-developer/references/database/models/label-relationship.md +155 -155
  42. package/dist/skills/fluentcart-developer/references/database/models/label.md +153 -153
  43. package/dist/skills/fluentcart-developer/references/database/models/license-activation.md +182 -182
  44. package/dist/skills/fluentcart-developer/references/database/models/license-meta.md +163 -163
  45. package/dist/skills/fluentcart-developer/references/database/models/license-site.md +208 -208
  46. package/dist/skills/fluentcart-developer/references/database/models/license.md +640 -640
  47. package/dist/skills/fluentcart-developer/references/database/models/meta.md +233 -233
  48. package/dist/skills/fluentcart-developer/references/database/models/order-address.md +391 -391
  49. package/dist/skills/fluentcart-developer/references/database/models/order-download-permission.md +144 -144
  50. package/dist/skills/fluentcart-developer/references/database/models/order-item.md +383 -383
  51. package/dist/skills/fluentcart-developer/references/database/models/order-meta.md +303 -303
  52. package/dist/skills/fluentcart-developer/references/database/models/order-operation.md +158 -158
  53. package/dist/skills/fluentcart-developer/references/database/models/order-promotion-stat.md +175 -175
  54. package/dist/skills/fluentcart-developer/references/database/models/order-promotion.md +250 -250
  55. package/dist/skills/fluentcart-developer/references/database/models/order-tax-rate.md +172 -172
  56. package/dist/skills/fluentcart-developer/references/database/models/order-transaction.md +440 -440
  57. package/dist/skills/fluentcart-developer/references/database/models/order.md +727 -727
  58. package/dist/skills/fluentcart-developer/references/database/models/product-detail.md +397 -397
  59. package/dist/skills/fluentcart-developer/references/database/models/product-download.md +258 -258
  60. package/dist/skills/fluentcart-developer/references/database/models/product-meta.md +153 -153
  61. package/dist/skills/fluentcart-developer/references/database/models/product-variation.md +556 -556
  62. package/dist/skills/fluentcart-developer/references/database/models/product.md +580 -580
  63. package/dist/skills/fluentcart-developer/references/database/models/relationships.md +427 -427
  64. package/dist/skills/fluentcart-developer/references/database/models/scheduled-action.md +175 -175
  65. package/dist/skills/fluentcart-developer/references/database/models/shipping-class.md +148 -148
  66. package/dist/skills/fluentcart-developer/references/database/models/shipping-method.md +280 -280
  67. package/dist/skills/fluentcart-developer/references/database/models/shipping-zone.md +205 -205
  68. package/dist/skills/fluentcart-developer/references/database/models/subscription-meta.md +173 -173
  69. package/dist/skills/fluentcart-developer/references/database/models/subscription.md +528 -528
  70. package/dist/skills/fluentcart-developer/references/database/models/tax-class.md +195 -195
  71. package/dist/skills/fluentcart-developer/references/database/models/tax-rate.md +225 -225
  72. package/dist/skills/fluentcart-developer/references/database/models/user-meta.md +166 -166
  73. package/dist/skills/fluentcart-developer/references/database/models/user.md +220 -220
  74. package/dist/skills/fluentcart-developer/references/database/models.md +404 -404
  75. package/dist/skills/fluentcart-developer/references/database/query-builder.md +860 -860
  76. package/dist/skills/fluentcart-developer/references/database/readme.md +276 -276
  77. package/dist/skills/fluentcart-developer/references/database/schema.md +1002 -1002
  78. package/dist/skills/fluentcart-developer/references/engineering/adding-custom-pages-to-the-customer-dashboard.md +395 -395
  79. package/dist/skills/fluentcart-developer/references/engineering/index.md +4 -4
  80. package/dist/skills/fluentcart-developer/references/engineering.md +4 -4
  81. package/dist/skills/fluentcart-developer/references/getting-started.md +249 -249
  82. package/dist/skills/fluentcart-developer/references/guides/frontend.md +519 -519
  83. package/dist/skills/fluentcart-developer/references/guides/index.md +107 -107
  84. package/dist/skills/fluentcart-developer/references/guides/integrations.md +600 -600
  85. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/index.md +237 -237
  86. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/labels-and-tracking.md +481 -481
  87. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/live-rates.md +269 -269
  88. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/reference.md +223 -223
  89. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/settings.md +370 -370
  90. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier.md +237 -237
  91. package/dist/skills/fluentcart-developer/references/guides/subscriptions.md +217 -217
  92. package/dist/skills/fluentcart-developer/references/hooks/actions/admin-and-templates.md +1079 -1079
  93. package/dist/skills/fluentcart-developer/references/hooks/actions/cart-and-checkout.md +1795 -1795
  94. package/dist/skills/fluentcart-developer/references/hooks/actions/customers-and-users.md +327 -327
  95. package/dist/skills/fluentcart-developer/references/hooks/actions/licenses.md +829 -829
  96. package/dist/skills/fluentcart-developer/references/hooks/actions/modules.md +81 -81
  97. package/dist/skills/fluentcart-developer/references/hooks/actions/orders.md +757 -757
  98. package/dist/skills/fluentcart-developer/references/hooks/actions/payments-and-integrations.md +1163 -1163
  99. package/dist/skills/fluentcart-developer/references/hooks/actions/pro-modules.md +219 -219
  100. package/dist/skills/fluentcart-developer/references/hooks/actions/products-and-coupons.md +1019 -1019
  101. package/dist/skills/fluentcart-developer/references/hooks/actions/subscriptions.md +1290 -1290
  102. package/dist/skills/fluentcart-developer/references/hooks/actions.md +16 -16
  103. package/dist/skills/fluentcart-developer/references/hooks/deprecated.md +60 -60
  104. package/dist/skills/fluentcart-developer/references/hooks/filters/cart-and-checkout.md +2032 -2032
  105. package/dist/skills/fluentcart-developer/references/hooks/filters/customers-and-subscriptions.md +1746 -1746
  106. package/dist/skills/fluentcart-developer/references/hooks/filters/integrations-and-advanced.md +2439 -2439
  107. package/dist/skills/fluentcart-developer/references/hooks/filters/modules.md +464 -464
  108. package/dist/skills/fluentcart-developer/references/hooks/filters/orders-and-payments.md +2658 -2658
  109. package/dist/skills/fluentcart-developer/references/hooks/filters/pro-modules.md +502 -502
  110. package/dist/skills/fluentcart-developer/references/hooks/filters/products-and-pricing.md +1785 -1785
  111. package/dist/skills/fluentcart-developer/references/hooks/filters/settings-and-configuration.md +2966 -2966
  112. package/dist/skills/fluentcart-developer/references/hooks/filters.md +14 -14
  113. package/dist/skills/fluentcart-developer/references/hooks/index.md +35 -35
  114. package/dist/skills/fluentcart-developer/references/index.md +625 -625
  115. package/dist/skills/fluentcart-developer/references/modules/fee-system.md +427 -427
  116. package/dist/skills/fluentcart-developer/references/modules/ghost-product-selling.md +440 -440
  117. package/dist/skills/fluentcart-developer/references/modules/index.md +484 -484
  118. package/dist/skills/fluentcart-developer/references/modules/licensing.md +342 -342
  119. package/dist/skills/fluentcart-developer/references/modules/order-bump.md +433 -433
  120. package/dist/skills/fluentcart-developer/references/modules/payment-methods.md +129 -129
  121. package/dist/skills/fluentcart-developer/references/modules/refunds.md +170 -170
  122. package/dist/skills/fluentcart-developer/references/modules/shipping.md +846 -846
  123. package/dist/skills/fluentcart-developer/references/modules/storage.md +986 -986
  124. package/dist/skills/fluentcart-developer/references/modules/subscription-vendor-ids.md +186 -186
  125. package/dist/skills/fluentcart-developer/references/modules/subscriptions.md +678 -678
  126. package/dist/skills/fluentcart-developer/references/payment-methods-integration/index.md +164 -164
  127. package/dist/skills/fluentcart-developer/references/payment-methods-integration/paddle-example.md +1648 -1648
  128. package/dist/skills/fluentcart-developer/references/payment-methods-integration/payment/setting/fields.md +353 -353
  129. package/dist/skills/fluentcart-developer/references/payment-methods-integration/quick-implementation.md +1079 -1079
  130. package/dist/skills/fluentcart-developer/references/payment-methods-integration.md +164 -164
  131. package/dist/skills/fluentcart-developer/references/restapi/checkout.md +573 -573
  132. package/dist/skills/fluentcart-developer/references/restapi/coupons.md +958 -958
  133. package/dist/skills/fluentcart-developer/references/restapi/customer-profile.md +1423 -1423
  134. package/dist/skills/fluentcart-developer/references/restapi/customers.md +1103 -1103
  135. package/dist/skills/fluentcart-developer/references/restapi/dashboard.md +1083 -1083
  136. package/dist/skills/fluentcart-developer/references/restapi/data-export.md +132 -132
  137. package/dist/skills/fluentcart-developer/references/restapi/email-notifications.md +846 -846
  138. package/dist/skills/fluentcart-developer/references/restapi/files.md +313 -313
  139. package/dist/skills/fluentcart-developer/references/restapi/index.md +127 -127
  140. package/dist/skills/fluentcart-developer/references/restapi/integrations.md +1000 -1000
  141. package/dist/skills/fluentcart-developer/references/restapi/inventory.md +192 -192
  142. package/dist/skills/fluentcart-developer/references/restapi/labels-and-attributes.md +797 -797
  143. package/dist/skills/fluentcart-developer/references/restapi/licensing.md +1733 -1733
  144. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-available-shipping-methods.md +30 -30
  145. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-checkout-summary.md +28 -28
  146. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-country-info.md +29 -29
  147. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-order-info.md +28 -28
  148. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-shipping-methods-list-view.md +30 -30
  149. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/login.md +66 -66
  150. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/place-order.md +179 -179
  151. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/apply-coupon.md +83 -83
  152. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/cancel-coupon.md +87 -87
  153. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/check-product-eligibility.md +59 -59
  154. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/create-coupon.md +230 -230
  155. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/delete-coupon.md +29 -29
  156. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/get-coupon-settings.md +20 -20
  157. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/get-coupon.md +27 -27
  158. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/list-coupon-codes.md +20 -20
  159. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/list-coupons.md +37 -37
  160. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/re-apply-coupons.md +75 -75
  161. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/store-coupon-settings.md +40 -40
  162. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/update-coupon.md +133 -133
  163. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/create-address-checkout.md +138 -138
  164. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/create-profile-address.md +119 -119
  165. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/dashboard-overview.md +22 -22
  166. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/delete-profile-address.md +46 -46
  167. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-order-details.md +30 -30
  168. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-portal-sections.md +29 -29
  169. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-profile-details.md +22 -22
  170. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-transaction-billing-address.md +30 -30
  171. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-upgrade-paths.md +31 -31
  172. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/list-downloads.md +29 -29
  173. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/list-orders.md +28 -28
  174. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/make-profile-address-primary.md +55 -55
  175. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/pause-subscription.md +29 -29
  176. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/resume-subscription.md +29 -29
  177. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/save-transaction-billing-address.md +92 -92
  178. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/select-address-for-checkout.md +32 -32
  179. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/update-profile-address.md +115 -115
  180. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/update-profile-details.md +69 -69
  181. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/attach-user.md +50 -50
  182. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/bulk-actions.md +65 -65
  183. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/create-address.md +135 -135
  184. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/create-customer.md +108 -108
  185. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/delete-address.md +62 -62
  186. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/detach-user.md +28 -28
  187. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/find-customer-order.md +27 -27
  188. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-attachable-users.md +20 -20
  189. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-addresses.md +28 -28
  190. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-orders.md +37 -37
  191. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-stats.md +27 -27
  192. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer.md +32 -32
  193. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/list-customers.md +37 -37
  194. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/recalculate-ltv.md +28 -28
  195. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/set-primary-address.md +72 -72
  196. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-additional-info.md +55 -55
  197. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-address.md +144 -144
  198. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-customer.md +123 -123
  199. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/attach-note-to-order.md +49 -49
  200. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/create-all-pages.md +21 -21
  201. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/create-single-page.md +55 -55
  202. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/delete-activity.md +28 -28
  203. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-country-info.md +29 -29
  204. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-dashboard-stats.md +22 -22
  205. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-filter-options.md +31 -31
  206. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-onboarding-data.md +20 -20
  207. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-onboarding-settings.md +20 -20
  208. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-print-templates.md +20 -20
  209. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-search-options.md +27 -27
  210. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-widgets.md +28 -28
  211. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/initialize-app.md +20 -20
  212. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-activities.md +33 -33
  213. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-attachments.md +21 -21
  214. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-countries.md +20 -20
  215. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/mark-activity-read.md +53 -53
  216. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/run-data-backfills.md +21 -21
  217. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-onboarding-settings.md +54 -54
  218. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-onboarding-tax-settings.md +73 -73
  219. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-print-templates.md +64 -64
  220. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/upload-attachment.md +42 -42
  221. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-customers-batch.md +129 -129
  222. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-licenses-batch.md +133 -133
  223. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-orders-batch.md +129 -129
  224. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-subscriptions-batch.md +129 -129
  225. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-customers-export-schema.md +21 -21
  226. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-licenses-export-schema.md +26 -26
  227. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-orders-export-schema.md +21 -21
  228. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-subscriptions-export-schema.md +21 -21
  229. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/enable-notification.md +57 -57
  230. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-digest-settings.md +22 -22
  231. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-notification.md +30 -30
  232. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-reminders.md +22 -22
  233. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-settings.md +22 -22
  234. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-shortcodes.md +22 -22
  235. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/list-notifications.md +20 -20
  236. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/preview-default-template.md +66 -66
  237. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/preview-notification.md +50 -50
  238. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-digest-settings.md +101 -101
  239. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-reminders.md +162 -162
  240. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-settings.md +99 -99
  241. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/send-digest-test.md +47 -47
  242. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/send-manual-reminder.md +51 -51
  243. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/update-notification.md +93 -93
  244. package/dist/skills/fluentcart-developer/references/restapi/operations/files/delete-file.md +31 -31
  245. package/dist/skills/fluentcart-developer/references/restapi/operations/files/get-bucket-list.md +28 -28
  246. package/dist/skills/fluentcart-developer/references/restapi/operations/files/list-files.md +30 -30
  247. package/dist/skills/fluentcart-developer/references/restapi/operations/files/upload-editor-file.md +32 -32
  248. package/dist/skills/fluentcart-developer/references/restapi/operations/files/upload-file.md +34 -34
  249. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/chained-data-request.md +46 -46
  250. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/change-feed-status.md +51 -51
  251. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/delete-feed.md +27 -27
  252. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-dynamic-options.md +29 -29
  253. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-feed-lists.md +27 -27
  254. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-feed-settings.md +27 -27
  255. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-global-feeds.md +20 -20
  256. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-global-settings.md +26 -26
  257. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/install-addon-plugin.md +49 -49
  258. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/list-addons.md +20 -20
  259. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/save-feed-settings.md +52 -52
  260. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/set-global-settings.md +50 -50
  261. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/bulk-update-stock.md +94 -94
  262. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/export-inventory.md +81 -81
  263. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/get-adjustment-history.md +26 -26
  264. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/get-inventory-stats.md +21 -21
  265. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/list-inventory.md +33 -33
  266. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/update-stock.md +75 -75
  267. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-attribute-group.md +31 -31
  268. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-label.md +31 -31
  269. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-terms.md +90 -90
  270. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/delete-attribute-group.md +28 -28
  271. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/delete-attribute-term.md +29 -29
  272. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/get-attribute-group.md +28 -28
  273. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/get-attribute-library.md +20 -20
  274. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-attribute-groups.md +32 -32
  275. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-attribute-terms.md +33 -33
  276. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-labels.md +20 -20
  277. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/reorder-groups.md +51 -51
  278. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/reorder-terms.md +56 -56
  279. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-attribute-group.md +37 -37
  280. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-attribute-term.md +39 -39
  281. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-label-selections.md +32 -32
  282. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/activate-plugin-license.md +41 -41
  283. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/activate-site-admin.md +60 -60
  284. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-plugin-license.md +18 -18
  285. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-site-admin.md +67 -67
  286. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-site-customer.md +47 -47
  287. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/delete-license.md +24 -24
  288. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/extend-license-validity.md +47 -47
  289. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-customer-license-details.md +25 -25
  290. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-customer-licenses-admin.md +26 -26
  291. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-activations.md +25 -25
  292. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-details.md +25 -25
  293. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-site.md +30 -30
  294. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-plugin-license-status.md +18 -18
  295. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-product-license-settings.md +24 -24
  296. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-customer-licenses.md +25 -25
  297. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-license-sites.md +33 -33
  298. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-licenses.md +38 -38
  299. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-activate-license.md +54 -54
  300. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-check-license.md +26 -26
  301. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-deactivate-license.md +46 -46
  302. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-download-license-package.md +23 -23
  303. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-get-license-version.md +26 -26
  304. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/regenerate-license-key.md +24 -24
  305. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/save-product-license-settings.md +193 -193
  306. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/update-license-activation-limit.md +53 -53
  307. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/update-license-status.md +52 -52
  308. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/create-order-bump.md +47 -47
  309. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/delete-order-bump.md +25 -25
  310. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/get-order-bump.md +25 -25
  311. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/list-order-bumps.md +29 -29
  312. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/update-order-bump.md +141 -141
  313. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/accept-dispute.md +47 -47
  314. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/bulk-actions.md +72 -72
  315. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/calculate-shipping.md +67 -67
  316. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/calculate-tax.md +98 -98
  317. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/change-customer.md +50 -50
  318. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/charge-now.md +29 -29
  319. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-and-change-customer.md +92 -92
  320. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-custom-order-item.md +68 -68
  321. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-order.md +351 -351
  322. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-renewal-now.md +29 -29
  323. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/delete-order.md +28 -28
  324. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/generate-missing-licenses.md +29 -29
  325. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-order-transactions.md +27 -27
  326. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-order.md +27 -27
  327. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-renewal.md +28 -28
  328. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-shipping-methods.md +28 -28
  329. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-single-transaction.md +28 -28
  330. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-order-currencies.md +22 -22
  331. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-orders.md +42 -42
  332. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-renewals.md +28 -28
  333. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/mark-as-paid.md +61 -61
  334. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/price-order.md +135 -135
  335. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/refund-order.md +72 -72
  336. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/resend-renewal-invoice.md +29 -29
  337. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/skip-renewal.md +48 -48
  338. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/sync-order-statuses.md +28 -28
  339. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/sync-pending-transaction.md +29 -29
  340. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order-address-id.md +60 -60
  341. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order-address.md +98 -98
  342. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order.md +172 -172
  343. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-statuses.md +77 -77
  344. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-subscription-details.md +84 -84
  345. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-transaction-status.md +51 -51
  346. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/void-renewal.md +30 -30
  347. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/create-pdf-template.md +42 -42
  348. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/delete-pdf-template.md +26 -26
  349. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/download-pdf-preview.md +44 -44
  350. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-factory-default-templates.md +19 -19
  351. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-pdf-status.md +21 -21
  352. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-pdf-template.md +26 -26
  353. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-saved-templates.md +21 -21
  354. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-seller-details.md +19 -19
  355. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/list-pdf-templates.md +19 -19
  356. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/save-pdf-template.md +53 -53
  357. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/save-seller-details.md +97 -97
  358. package/dist/skills/fluentcart-developer/references/restapi/operations/products/add-product-terms.md +64 -64
  359. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-edit-fetch.md +30 -30
  360. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-insert-products.md +62 -62
  361. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-update-products.md +59 -59
  362. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-update-variants.md +83 -83
  363. package/dist/skills/fluentcart-developer/references/restapi/operations/products/change-integration-status.md +64 -64
  364. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-dummy-products.md +45 -45
  365. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-product.md +81 -81
  366. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-variation.md +181 -181
  367. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-downloadable-file.md +27 -27
  368. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-product-integration.md +30 -30
  369. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-product.md +27 -27
  370. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-taxonomy-term.md +55 -55
  371. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-upgrade-path.md +27 -27
  372. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-variation.md +27 -27
  373. package/dist/skills/fluentcart-developer/references/restapi/operations/products/do-bulk-action.md +56 -56
  374. package/dist/skills/fluentcart-developer/references/restapi/operations/products/duplicate-product.md +56 -56
  375. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-products-by-ids.md +26 -26
  376. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-taxonomy-terms.md +20 -20
  377. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-terms-by-parent.md +60 -60
  378. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-variations-by-ids.md +26 -26
  379. package/dist/skills/fluentcart-developer/references/restapi/operations/products/find-subscription-variants.md +26 -26
  380. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-bundle-info.md +27 -27
  381. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-downloadable-url.md +27 -27
  382. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-max-excerpt-word-count.md +20 -20
  383. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-pricing-widgets.md +27 -27
  384. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-integration-feeds.md +29 -29
  385. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-integration-settings.md +31 -31
  386. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-pricing.md +28 -28
  387. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product.md +28 -28
  388. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-related-products.md +31 -31
  389. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-upgrade-settings.md +27 -27
  390. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-variation-upgrade-paths.md +28 -28
  391. package/dist/skills/fluentcart-developer/references/restapi/operations/products/group-bulk-update-variants.md +103 -103
  392. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-all-variants.md +26 -26
  393. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-product-variations.md +26 -26
  394. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-products.md +34 -34
  395. package/dist/skills/fluentcart-developer/references/restapi/operations/products/remove-shipping-class.md +27 -27
  396. package/dist/skills/fluentcart-developer/references/restapi/operations/products/remove-tax-class.md +27 -27
  397. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-bundle-info.md +56 -56
  398. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-product-integration.md +62 -62
  399. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-upgrade-path.md +78 -78
  400. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-product-variant-options.md +29 -29
  401. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-products-by-name.md +28 -28
  402. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-variants-by-name.md +28 -28
  403. package/dist/skills/fluentcart-developer/references/restapi/operations/products/set-variation-media.md +74 -74
  404. package/dist/skills/fluentcart-developer/references/restapi/operations/products/suggest-sku.md +28 -28
  405. package/dist/skills/fluentcart-developer/references/restapi/operations/products/sync-downloadable-files.md +134 -134
  406. package/dist/skills/fluentcart-developer/references/restapi/operations/products/sync-taxonomy-terms.md +61 -61
  407. package/dist/skills/fluentcart-developer/references/restapi/operations/products/toggle-product-tax-exemption.md +56 -56
  408. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-downloadable-file.md +98 -98
  409. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-inventory.md +56 -56
  410. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-long-desc-editor-mode.md +49 -49
  411. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-manage-stock.md +53 -53
  412. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-product-detail.md +58 -58
  413. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-product-pricing.md +225 -225
  414. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-shipping-class.md +49 -49
  415. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-tax-class.md +49 -49
  416. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-upgrade-path.md +78 -78
  417. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variant-option.md +79 -79
  418. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variant-tax-exemption.md +56 -56
  419. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variation-pricing-table.md +49 -49
  420. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variation.md +105 -105
  421. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/get-product-views.md +34 -34
  422. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/list-products.md +42 -42
  423. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/search-products.md +30 -30
  424. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/channel-rules.md +24 -24
  425. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/country-heat-map.md +22 -22
  426. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/coupon-overview.md +37 -37
  427. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/coupons.md +36 -36
  428. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-insights.md +31 -31
  429. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-overview.md +36 -36
  430. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-repeat.md +35 -35
  431. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-segment-customers.md +36 -36
  432. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-segments.md +30 -30
  433. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-value.md +34 -34
  434. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/dashboard-stats.md +30 -30
  435. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/failed-orders.md +34 -34
  436. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-new-vs-returning-customer.md +34 -34
  437. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-report-by-day-and-hour.md +34 -34
  438. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-report-meta.md +29 -29
  439. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-top-sold-products.md +34 -34
  440. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/future-renewals.md +31 -31
  441. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/generate-retention-snapshots.md +24 -24
  442. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-overview.md +30 -30
  443. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-recent-activities.md +26 -26
  444. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-recent-orders.md +20 -20
  445. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-revenue.md +37 -37
  446. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments-at-risk.md +35 -35
  447. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments-variations.md +33 -33
  448. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments.md +33 -33
  449. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/item-count-distribution.md +34 -34
  450. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-chart.md +30 -30
  451. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-pie-chart.md +22 -22
  452. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-summary.md +22 -22
  453. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/locations.md +43 -43
  454. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-chart.md +37 -37
  455. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-completion-time.md +34 -34
  456. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-mix.md +34 -34
  457. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-value-distribution.md +34 -34
  458. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods-disputes.md +38 -38
  459. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods-methods.md +36 -36
  460. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods.md +37 -37
  461. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-comparison-launch.md +33 -33
  462. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-comparison.md +40 -40
  463. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-detail.md +37 -37
  464. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-sales.md +37 -37
  465. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/refunds-overview.md +37 -37
  466. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/retention-snapshots-step.md +45 -45
  467. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/sales-growth-chart.md +35 -35
  468. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/save-channel-rules.md +73 -73
  469. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/source-channels.md +37 -37
  470. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/sources.md +49 -49
  471. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-cohorts.md +33 -33
  472. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-health.md +30 -30
  473. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-rebuys.md +37 -37
  474. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-retention.md +34 -34
  475. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-variations.md +22 -22
  476. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscriptions-overview.md +37 -37
  477. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/weeks-between-refund.md +34 -34
  478. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/assign-role.md +48 -48
  479. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/delete-role-assignment.md +47 -47
  480. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/get-role.md +25 -25
  481. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/list-managers.md +18 -18
  482. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/list-roles.md +18 -18
  483. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/search-users.md +25 -25
  484. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/update-role.md +43 -43
  485. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/create-saved-view.md +106 -106
  486. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/delete-saved-view.md +26 -26
  487. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/list-saved-views.md +25 -25
  488. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/update-saved-view.md +83 -83
  489. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/activate-payment-addon.md +44 -44
  490. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/activate-plugin-addon.md +44 -44
  491. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/change-storage-driver-status.md +56 -56
  492. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/check-paypal-webhook.md +26 -26
  493. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/create-storage-bucket.md +63 -63
  494. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/disconnect-payment-method.md +55 -55
  495. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/exchange-paypal-seller-auth-token.md +62 -62
  496. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-active-storage-drivers.md +20 -20
  497. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-checkout-fields.md +22 -22
  498. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-email-shortcodes.md +20 -20
  499. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-mcp-config-snippets.md +26 -26
  500. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-mcp-status.md +20 -20
  501. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-module-settings.md +20 -20
  502. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-payment-method-connection-info.md +26 -26
  503. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-payment-method-settings.md +26 -26
  504. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-permissions.md +22 -22
  505. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-plugin-addons.md +20 -20
  506. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-storage-driver-settings.md +27 -27
  507. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-store-settings.md +26 -26
  508. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-mcp-adapter.md +21 -21
  509. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-payment-addon.md +60 -60
  510. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-plugin-addon.md +64 -64
  511. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-all-payment-methods.md +20 -20
  512. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-all-storage-drivers.md +20 -20
  513. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-storage-buckets.md +67 -67
  514. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/reorder-payment-methods.md +55 -55
  515. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/reset-storage-driver-settings.md +45 -45
  516. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-checkout-fields.md +133 -133
  517. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-confirmation-settings.md +68 -68
  518. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-module-settings.md +68 -68
  519. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-payment-method-design.md +67 -67
  520. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-payment-method-settings.md +58 -58
  521. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-permissions.md +68 -68
  522. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-storage-driver-settings.md +62 -62
  523. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-store-settings.md +239 -239
  524. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/setup-paypal-webhook.md +48 -48
  525. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/toggle-mcp.md +40 -40
  526. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/verify-storage-driver-connection.md +62 -62
  527. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/verify-turnstile-keys.md +55 -55
  528. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-class.md +73 -73
  529. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-method.md +110 -110
  530. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-zone.md +56 -56
  531. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-class.md +29 -29
  532. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-method.md +29 -29
  533. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-zone.md +29 -29
  534. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-class-profile.md +30 -30
  535. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-class.md +29 -29
  536. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-packages.md +22 -22
  537. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-zone.md +27 -27
  538. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-zone-countries.md +22 -22
  539. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-zone-states.md +28 -28
  540. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/list-shipping-classes.md +31 -31
  541. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/list-shipping-zones.md +31 -31
  542. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/save-shipping-packages.md +112 -112
  543. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-class.md +79 -79
  544. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-method.md +113 -113
  545. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-zone.md +62 -62
  546. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-zone-order.md +52 -52
  547. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/cancel-auto-renew.md +30 -30
  548. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/cancel-subscription.md +52 -52
  549. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/confirm-subscription-switch.md +70 -70
  550. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/fetch-subscription-remote.md +28 -28
  551. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/generate-early-payment-link.md +29 -29
  552. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-customer-subscription.md +27 -27
  553. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-or-create-plan.md +69 -69
  554. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-setup-intent-attempts.md +30 -30
  555. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-subscription.md +28 -28
  556. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/initiate-early-payment.md +31 -31
  557. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/list-customer-subscriptions.md +27 -27
  558. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/list-subscriptions.md +39 -39
  559. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/pause-subscription.md +28 -28
  560. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/reactivate-subscription.md +28 -28
  561. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/resume-subscription.md +28 -28
  562. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/switch-payment-method.md +70 -70
  563. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/update-payment-method.md +69 -69
  564. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/update-vendor-ids.md +56 -56
  565. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/verify-vendor-ids.md +56 -56
  566. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/create-tax-class.md +51 -51
  567. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/create-tax-rate.md +117 -117
  568. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-product-override.md +27 -27
  569. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-shipping-tax-override.md +27 -27
  570. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-tax-class.md +28 -28
  571. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-tax-rate.md +27 -27
  572. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-country-tax-id.md +27 -27
  573. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-country-tax-rates.md +28 -28
  574. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-eu-vat-product-overrides.md +20 -20
  575. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-oss-country-rates.md +20 -20
  576. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-preconfigured-tax-rates.md +20 -20
  577. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-product-overrides.md +27 -27
  578. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-tax-settings.md +20 -20
  579. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-all-tax-rates.md +20 -20
  580. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-tax-classes.md +20 -20
  581. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-tax-records.md +37 -37
  582. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/mark-taxes-as-filed.md +58 -58
  583. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/reset-eu-vat-rates.md +21 -21
  584. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-configured-countries.md +57 -57
  585. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-country-tax-id.md +50 -50
  586. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-eu-vat-cross-border-settings.md +127 -127
  587. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-oss-country-rates.md +100 -100
  588. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-product-override.md +110 -110
  589. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-shipping-tax-override.md +52 -52
  590. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-tax-settings.md +166 -166
  591. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/update-country-status.md +54 -54
  592. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/update-tax-rate.md +116 -116
  593. package/dist/skills/fluentcart-developer/references/restapi/order-bumps.md +433 -433
  594. package/dist/skills/fluentcart-developer/references/restapi/orders.md +1212 -1212
  595. package/dist/skills/fluentcart-developer/references/restapi/pdf-templates.md +212 -212
  596. package/dist/skills/fluentcart-developer/references/restapi/products.md +2485 -2485
  597. package/dist/skills/fluentcart-developer/references/restapi/public-shop.md +191 -191
  598. package/dist/skills/fluentcart-developer/references/restapi/reports.md +3773 -3773
  599. package/dist/skills/fluentcart-developer/references/restapi/roles.md +403 -403
  600. package/dist/skills/fluentcart-developer/references/restapi/saved-views.md +136 -136
  601. package/dist/skills/fluentcart-developer/references/restapi/settings.md +1423 -1423
  602. package/dist/skills/fluentcart-developer/references/restapi/shipping.md +905 -905
  603. package/dist/skills/fluentcart-developer/references/restapi/subscriptions.md +1169 -1169
  604. package/dist/skills/fluentcart-developer/references/restapi/tax.md +1551 -1551
  605. package/dist/skills/fluentcart-developer/references/restapi.md +127 -127
  606. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  607. package/dist/version.d.ts +1 -1
  608. package/dist/version.js +1 -1
  609. package/package.json +66 -65
@@ -1,1648 +1,1648 @@
1
- # Paddle Gateway Case Study
2
-
3
- Learn from a real-world implementation by examining how the Paddle payment gateway was integrated into FluentCart Pro. This case study provides practical insights and patterns you can apply to your own gateway development.
4
-
5
- ## Overview
6
-
7
- The Paddle Gateway demonstrates a **complete production-ready implementation** featuring:
8
-
9
- - **One-time payments** with full transaction lifecycle
10
- - **Subscription payments** with recurring billing management
11
- - **Comprehensive webhook/IPN handling** for real-time updates
12
- - **Custom checkout experience** with UI customization
13
- - **Multi-environment support** (test/live modes)
14
- - **Advanced settings management** with dynamic configuration
15
- - **Frontend integration** with JavaScript SDK
16
- - **Error handling and logging** for production reliability
17
- - **Security best practices** with signature verification
18
-
19
- This case study shows how to implement **all major payment gateway features** that third-party developers typically need.
20
-
21
- ## Architecture Analysis
22
-
23
- ### File Structure
24
-
25
- ```
26
- fluent-cart-pro/app/Modules/PaymentMethods/PaddleGateway/
27
- ├── Paddle.php # Main gateway class
28
- ├── PaddleSettings.php # Settings management
29
- ├── PaddleSubscriptions.php # Subscription handling
30
- ├── PaddleHelper.php # Utility functions
31
- ├── Processor.php # Payment processing
32
- ├── Confirmations.php # Payment confirmations
33
- ├── Price.php # Price management
34
- ├── Product.php # Product handling
35
- ├── SubscriptionsManager.php # Subscription lifecycle
36
- ├── API/
37
- │ └── API.php # API communication
38
- └── Webhook/
39
- └── IPN.php # Web hook processing
40
- ```
41
-
42
- ## Main Gateway Implementation
43
-
44
- ### Core Gateway Class
45
-
46
- ```
47
- class Paddle extends AbstractPaymentGateway
48
- {
49
- private $methodSlug = 'paddle';
50
-
51
- public array $supportedFeatures = [
52
- 'payment',
53
- 'refund',
54
- 'webhook',
55
- 'subscriptions',
56
- 'custom_payment'
57
- ];
58
-
59
- public function __construct()
60
- {
61
- parent::__construct(
62
- new PaddleSettings(),
63
- new PaddleSubscriptions()
64
- );
65
-
66
- // Register custom checkout filter
67
- add_filter('fluent_cart/payment_methods_with_custom_checkout_buttons', function ($methods) {
68
- $methods[] = 'paddle';
69
- return $methods;
70
- });
71
- }
72
- }
73
- ```
74
-
75
- **Key Insights:**
76
-
77
- - Uses composition pattern with separate settings and subscription classes
78
- - Declares all supported features upfront
79
- - Registers custom checkout behavior during construction
80
-
81
- ### Gateway Metadata
82
-
83
- ```
84
- public function meta(): array
85
- {
86
- return [
87
- 'title' => __('Paddle', 'fluent-cart-pro'),
88
- 'route' => 'paddle',
89
- 'slug' => 'paddle',
90
- 'description' => __('Pay securely with Paddle - Complete payment solution', 'fluent-cart-pro'),
91
- 'logo' => Vite::getAssetUrl("images/payment-methods/paddle-logo.svg"),
92
- 'icon' => Vite::getAssetUrl("images/payment-methods/paddle-logo.svg"),
93
- 'brand_color' => '#7c3aed',
94
- 'status' => $this->settings->get('is_active') === 'yes',
95
- 'upcoming' => false,
96
- 'supported_features' => $this->supportedFeatures,
97
- 'tag' => 'beta'
98
- ];
99
- }
100
- ```
101
-
102
- **Key Insights:**
103
-
104
- - Uses asset management system (Vite) for icons and logos
105
- - Includes visual branding with brand colors
106
- - Shows development status with tags
107
- - Status reflects actual settings configuration
108
-
109
- ## Settings Architecture
110
-
111
- ### Hierarchical Settings Structure
112
-
113
- ```
114
- class PaddleSettings extends BaseGatewaySettings
115
- {
116
- public $methodHandler = 'fluent_cart_payment_settings_paddle';
117
-
118
- public static function getDefaults()
119
- {
120
- return [
121
- 'is_active' => 'no',
122
- 'provider' => 'api_keys',
123
- 'live_api_key' => '',
124
- 'live_client_token' => '',
125
- 'live_webhook_secret' => '',
126
- 'test_api_key' => '',
127
- 'test_client_token' => '',
128
- 'test_webhook_secret' => '',
129
- 'payment_mode' => 'test',
130
- 'tax_mode' => 'internal',
131
- // UI customization options
132
- 'paddle_checkout_theme' => 'light',
133
- 'paddle_checkout_button_text' => 'Pay with Paddle',
134
- 'paddle_checkout_button_color' => '',
135
- // ... more settings
136
- ];
137
- }
138
- }
139
- ```
140
-
141
- **Key Insights:**
142
-
143
- - Separates live and test credentials
144
- - Includes UI customization options
145
- - Uses descriptive setting keys
146
- - Provides sensible defaults
147
-
148
- ### Environment-Aware API Keys
149
-
150
- ```
151
- public function getApiKey($mode = '')
152
- {
153
- if (!$mode) {
154
- $mode = $this->getMode();
155
- }
156
- return $this->get($mode . '_api_key');
157
- }
158
-
159
- public function getMode()
160
- {
161
- return $this->get('payment_mode');
162
- }
163
- ```
164
-
165
- **Key Insights:**
166
-
167
- - Dynamic key resolution based on mode
168
- - Centralized mode management
169
- - Consistent naming patterns
170
-
171
- ### Important: Payment Mode vs Order Mode
172
-
173
- FluentCart distinguishes between two different "modes":
174
-
175
- 1. **Payment Mode** (`payment_mode` in settings): The current test/live configuration in payment gateway settings
176
-
177
- ```
178
- $this->settings->getMode(); // Returns current payment mode from settings
179
- ```
180
-
181
- 2. **Order Mode** (`$order->mode`): The mode captured at checkout time and stored with the order
182
-
183
- ```
184
- $order->mode; // Returns the mode when this specific order was placed
185
- ```
186
-
187
- **Usage Guidelines:**
188
-
189
- - **For API calls**: Use order mode from `$order->mode` to ensure consistency with the original transaction
190
- - **For settings/configuration**: Use payment mode from `$this->settings->getMode()`
191
- - **For transaction storage**: Always store `payment_mode` as `$order->mode` to preserve checkout-time context
192
- - **For transaction URLs**: Use the stored `payment_mode` from transaction data
193
-
194
- ## Complete Payment Processing Implementation
195
-
196
- ### One-Time Payment Flow
197
-
198
- ```
199
- class Processor
200
- {
201
- public function handleSinglePayment(PaymentInstance $paymentInstance)
202
- {
203
- $order = $paymentInstance->order;
204
- $transaction = $paymentInstance->transaction;
205
-
206
- // Prepare payment data for external API
207
- $paymentData = [
208
- 'items' => $this->prepareOrderItems($order),
209
- 'customer' => [
210
- 'email' => $order->email,
211
- 'name' => $order->billing_name,
212
- 'address' => $this->prepareAddress($order)
213
- ],
214
- 'custom_data' => [
215
- 'fct_transaction_hash' => $transaction->uuid,
216
- 'fct_order_id' => $order->id
217
- ],
218
- 'checkout' => [
219
- 'url' => $this->getCheckoutUrl($order),
220
- 'success_url' => $this->getSuccessUrl($transaction),
221
- 'cancel_url' => $this->getCancelUrl($order)
222
- ]
223
- ];
224
-
225
- // Create payment at external gateway
226
- // Always explicitly pass the order mode for consistency
227
- $response = API::createPaddleObject('transactions', $paymentData, $order->mode);
228
-
229
- if (is_wp_error($response)) {
230
- return [
231
- 'success' => false,
232
- 'message' => $response->get_error_message()
233
- ];
234
- }
235
-
236
- // Store external payment ID for webhook processing
237
- $transaction->update([
238
- 'vendor_charge_id' => $response['data']['id'],
239
- 'payment_mode' => $order->mode, // Store order mode from checkout time
240
- 'meta' => array_merge($transaction->meta ?? [], [
241
- 'gateway_response' => $response['data']
242
- ])
243
- ]);
244
-
245
- return [
246
- 'success' => true,
247
- 'redirect_url' => $response['data']['checkout']['url'],
248
- 'transaction_id' => $response['data']['id']
249
- ];
250
- }
251
-
252
- private function prepareOrderItems($order)
253
- {
254
- $items = [];
255
- foreach ($order->items as $item) {
256
- $items[] = [
257
- 'price_id' => $item->meta['external_price_id'] ?? null,
258
- 'quantity' => $item->quantity,
259
- 'name' => $item->title,
260
- 'description' => $item->description,
261
- 'unit_price' => $item->unit_price * 100, // Convert to cents
262
- 'total_price' => $item->total * 100
263
- ];
264
- }
265
- return $items;
266
- }
267
- }
268
- ```
269
-
270
- **Key Insights:**
271
-
272
- - Comprehensive order data mapping to external gateway format
273
- - Custom data inclusion for webhook correlation
274
- - Proper URL handling for checkout flow
275
- - Error handling with WP_Error integration
276
- - Transaction metadata storage for later processing
277
-
278
- ### Subscription Payment Flow
279
-
280
- ```
281
- public function handleSubscriptionPayment(PaymentInstance $paymentInstance)
282
- {
283
- $order = $paymentInstance->order;
284
- $subscription = $paymentInstance->subscription;
285
- $transaction = $paymentInstance->transaction;
286
-
287
- // Prepare subscription-specific data
288
- $subscriptionData = [
289
- 'items' => $this->prepareSubscriptionItems($order, $subscription),
290
- 'customer' => $this->prepareCustomerData($order),
291
- 'billing_cycle' => $this->mapBillingCycle($subscription),
292
- 'collection_mode' => 'automatic',
293
- 'proration_billing_mode' => 'prorated_immediately',
294
- 'custom_data' => [
295
- 'fct_subscription_hash' => $subscription->uuid,
296
- 'fct_order_id' => $order->id,
297
- 'fct_transaction_hash' => $transaction->uuid
298
- ],
299
- 'checkout' => [
300
- 'url' => $this->getCheckoutUrl($order),
301
- 'success_url' => $this->getSuccessUrl($transaction),
302
- 'cancel_url' => $this->getCancelUrl($order)
303
- ]
304
- ];
305
-
306
- // Add trial period if applicable
307
- if ($subscription->trial_days > 0) {
308
- $subscriptionData['scheduled_change'] = [
309
- 'action' => 'resume',
310
- 'effective_at' => gmdate('Y-m-d\TH:i:s\Z', strtotime('+' . $subscription->trial_days . ' days'))
311
- ];
312
- }
313
-
314
- // Create subscription at external gateway
315
- // Always explicitly pass the order mode for consistency
316
- $response = API::createPaddleObject('subscriptions', $subscriptionData, $order->mode);
317
-
318
- if (is_wp_error($response)) {
319
- return [
320
- 'success' => false,
321
- 'message' => $response->get_error_message()
322
- ];
323
- }
324
-
325
- // Store subscription and transaction data
326
- $subscription->update([
327
- 'vendor_subscription_id' => $response['data']['id'],
328
- 'status' => 'pending',
329
- 'meta' => array_merge($subscription->meta ?? [], [
330
- 'gateway_response' => $response['data'],
331
- 'billing_cycle_data' => $response['data']['billing_cycle'] ?? []
332
- ])
333
- ]);
334
-
335
- $transaction->update([
336
- 'vendor_charge_id' => $response['data']['id'],
337
- 'subscription_id' => $subscription->id,
338
- 'payment_mode' => $order->mode, // Store order mode from checkout time
339
- 'meta' => array_merge($transaction->meta ?? [], [
340
- 'subscription_data' => $response['data']
341
- ])
342
- ]);
343
-
344
- return [
345
- 'success' => true,
346
- 'redirect_url' => $response['data']['checkout']['url'],
347
- 'subscription_id' => $response['data']['id']
348
- ];
349
- }
350
-
351
- private function prepareSubscriptionItems($order, $subscription)
352
- {
353
- $items = [];
354
- foreach ($order->items as $item) {
355
- // Map to subscription pricing structure
356
- $items[] = [
357
- 'price_id' => $item->meta['recurring_price_id'] ?? $item->meta['external_price_id'],
358
- 'quantity' => $item->quantity,
359
- 'name' => $item->title,
360
- 'description' => $item->description,
361
- 'billing_cycle' => [
362
- 'interval' => $this->mapInterval($subscription->billing_interval),
363
- 'frequency' => $subscription->billing_interval_count ?? 1
364
- ],
365
- 'unit_price' => $item->unit_price * 100,
366
- 'trial_period' => $subscription->trial_days > 0 ? [
367
- 'interval' => 'day',
368
- 'frequency' => $subscription->trial_days
369
- ] : null
370
- ];
371
- }
372
- return $items;
373
- }
374
-
375
- private function mapBillingCycle($subscription)
376
- {
377
- $intervalMap = [
378
- 'day' => 'day',
379
- 'week' => 'week',
380
- 'month' => 'month',
381
- 'year' => 'year'
382
- ];
383
-
384
- return [
385
- 'interval' => $intervalMap[$subscription->billing_interval] ?? 'month',
386
- 'frequency' => $subscription->billing_interval_count ?? 1
387
- ];
388
- }
389
- ```
390
-
391
- **Key Insights:**
392
-
393
- - Subscription-specific data structure with billing cycles
394
- - Trial period handling with scheduled changes
395
- - Separate subscription and transaction storage
396
- - Complex item mapping for recurring pricing
397
- - Comprehensive metadata storage for webhook processing
398
-
399
- ## Payment Processing
400
-
401
- ### Payment Delegation Pattern
402
-
403
- ```
404
- public function makePaymentFromPaymentInstance(PaymentInstance $paymentInstance)
405
- {
406
- $order = $paymentInstance->order;
407
-
408
- if ($paymentInstance->subscription) {
409
- return (new Processor())->handleSubscriptionPayment($paymentInstance);
410
- }
411
-
412
- return (new Processor())->handleSinglePayment($paymentInstance);
413
- }
414
- ```
415
-
416
- **Key Insights:**
417
-
418
- - Delegates to specialized processor class
419
- - Clean separation between single and subscription payments
420
- - Maintains single responsibility principle
421
-
422
- ### API Communication Layer
423
-
424
- ```
425
- class API
426
- {
427
- public static function makeRequest($endpoint, $data = [], $method = 'POST', $mode = '')
428
- {
429
- $settings = self::getSettings();
430
-
431
- if (!$mode) {
432
- $mode = $settings->getMode(); // Get current payment mode from settings
433
- }
434
-
435
- $apiKey = $settings->getApiKey($mode);
436
- if (empty($apiKey)) {
437
- return new \WP_Error('paddle_api_key_missing', 'API key is missing');
438
- }
439
-
440
- $baseUrl = $mode === 'test'
441
- ? 'https://sandbox-api.paddle.com'
442
- : 'https://api.paddle.com';
443
-
444
- $response = wp_remote_request($baseUrl . $endpoint, [
445
- 'method' => $method,
446
- 'headers' => [
447
- 'Authorization' => 'Bearer ' . $apiKey,
448
- 'Content-Type' => 'application/json',
449
- ],
450
- 'body' => $method !== 'GET' ? json_encode($data) : null,
451
- 'timeout' => 30
452
- ]);
453
-
454
- // Error handling...
455
- return $decodedBody;
456
- }
457
- }
458
- ```
459
-
460
- **Key Insights:**
461
-
462
- - Environment-aware endpoint selection
463
- - Consistent error handling with WP_Error
464
- - Proper timeout configuration
465
- - Bearer token authentication
466
- - **Fallback to settings mode** when no mode parameter provided
467
- - **Best Practice**: Always explicitly pass the mode parameter for consistency
468
-
469
- ## Comprehensive Webhook/IPN Implementation
470
-
471
- ### Complete Webhook Processing Architecture
472
-
473
- The Paddle gateway implements a sophisticated three-layer webhook processing system that handles all payment and subscription events:
474
-
475
- ```
476
- class IPN
477
- {
478
- private PaddleSettings $settings;
479
-
480
- public function __construct()
481
- {
482
- $this->settings = new PaddleSettings();
483
- }
484
-
485
- /**
486
- * Initialize all webhook event handlers
487
- */
488
- public function init(): void
489
- {
490
- // Payment lifecycle events
491
- add_action('fluent_cart/payments/paddle/webhook_transaction_paid', [$this, 'handleTransactionPaid'], 10, 1);
492
- add_action('fluent_cart/payments/paddle/webhook_transaction_completed', [$this, 'handleTransactionCompleted'], 10, 1);
493
- add_action('fluent_cart/payments/paddle/webhook_transaction_payment_failed', [$this, 'handleTransactionPaymentFailed'], 10, 1);
494
-
495
- // Subscription lifecycle events
496
- add_action('fluent_cart/payments/paddle/webhook_subscription_created', [$this, 'handleSubscriptionActivated'], 10, 1);
497
- add_action('fluent_cart/payments/paddle/webhook_subscription_activated', [$this, 'handleSubscriptionActivated'], 10, 1);
498
- add_action('fluent_cart/payments/paddle/webhook_subscription_updated', [$this, 'handleSubscriptionUpdated'], 10, 1);
499
- add_action('fluent_cart/payments/paddle/webhook_subscription_canceled', [$this, 'handleSubscriptionCanceled'], 10, 1);
500
- add_action('fluent_cart/payments/paddle/webhook_subscription_paused', [$this, 'handleSubscriptionUpdated'], 10, 1);
501
- add_action('fluent_cart/payments/paddle/webhook_subscription_resumed', [$this, 'handleSubscriptionUpdated'], 10, 1);
502
- add_action('fluent_cart/payments/paddle/webhook_subscription_past_due', [$this, 'handleSubscriptionUpdated'], 10, 1);
503
- add_action('fluent_cart/payments/paddle/webhook_subscription_payment_received', [$this, 'handleSubscriptionPaymentReceived'], 10, 1);
504
-
505
- // Refund/adjustment events
506
- add_action('fluent_cart/payments/paddle/webhook_adjustment_created', [$this, 'handleAdjustmentCreated'], 10, 1);
507
- add_action('fluent_cart/payments/paddle/webhook_adjustment_updated', [$this, 'handleAdjustmentUpdated'], 10, 1);
508
- }
509
-
510
- /**
511
- * Main webhook entry point and processor
512
- */
513
- public function verifyAndProcess()
514
- {
515
- $rawPayload = file_get_contents('php://input');
516
- $payload = json_decode($rawPayload, true);
517
-
518
- if (!$payload) {
519
- $this->sendResponse(400, 'Invalid JSON payload');
520
- return;
521
- }
522
-
523
- // Verify webhook signature if not disabled
524
- if (!$this->settings->isWebhookVerificationDisabled()) {
525
- $webhookSecret = $this->settings->getWebhookSecret();
526
- if (empty($webhookSecret)) {
527
- error_log('Paddle Webhook Failed: Webhook secret not configured');
528
- $this->sendResponse(500, 'Webhook secret not configured');
529
- return;
530
- }
531
-
532
- $verifier = new WebhookVerifier($webhookSecret);
533
- $paddleSignature = $_SERVER['HTTP_PADDLE_SIGNATURE'];
534
-
535
- if (!$verifier->verify($paddleSignature, $rawPayload)) {
536
- error_log('Paddle Webhook Failed: Invalid webhook signature');
537
- $this->sendResponse(401, 'Invalid webhook signature');
538
- return;
539
- }
540
- }
541
-
542
- // Get order from webhook data
543
- $order = PaddleHelper::getOrderFromWebhookData($payload);
544
- if (!$order) {
545
- $this->sendResponse(200, 'Order not found');
546
- return;
547
- }
548
-
549
- $eventType = Arr::get($payload, 'event_type');
550
-
551
- // Validate accepted events
552
- $acceptedEvents = [
553
- 'transaction.paid', 'transaction.completed', 'transaction.payment_failed',
554
- 'adjustment.created', 'adjustment.updated',
555
- 'subscription.created', 'subscription.activated', 'subscription.updated',
556
- 'subscription.canceled', 'subscription.paused', 'subscription.resumed',
557
- 'subscription.past_due'
558
- ];
559
-
560
- if (!in_array($eventType, $acceptedEvents)) {
561
- $this->sendResponse(200, 'Event type not handled');
562
- return;
563
- }
564
-
565
- // Log webhook for debugging
566
- do_action('fluent_cart/paddle_webhook_received', [
567
- 'event_type' => $eventType,
568
- 'data' => $payload,
569
- 'raw' => $rawPayload,
570
- 'order' => $order
571
- ]);
572
-
573
- // Process specific webhook event
574
- $eventTypeFormatted = str_replace('.', '_', $eventType);
575
-
576
- // Handle subscription renewal detection
577
- if ($eventTypeFormatted === 'transaction_completed' || $eventTypeFormatted === 'transaction_paid') {
578
- $paddleTransaction = Arr::get($payload, 'data');
579
- $vendorSubscriptionId = Arr::get($paddleTransaction, 'subscription_id');
580
-
581
- if ($vendorSubscriptionId) {
582
- $eventTypeFormatted = 'subscription_payment_received';
583
- }
584
- }
585
-
586
- // Fire specific event handler
587
- if (has_action('fluent_cart/payments/paddle/webhook_' . $eventTypeFormatted)) {
588
- do_action('fluent_cart/payments/paddle/webhook_' . $eventTypeFormatted, [
589
- 'event_type' => $eventType,
590
- 'data' => $payload,
591
- 'raw' => $rawPayload,
592
- 'order' => $order
593
- ]);
594
-
595
- $this->sendResponse(200, 'Webhook processed successfully');
596
- } else {
597
- $this->sendResponse(200, 'No handler found for event type');
598
- }
599
- }
600
- }
601
- ```
602
-
603
- `isWebhookVerificationDisabled()` is true only in test mode:
604
-
605
- ```
606
- public function isWebhookVerificationDisabled()
607
- {
608
- return $this->getMode() === 'test' && $this->get('disable_webhook_verification') === 'yes';
609
- }
610
- ```
611
-
612
- In live mode the signature is always checked, whatever the setting says. If you offer a "disable verification" setting, gate it to test mode the same way.
613
-
614
- ### Individual Event Handlers
615
-
616
- #### Payment Completion Handler
617
-
618
- ```
619
- public function handleTransactionPaid($webhookData)
620
- {
621
- $payload = Arr::get($webhookData, 'data');
622
- $paddleTransaction = Arr::get($payload, 'data');
623
- $paddleTransactionId = Arr::get($paddleTransaction, 'id');
624
-
625
- // Extract custom data for correlation
626
- $customData = Arr::get($paddleTransaction, 'custom_data', []);
627
- $transactionHash = Arr::get($customData, 'fct_transaction_hash');
628
-
629
- // Find transaction by vendor ID or hash
630
- $transactionModel = OrderTransaction::query()->where('vendor_charge_id', $paddleTransactionId)->first();
631
-
632
- if (!$transactionModel && $transactionHash) {
633
- $transactionModel = OrderTransaction::query()->where('uuid', $transactionHash)->first();
634
- }
635
-
636
- if (!$transactionModel || $transactionModel->status === Status::TRANSACTION_SUCCEEDED) {
637
- return false;
638
- }
639
-
640
- // Use FluentCart's confirmation service
641
- (new Confirmations())->confirmPaymentSuccessByCharge($transactionModel, [
642
- 'vendor_charge_id' => $paddleTransactionId,
643
- 'charge' => $paddleTransaction
644
- ]);
645
-
646
- return true;
647
- }
648
- ```
649
-
650
- #### Subscription Management Handler
651
-
652
- ```
653
- public function handleSubscriptionActivated($webhookData)
654
- {
655
- $data = Arr::get($webhookData, 'data');
656
- $paddleSubscription = Arr::get($data, 'data');
657
- $order = Arr::get($webhookData, 'order');
658
-
659
- $customData = Arr::get($paddleSubscription, 'custom_data', []);
660
- $subscriptionHash = Arr::get($customData, 'fct_subscription_hash');
661
- $vendorSubscriptionId = Arr::get($paddleSubscription, 'id');
662
-
663
- // Find subscription by vendor ID or hash
664
- $subscription = Subscription::query()->where('vendor_subscription_id', $vendorSubscriptionId)->first();
665
-
666
- if (!$subscription) {
667
- $subscription = Subscription::query()->where('uuid', $subscriptionHash)->first();
668
- }
669
-
670
- if (!$subscription) {
671
- return false;
672
- }
673
-
674
- // Update subscription with complete data
675
- $billCount = OrderTransaction::query()->where('subscription_id', $subscription->id)->count();
676
- $updateData = [
677
- 'vendor_subscription_id' => Arr::get($paddleSubscription, 'id'),
678
- 'current_payment_method' => 'paddle',
679
- 'status' => PaddleHelper::transformSubscriptionStatus(Arr::get($paddleSubscription, 'status')),
680
- 'bill_count' => $billCount,
681
- 'next_billing_date' => gmdate('Y-m-d H:i:s', strtotime(Arr::get($paddleSubscription, 'next_billed_at'))),
682
- 'vendor_response' => json_encode($paddleSubscription)
683
- ];
684
-
685
- $oldStatus = $subscription->status;
686
- $subscription->update($updateData);
687
-
688
- // Fire subscription activated event for new subscriptions
689
- if (in_array($subscription->status, [Status::SUBSCRIPTION_ACTIVE, Status::SUBSCRIPTION_TRIALING])
690
- && !in_array($oldStatus, [Status::SUBSCRIPTION_ACTIVE, Status::SUBSCRIPTION_TRIALING])
691
- && $subscription->bill_count === 0) {
692
-
693
- (new SubscriptionActivated($subscription, $order, $order->customer))->dispatch();
694
- }
695
-
696
- return true;
697
- }
698
- ```
699
-
700
- #### Refund Processing Handler
701
-
702
- ```
703
- public function handleAdjustmentCreated($webhookData)
704
- {
705
- $payload = Arr::get($webhookData, 'data');
706
- $paddleAdjustment = Arr::get($payload, 'data');
707
- $paddleAdjustmentId = Arr::get($paddleAdjustment, 'id');
708
- $action = Arr::get($paddleAdjustment, 'action');
709
-
710
- // Only handle refund adjustments
711
- if ($action !== 'refund') {
712
- return false;
713
- }
714
-
715
- $parentTransactionId = Arr::get($paddleAdjustment, 'transaction_id');
716
- $parentTransaction = OrderTransaction::query()->where('vendor_charge_id', $parentTransactionId)->first();
717
-
718
- if (!$parentTransaction) {
719
- return false;
720
- }
721
-
722
- // Calculate refund amount from adjustment items
723
- $paddleRefundAmount = 0;
724
- foreach (Arr::get($paddleAdjustment, 'items', []) as $item) {
725
- $paddleRefundAmount += Arr::get($item, 'totals.total', 0);
726
- }
727
-
728
- $status = $this->transformAdjustmentStatus(Arr::get($paddleAdjustment, 'status'));
729
-
730
- // Use FluentCart's refund service
731
- return \FluentCart\App\Services\Payments\Refund::createOrRecordRefund([
732
- 'vendor_charge_id' => $paddleAdjustmentId,
733
- 'payment_method' => 'paddle',
734
- 'payment_mode' => $parentTransaction->payment_mode, // Use stored order mode
735
- 'status' => $status,
736
- 'total' => $paddleRefundAmount,
737
- ], $parentTransaction);
738
- }
739
-
740
- public function handleAdjustmentUpdated($webhookData)
741
- {
742
- $payload = Arr::get($webhookData, 'data');
743
- $paddleAdjustment = Arr::get($payload, 'data');
744
- $paddleAdjustmentId = Arr::get($paddleAdjustment, 'id');
745
-
746
- $adjustmentTransaction = OrderTransaction::query()->where('vendor_charge_id', $paddleAdjustmentId)->first();
747
-
748
- if (!$adjustmentTransaction) {
749
- return false;
750
- }
751
-
752
- // Update refund status
753
- $adjustmentTransaction->update([
754
- 'status' => $this->transformAdjustmentStatus(Arr::get($paddleAdjustment, 'status'))
755
- ]);
756
-
757
- // Fire refund event if completed
758
- if ($adjustmentTransaction->status === Status::TRANSACTION_REFUNDED) {
759
- (new OrderRefund($order, $adjustmentTransaction))->dispatch();
760
- }
761
-
762
- return true;
763
- }
764
- ```
765
-
766
- #### Subscription Renewal Handler
767
-
768
- ```
769
- public function handleSubscriptionPaymentReceived($webhookData)
770
- {
771
- $order = Arr::get($webhookData, 'order');
772
- $payload = Arr::get($webhookData, 'data');
773
- $paddleSubscriptionId = Arr::get($payload, 'data.subscription_id');
774
-
775
- // Find subscription
776
- $subscriptionModel = Subscription::query()->where('vendor_subscription_id', $paddleSubscriptionId)->first();
777
-
778
- if (!$subscriptionModel) {
779
- $subscriptionModel = Subscription::query()->where('parent_order_id', $order->id)->first();
780
- }
781
-
782
- if (!$subscriptionModel) {
783
- return false;
784
- }
785
-
786
- // Re-sync subscription data from remote
787
- $subscriptionModel->reSyncFromRemote();
788
-
789
- return true;
790
- }
791
- ```
792
-
793
- **Key Insights:**
794
-
795
- - **Complete Event Coverage**: Handles all payment, subscription, and refund events
796
- - **Smart Event Detection**: Automatically detects subscription renewals vs new payments
797
- - **Service Method Integration**: Uses FluentCart's service methods instead of manual hook firing
798
- - **Robust Error Handling**: Comprehensive validation and error responses
799
- - **Data Correlation**: Uses custom data fields to correlate webhooks with local records
800
- - **Status Management**: Proper status transformations and updates
801
- - **Signature Verification**: Required in live mode. It can be switched off in test mode only
802
- - **Logging Integration**: Uses FluentCart's action system for debugging
803
-
804
- ## Web Hook Implementation
805
-
806
- ### Signature Verification
807
-
808
- ```
809
- public static function verifyWebhook($payload = null, $signature = null, $mode = '')
810
- {
811
- if ($payload === null) {
812
- $payload = file_get_contents('php://input');
813
- }
814
-
815
- if ($signature === null) {
816
- $signature = $_SERVER['HTTP_PADDLE_SIGNATURE'] ?? '';
817
- }
818
-
819
- return self::verifyWebhookSignature($payload, $signature, $mode);
820
- }
821
-
822
- private static function verifyWebhookSignature($payload, $signature, $mode)
823
- {
824
- $settings = new PaddleSettings();
825
- $secret = $settings->getWebhookSecret($mode);
826
-
827
- if (!$secret || !$signature) {
828
- return false;
829
- }
830
-
831
- // Paddle-specific signature verification logic
832
- // This uses Paddle's signature format and algorithm
833
- return hash_equals($expectedSignature, $signature);
834
- }
835
- ```
836
-
837
- **Key Insights:**
838
-
839
- - Flexible parameter handling (allows testing)
840
- - Environment-aware secret selection
841
- - Uses hash_equals for timing attack protection
842
- - Gateway-specific signature algorithms
843
-
844
- ### Event Processing
845
-
846
- ```
847
- class IPN
848
- {
849
- public function init(): void
850
- {
851
- // Register webhook event handlers
852
- add_action('fluent_cart/payments/paddle/webhook_transaction_paid', [$this, 'handleTransactionPaid'], 10, 1);
853
- add_action('fluent_cart/payments/paddle/webhook_transaction_completed', [$this, 'handleTransactionCompleted'], 10, 1);
854
- add_action('fluent_cart/payments/paddle/webhook_subscription_created', [$this, 'handleSubscriptionCreated'], 10, 1);
855
- // ... more handlers
856
- }
857
-
858
- public function verifyAndProcess(): void
859
- {
860
- $payload = file_get_contents('php://input');
861
- $signature = $_SERVER['HTTP_PADDLE_SIGNATURE'] ?? '';
862
-
863
- if (!API::verifyWebhook($payload, $signature)) {
864
- http_response_code(401);
865
- exit('Unauthorized');
866
- }
867
-
868
- $data = json_decode($payload, true);
869
- $this->processWebhookEvent($data);
870
-
871
- http_response_code(200);
872
- exit('OK');
873
- }
874
- }
875
- ```
876
-
877
- **Key Insights:**
878
-
879
- - Uses WordPress action system for event handling
880
- - Modular event processing
881
- - Proper HTTP response codes
882
- - Early exit after processing
883
-
884
- ## Complete Frontend Integration
885
-
886
- ### Multi-Script Asset Management
887
-
888
- ```
889
- public function getEnqueueScriptSrc($hasSubscription = 'no'): array
890
- {
891
- $paddleJsUrl = 'https://cdn.paddle.com/paddle/v2/paddle.js';
892
-
893
- return [
894
- [
895
- 'handle' => 'fluent-cart-checkout-sdk-paddle-js',
896
- 'src' => $paddleJsUrl,
897
- ],
898
- [
899
- 'handle' => 'fluent-cart-paddle-checkout',
900
- 'src' => Vite::getEnqueuePath('public/payment-methods/paddle-checkout.js'),
901
- 'deps' => ['fluent-cart-checkout-sdk-paddle-js']
902
- ]
903
- ];
904
- }
905
-
906
- public function getLocalizeData(): array
907
- {
908
- return [
909
- 'fct_paddle_data' => [
910
- 'translations' => [
911
- 'Paddle SDK is not loaded. Please ensure the Paddle script is included.' => __('Paddle SDK is not loaded...', 'fluent-cart-pro'),
912
- 'Paddle client token is missing or invalid.' => __('Paddle client token is missing or invalid.', 'fluent-cart-pro'),
913
- 'Pay with Paddle' => __('Pay with Paddle', 'fluent-cart-pro'),
914
- 'Secure payment powered by Paddle' => __('Secure payment powered by Paddle', 'fluent-cart-pro'),
915
- 'Order creation failed' => __('Order creation failed', 'fluent-cart-pro'),
916
- 'Failed to create order' => __('Failed to create order', 'fluent-cart-pro'),
917
- 'No Paddle price IDs found in order data. Please ensure Paddle products are properly configured.' => __('No Paddle price IDs found...', 'fluent-cart-pro'),
918
- 'Error: Missing transaction ID' => __('Error: Missing transaction ID', 'fluent-cart-pro'),
919
- 'Payment failed' => __('Payment failed', 'fluent-cart-pro'),
920
- 'An error occurred. Please try again.' => __('An error occurred. Please try again.', 'fluent-cart-pro'),
921
- ]
922
- ]
923
- ];
924
- }
925
- ```
926
-
927
- ### Dynamic Order Information Handling
928
-
929
- ```
930
- public function getOrderInfo(array $data)
931
- {
932
- $cart = CartHelper::getCart();
933
- $checkOutHelper = new CartCheckoutHelper(true);
934
- $shippingChargeData = (new WebCheckoutHandler())->getShippingChargeData($cart);
935
- $shippingCharge = Arr::get($shippingChargeData, 'charge');
936
- $totalPrice = $checkOutHelper->getItemsAmountTotal(false) + $shippingCharge;
937
-
938
- $items = $checkOutHelper->getItems();
939
- $hasSubscription = $this->validateSubscriptions($items);
940
-
941
- $clientToken = $this->settings->getClientToken();
942
- $settings = $this->settings->get();
943
-
944
- // Prepare frontend payment arguments
945
- $paymentArgs = [
946
- 'client_token' => $clientToken ?: '',
947
- 'mode' => $this->settings->getMode(), // Current payment mode from settings
948
- 'paddle_checkout_button_text' => Arr::get($settings, 'paddle_checkout_button_text', ''),
949
- 'paddle_checkout_button_color' => Arr::get($settings, 'paddle_checkout_button_color', ''),
950
- 'paddle_checkout_button_hover_color' => Arr::get($settings, 'paddle_checkout_button_hover_color', ''),
951
- 'paddle_checkout_button_text_color' => Arr::get($settings, 'paddle_checkout_button_text_color', ''),
952
- 'paddle_checkout_button_font_size' => Arr::get($settings, 'paddle_checkout_button_font_size', '')
953
- ];
954
-
955
- // Prepare payment details
956
- $paymentDetails = [
957
- 'mode' => 'payment',
958
- 'theme' => Arr::get($settings, 'paddle_checkout_theme', 'light'),
959
- 'amount' => Helper::toDecimalWithoutComma($totalPrice),
960
- 'currency' => strtoupper(CurrencySettings::get('currency')),
961
- 'locale' => (new StoreSettings())->get('locale', 'en'),
962
- ];
963
-
964
- if ($hasSubscription) {
965
- $paymentDetails['mode'] = 'subscription';
966
- }
967
-
968
- $this->checkCurrencySupport();
969
-
970
- wp_send_json([
971
- 'status' => 'success',
972
- 'payment_args' => $paymentArgs,
973
- 'intent' => $paymentDetails,
974
- 'has_subscription' => $hasSubscription,
975
- 'message' => __('Order info retrieved!', 'fluent-cart-pro')
976
- ], 200);
977
- }
978
- ```
979
-
980
- **Key Insights:**
981
-
982
- - **Dynamic Asset Loading**: External SDK + custom integration scripts
983
-
984
- ### Paddle Checkout JavaScript Implementation
985
-
986
- The frontend JavaScript implementation handles the customer checkout experience:
987
-
988
- ```
989
- // File: resources/public/payment-methods/paddle-checkout.js
990
- class PaddleCheckout {
991
- constructor(form, orderHandler, response, paymentLoader) {
992
- this.form = form;
993
- this.orderHandler = orderHandler;
994
- this.data = response;
995
- this.paymentArgs = response?.payment_args || {};
996
- this.intent = response?.intent || {};
997
- this.paymentLoader = paymentLoader;
998
- this.currentOrderData = null;
999
- this.$t = this.translate.bind(this);
1000
- }
1001
-
1002
- translate(string) {
1003
- const translations = window.fct_paddle_data?.translations || {};
1004
- return translations[string] || string;
1005
- }
1006
-
1007
- init() {
1008
- const paddleButtonContainer = document.querySelector('.fluent-cart-checkout_embed_payment_container_paddle');
1009
- if (!paddleButtonContainer) {
1010
- console.error('Paddle container not found');
1011
- return;
1012
- }
1013
-
1014
- // Clear any existing content
1015
- paddleButtonContainer.innerHTML = '';
1016
-
1017
- // Initialize Paddle SDK and create button
1018
- this.initializePaddleSDK()
1019
- .then(() => {
1020
- this.createPaddleButton(paddleButtonContainer);
1021
- })
1022
- .catch((error) => {
1023
- console.error('Paddle initialization error:', error);
1024
- this.displayErrorMessage(paddleButtonContainer, error.message);
1025
- });
1026
- }
1027
-
1028
- async initializePaddleSDK() {
1029
- if (typeof Paddle === 'undefined') {
1030
- throw new Error(this.$t('Paddle SDK is not loaded. Please ensure the Paddle script is included.'));
1031
- }
1032
-
1033
- const clientToken = this.paymentArgs?.client_token;
1034
- const environment = this.paymentArgs?.mode === 'test' ? 'sandbox' : 'production';
1035
-
1036
- if (!clientToken) {
1037
- throw new Error(this.$t('Paddle client token is missing or invalid.'));
1038
- }
1039
-
1040
- Paddle.Environment.set(environment);
1041
- Paddle.Initialize({
1042
- token: clientToken.trim(),
1043
- eventCallback: (data) => {
1044
- this.handlePaddleEvent(data);
1045
- }
1046
- });
1047
- }
1048
-
1049
- createPaddleButton(container) {
1050
- const paddleButton = document.createElement('button');
1051
- paddleButton.id = 'paddle-pay-button';
1052
- paddleButton.className = 'paddle-checkout-button';
1053
- paddleButton.innerHTML = this.$t('Pay with Paddle');
1054
- paddleButton.style.cssText = `
1055
- width: 100%;
1056
- padding: 12px 24px;
1057
- background: #1a73e8;
1058
- color: #fff;
1059
- border: none;
1060
- border-radius: 6px;
1061
- font-weight: 500;
1062
- cursor: pointer;
1063
- `;
1064
-
1065
- paddleButton.addEventListener('click', async (e) => {
1066
- e.preventDefault();
1067
- await this.handlePaddleButtonClick();
1068
- });
1069
-
1070
- container.appendChild(paddleButton);
1071
- }
1072
-
1073
- async handlePaddleButtonClick() {
1074
- try {
1075
- this.paymentLoader?.changeLoaderStatus('processing');
1076
-
1077
- if (typeof this.orderHandler === 'function') {
1078
- const orderData = await this.orderHandler();
1079
- if (!orderData) {
1080
- throw new Error(this.$t('Failed to create order'));
1081
- }
1082
-
1083
- // Open Paddle overlay checkout
1084
- await this.openPaddleOverlay(orderData);
1085
- } else {
1086
- throw new Error(this.$t('Order handler is not properly configured'));
1087
- }
1088
- } catch (error) {
1089
- this.paymentLoader?.changeLoaderStatus('Error: ' + error.message);
1090
- this.displayErrorMessage(
1091
- document.querySelector('.fluent-cart-checkout_embed_payment_container_paddle'),
1092
- error.message
1093
- );
1094
- }
1095
- }
1096
-
1097
- async openPaddleOverlay(orderData) {
1098
- this.currentOrderData = orderData;
1099
-
1100
- const paddleData = orderData?.response || orderData;
1101
- const items = paddleData?.paddle_price_ids?.map(item => ({
1102
- priceId: item.price_id,
1103
- quantity: parseInt(item.quantity) || 1
1104
- }));
1105
-
1106
- if (!items || items.length === 0) {
1107
- throw new Error(this.$t('No Paddle price IDs found in order data'));
1108
- }
1109
-
1110
- Paddle.Checkout.open({
1111
- settings: {
1112
- displayMode: 'overlay',
1113
- theme: this.intent?.theme || 'light',
1114
- locale: this.intent?.locale || 'en'
1115
- },
1116
- items: items,
1117
- customData: {
1118
- fct_order_hash: orderData?.data?.order?.hash || '',
1119
- fct_transaction_hash: orderData?.data?.transaction?.hash || '',
1120
- }
1121
- });
1122
- }
1123
-
1124
- handlePaddleEvent(eventData) {
1125
- switch (eventData.name) {
1126
- case 'checkout.completed':
1127
- this.handlePaddlePaymentSuccess(eventData.data);
1128
- break;
1129
- case 'checkout.closed':
1130
- this.handlePaddleCheckoutClosed(eventData.data);
1131
- break;
1132
- case 'checkout.payment.failed':
1133
- this.handlePaddlePaymentFailed(eventData.data);
1134
- break;
1135
- case 'checkout.error':
1136
- this.handlePaddleError(eventData.data);
1137
- break;
1138
- }
1139
- }
1140
-
1141
- async handlePaddlePaymentSuccess(paddleData) {
1142
- try {
1143
- this.paymentLoader?.changeLoaderStatus('confirming');
1144
- const transactionId = paddleData?.transaction_id;
1145
-
1146
- if (!transactionId) {
1147
- this.paymentLoader?.changeLoaderStatus(this.$t('Error: Missing transaction ID'));
1148
- return;
1149
- }
1150
-
1151
- const customData = paddleData.custom_data;
1152
- const confirmResponse = await this.confirmPayment(transactionId, customData);
1153
-
1154
- if (confirmResponse?.redirect_url) {
1155
- this.paymentLoader?.changeLoaderStatus('redirecting');
1156
- window.location.href = confirmResponse.redirect_url;
1157
- }
1158
- } catch (error) {
1159
- this.paymentLoader?.changeLoaderStatus('Error: ' + error.message);
1160
- }
1161
- }
1162
-
1163
- displayErrorMessage(container, message) {
1164
- const errorDiv = document.createElement('div');
1165
- errorDiv.style.color = 'red';
1166
- errorDiv.textContent = message;
1167
- container.appendChild(errorDiv);
1168
- }
1169
- }
1170
-
1171
- // Initialize when FluentCart triggers the event
1172
- window.addEventListener("fluent_cart_load_payments_paddle", function (e) {
1173
- fetch(e.detail.paymentInfoUrl, {
1174
- method: "POST",
1175
- headers: {
1176
- "Content-Type": "application/json",
1177
- "X-WP-Nonce": e.detail.nonce,
1178
- },
1179
- credentials: 'include'
1180
- }).then(async (response) => {
1181
- response = await response.json();
1182
- new PaddleCheckout(e.detail.form, e.detail.orderHandler, response, e.detail.paymentLoader).init();
1183
- }).catch(error => {
1184
- console.error('Failed to load Paddle payment info:', error);
1185
- });
1186
- });
1187
- ```
1188
-
1189
- - **Comprehensive Localization**: All user-facing messages translated
1190
- - **Real-time Order Processing**: Cart data processed on-demand
1191
- - **Subscription Detection**: Automatic mode switching based on cart contents
1192
- - **UI Customization**: Extensive theming and styling options
1193
- - **Currency Validation**: Pre-flight currency support checking
1194
-
1195
- ## Advanced Production Features
1196
-
1197
- ### Comprehensive Settings with Dynamic Instructions
1198
-
1199
- ```
1200
- public function fields(): array
1201
- {
1202
- $webhookInstructions = $this->getWebhookInstructions();
1203
-
1204
- $testSchema = [
1205
- 'test_api_key' => array(
1206
- 'value' => '',
1207
- 'label' => __('Sandbox API Key', 'fluent-cart-pro'),
1208
- 'type' => 'password',
1209
- 'placeholder' => __('Your sandbox API key', 'fluent-cart-pro'),
1210
- 'help_text' => __('Get your API key from Paddle Dashboard > Developer Tools > Authentication', 'fluent-cart-pro')
1211
- ),
1212
- 'test_client_token' => array(
1213
- 'value' => '',
1214
- 'label' => __('Sandbox Client Token / Public Key', 'fluent-cart-pro'),
1215
- 'type' => 'text',
1216
- 'placeholder' => __('Your sandbox client token', 'fluent-cart-pro'),
1217
- 'help_text' => __('Optional: Used for frontend checkout integration', 'fluent-cart-pro')
1218
- ),
1219
- 'test_webhook_secret' => array(
1220
- 'value' => '',
1221
- 'label' => __('Sandbox Webhook Secret', 'fluent-cart-pro'),
1222
- 'type' => 'password',
1223
- 'placeholder' => __('Your sandbox webhook secret', 'fluent-cart-pro'),
1224
- 'help_text' => __('Used to verify webhook signatures', 'fluent-cart-pro')
1225
- ),
1226
- 'test_webhook_desc' => array(
1227
- 'value' => $webhookInstructions,
1228
- 'label' => __('Webhook Configuration', 'fluent-cart-pro'),
1229
- 'type' => 'html_attr'
1230
- ),
1231
- ];
1232
-
1233
- // Live schema similar structure...
1234
-
1235
- return array(
1236
- 'notice' => [
1237
- 'value' => $this->renderStoreModeNotice(),
1238
- 'label' => __('Store Mode notice', 'fluent-cart-pro'),
1239
- 'type' => 'notice'
1240
- ],
1241
- 'beta_notice' => [
1242
- 'value' => '<p class="text-gray-500">Paddle payment gateway is currently in beta. Please use with caution!</p>',
1243
- 'label' => __('Beta Notice', 'fluent-cart-pro'),
1244
- 'type' => 'html_attr'
1245
- ],
1246
- 'payment_mode' => [
1247
- 'type' => 'tabs',
1248
- 'schema' => [
1249
- [
1250
- 'type' => 'tab',
1251
- 'label' => __('Live credentials', 'fluent-cart-pro'),
1252
- 'value' => 'live',
1253
- 'schema' => $liveSchema
1254
- ],
1255
- [
1256
- 'type' => 'tab',
1257
- 'label' => __('Test credentials', 'fluent-cart-pro'),
1258
- 'value' => 'test',
1259
- 'schema' => $testSchema
1260
- ]
1261
- ]
1262
- ],
1263
- 'paddle_checkout_theme' => [
1264
- 'value' => 'light',
1265
- 'label' => __('Paddle Checkout Theme', 'fluent-cart-pro'),
1266
- 'type' => 'select',
1267
- 'options' => [
1268
- 'light' => ['label' => __('Light', 'fluent-cart-pro'), 'value' => 'light'],
1269
- 'dark' => ['label' => __('Dark', 'fluent-cart-pro'), 'value' => 'dark']
1270
- ],
1271
- 'tooltip' => __('Theme to use for Paddle checkout modal', 'fluent-cart-pro')
1272
- ],
1273
- 'paddle_checkout_button_text' => [
1274
- 'value' => __('Pay with Paddle', 'fluent-cart-pro'),
1275
- 'label' => __('Paddle Checkout Button Text', 'fluent-cart-pro'),
1276
- 'type' => 'text',
1277
- 'placeholder' => __('Pay with Paddle', 'fluent-cart-pro'),
1278
- 'tooltip' => __('Text to display on the Paddle checkout button', 'fluent-cart-pro')
1279
- ],
1280
- 'paddle_checkout_button_color' => [
1281
- 'value' => '',
1282
- 'label' => __('Paddle Checkout Button Color', 'fluent-cart-pro'),
1283
- 'type' => 'color',
1284
- 'tooltip' => __('Color of the Paddle checkout button', 'fluent-cart-pro')
1285
- ],
1286
- 'disable_webhook_verification' => [
1287
- 'value' => 'no',
1288
- 'label' => __('Disable Webhook Verification', 'fluent-cart-pro'),
1289
- 'type' => 'checkbox',
1290
- 'tooltip' => __('Only disable this for testing purposes. Keep enabled for production.', 'fluent-cart-pro')
1291
- ]
1292
- );
1293
- }
1294
-
1295
- public function getWebhookInstructions()
1296
- {
1297
- $webhook_url = $this->getWebhookUrl();
1298
- $eventsHtml = $this->getEventshtml();
1299
-
1300
- // Dynamic HTML instructions based on configuration state
1301
- $instructionsHtml =
1302
- '<div class="paddle-webhook-instructions" style="padding:12px 0;">'
1303
- . '<p><strong>' . esc_html__('Webhook URL:', 'fluent-cart-pro') . '</strong> '
1304
- . '<code class="copyable-content" data-copy="' . esc_attr($webhook_url) . '">' . esc_html($webhook_url) . '</code></p>'
1305
- . '<p>' . esc_html__('You should configure your Paddle webhooks to get all updates of your payments remotely.', 'fluent-cart-pro') . '</p>'
1306
- . '<p>' . esc_html__('Select the following events:', 'fluent-cart-pro') . '</p>'
1307
- . '<p style="display:flex; align-items:center; flex-wrap:wrap; gap:8px 4px;">' . wp_kses_post($eventsHtml) . '</p>'
1308
- . '</div>';
1309
-
1310
- return $instructionsHtml;
1311
- }
1312
- ```
1313
-
1314
- ### Multi-Environment Support with Security
1315
-
1316
- ```
1317
- public static function beforeSettingsUpdate($data, $oldSettings): array
1318
- {
1319
- $mode = Arr::get($data, 'payment_mode', 'live');
1320
- $apiKeyField = $mode . '_api_key';
1321
-
1322
- // Encrypt sensitive data before storage
1323
- $data[$apiKeyField] = Helper::encryptKey($data[$apiKeyField]);
1324
-
1325
- return $data;
1326
- }
1327
-
1328
- public static function validateSettings($data): array
1329
- {
1330
- $mode = Arr::get($data, 'payment_mode', 'live');
1331
- $apiKey = Arr::get($data, $mode . '_api_key');
1332
-
1333
- if (empty($apiKey)) {
1334
- return [
1335
- 'status' => 'failed',
1336
- 'message' => __('API key is required.', 'fluent-cart-pro')
1337
- ];
1338
- }
1339
-
1340
- // Could add live API connectivity test here
1341
- // $testResponse = API::testConnection($apiKey, $mode);
1342
-
1343
- return [
1344
- 'status' => 'success',
1345
- 'message' => __('Paddle gateway credentials verified successfully!', 'fluent-cart-pro')
1346
- ];
1347
- }
1348
- ```
1349
-
1350
- ### Currency and Transaction URL Management
1351
-
1352
- ```
1353
- public function isCurrencySupported(): bool
1354
- {
1355
- $supportedCurrencies = [
1356
- 'USD', 'EUR', 'GBP', 'JPY', 'AUD', 'CAD', 'CHF', 'HKD', 'SGD', 'SEK',
1357
- 'ARS', 'BRL', 'CNY', 'COP', 'CZK', 'DKK', 'HUF', 'ILS', 'INR', 'KRW',
1358
- 'MXN', 'NOK', 'NZD', 'PLN', 'RUB', 'THB', 'TRY', 'TWD', 'UAH', 'VND', 'ZAR'
1359
- ];
1360
-
1361
- return in_array(strtoupper(CurrencySettings::get('currency')), $supportedCurrencies);
1362
- }
1363
-
1364
- public function getTransactionUrl($url, $data)
1365
- {
1366
- if (Arr::get($data, 'transaction_type') === 'refund') {
1367
- $parentTransaction = OrderTransaction::query()->where('id', Arr::get($data, 'transaction.meta.parent_id'))->first();
1368
- $data['vendor_charge_id'] = $parentTransaction->vendor_charge_id;
1369
- }
1370
-
1371
- // Use payment_mode from transaction data (stored order mode at checkout time)
1372
- if (Arr::get($data, 'payment_mode') === 'test') {
1373
- return 'https://sandbox-vendors.paddle.com/transactions-v2/' . Arr::get($data, 'vendor_charge_id');
1374
- }
1375
-
1376
- return 'https://vendors.paddle.com/transactions-v2/' . Arr::get($data, 'vendor_charge_id');
1377
- }
1378
-
1379
- public function getSubscriptionUrl($url, $data)
1380
- {
1381
- // Use payment_mode from subscription data (stored order mode at checkout time)
1382
- if (Arr::get($data, 'payment_mode') === 'test') {
1383
- return 'https://sandbox-vendors.paddle.com/subscriptions-v2/' . Arr::get($data, 'vendor_subscription_id');
1384
- }
1385
-
1386
- return 'https://vendors.paddle.com/subscriptions-v2/' . Arr::get($data, 'vendor_subscription_id');
1387
- }
1388
- ```
1389
-
1390
- ### Success and Cancel URL Handling
1391
-
1392
- ```
1393
- public function getSuccessUrl($transaction, $args = [])
1394
- {
1395
- $paymentHelper = new PaymentHelper($this->getMeta('route'));
1396
- return $paymentHelper->successUrl($transaction->uuid, $args);
1397
- }
1398
-
1399
- public static function getCancelUrl(): string
1400
- {
1401
- $checkoutPage = (new StoreSettings())->getCheckoutPage();
1402
- $cartHash = $_GET['fct_cart_hash'] ?? '';
1403
-
1404
- if ($cartHash) {
1405
- return add_query_arg([
1406
- 'fct_cart_hash' => $cartHash
1407
- ], $checkoutPage);
1408
- }
1409
-
1410
- return $checkoutPage;
1411
- }
1412
- ```
1413
-
1414
- **Key Insights:**
1415
-
1416
- - **Dynamic Configuration**: Settings UI changes based on configuration state
1417
- - **Security-First Approach**: API key encryption and secure storage
1418
- - **Environment Awareness**: All URLs and endpoints environment-specific
1419
- - **Comprehensive Validation**: Settings validation with optional API testing
1420
- - **User Experience**: Helpful instructions and copyable content
1421
- - **Production-Ready**: Extensive customization options for branding
1422
- - **URL Management**: Proper success/cancel URL handling with cart state preservation
1423
-
1424
- ## Registration Pattern
1425
-
1426
- ```
1427
- public static function register()
1428
- {
1429
- fluent_cart_api()->registerCustomPaymentMethod('paddle', new self());
1430
- }
1431
- ```
1432
-
1433
- **Key Insights:**
1434
-
1435
- - Simple static registration method
1436
- - Self-instantiation pattern
1437
- - Called from bootstrap file
1438
-
1439
- ## Comprehensive Lessons Learned
1440
-
1441
- ### 1. **Complete Payment Lifecycle Management**
1442
-
1443
- - **One-time Payments**: Full transaction flow from creation to confirmation
1444
- - **Subscription Payments**: Complex billing cycles, trials, and renewal handling
1445
- - **Refund Processing**: Comprehensive adjustment and refund management
1446
- - **Status Synchronization**: Real-time status updates via webhooks
1447
-
1448
- ### 2. **Three-Layer Webhook Architecture**
1449
-
1450
- - **Entry Point**: Single `handleIPN()` method for all webhook traffic
1451
- - **Central Processor**: `verifyAndProcess()` with signature verification and routing
1452
- - **Event Handlers**: Specific handlers for each event type using FluentCart services
1453
- - **Error Handling**: Comprehensive HTTP response codes and logging
1454
-
1455
- ### 3. **Service Method Integration**
1456
-
1457
- - **StatusHelper**: Automatic order status sync and hook firing
1458
- - **Refund Service**: Complete refund transaction management
1459
- - **SubscriptionService**: Subscription lifecycle and renewal processing
1460
- - **Confirmation Service**: Payment confirmation with complex data handling
1461
-
1462
- ### 4. **Production-Ready Security**
1463
-
1464
- - **Signature Verification**: Optional but recommended webhook signature validation
1465
- - **API Key Encryption**: Secure storage of sensitive credentials
1466
- - **Environment Separation**: Complete test/live mode isolation
1467
- - **Input Validation**: Comprehensive data validation and sanitization
1468
-
1469
- ### 5. **Advanced Settings Architecture**
1470
-
1471
- - **Dynamic Configuration**: UI that changes based on current settings
1472
- - **Tabbed Interface**: Clean separation of test/live credentials
1473
- - **Visual Customization**: Extensive theming and branding options
1474
- - **Helpful Instructions**: Dynamic webhook setup guidance
1475
-
1476
- ### 6. **Frontend Integration Excellence**
1477
-
1478
- - **Multi-Script Loading**: External SDK + custom integration scripts
1479
- - **Comprehensive Localization**: All user-facing messages translated
1480
- - **Real-time Processing**: Dynamic order and cart processing
1481
- - **UI Customization**: Extensive checkout appearance options
1482
-
1483
- ### 7. **Subscription Management Complexity**
1484
-
1485
- - **Billing Cycle Mapping**: Complex interval and frequency handling
1486
- - **Trial Period Support**: Scheduled activation after trial periods
1487
- - **Renewal Detection**: Smart detection of subscription vs one-time payments
1488
- - **Status Transformation**: Gateway-specific to FluentCart status mapping
1489
-
1490
- ### 8. **Data Architecture Patterns**
1491
-
1492
- - **Custom Data Fields**: Webhook correlation via custom metadata
1493
- - **Comprehensive Storage**: Full gateway response storage for debugging
1494
- - **Status Mapping**: Bidirectional status transformation
1495
- - **Transaction Relationships**: Parent-child relationships for refunds
1496
-
1497
- ## Application to Your Gateway Development
1498
-
1499
- ### Essential Implementation Patterns
1500
-
1501
- 1. **Gateway Class Structure**
1502
-
1503
- ```
1504
- // Complete feature declaration
1505
- public array $supportedFeatures = ['payment', 'refund', 'webhook', 'subscriptions'];
1506
-
1507
- // Composition over inheritance
1508
- public function __construct() {
1509
- parent::__construct(new YourSettings(), new YourSubscriptions());
1510
- }
1511
- ```
1512
-
1513
- 2. **Payment Processing Delegation**
1514
-
1515
- ```
1516
- // Clean separation of concerns
1517
- public function makePaymentFromPaymentInstance(PaymentInstance $instance) {
1518
- if ($instance->subscription) {
1519
- return (new Processor())->handleSubscriptionPayment($instance);
1520
- }
1521
- return (new Processor())->handleSinglePayment($instance);
1522
- }
1523
- ```
1524
-
1525
- 3. **Webhook Architecture Implementation**
1526
-
1527
- ```
1528
- // Three-layer pattern
1529
- public function handleIPN() { $this->verifyAndProcess(); }
1530
- private function verifyAndProcess() { /* verification + routing */ }
1531
- public function handleSpecificEvent($data) { /* use service methods */ }
1532
- ```
1533
-
1534
- 4. **Service Method Usage**
1535
-
1536
- ```
1537
- // Use FluentCart services instead of manual hooks
1538
- (new StatusHelper($order))->syncOrderStatuses($transaction);
1539
- Refund::createOrRecordRefund([...], $parentTransaction);
1540
- SubscriptionService::recordManualRenewal($subscription, $transaction, $args);
1541
- ```
1542
-
1543
- 5. **Environment-Aware Configuration**
1544
-
1545
- ```
1546
- // Dynamic configuration based on mode
1547
- public function getApiKey($mode = '') {
1548
- if (!$mode) $mode = $this->getMode(); // Gets payment mode from settings
1549
- return $this->get($mode . '_api_key');
1550
- }
1551
-
1552
- // API calls should use order mode for consistency
1553
- API::createTransaction($data, $order->mode); // Use order's mode
1554
- ```
1555
-
1556
- 6. **Mode Management Best Practices**
1557
-
1558
- ```
1559
- // ✅ Correct: Store order mode with transaction
1560
- $transaction->update(['payment_mode' => $order->mode]);
1561
-
1562
- // ✅ Correct: Always explicitly pass mode to API calls
1563
- API::createTransaction($data, $order->mode);
1564
- API::refundTransaction($transactionId, $order->mode);
1565
-
1566
- // ✅ Correct: Use payment mode for settings
1567
- $apiKey = $this->settings->getApiKey($this->settings->getMode());
1568
-
1569
- // ⚠️ Works but not recommended: Relying on fallback
1570
- API::createTransaction($data); // Falls back to settings mode
1571
-
1572
- // ❌ Wrong: Don't mix up the modes
1573
- $transaction->update(['payment_mode' => $this->settings->getMode()]);
1574
- ```
1575
-
1576
- ### Critical Success Factors
1577
-
1578
- 1. **Use FluentCart's Service Layer**: Never manually fire hooks - use service methods
1579
- 2. **Implement Complete Webhook Handling**: Cover all payment lifecycle events
1580
- 3. **Understand Mode Management**: Use `$order->mode` for API calls, `$this->settings->getMode()` for configuration
1581
- 4. **Always Pass Mode Explicitly**: Don't rely on fallbacks - explicitly pass mode to all API calls
1582
- 5. **Plan for Subscriptions**: Even if not initial scope, design architecture to support them
1583
- 6. **Security First**: Implement signature verification and secure credential storage
1584
- 7. **Environment Awareness**: Support test/live modes throughout the entire implementation
1585
- 8. **Comprehensive Error Handling**: Proper HTTP responses, logging, and user feedback
1586
- 9. **Frontend Integration**: Plan for JavaScript SDK integration and UI customization
1587
- 10. **Production Considerations**: Currency support, URL management, transaction linking
1588
-
1589
- ### Architecture Decisions Framework
1590
-
1591
- - **Composition over Inheritance**: Separate settings, subscriptions, and processing classes
1592
- - **Service Layer Integration**: Use FluentCart's built-in services for all core operations
1593
- - **Event-Driven Webhooks**: Use WordPress actions for flexible webhook event handling
1594
- - **Environment Separation**: Complete isolation between test and live configurations
1595
- - **Security by Default**: Implement all security measures from the start
1596
- - **Extensible Design**: Plan for future features like subscriptions and advanced options
1597
-
1598
- This comprehensive case study demonstrates that a complete payment gateway implementation requires careful attention to **payment lifecycles**, **webhook architecture**, **service integration**, **security**, and **user experience** - all working together in a cohesive, production-ready system.
1599
-
1600
- ## Application to Your Gateway
1601
-
1602
- ### Code Patterns to Adopt
1603
-
1604
- 1. **Settings Structure**
1605
-
1606
- ```
1607
- // Environment-aware getters
1608
- public function getApiKey($mode = '') {
1609
- if (!$mode) $mode = $this->getMode();
1610
- return $this->get($mode . '_api_key');
1611
- }
1612
- ```
1613
-
1614
- 2. **Error Handling**
1615
-
1616
- ```
1617
- // Consistent error responses
1618
- if (is_wp_error($response)) {
1619
- return new \WP_Error('gateway_error', $response->get_error_message());
1620
- }
1621
- ```
1622
-
1623
- 3. **Web Hook Verification**
1624
-
1625
- ```
1626
- // Always verify webhooks
1627
- if (!$this->verifyWebhookSignature($payload, $signature)) {
1628
- http_response_code(401);
1629
- exit('Unauthorized');
1630
- }
1631
- ```
1632
-
1633
- 4. **Feature Detection**
1634
-
1635
- ```
1636
- // Declare supported features clearly
1637
- public array $supportedFeatures = ['payment', 'refund', 'subscriptions', 'webhook'];
1638
- ```
1639
-
1640
- ### Architecture Decisions
1641
-
1642
- 1. **Use composition over inheritance** for complex functionality
1643
- 2. **Separate API communication** into dedicated classes
1644
- 3. **Implement proper validation** at the settings level
1645
- 4. **Plan for localization** from the start
1646
- 5. **Design for testability** with dependency injection
1647
-
1648
- **Next:** [Get Started](./index.md) integrating custom payment gateways with FluentCart.
1
+ # Paddle Gateway Case Study
2
+
3
+ Learn from a real-world implementation by examining how the Paddle payment gateway was integrated into FluentCart Pro. This case study provides practical insights and patterns you can apply to your own gateway development.
4
+
5
+ ## Overview
6
+
7
+ The Paddle Gateway demonstrates a **complete production-ready implementation** featuring:
8
+
9
+ - **One-time payments** with full transaction lifecycle
10
+ - **Subscription payments** with recurring billing management
11
+ - **Comprehensive webhook/IPN handling** for real-time updates
12
+ - **Custom checkout experience** with UI customization
13
+ - **Multi-environment support** (test/live modes)
14
+ - **Advanced settings management** with dynamic configuration
15
+ - **Frontend integration** with JavaScript SDK
16
+ - **Error handling and logging** for production reliability
17
+ - **Security best practices** with signature verification
18
+
19
+ This case study shows how to implement **all major payment gateway features** that third-party developers typically need.
20
+
21
+ ## Architecture Analysis
22
+
23
+ ### File Structure
24
+
25
+ ```
26
+ fluent-cart-pro/app/Modules/PaymentMethods/PaddleGateway/
27
+ ├── Paddle.php # Main gateway class
28
+ ├── PaddleSettings.php # Settings management
29
+ ├── PaddleSubscriptions.php # Subscription handling
30
+ ├── PaddleHelper.php # Utility functions
31
+ ├── Processor.php # Payment processing
32
+ ├── Confirmations.php # Payment confirmations
33
+ ├── Price.php # Price management
34
+ ├── Product.php # Product handling
35
+ ├── SubscriptionsManager.php # Subscription lifecycle
36
+ ├── API/
37
+ │ └── API.php # API communication
38
+ └── Webhook/
39
+ └── IPN.php # Web hook processing
40
+ ```
41
+
42
+ ## Main Gateway Implementation
43
+
44
+ ### Core Gateway Class
45
+
46
+ ```
47
+ class Paddle extends AbstractPaymentGateway
48
+ {
49
+ private $methodSlug = 'paddle';
50
+
51
+ public array $supportedFeatures = [
52
+ 'payment',
53
+ 'refund',
54
+ 'webhook',
55
+ 'subscriptions',
56
+ 'custom_payment'
57
+ ];
58
+
59
+ public function __construct()
60
+ {
61
+ parent::__construct(
62
+ new PaddleSettings(),
63
+ new PaddleSubscriptions()
64
+ );
65
+
66
+ // Register custom checkout filter
67
+ add_filter('fluent_cart/payment_methods_with_custom_checkout_buttons', function ($methods) {
68
+ $methods[] = 'paddle';
69
+ return $methods;
70
+ });
71
+ }
72
+ }
73
+ ```
74
+
75
+ **Key Insights:**
76
+
77
+ - Uses composition pattern with separate settings and subscription classes
78
+ - Declares all supported features upfront
79
+ - Registers custom checkout behavior during construction
80
+
81
+ ### Gateway Metadata
82
+
83
+ ```
84
+ public function meta(): array
85
+ {
86
+ return [
87
+ 'title' => __('Paddle', 'fluent-cart-pro'),
88
+ 'route' => 'paddle',
89
+ 'slug' => 'paddle',
90
+ 'description' => __('Pay securely with Paddle - Complete payment solution', 'fluent-cart-pro'),
91
+ 'logo' => Vite::getAssetUrl("images/payment-methods/paddle-logo.svg"),
92
+ 'icon' => Vite::getAssetUrl("images/payment-methods/paddle-logo.svg"),
93
+ 'brand_color' => '#7c3aed',
94
+ 'status' => $this->settings->get('is_active') === 'yes',
95
+ 'upcoming' => false,
96
+ 'supported_features' => $this->supportedFeatures,
97
+ 'tag' => 'beta'
98
+ ];
99
+ }
100
+ ```
101
+
102
+ **Key Insights:**
103
+
104
+ - Uses asset management system (Vite) for icons and logos
105
+ - Includes visual branding with brand colors
106
+ - Shows development status with tags
107
+ - Status reflects actual settings configuration
108
+
109
+ ## Settings Architecture
110
+
111
+ ### Hierarchical Settings Structure
112
+
113
+ ```
114
+ class PaddleSettings extends BaseGatewaySettings
115
+ {
116
+ public $methodHandler = 'fluent_cart_payment_settings_paddle';
117
+
118
+ public static function getDefaults()
119
+ {
120
+ return [
121
+ 'is_active' => 'no',
122
+ 'provider' => 'api_keys',
123
+ 'live_api_key' => '',
124
+ 'live_client_token' => '',
125
+ 'live_webhook_secret' => '',
126
+ 'test_api_key' => '',
127
+ 'test_client_token' => '',
128
+ 'test_webhook_secret' => '',
129
+ 'payment_mode' => 'test',
130
+ 'tax_mode' => 'internal',
131
+ // UI customization options
132
+ 'paddle_checkout_theme' => 'light',
133
+ 'paddle_checkout_button_text' => 'Pay with Paddle',
134
+ 'paddle_checkout_button_color' => '',
135
+ // ... more settings
136
+ ];
137
+ }
138
+ }
139
+ ```
140
+
141
+ **Key Insights:**
142
+
143
+ - Separates live and test credentials
144
+ - Includes UI customization options
145
+ - Uses descriptive setting keys
146
+ - Provides sensible defaults
147
+
148
+ ### Environment-Aware API Keys
149
+
150
+ ```
151
+ public function getApiKey($mode = '')
152
+ {
153
+ if (!$mode) {
154
+ $mode = $this->getMode();
155
+ }
156
+ return $this->get($mode . '_api_key');
157
+ }
158
+
159
+ public function getMode()
160
+ {
161
+ return $this->get('payment_mode');
162
+ }
163
+ ```
164
+
165
+ **Key Insights:**
166
+
167
+ - Dynamic key resolution based on mode
168
+ - Centralized mode management
169
+ - Consistent naming patterns
170
+
171
+ ### Important: Payment Mode vs Order Mode
172
+
173
+ FluentCart distinguishes between two different "modes":
174
+
175
+ 1. **Payment Mode** (`payment_mode` in settings): The current test/live configuration in payment gateway settings
176
+
177
+ ```
178
+ $this->settings->getMode(); // Returns current payment mode from settings
179
+ ```
180
+
181
+ 2. **Order Mode** (`$order->mode`): The mode captured at checkout time and stored with the order
182
+
183
+ ```
184
+ $order->mode; // Returns the mode when this specific order was placed
185
+ ```
186
+
187
+ **Usage Guidelines:**
188
+
189
+ - **For API calls**: Use order mode from `$order->mode` to ensure consistency with the original transaction
190
+ - **For settings/configuration**: Use payment mode from `$this->settings->getMode()`
191
+ - **For transaction storage**: Always store `payment_mode` as `$order->mode` to preserve checkout-time context
192
+ - **For transaction URLs**: Use the stored `payment_mode` from transaction data
193
+
194
+ ## Complete Payment Processing Implementation
195
+
196
+ ### One-Time Payment Flow
197
+
198
+ ```
199
+ class Processor
200
+ {
201
+ public function handleSinglePayment(PaymentInstance $paymentInstance)
202
+ {
203
+ $order = $paymentInstance->order;
204
+ $transaction = $paymentInstance->transaction;
205
+
206
+ // Prepare payment data for external API
207
+ $paymentData = [
208
+ 'items' => $this->prepareOrderItems($order),
209
+ 'customer' => [
210
+ 'email' => $order->email,
211
+ 'name' => $order->billing_name,
212
+ 'address' => $this->prepareAddress($order)
213
+ ],
214
+ 'custom_data' => [
215
+ 'fct_transaction_hash' => $transaction->uuid,
216
+ 'fct_order_id' => $order->id
217
+ ],
218
+ 'checkout' => [
219
+ 'url' => $this->getCheckoutUrl($order),
220
+ 'success_url' => $this->getSuccessUrl($transaction),
221
+ 'cancel_url' => $this->getCancelUrl($order)
222
+ ]
223
+ ];
224
+
225
+ // Create payment at external gateway
226
+ // Always explicitly pass the order mode for consistency
227
+ $response = API::createPaddleObject('transactions', $paymentData, $order->mode);
228
+
229
+ if (is_wp_error($response)) {
230
+ return [
231
+ 'success' => false,
232
+ 'message' => $response->get_error_message()
233
+ ];
234
+ }
235
+
236
+ // Store external payment ID for webhook processing
237
+ $transaction->update([
238
+ 'vendor_charge_id' => $response['data']['id'],
239
+ 'payment_mode' => $order->mode, // Store order mode from checkout time
240
+ 'meta' => array_merge($transaction->meta ?? [], [
241
+ 'gateway_response' => $response['data']
242
+ ])
243
+ ]);
244
+
245
+ return [
246
+ 'success' => true,
247
+ 'redirect_url' => $response['data']['checkout']['url'],
248
+ 'transaction_id' => $response['data']['id']
249
+ ];
250
+ }
251
+
252
+ private function prepareOrderItems($order)
253
+ {
254
+ $items = [];
255
+ foreach ($order->items as $item) {
256
+ $items[] = [
257
+ 'price_id' => $item->meta['external_price_id'] ?? null,
258
+ 'quantity' => $item->quantity,
259
+ 'name' => $item->title,
260
+ 'description' => $item->description,
261
+ 'unit_price' => $item->unit_price * 100, // Convert to cents
262
+ 'total_price' => $item->total * 100
263
+ ];
264
+ }
265
+ return $items;
266
+ }
267
+ }
268
+ ```
269
+
270
+ **Key Insights:**
271
+
272
+ - Comprehensive order data mapping to external gateway format
273
+ - Custom data inclusion for webhook correlation
274
+ - Proper URL handling for checkout flow
275
+ - Error handling with WP_Error integration
276
+ - Transaction metadata storage for later processing
277
+
278
+ ### Subscription Payment Flow
279
+
280
+ ```
281
+ public function handleSubscriptionPayment(PaymentInstance $paymentInstance)
282
+ {
283
+ $order = $paymentInstance->order;
284
+ $subscription = $paymentInstance->subscription;
285
+ $transaction = $paymentInstance->transaction;
286
+
287
+ // Prepare subscription-specific data
288
+ $subscriptionData = [
289
+ 'items' => $this->prepareSubscriptionItems($order, $subscription),
290
+ 'customer' => $this->prepareCustomerData($order),
291
+ 'billing_cycle' => $this->mapBillingCycle($subscription),
292
+ 'collection_mode' => 'automatic',
293
+ 'proration_billing_mode' => 'prorated_immediately',
294
+ 'custom_data' => [
295
+ 'fct_subscription_hash' => $subscription->uuid,
296
+ 'fct_order_id' => $order->id,
297
+ 'fct_transaction_hash' => $transaction->uuid
298
+ ],
299
+ 'checkout' => [
300
+ 'url' => $this->getCheckoutUrl($order),
301
+ 'success_url' => $this->getSuccessUrl($transaction),
302
+ 'cancel_url' => $this->getCancelUrl($order)
303
+ ]
304
+ ];
305
+
306
+ // Add trial period if applicable
307
+ if ($subscription->trial_days > 0) {
308
+ $subscriptionData['scheduled_change'] = [
309
+ 'action' => 'resume',
310
+ 'effective_at' => gmdate('Y-m-d\TH:i:s\Z', strtotime('+' . $subscription->trial_days . ' days'))
311
+ ];
312
+ }
313
+
314
+ // Create subscription at external gateway
315
+ // Always explicitly pass the order mode for consistency
316
+ $response = API::createPaddleObject('subscriptions', $subscriptionData, $order->mode);
317
+
318
+ if (is_wp_error($response)) {
319
+ return [
320
+ 'success' => false,
321
+ 'message' => $response->get_error_message()
322
+ ];
323
+ }
324
+
325
+ // Store subscription and transaction data
326
+ $subscription->update([
327
+ 'vendor_subscription_id' => $response['data']['id'],
328
+ 'status' => 'pending',
329
+ 'meta' => array_merge($subscription->meta ?? [], [
330
+ 'gateway_response' => $response['data'],
331
+ 'billing_cycle_data' => $response['data']['billing_cycle'] ?? []
332
+ ])
333
+ ]);
334
+
335
+ $transaction->update([
336
+ 'vendor_charge_id' => $response['data']['id'],
337
+ 'subscription_id' => $subscription->id,
338
+ 'payment_mode' => $order->mode, // Store order mode from checkout time
339
+ 'meta' => array_merge($transaction->meta ?? [], [
340
+ 'subscription_data' => $response['data']
341
+ ])
342
+ ]);
343
+
344
+ return [
345
+ 'success' => true,
346
+ 'redirect_url' => $response['data']['checkout']['url'],
347
+ 'subscription_id' => $response['data']['id']
348
+ ];
349
+ }
350
+
351
+ private function prepareSubscriptionItems($order, $subscription)
352
+ {
353
+ $items = [];
354
+ foreach ($order->items as $item) {
355
+ // Map to subscription pricing structure
356
+ $items[] = [
357
+ 'price_id' => $item->meta['recurring_price_id'] ?? $item->meta['external_price_id'],
358
+ 'quantity' => $item->quantity,
359
+ 'name' => $item->title,
360
+ 'description' => $item->description,
361
+ 'billing_cycle' => [
362
+ 'interval' => $this->mapInterval($subscription->billing_interval),
363
+ 'frequency' => $subscription->billing_interval_count ?? 1
364
+ ],
365
+ 'unit_price' => $item->unit_price * 100,
366
+ 'trial_period' => $subscription->trial_days > 0 ? [
367
+ 'interval' => 'day',
368
+ 'frequency' => $subscription->trial_days
369
+ ] : null
370
+ ];
371
+ }
372
+ return $items;
373
+ }
374
+
375
+ private function mapBillingCycle($subscription)
376
+ {
377
+ $intervalMap = [
378
+ 'day' => 'day',
379
+ 'week' => 'week',
380
+ 'month' => 'month',
381
+ 'year' => 'year'
382
+ ];
383
+
384
+ return [
385
+ 'interval' => $intervalMap[$subscription->billing_interval] ?? 'month',
386
+ 'frequency' => $subscription->billing_interval_count ?? 1
387
+ ];
388
+ }
389
+ ```
390
+
391
+ **Key Insights:**
392
+
393
+ - Subscription-specific data structure with billing cycles
394
+ - Trial period handling with scheduled changes
395
+ - Separate subscription and transaction storage
396
+ - Complex item mapping for recurring pricing
397
+ - Comprehensive metadata storage for webhook processing
398
+
399
+ ## Payment Processing
400
+
401
+ ### Payment Delegation Pattern
402
+
403
+ ```
404
+ public function makePaymentFromPaymentInstance(PaymentInstance $paymentInstance)
405
+ {
406
+ $order = $paymentInstance->order;
407
+
408
+ if ($paymentInstance->subscription) {
409
+ return (new Processor())->handleSubscriptionPayment($paymentInstance);
410
+ }
411
+
412
+ return (new Processor())->handleSinglePayment($paymentInstance);
413
+ }
414
+ ```
415
+
416
+ **Key Insights:**
417
+
418
+ - Delegates to specialized processor class
419
+ - Clean separation between single and subscription payments
420
+ - Maintains single responsibility principle
421
+
422
+ ### API Communication Layer
423
+
424
+ ```
425
+ class API
426
+ {
427
+ public static function makeRequest($endpoint, $data = [], $method = 'POST', $mode = '')
428
+ {
429
+ $settings = self::getSettings();
430
+
431
+ if (!$mode) {
432
+ $mode = $settings->getMode(); // Get current payment mode from settings
433
+ }
434
+
435
+ $apiKey = $settings->getApiKey($mode);
436
+ if (empty($apiKey)) {
437
+ return new \WP_Error('paddle_api_key_missing', 'API key is missing');
438
+ }
439
+
440
+ $baseUrl = $mode === 'test'
441
+ ? 'https://sandbox-api.paddle.com'
442
+ : 'https://api.paddle.com';
443
+
444
+ $response = wp_remote_request($baseUrl . $endpoint, [
445
+ 'method' => $method,
446
+ 'headers' => [
447
+ 'Authorization' => 'Bearer ' . $apiKey,
448
+ 'Content-Type' => 'application/json',
449
+ ],
450
+ 'body' => $method !== 'GET' ? json_encode($data) : null,
451
+ 'timeout' => 30
452
+ ]);
453
+
454
+ // Error handling...
455
+ return $decodedBody;
456
+ }
457
+ }
458
+ ```
459
+
460
+ **Key Insights:**
461
+
462
+ - Environment-aware endpoint selection
463
+ - Consistent error handling with WP_Error
464
+ - Proper timeout configuration
465
+ - Bearer token authentication
466
+ - **Fallback to settings mode** when no mode parameter provided
467
+ - **Best Practice**: Always explicitly pass the mode parameter for consistency
468
+
469
+ ## Comprehensive Webhook/IPN Implementation
470
+
471
+ ### Complete Webhook Processing Architecture
472
+
473
+ The Paddle gateway implements a sophisticated three-layer webhook processing system that handles all payment and subscription events:
474
+
475
+ ```
476
+ class IPN
477
+ {
478
+ private PaddleSettings $settings;
479
+
480
+ public function __construct()
481
+ {
482
+ $this->settings = new PaddleSettings();
483
+ }
484
+
485
+ /**
486
+ * Initialize all webhook event handlers
487
+ */
488
+ public function init(): void
489
+ {
490
+ // Payment lifecycle events
491
+ add_action('fluent_cart/payments/paddle/webhook_transaction_paid', [$this, 'handleTransactionPaid'], 10, 1);
492
+ add_action('fluent_cart/payments/paddle/webhook_transaction_completed', [$this, 'handleTransactionCompleted'], 10, 1);
493
+ add_action('fluent_cart/payments/paddle/webhook_transaction_payment_failed', [$this, 'handleTransactionPaymentFailed'], 10, 1);
494
+
495
+ // Subscription lifecycle events
496
+ add_action('fluent_cart/payments/paddle/webhook_subscription_created', [$this, 'handleSubscriptionActivated'], 10, 1);
497
+ add_action('fluent_cart/payments/paddle/webhook_subscription_activated', [$this, 'handleSubscriptionActivated'], 10, 1);
498
+ add_action('fluent_cart/payments/paddle/webhook_subscription_updated', [$this, 'handleSubscriptionUpdated'], 10, 1);
499
+ add_action('fluent_cart/payments/paddle/webhook_subscription_canceled', [$this, 'handleSubscriptionCanceled'], 10, 1);
500
+ add_action('fluent_cart/payments/paddle/webhook_subscription_paused', [$this, 'handleSubscriptionUpdated'], 10, 1);
501
+ add_action('fluent_cart/payments/paddle/webhook_subscription_resumed', [$this, 'handleSubscriptionUpdated'], 10, 1);
502
+ add_action('fluent_cart/payments/paddle/webhook_subscription_past_due', [$this, 'handleSubscriptionUpdated'], 10, 1);
503
+ add_action('fluent_cart/payments/paddle/webhook_subscription_payment_received', [$this, 'handleSubscriptionPaymentReceived'], 10, 1);
504
+
505
+ // Refund/adjustment events
506
+ add_action('fluent_cart/payments/paddle/webhook_adjustment_created', [$this, 'handleAdjustmentCreated'], 10, 1);
507
+ add_action('fluent_cart/payments/paddle/webhook_adjustment_updated', [$this, 'handleAdjustmentUpdated'], 10, 1);
508
+ }
509
+
510
+ /**
511
+ * Main webhook entry point and processor
512
+ */
513
+ public function verifyAndProcess()
514
+ {
515
+ $rawPayload = file_get_contents('php://input');
516
+ $payload = json_decode($rawPayload, true);
517
+
518
+ if (!$payload) {
519
+ $this->sendResponse(400, 'Invalid JSON payload');
520
+ return;
521
+ }
522
+
523
+ // Verify webhook signature if not disabled
524
+ if (!$this->settings->isWebhookVerificationDisabled()) {
525
+ $webhookSecret = $this->settings->getWebhookSecret();
526
+ if (empty($webhookSecret)) {
527
+ error_log('Paddle Webhook Failed: Webhook secret not configured');
528
+ $this->sendResponse(500, 'Webhook secret not configured');
529
+ return;
530
+ }
531
+
532
+ $verifier = new WebhookVerifier($webhookSecret);
533
+ $paddleSignature = $_SERVER['HTTP_PADDLE_SIGNATURE'];
534
+
535
+ if (!$verifier->verify($paddleSignature, $rawPayload)) {
536
+ error_log('Paddle Webhook Failed: Invalid webhook signature');
537
+ $this->sendResponse(401, 'Invalid webhook signature');
538
+ return;
539
+ }
540
+ }
541
+
542
+ // Get order from webhook data
543
+ $order = PaddleHelper::getOrderFromWebhookData($payload);
544
+ if (!$order) {
545
+ $this->sendResponse(200, 'Order not found');
546
+ return;
547
+ }
548
+
549
+ $eventType = Arr::get($payload, 'event_type');
550
+
551
+ // Validate accepted events
552
+ $acceptedEvents = [
553
+ 'transaction.paid', 'transaction.completed', 'transaction.payment_failed',
554
+ 'adjustment.created', 'adjustment.updated',
555
+ 'subscription.created', 'subscription.activated', 'subscription.updated',
556
+ 'subscription.canceled', 'subscription.paused', 'subscription.resumed',
557
+ 'subscription.past_due'
558
+ ];
559
+
560
+ if (!in_array($eventType, $acceptedEvents)) {
561
+ $this->sendResponse(200, 'Event type not handled');
562
+ return;
563
+ }
564
+
565
+ // Log webhook for debugging
566
+ do_action('fluent_cart/paddle_webhook_received', [
567
+ 'event_type' => $eventType,
568
+ 'data' => $payload,
569
+ 'raw' => $rawPayload,
570
+ 'order' => $order
571
+ ]);
572
+
573
+ // Process specific webhook event
574
+ $eventTypeFormatted = str_replace('.', '_', $eventType);
575
+
576
+ // Handle subscription renewal detection
577
+ if ($eventTypeFormatted === 'transaction_completed' || $eventTypeFormatted === 'transaction_paid') {
578
+ $paddleTransaction = Arr::get($payload, 'data');
579
+ $vendorSubscriptionId = Arr::get($paddleTransaction, 'subscription_id');
580
+
581
+ if ($vendorSubscriptionId) {
582
+ $eventTypeFormatted = 'subscription_payment_received';
583
+ }
584
+ }
585
+
586
+ // Fire specific event handler
587
+ if (has_action('fluent_cart/payments/paddle/webhook_' . $eventTypeFormatted)) {
588
+ do_action('fluent_cart/payments/paddle/webhook_' . $eventTypeFormatted, [
589
+ 'event_type' => $eventType,
590
+ 'data' => $payload,
591
+ 'raw' => $rawPayload,
592
+ 'order' => $order
593
+ ]);
594
+
595
+ $this->sendResponse(200, 'Webhook processed successfully');
596
+ } else {
597
+ $this->sendResponse(200, 'No handler found for event type');
598
+ }
599
+ }
600
+ }
601
+ ```
602
+
603
+ `isWebhookVerificationDisabled()` is true only in test mode:
604
+
605
+ ```
606
+ public function isWebhookVerificationDisabled()
607
+ {
608
+ return $this->getMode() === 'test' && $this->get('disable_webhook_verification') === 'yes';
609
+ }
610
+ ```
611
+
612
+ In live mode the signature is always checked, whatever the setting says. If you offer a "disable verification" setting, gate it to test mode the same way.
613
+
614
+ ### Individual Event Handlers
615
+
616
+ #### Payment Completion Handler
617
+
618
+ ```
619
+ public function handleTransactionPaid($webhookData)
620
+ {
621
+ $payload = Arr::get($webhookData, 'data');
622
+ $paddleTransaction = Arr::get($payload, 'data');
623
+ $paddleTransactionId = Arr::get($paddleTransaction, 'id');
624
+
625
+ // Extract custom data for correlation
626
+ $customData = Arr::get($paddleTransaction, 'custom_data', []);
627
+ $transactionHash = Arr::get($customData, 'fct_transaction_hash');
628
+
629
+ // Find transaction by vendor ID or hash
630
+ $transactionModel = OrderTransaction::query()->where('vendor_charge_id', $paddleTransactionId)->first();
631
+
632
+ if (!$transactionModel && $transactionHash) {
633
+ $transactionModel = OrderTransaction::query()->where('uuid', $transactionHash)->first();
634
+ }
635
+
636
+ if (!$transactionModel || $transactionModel->status === Status::TRANSACTION_SUCCEEDED) {
637
+ return false;
638
+ }
639
+
640
+ // Use FluentCart's confirmation service
641
+ (new Confirmations())->confirmPaymentSuccessByCharge($transactionModel, [
642
+ 'vendor_charge_id' => $paddleTransactionId,
643
+ 'charge' => $paddleTransaction
644
+ ]);
645
+
646
+ return true;
647
+ }
648
+ ```
649
+
650
+ #### Subscription Management Handler
651
+
652
+ ```
653
+ public function handleSubscriptionActivated($webhookData)
654
+ {
655
+ $data = Arr::get($webhookData, 'data');
656
+ $paddleSubscription = Arr::get($data, 'data');
657
+ $order = Arr::get($webhookData, 'order');
658
+
659
+ $customData = Arr::get($paddleSubscription, 'custom_data', []);
660
+ $subscriptionHash = Arr::get($customData, 'fct_subscription_hash');
661
+ $vendorSubscriptionId = Arr::get($paddleSubscription, 'id');
662
+
663
+ // Find subscription by vendor ID or hash
664
+ $subscription = Subscription::query()->where('vendor_subscription_id', $vendorSubscriptionId)->first();
665
+
666
+ if (!$subscription) {
667
+ $subscription = Subscription::query()->where('uuid', $subscriptionHash)->first();
668
+ }
669
+
670
+ if (!$subscription) {
671
+ return false;
672
+ }
673
+
674
+ // Update subscription with complete data
675
+ $billCount = OrderTransaction::query()->where('subscription_id', $subscription->id)->count();
676
+ $updateData = [
677
+ 'vendor_subscription_id' => Arr::get($paddleSubscription, 'id'),
678
+ 'current_payment_method' => 'paddle',
679
+ 'status' => PaddleHelper::transformSubscriptionStatus(Arr::get($paddleSubscription, 'status')),
680
+ 'bill_count' => $billCount,
681
+ 'next_billing_date' => gmdate('Y-m-d H:i:s', strtotime(Arr::get($paddleSubscription, 'next_billed_at'))),
682
+ 'vendor_response' => json_encode($paddleSubscription)
683
+ ];
684
+
685
+ $oldStatus = $subscription->status;
686
+ $subscription->update($updateData);
687
+
688
+ // Fire subscription activated event for new subscriptions
689
+ if (in_array($subscription->status, [Status::SUBSCRIPTION_ACTIVE, Status::SUBSCRIPTION_TRIALING])
690
+ && !in_array($oldStatus, [Status::SUBSCRIPTION_ACTIVE, Status::SUBSCRIPTION_TRIALING])
691
+ && $subscription->bill_count === 0) {
692
+
693
+ (new SubscriptionActivated($subscription, $order, $order->customer))->dispatch();
694
+ }
695
+
696
+ return true;
697
+ }
698
+ ```
699
+
700
+ #### Refund Processing Handler
701
+
702
+ ```
703
+ public function handleAdjustmentCreated($webhookData)
704
+ {
705
+ $payload = Arr::get($webhookData, 'data');
706
+ $paddleAdjustment = Arr::get($payload, 'data');
707
+ $paddleAdjustmentId = Arr::get($paddleAdjustment, 'id');
708
+ $action = Arr::get($paddleAdjustment, 'action');
709
+
710
+ // Only handle refund adjustments
711
+ if ($action !== 'refund') {
712
+ return false;
713
+ }
714
+
715
+ $parentTransactionId = Arr::get($paddleAdjustment, 'transaction_id');
716
+ $parentTransaction = OrderTransaction::query()->where('vendor_charge_id', $parentTransactionId)->first();
717
+
718
+ if (!$parentTransaction) {
719
+ return false;
720
+ }
721
+
722
+ // Calculate refund amount from adjustment items
723
+ $paddleRefundAmount = 0;
724
+ foreach (Arr::get($paddleAdjustment, 'items', []) as $item) {
725
+ $paddleRefundAmount += Arr::get($item, 'totals.total', 0);
726
+ }
727
+
728
+ $status = $this->transformAdjustmentStatus(Arr::get($paddleAdjustment, 'status'));
729
+
730
+ // Use FluentCart's refund service
731
+ return \FluentCart\App\Services\Payments\Refund::createOrRecordRefund([
732
+ 'vendor_charge_id' => $paddleAdjustmentId,
733
+ 'payment_method' => 'paddle',
734
+ 'payment_mode' => $parentTransaction->payment_mode, // Use stored order mode
735
+ 'status' => $status,
736
+ 'total' => $paddleRefundAmount,
737
+ ], $parentTransaction);
738
+ }
739
+
740
+ public function handleAdjustmentUpdated($webhookData)
741
+ {
742
+ $payload = Arr::get($webhookData, 'data');
743
+ $paddleAdjustment = Arr::get($payload, 'data');
744
+ $paddleAdjustmentId = Arr::get($paddleAdjustment, 'id');
745
+
746
+ $adjustmentTransaction = OrderTransaction::query()->where('vendor_charge_id', $paddleAdjustmentId)->first();
747
+
748
+ if (!$adjustmentTransaction) {
749
+ return false;
750
+ }
751
+
752
+ // Update refund status
753
+ $adjustmentTransaction->update([
754
+ 'status' => $this->transformAdjustmentStatus(Arr::get($paddleAdjustment, 'status'))
755
+ ]);
756
+
757
+ // Fire refund event if completed
758
+ if ($adjustmentTransaction->status === Status::TRANSACTION_REFUNDED) {
759
+ (new OrderRefund($order, $adjustmentTransaction))->dispatch();
760
+ }
761
+
762
+ return true;
763
+ }
764
+ ```
765
+
766
+ #### Subscription Renewal Handler
767
+
768
+ ```
769
+ public function handleSubscriptionPaymentReceived($webhookData)
770
+ {
771
+ $order = Arr::get($webhookData, 'order');
772
+ $payload = Arr::get($webhookData, 'data');
773
+ $paddleSubscriptionId = Arr::get($payload, 'data.subscription_id');
774
+
775
+ // Find subscription
776
+ $subscriptionModel = Subscription::query()->where('vendor_subscription_id', $paddleSubscriptionId)->first();
777
+
778
+ if (!$subscriptionModel) {
779
+ $subscriptionModel = Subscription::query()->where('parent_order_id', $order->id)->first();
780
+ }
781
+
782
+ if (!$subscriptionModel) {
783
+ return false;
784
+ }
785
+
786
+ // Re-sync subscription data from remote
787
+ $subscriptionModel->reSyncFromRemote();
788
+
789
+ return true;
790
+ }
791
+ ```
792
+
793
+ **Key Insights:**
794
+
795
+ - **Complete Event Coverage**: Handles all payment, subscription, and refund events
796
+ - **Smart Event Detection**: Automatically detects subscription renewals vs new payments
797
+ - **Service Method Integration**: Uses FluentCart's service methods instead of manual hook firing
798
+ - **Robust Error Handling**: Comprehensive validation and error responses
799
+ - **Data Correlation**: Uses custom data fields to correlate webhooks with local records
800
+ - **Status Management**: Proper status transformations and updates
801
+ - **Signature Verification**: Required in live mode. It can be switched off in test mode only
802
+ - **Logging Integration**: Uses FluentCart's action system for debugging
803
+
804
+ ## Web Hook Implementation
805
+
806
+ ### Signature Verification
807
+
808
+ ```
809
+ public static function verifyWebhook($payload = null, $signature = null, $mode = '')
810
+ {
811
+ if ($payload === null) {
812
+ $payload = file_get_contents('php://input');
813
+ }
814
+
815
+ if ($signature === null) {
816
+ $signature = $_SERVER['HTTP_PADDLE_SIGNATURE'] ?? '';
817
+ }
818
+
819
+ return self::verifyWebhookSignature($payload, $signature, $mode);
820
+ }
821
+
822
+ private static function verifyWebhookSignature($payload, $signature, $mode)
823
+ {
824
+ $settings = new PaddleSettings();
825
+ $secret = $settings->getWebhookSecret($mode);
826
+
827
+ if (!$secret || !$signature) {
828
+ return false;
829
+ }
830
+
831
+ // Paddle-specific signature verification logic
832
+ // This uses Paddle's signature format and algorithm
833
+ return hash_equals($expectedSignature, $signature);
834
+ }
835
+ ```
836
+
837
+ **Key Insights:**
838
+
839
+ - Flexible parameter handling (allows testing)
840
+ - Environment-aware secret selection
841
+ - Uses hash_equals for timing attack protection
842
+ - Gateway-specific signature algorithms
843
+
844
+ ### Event Processing
845
+
846
+ ```
847
+ class IPN
848
+ {
849
+ public function init(): void
850
+ {
851
+ // Register webhook event handlers
852
+ add_action('fluent_cart/payments/paddle/webhook_transaction_paid', [$this, 'handleTransactionPaid'], 10, 1);
853
+ add_action('fluent_cart/payments/paddle/webhook_transaction_completed', [$this, 'handleTransactionCompleted'], 10, 1);
854
+ add_action('fluent_cart/payments/paddle/webhook_subscription_created', [$this, 'handleSubscriptionCreated'], 10, 1);
855
+ // ... more handlers
856
+ }
857
+
858
+ public function verifyAndProcess(): void
859
+ {
860
+ $payload = file_get_contents('php://input');
861
+ $signature = $_SERVER['HTTP_PADDLE_SIGNATURE'] ?? '';
862
+
863
+ if (!API::verifyWebhook($payload, $signature)) {
864
+ http_response_code(401);
865
+ exit('Unauthorized');
866
+ }
867
+
868
+ $data = json_decode($payload, true);
869
+ $this->processWebhookEvent($data);
870
+
871
+ http_response_code(200);
872
+ exit('OK');
873
+ }
874
+ }
875
+ ```
876
+
877
+ **Key Insights:**
878
+
879
+ - Uses WordPress action system for event handling
880
+ - Modular event processing
881
+ - Proper HTTP response codes
882
+ - Early exit after processing
883
+
884
+ ## Complete Frontend Integration
885
+
886
+ ### Multi-Script Asset Management
887
+
888
+ ```
889
+ public function getEnqueueScriptSrc($hasSubscription = 'no'): array
890
+ {
891
+ $paddleJsUrl = 'https://cdn.paddle.com/paddle/v2/paddle.js';
892
+
893
+ return [
894
+ [
895
+ 'handle' => 'fluent-cart-checkout-sdk-paddle-js',
896
+ 'src' => $paddleJsUrl,
897
+ ],
898
+ [
899
+ 'handle' => 'fluent-cart-paddle-checkout',
900
+ 'src' => Vite::getEnqueuePath('public/payment-methods/paddle-checkout.js'),
901
+ 'deps' => ['fluent-cart-checkout-sdk-paddle-js']
902
+ ]
903
+ ];
904
+ }
905
+
906
+ public function getLocalizeData(): array
907
+ {
908
+ return [
909
+ 'fct_paddle_data' => [
910
+ 'translations' => [
911
+ 'Paddle SDK is not loaded. Please ensure the Paddle script is included.' => __('Paddle SDK is not loaded...', 'fluent-cart-pro'),
912
+ 'Paddle client token is missing or invalid.' => __('Paddle client token is missing or invalid.', 'fluent-cart-pro'),
913
+ 'Pay with Paddle' => __('Pay with Paddle', 'fluent-cart-pro'),
914
+ 'Secure payment powered by Paddle' => __('Secure payment powered by Paddle', 'fluent-cart-pro'),
915
+ 'Order creation failed' => __('Order creation failed', 'fluent-cart-pro'),
916
+ 'Failed to create order' => __('Failed to create order', 'fluent-cart-pro'),
917
+ 'No Paddle price IDs found in order data. Please ensure Paddle products are properly configured.' => __('No Paddle price IDs found...', 'fluent-cart-pro'),
918
+ 'Error: Missing transaction ID' => __('Error: Missing transaction ID', 'fluent-cart-pro'),
919
+ 'Payment failed' => __('Payment failed', 'fluent-cart-pro'),
920
+ 'An error occurred. Please try again.' => __('An error occurred. Please try again.', 'fluent-cart-pro'),
921
+ ]
922
+ ]
923
+ ];
924
+ }
925
+ ```
926
+
927
+ ### Dynamic Order Information Handling
928
+
929
+ ```
930
+ public function getOrderInfo(array $data)
931
+ {
932
+ $cart = CartHelper::getCart();
933
+ $checkOutHelper = new CartCheckoutHelper(true);
934
+ $shippingChargeData = (new WebCheckoutHandler())->getShippingChargeData($cart);
935
+ $shippingCharge = Arr::get($shippingChargeData, 'charge');
936
+ $totalPrice = $checkOutHelper->getItemsAmountTotal(false) + $shippingCharge;
937
+
938
+ $items = $checkOutHelper->getItems();
939
+ $hasSubscription = $this->validateSubscriptions($items);
940
+
941
+ $clientToken = $this->settings->getClientToken();
942
+ $settings = $this->settings->get();
943
+
944
+ // Prepare frontend payment arguments
945
+ $paymentArgs = [
946
+ 'client_token' => $clientToken ?: '',
947
+ 'mode' => $this->settings->getMode(), // Current payment mode from settings
948
+ 'paddle_checkout_button_text' => Arr::get($settings, 'paddle_checkout_button_text', ''),
949
+ 'paddle_checkout_button_color' => Arr::get($settings, 'paddle_checkout_button_color', ''),
950
+ 'paddle_checkout_button_hover_color' => Arr::get($settings, 'paddle_checkout_button_hover_color', ''),
951
+ 'paddle_checkout_button_text_color' => Arr::get($settings, 'paddle_checkout_button_text_color', ''),
952
+ 'paddle_checkout_button_font_size' => Arr::get($settings, 'paddle_checkout_button_font_size', '')
953
+ ];
954
+
955
+ // Prepare payment details
956
+ $paymentDetails = [
957
+ 'mode' => 'payment',
958
+ 'theme' => Arr::get($settings, 'paddle_checkout_theme', 'light'),
959
+ 'amount' => Helper::toDecimalWithoutComma($totalPrice),
960
+ 'currency' => strtoupper(CurrencySettings::get('currency')),
961
+ 'locale' => (new StoreSettings())->get('locale', 'en'),
962
+ ];
963
+
964
+ if ($hasSubscription) {
965
+ $paymentDetails['mode'] = 'subscription';
966
+ }
967
+
968
+ $this->checkCurrencySupport();
969
+
970
+ wp_send_json([
971
+ 'status' => 'success',
972
+ 'payment_args' => $paymentArgs,
973
+ 'intent' => $paymentDetails,
974
+ 'has_subscription' => $hasSubscription,
975
+ 'message' => __('Order info retrieved!', 'fluent-cart-pro')
976
+ ], 200);
977
+ }
978
+ ```
979
+
980
+ **Key Insights:**
981
+
982
+ - **Dynamic Asset Loading**: External SDK + custom integration scripts
983
+
984
+ ### Paddle Checkout JavaScript Implementation
985
+
986
+ The frontend JavaScript implementation handles the customer checkout experience:
987
+
988
+ ```
989
+ // File: resources/public/payment-methods/paddle-checkout.js
990
+ class PaddleCheckout {
991
+ constructor(form, orderHandler, response, paymentLoader) {
992
+ this.form = form;
993
+ this.orderHandler = orderHandler;
994
+ this.data = response;
995
+ this.paymentArgs = response?.payment_args || {};
996
+ this.intent = response?.intent || {};
997
+ this.paymentLoader = paymentLoader;
998
+ this.currentOrderData = null;
999
+ this.$t = this.translate.bind(this);
1000
+ }
1001
+
1002
+ translate(string) {
1003
+ const translations = window.fct_paddle_data?.translations || {};
1004
+ return translations[string] || string;
1005
+ }
1006
+
1007
+ init() {
1008
+ const paddleButtonContainer = document.querySelector('.fluent-cart-checkout_embed_payment_container_paddle');
1009
+ if (!paddleButtonContainer) {
1010
+ console.error('Paddle container not found');
1011
+ return;
1012
+ }
1013
+
1014
+ // Clear any existing content
1015
+ paddleButtonContainer.innerHTML = '';
1016
+
1017
+ // Initialize Paddle SDK and create button
1018
+ this.initializePaddleSDK()
1019
+ .then(() => {
1020
+ this.createPaddleButton(paddleButtonContainer);
1021
+ })
1022
+ .catch((error) => {
1023
+ console.error('Paddle initialization error:', error);
1024
+ this.displayErrorMessage(paddleButtonContainer, error.message);
1025
+ });
1026
+ }
1027
+
1028
+ async initializePaddleSDK() {
1029
+ if (typeof Paddle === 'undefined') {
1030
+ throw new Error(this.$t('Paddle SDK is not loaded. Please ensure the Paddle script is included.'));
1031
+ }
1032
+
1033
+ const clientToken = this.paymentArgs?.client_token;
1034
+ const environment = this.paymentArgs?.mode === 'test' ? 'sandbox' : 'production';
1035
+
1036
+ if (!clientToken) {
1037
+ throw new Error(this.$t('Paddle client token is missing or invalid.'));
1038
+ }
1039
+
1040
+ Paddle.Environment.set(environment);
1041
+ Paddle.Initialize({
1042
+ token: clientToken.trim(),
1043
+ eventCallback: (data) => {
1044
+ this.handlePaddleEvent(data);
1045
+ }
1046
+ });
1047
+ }
1048
+
1049
+ createPaddleButton(container) {
1050
+ const paddleButton = document.createElement('button');
1051
+ paddleButton.id = 'paddle-pay-button';
1052
+ paddleButton.className = 'paddle-checkout-button';
1053
+ paddleButton.innerHTML = this.$t('Pay with Paddle');
1054
+ paddleButton.style.cssText = `
1055
+ width: 100%;
1056
+ padding: 12px 24px;
1057
+ background: #1a73e8;
1058
+ color: #fff;
1059
+ border: none;
1060
+ border-radius: 6px;
1061
+ font-weight: 500;
1062
+ cursor: pointer;
1063
+ `;
1064
+
1065
+ paddleButton.addEventListener('click', async (e) => {
1066
+ e.preventDefault();
1067
+ await this.handlePaddleButtonClick();
1068
+ });
1069
+
1070
+ container.appendChild(paddleButton);
1071
+ }
1072
+
1073
+ async handlePaddleButtonClick() {
1074
+ try {
1075
+ this.paymentLoader?.changeLoaderStatus('processing');
1076
+
1077
+ if (typeof this.orderHandler === 'function') {
1078
+ const orderData = await this.orderHandler();
1079
+ if (!orderData) {
1080
+ throw new Error(this.$t('Failed to create order'));
1081
+ }
1082
+
1083
+ // Open Paddle overlay checkout
1084
+ await this.openPaddleOverlay(orderData);
1085
+ } else {
1086
+ throw new Error(this.$t('Order handler is not properly configured'));
1087
+ }
1088
+ } catch (error) {
1089
+ this.paymentLoader?.changeLoaderStatus('Error: ' + error.message);
1090
+ this.displayErrorMessage(
1091
+ document.querySelector('.fluent-cart-checkout_embed_payment_container_paddle'),
1092
+ error.message
1093
+ );
1094
+ }
1095
+ }
1096
+
1097
+ async openPaddleOverlay(orderData) {
1098
+ this.currentOrderData = orderData;
1099
+
1100
+ const paddleData = orderData?.response || orderData;
1101
+ const items = paddleData?.paddle_price_ids?.map(item => ({
1102
+ priceId: item.price_id,
1103
+ quantity: parseInt(item.quantity) || 1
1104
+ }));
1105
+
1106
+ if (!items || items.length === 0) {
1107
+ throw new Error(this.$t('No Paddle price IDs found in order data'));
1108
+ }
1109
+
1110
+ Paddle.Checkout.open({
1111
+ settings: {
1112
+ displayMode: 'overlay',
1113
+ theme: this.intent?.theme || 'light',
1114
+ locale: this.intent?.locale || 'en'
1115
+ },
1116
+ items: items,
1117
+ customData: {
1118
+ fct_order_hash: orderData?.data?.order?.hash || '',
1119
+ fct_transaction_hash: orderData?.data?.transaction?.hash || '',
1120
+ }
1121
+ });
1122
+ }
1123
+
1124
+ handlePaddleEvent(eventData) {
1125
+ switch (eventData.name) {
1126
+ case 'checkout.completed':
1127
+ this.handlePaddlePaymentSuccess(eventData.data);
1128
+ break;
1129
+ case 'checkout.closed':
1130
+ this.handlePaddleCheckoutClosed(eventData.data);
1131
+ break;
1132
+ case 'checkout.payment.failed':
1133
+ this.handlePaddlePaymentFailed(eventData.data);
1134
+ break;
1135
+ case 'checkout.error':
1136
+ this.handlePaddleError(eventData.data);
1137
+ break;
1138
+ }
1139
+ }
1140
+
1141
+ async handlePaddlePaymentSuccess(paddleData) {
1142
+ try {
1143
+ this.paymentLoader?.changeLoaderStatus('confirming');
1144
+ const transactionId = paddleData?.transaction_id;
1145
+
1146
+ if (!transactionId) {
1147
+ this.paymentLoader?.changeLoaderStatus(this.$t('Error: Missing transaction ID'));
1148
+ return;
1149
+ }
1150
+
1151
+ const customData = paddleData.custom_data;
1152
+ const confirmResponse = await this.confirmPayment(transactionId, customData);
1153
+
1154
+ if (confirmResponse?.redirect_url) {
1155
+ this.paymentLoader?.changeLoaderStatus('redirecting');
1156
+ window.location.href = confirmResponse.redirect_url;
1157
+ }
1158
+ } catch (error) {
1159
+ this.paymentLoader?.changeLoaderStatus('Error: ' + error.message);
1160
+ }
1161
+ }
1162
+
1163
+ displayErrorMessage(container, message) {
1164
+ const errorDiv = document.createElement('div');
1165
+ errorDiv.style.color = 'red';
1166
+ errorDiv.textContent = message;
1167
+ container.appendChild(errorDiv);
1168
+ }
1169
+ }
1170
+
1171
+ // Initialize when FluentCart triggers the event
1172
+ window.addEventListener("fluent_cart_load_payments_paddle", function (e) {
1173
+ fetch(e.detail.paymentInfoUrl, {
1174
+ method: "POST",
1175
+ headers: {
1176
+ "Content-Type": "application/json",
1177
+ "X-WP-Nonce": e.detail.nonce,
1178
+ },
1179
+ credentials: 'include'
1180
+ }).then(async (response) => {
1181
+ response = await response.json();
1182
+ new PaddleCheckout(e.detail.form, e.detail.orderHandler, response, e.detail.paymentLoader).init();
1183
+ }).catch(error => {
1184
+ console.error('Failed to load Paddle payment info:', error);
1185
+ });
1186
+ });
1187
+ ```
1188
+
1189
+ - **Comprehensive Localization**: All user-facing messages translated
1190
+ - **Real-time Order Processing**: Cart data processed on-demand
1191
+ - **Subscription Detection**: Automatic mode switching based on cart contents
1192
+ - **UI Customization**: Extensive theming and styling options
1193
+ - **Currency Validation**: Pre-flight currency support checking
1194
+
1195
+ ## Advanced Production Features
1196
+
1197
+ ### Comprehensive Settings with Dynamic Instructions
1198
+
1199
+ ```
1200
+ public function fields(): array
1201
+ {
1202
+ $webhookInstructions = $this->getWebhookInstructions();
1203
+
1204
+ $testSchema = [
1205
+ 'test_api_key' => array(
1206
+ 'value' => '',
1207
+ 'label' => __('Sandbox API Key', 'fluent-cart-pro'),
1208
+ 'type' => 'password',
1209
+ 'placeholder' => __('Your sandbox API key', 'fluent-cart-pro'),
1210
+ 'help_text' => __('Get your API key from Paddle Dashboard > Developer Tools > Authentication', 'fluent-cart-pro')
1211
+ ),
1212
+ 'test_client_token' => array(
1213
+ 'value' => '',
1214
+ 'label' => __('Sandbox Client Token / Public Key', 'fluent-cart-pro'),
1215
+ 'type' => 'text',
1216
+ 'placeholder' => __('Your sandbox client token', 'fluent-cart-pro'),
1217
+ 'help_text' => __('Optional: Used for frontend checkout integration', 'fluent-cart-pro')
1218
+ ),
1219
+ 'test_webhook_secret' => array(
1220
+ 'value' => '',
1221
+ 'label' => __('Sandbox Webhook Secret', 'fluent-cart-pro'),
1222
+ 'type' => 'password',
1223
+ 'placeholder' => __('Your sandbox webhook secret', 'fluent-cart-pro'),
1224
+ 'help_text' => __('Used to verify webhook signatures', 'fluent-cart-pro')
1225
+ ),
1226
+ 'test_webhook_desc' => array(
1227
+ 'value' => $webhookInstructions,
1228
+ 'label' => __('Webhook Configuration', 'fluent-cart-pro'),
1229
+ 'type' => 'html_attr'
1230
+ ),
1231
+ ];
1232
+
1233
+ // Live schema similar structure...
1234
+
1235
+ return array(
1236
+ 'notice' => [
1237
+ 'value' => $this->renderStoreModeNotice(),
1238
+ 'label' => __('Store Mode notice', 'fluent-cart-pro'),
1239
+ 'type' => 'notice'
1240
+ ],
1241
+ 'beta_notice' => [
1242
+ 'value' => '<p class="text-gray-500">Paddle payment gateway is currently in beta. Please use with caution!</p>',
1243
+ 'label' => __('Beta Notice', 'fluent-cart-pro'),
1244
+ 'type' => 'html_attr'
1245
+ ],
1246
+ 'payment_mode' => [
1247
+ 'type' => 'tabs',
1248
+ 'schema' => [
1249
+ [
1250
+ 'type' => 'tab',
1251
+ 'label' => __('Live credentials', 'fluent-cart-pro'),
1252
+ 'value' => 'live',
1253
+ 'schema' => $liveSchema
1254
+ ],
1255
+ [
1256
+ 'type' => 'tab',
1257
+ 'label' => __('Test credentials', 'fluent-cart-pro'),
1258
+ 'value' => 'test',
1259
+ 'schema' => $testSchema
1260
+ ]
1261
+ ]
1262
+ ],
1263
+ 'paddle_checkout_theme' => [
1264
+ 'value' => 'light',
1265
+ 'label' => __('Paddle Checkout Theme', 'fluent-cart-pro'),
1266
+ 'type' => 'select',
1267
+ 'options' => [
1268
+ 'light' => ['label' => __('Light', 'fluent-cart-pro'), 'value' => 'light'],
1269
+ 'dark' => ['label' => __('Dark', 'fluent-cart-pro'), 'value' => 'dark']
1270
+ ],
1271
+ 'tooltip' => __('Theme to use for Paddle checkout modal', 'fluent-cart-pro')
1272
+ ],
1273
+ 'paddle_checkout_button_text' => [
1274
+ 'value' => __('Pay with Paddle', 'fluent-cart-pro'),
1275
+ 'label' => __('Paddle Checkout Button Text', 'fluent-cart-pro'),
1276
+ 'type' => 'text',
1277
+ 'placeholder' => __('Pay with Paddle', 'fluent-cart-pro'),
1278
+ 'tooltip' => __('Text to display on the Paddle checkout button', 'fluent-cart-pro')
1279
+ ],
1280
+ 'paddle_checkout_button_color' => [
1281
+ 'value' => '',
1282
+ 'label' => __('Paddle Checkout Button Color', 'fluent-cart-pro'),
1283
+ 'type' => 'color',
1284
+ 'tooltip' => __('Color of the Paddle checkout button', 'fluent-cart-pro')
1285
+ ],
1286
+ 'disable_webhook_verification' => [
1287
+ 'value' => 'no',
1288
+ 'label' => __('Disable Webhook Verification', 'fluent-cart-pro'),
1289
+ 'type' => 'checkbox',
1290
+ 'tooltip' => __('Only disable this for testing purposes. Keep enabled for production.', 'fluent-cart-pro')
1291
+ ]
1292
+ );
1293
+ }
1294
+
1295
+ public function getWebhookInstructions()
1296
+ {
1297
+ $webhook_url = $this->getWebhookUrl();
1298
+ $eventsHtml = $this->getEventshtml();
1299
+
1300
+ // Dynamic HTML instructions based on configuration state
1301
+ $instructionsHtml =
1302
+ '<div class="paddle-webhook-instructions" style="padding:12px 0;">'
1303
+ . '<p><strong>' . esc_html__('Webhook URL:', 'fluent-cart-pro') . '</strong> '
1304
+ . '<code class="copyable-content" data-copy="' . esc_attr($webhook_url) . '">' . esc_html($webhook_url) . '</code></p>'
1305
+ . '<p>' . esc_html__('You should configure your Paddle webhooks to get all updates of your payments remotely.', 'fluent-cart-pro') . '</p>'
1306
+ . '<p>' . esc_html__('Select the following events:', 'fluent-cart-pro') . '</p>'
1307
+ . '<p style="display:flex; align-items:center; flex-wrap:wrap; gap:8px 4px;">' . wp_kses_post($eventsHtml) . '</p>'
1308
+ . '</div>';
1309
+
1310
+ return $instructionsHtml;
1311
+ }
1312
+ ```
1313
+
1314
+ ### Multi-Environment Support with Security
1315
+
1316
+ ```
1317
+ public static function beforeSettingsUpdate($data, $oldSettings): array
1318
+ {
1319
+ $mode = Arr::get($data, 'payment_mode', 'live');
1320
+ $apiKeyField = $mode . '_api_key';
1321
+
1322
+ // Encrypt sensitive data before storage
1323
+ $data[$apiKeyField] = Helper::encryptKey($data[$apiKeyField]);
1324
+
1325
+ return $data;
1326
+ }
1327
+
1328
+ public static function validateSettings($data): array
1329
+ {
1330
+ $mode = Arr::get($data, 'payment_mode', 'live');
1331
+ $apiKey = Arr::get($data, $mode . '_api_key');
1332
+
1333
+ if (empty($apiKey)) {
1334
+ return [
1335
+ 'status' => 'failed',
1336
+ 'message' => __('API key is required.', 'fluent-cart-pro')
1337
+ ];
1338
+ }
1339
+
1340
+ // Could add live API connectivity test here
1341
+ // $testResponse = API::testConnection($apiKey, $mode);
1342
+
1343
+ return [
1344
+ 'status' => 'success',
1345
+ 'message' => __('Paddle gateway credentials verified successfully!', 'fluent-cart-pro')
1346
+ ];
1347
+ }
1348
+ ```
1349
+
1350
+ ### Currency and Transaction URL Management
1351
+
1352
+ ```
1353
+ public function isCurrencySupported(): bool
1354
+ {
1355
+ $supportedCurrencies = [
1356
+ 'USD', 'EUR', 'GBP', 'JPY', 'AUD', 'CAD', 'CHF', 'HKD', 'SGD', 'SEK',
1357
+ 'ARS', 'BRL', 'CNY', 'COP', 'CZK', 'DKK', 'HUF', 'ILS', 'INR', 'KRW',
1358
+ 'MXN', 'NOK', 'NZD', 'PLN', 'RUB', 'THB', 'TRY', 'TWD', 'UAH', 'VND', 'ZAR'
1359
+ ];
1360
+
1361
+ return in_array(strtoupper(CurrencySettings::get('currency')), $supportedCurrencies);
1362
+ }
1363
+
1364
+ public function getTransactionUrl($url, $data)
1365
+ {
1366
+ if (Arr::get($data, 'transaction_type') === 'refund') {
1367
+ $parentTransaction = OrderTransaction::query()->where('id', Arr::get($data, 'transaction.meta.parent_id'))->first();
1368
+ $data['vendor_charge_id'] = $parentTransaction->vendor_charge_id;
1369
+ }
1370
+
1371
+ // Use payment_mode from transaction data (stored order mode at checkout time)
1372
+ if (Arr::get($data, 'payment_mode') === 'test') {
1373
+ return 'https://sandbox-vendors.paddle.com/transactions-v2/' . Arr::get($data, 'vendor_charge_id');
1374
+ }
1375
+
1376
+ return 'https://vendors.paddle.com/transactions-v2/' . Arr::get($data, 'vendor_charge_id');
1377
+ }
1378
+
1379
+ public function getSubscriptionUrl($url, $data)
1380
+ {
1381
+ // Use payment_mode from subscription data (stored order mode at checkout time)
1382
+ if (Arr::get($data, 'payment_mode') === 'test') {
1383
+ return 'https://sandbox-vendors.paddle.com/subscriptions-v2/' . Arr::get($data, 'vendor_subscription_id');
1384
+ }
1385
+
1386
+ return 'https://vendors.paddle.com/subscriptions-v2/' . Arr::get($data, 'vendor_subscription_id');
1387
+ }
1388
+ ```
1389
+
1390
+ ### Success and Cancel URL Handling
1391
+
1392
+ ```
1393
+ public function getSuccessUrl($transaction, $args = [])
1394
+ {
1395
+ $paymentHelper = new PaymentHelper($this->getMeta('route'));
1396
+ return $paymentHelper->successUrl($transaction->uuid, $args);
1397
+ }
1398
+
1399
+ public static function getCancelUrl(): string
1400
+ {
1401
+ $checkoutPage = (new StoreSettings())->getCheckoutPage();
1402
+ $cartHash = $_GET['fct_cart_hash'] ?? '';
1403
+
1404
+ if ($cartHash) {
1405
+ return add_query_arg([
1406
+ 'fct_cart_hash' => $cartHash
1407
+ ], $checkoutPage);
1408
+ }
1409
+
1410
+ return $checkoutPage;
1411
+ }
1412
+ ```
1413
+
1414
+ **Key Insights:**
1415
+
1416
+ - **Dynamic Configuration**: Settings UI changes based on configuration state
1417
+ - **Security-First Approach**: API key encryption and secure storage
1418
+ - **Environment Awareness**: All URLs and endpoints environment-specific
1419
+ - **Comprehensive Validation**: Settings validation with optional API testing
1420
+ - **User Experience**: Helpful instructions and copyable content
1421
+ - **Production-Ready**: Extensive customization options for branding
1422
+ - **URL Management**: Proper success/cancel URL handling with cart state preservation
1423
+
1424
+ ## Registration Pattern
1425
+
1426
+ ```
1427
+ public static function register()
1428
+ {
1429
+ fluent_cart_api()->registerCustomPaymentMethod('paddle', new self());
1430
+ }
1431
+ ```
1432
+
1433
+ **Key Insights:**
1434
+
1435
+ - Simple static registration method
1436
+ - Self-instantiation pattern
1437
+ - Called from bootstrap file
1438
+
1439
+ ## Comprehensive Lessons Learned
1440
+
1441
+ ### 1. **Complete Payment Lifecycle Management**
1442
+
1443
+ - **One-time Payments**: Full transaction flow from creation to confirmation
1444
+ - **Subscription Payments**: Complex billing cycles, trials, and renewal handling
1445
+ - **Refund Processing**: Comprehensive adjustment and refund management
1446
+ - **Status Synchronization**: Real-time status updates via webhooks
1447
+
1448
+ ### 2. **Three-Layer Webhook Architecture**
1449
+
1450
+ - **Entry Point**: Single `handleIPN()` method for all webhook traffic
1451
+ - **Central Processor**: `verifyAndProcess()` with signature verification and routing
1452
+ - **Event Handlers**: Specific handlers for each event type using FluentCart services
1453
+ - **Error Handling**: Comprehensive HTTP response codes and logging
1454
+
1455
+ ### 3. **Service Method Integration**
1456
+
1457
+ - **StatusHelper**: Automatic order status sync and hook firing
1458
+ - **Refund Service**: Complete refund transaction management
1459
+ - **SubscriptionService**: Subscription lifecycle and renewal processing
1460
+ - **Confirmation Service**: Payment confirmation with complex data handling
1461
+
1462
+ ### 4. **Production-Ready Security**
1463
+
1464
+ - **Signature Verification**: Optional but recommended webhook signature validation
1465
+ - **API Key Encryption**: Secure storage of sensitive credentials
1466
+ - **Environment Separation**: Complete test/live mode isolation
1467
+ - **Input Validation**: Comprehensive data validation and sanitization
1468
+
1469
+ ### 5. **Advanced Settings Architecture**
1470
+
1471
+ - **Dynamic Configuration**: UI that changes based on current settings
1472
+ - **Tabbed Interface**: Clean separation of test/live credentials
1473
+ - **Visual Customization**: Extensive theming and branding options
1474
+ - **Helpful Instructions**: Dynamic webhook setup guidance
1475
+
1476
+ ### 6. **Frontend Integration Excellence**
1477
+
1478
+ - **Multi-Script Loading**: External SDK + custom integration scripts
1479
+ - **Comprehensive Localization**: All user-facing messages translated
1480
+ - **Real-time Processing**: Dynamic order and cart processing
1481
+ - **UI Customization**: Extensive checkout appearance options
1482
+
1483
+ ### 7. **Subscription Management Complexity**
1484
+
1485
+ - **Billing Cycle Mapping**: Complex interval and frequency handling
1486
+ - **Trial Period Support**: Scheduled activation after trial periods
1487
+ - **Renewal Detection**: Smart detection of subscription vs one-time payments
1488
+ - **Status Transformation**: Gateway-specific to FluentCart status mapping
1489
+
1490
+ ### 8. **Data Architecture Patterns**
1491
+
1492
+ - **Custom Data Fields**: Webhook correlation via custom metadata
1493
+ - **Comprehensive Storage**: Full gateway response storage for debugging
1494
+ - **Status Mapping**: Bidirectional status transformation
1495
+ - **Transaction Relationships**: Parent-child relationships for refunds
1496
+
1497
+ ## Application to Your Gateway Development
1498
+
1499
+ ### Essential Implementation Patterns
1500
+
1501
+ 1. **Gateway Class Structure**
1502
+
1503
+ ```
1504
+ // Complete feature declaration
1505
+ public array $supportedFeatures = ['payment', 'refund', 'webhook', 'subscriptions'];
1506
+
1507
+ // Composition over inheritance
1508
+ public function __construct() {
1509
+ parent::__construct(new YourSettings(), new YourSubscriptions());
1510
+ }
1511
+ ```
1512
+
1513
+ 2. **Payment Processing Delegation**
1514
+
1515
+ ```
1516
+ // Clean separation of concerns
1517
+ public function makePaymentFromPaymentInstance(PaymentInstance $instance) {
1518
+ if ($instance->subscription) {
1519
+ return (new Processor())->handleSubscriptionPayment($instance);
1520
+ }
1521
+ return (new Processor())->handleSinglePayment($instance);
1522
+ }
1523
+ ```
1524
+
1525
+ 3. **Webhook Architecture Implementation**
1526
+
1527
+ ```
1528
+ // Three-layer pattern
1529
+ public function handleIPN() { $this->verifyAndProcess(); }
1530
+ private function verifyAndProcess() { /* verification + routing */ }
1531
+ public function handleSpecificEvent($data) { /* use service methods */ }
1532
+ ```
1533
+
1534
+ 4. **Service Method Usage**
1535
+
1536
+ ```
1537
+ // Use FluentCart services instead of manual hooks
1538
+ (new StatusHelper($order))->syncOrderStatuses($transaction);
1539
+ Refund::createOrRecordRefund([...], $parentTransaction);
1540
+ SubscriptionService::recordManualRenewal($subscription, $transaction, $args);
1541
+ ```
1542
+
1543
+ 5. **Environment-Aware Configuration**
1544
+
1545
+ ```
1546
+ // Dynamic configuration based on mode
1547
+ public function getApiKey($mode = '') {
1548
+ if (!$mode) $mode = $this->getMode(); // Gets payment mode from settings
1549
+ return $this->get($mode . '_api_key');
1550
+ }
1551
+
1552
+ // API calls should use order mode for consistency
1553
+ API::createTransaction($data, $order->mode); // Use order's mode
1554
+ ```
1555
+
1556
+ 6. **Mode Management Best Practices**
1557
+
1558
+ ```
1559
+ // ✅ Correct: Store order mode with transaction
1560
+ $transaction->update(['payment_mode' => $order->mode]);
1561
+
1562
+ // ✅ Correct: Always explicitly pass mode to API calls
1563
+ API::createTransaction($data, $order->mode);
1564
+ API::refundTransaction($transactionId, $order->mode);
1565
+
1566
+ // ✅ Correct: Use payment mode for settings
1567
+ $apiKey = $this->settings->getApiKey($this->settings->getMode());
1568
+
1569
+ // ⚠️ Works but not recommended: Relying on fallback
1570
+ API::createTransaction($data); // Falls back to settings mode
1571
+
1572
+ // ❌ Wrong: Don't mix up the modes
1573
+ $transaction->update(['payment_mode' => $this->settings->getMode()]);
1574
+ ```
1575
+
1576
+ ### Critical Success Factors
1577
+
1578
+ 1. **Use FluentCart's Service Layer**: Never manually fire hooks - use service methods
1579
+ 2. **Implement Complete Webhook Handling**: Cover all payment lifecycle events
1580
+ 3. **Understand Mode Management**: Use `$order->mode` for API calls, `$this->settings->getMode()` for configuration
1581
+ 4. **Always Pass Mode Explicitly**: Don't rely on fallbacks - explicitly pass mode to all API calls
1582
+ 5. **Plan for Subscriptions**: Even if not initial scope, design architecture to support them
1583
+ 6. **Security First**: Implement signature verification and secure credential storage
1584
+ 7. **Environment Awareness**: Support test/live modes throughout the entire implementation
1585
+ 8. **Comprehensive Error Handling**: Proper HTTP responses, logging, and user feedback
1586
+ 9. **Frontend Integration**: Plan for JavaScript SDK integration and UI customization
1587
+ 10. **Production Considerations**: Currency support, URL management, transaction linking
1588
+
1589
+ ### Architecture Decisions Framework
1590
+
1591
+ - **Composition over Inheritance**: Separate settings, subscriptions, and processing classes
1592
+ - **Service Layer Integration**: Use FluentCart's built-in services for all core operations
1593
+ - **Event-Driven Webhooks**: Use WordPress actions for flexible webhook event handling
1594
+ - **Environment Separation**: Complete isolation between test and live configurations
1595
+ - **Security by Default**: Implement all security measures from the start
1596
+ - **Extensible Design**: Plan for future features like subscriptions and advanced options
1597
+
1598
+ This comprehensive case study demonstrates that a complete payment gateway implementation requires careful attention to **payment lifecycles**, **webhook architecture**, **service integration**, **security**, and **user experience** - all working together in a cohesive, production-ready system.
1599
+
1600
+ ## Application to Your Gateway
1601
+
1602
+ ### Code Patterns to Adopt
1603
+
1604
+ 1. **Settings Structure**
1605
+
1606
+ ```
1607
+ // Environment-aware getters
1608
+ public function getApiKey($mode = '') {
1609
+ if (!$mode) $mode = $this->getMode();
1610
+ return $this->get($mode . '_api_key');
1611
+ }
1612
+ ```
1613
+
1614
+ 2. **Error Handling**
1615
+
1616
+ ```
1617
+ // Consistent error responses
1618
+ if (is_wp_error($response)) {
1619
+ return new \WP_Error('gateway_error', $response->get_error_message());
1620
+ }
1621
+ ```
1622
+
1623
+ 3. **Web Hook Verification**
1624
+
1625
+ ```
1626
+ // Always verify webhooks
1627
+ if (!$this->verifyWebhookSignature($payload, $signature)) {
1628
+ http_response_code(401);
1629
+ exit('Unauthorized');
1630
+ }
1631
+ ```
1632
+
1633
+ 4. **Feature Detection**
1634
+
1635
+ ```
1636
+ // Declare supported features clearly
1637
+ public array $supportedFeatures = ['payment', 'refund', 'subscriptions', 'webhook'];
1638
+ ```
1639
+
1640
+ ### Architecture Decisions
1641
+
1642
+ 1. **Use composition over inheritance** for complex functionality
1643
+ 2. **Separate API communication** into dedicated classes
1644
+ 3. **Implement proper validation** at the settings level
1645
+ 4. **Plan for localization** from the start
1646
+ 5. **Design for testability** with dependency injection
1647
+
1648
+ **Next:** [Get Started](./index.md) integrating custom payment gateways with FluentCart.