dw.apps.checkout.hooks.PaymentAppHooks
These hooks provide integration points for payment Commerce Apps installed via the Commerce App framework. They are called by the platform during SCAPI basket and order operations when a payment Commerce App is registered for the relevant payment method.
IMPORTANT: These hooks should only be implemented and registered by Commerce Apps (applications installed via the Commerce App framework with a CAP file). They are not intended for custom merchant cartridges.
Hook Registration
A function must be defined inside a JavaScript source and must be exported. The script with the exported hook function must be located inside a site cartridge. Inside the site cartridge apackage.json file with a 'hooks' entry must exist:
"hooks": "./hooks.json"
The hooks entry links to a JSON file, relative to the package.json file:
"hooks": [
{"name": "sfcc.app.payment.getClaimedPaymentMethods", "script": "./paymentHooks.js"},
{"name": "sfcc.app.payment.afterCreateBasketPaymentInstrument", "script": "./paymentHooks.js"},
{"name": "sfcc.app.payment.afterUpdateBasketPaymentInstrument", "script": "./paymentHooks.js"},
{"name": "sfcc.app.payment.afterCreateOrderPaymentInstrument", "script": "./paymentHooks.js"},
{"name": "sfcc.app.payment.afterUpdateOrderPaymentInstrument", "script": "./paymentHooks.js"},
{"name": "sfcc.app.payment.onAttemptOrderTransition", "script": "./paymentHooks.js"},
{"name": "sfcc.app.payment.reversePayment", "script": "./paymentHooks.js"},
{"name": "sfcc.app.payment.authorizePayment", "script": "./paymentHooks.js"},
{"name": "sfcc.app.payment.cancelAuthorization", "script": "./paymentHooks.js"},
{"name": "sfcc.app.payment.capturePayment", "script": "./paymentHooks.js"},
{"name": "sfcc.app.payment.refundCapture", "script": "./paymentHooks.js"}
]
A hook entry has a name and a script property:
- The
namecontains the extension point name (the hook name). - The
scriptcontains the script path relative to the hooks file, with the exported hook function.
Function Naming Convention: The exported JavaScript function name must match the last segment of the
extension point name: afterCreateBasketPaymentInstrument.
Transaction Semantics
The effect of returningStatus.ERROR or throwing an uncaught exception differs
for basket hooks and order hooks:
- Basket payment instrument hooks (
afterCreateBasketPaymentInstrument,afterUpdateBasketPaymentInstrument): these execute within the platform's transaction boundary for the current basket operation. No order has been created yet, soStatus.ERRORor an uncaught exception rolls back that operation; the basket payment instrument is not created or updated. - Order payment instrument hooks (
afterCreateOrderPaymentInstrument,afterUpdateOrderPaymentInstrument,onAttemptOrderTransition): the order already exists and its creation has already committed, so there is no operation to roll back. Instead,Status.ERRORor an uncaught exception causes the platform to fail the order and reopen the basket, compensating by reversing any payments and refunding any gift cards already captured for the order.
Hook Precedence
- When a Commerce App claims the payment method for a payment instrument, these hooks take precedence over
dw.order.payment.*hooks. - If no Commerce App claims the payment method, the platform falls back to the standard behavior.
["CREDIT_CARD", "BANK_TRANSFER"]). When a payment
instrument has a payment method that appears in the returned array, its payment lifecycle will be handled by the
payment Commerce App.Called to authorize payment for a payment instrument.
Called to void or cancel the authorization for a payment instrument.
Called to capture a previous payment authorization.
Called to refund a previously captured payment.
Status.OK to proceed or Status.ERROR to roll back
Status.OK to proceed or Status.ERROR to fail the order and reopen the basket
Status.OK to proceed or Status.ERROR to roll back
Status.OK to proceed or Status.ERROR to fail the order and reopen the basket
Called to authorize payment for a payment instrument.
Note: The platform does not call this hook directly, so there is no guarantee the given payment instrument is claimed by this payment Commerce App. Call this hook in your custom hook implementations to perform authorization. Implement this hook to support payment authorization outside of the defined platform extension points.
Status.OK on successful authorization or Status.ERROR if authorization fails
Called to void or cancel the authorization for a payment instrument.
Note: The platform does not call this hook directly, so there is no guarantee the given payment instrument is claimed by this payment Commerce App. Call this hook in your custom hook implementations to perform authorization reversal. Implement this hook to support authorization reversal outside of the defined platform extension points.
Status.OK on successful reversal or Status.ERROR if reversal fails
Called to capture a previous payment authorization.
Note: The platform does not call this hook directly, so there is no guarantee the given payment instrument is claimed by this payment Commerce App. Call this hook in your custom hook implementations to capture payment. Implement this hook to support capture outside of the defined platform extension points.
Status.OK on successful capture or Status.ERROR if capture fails
["CREDIT_CARD", "BANK_TRANSFER"]). When a payment
instrument has a payment method that appears in the returned array, its payment lifecycle will be handled by the
payment Commerce App.
When the app authorizes the payment synchronously within this hook, set the payment transaction status on
paymentInstrument to PaymentTransaction.STATUS_AUTHORIZED or
PaymentTransaction.STATUS_CAPTURED before returning Status.OK. When the app initiates
asynchronous payment authorization or capture, set the payment transaction status to
PaymentTransaction.STATUS_PENDING.
Status.OK to proceed or Status.ERROR to fail the order and reopen the basket
Called to refund a previously captured payment.
Note: The platform does not call this hook directly, so there is no guarantee the given payment instrument is claimed by this payment Commerce App. Call this hook in your custom hook implementations to refund payment. Implement this hook to support refund outside of the defined platform extension points.
Status.OK on successful refund or Status.ERROR if refund fails