Documentation You are here: start » v » 2.0 » pre_payment_webhook

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
v:2.0:pre_payment_webhook [2019/04/25 08:33] – [Example Endpoint] foxybrettv:2.0:pre_payment_webhook [2021/05/26 10:30] (current) – [Headers] adam
Line 9: Line 9:
   * Integrations with custom validation or fraud-check services (such as [[https://wiki.foxycart.com/integration/fraudlabspro|FraudLabsPro]]).   * Integrations with custom validation or fraud-check services (such as [[https://wiki.foxycart.com/integration/fraudlabspro|FraudLabsPro]]).
  
-==== Enabling the pre-payment Hook ====+===== Enabling the pre-payment Hook =====
  
 To enable the pre-payment hook, head to the "payment" setting page in your store's FoxyCart administration, ensuring that you've selected the [[.:payment_sets|payment set]] you're wanting to enable the hook for. Within the "Anti-Fraud Integrations" section, check the checkbox to "enable custom pre-payment hook" and complete the settings below. To enable the pre-payment hook, head to the "payment" setting page in your store's FoxyCart administration, ensuring that you've selected the [[.:payment_sets|payment set]] you're wanting to enable the hook for. Within the "Anti-Fraud Integrations" section, check the checkbox to "enable custom pre-payment hook" and complete the settings below.
Line 19: Line 19:
  
  
-==== Handling the request ====+===== Handling the request ===== 
 + 
 +==== Headers ==== 
 + 
 +Any requests made to your webhook's endpoint will also contain several special headers: 
 + 
 +^ Header ^ Description ^ 
 +| ''Foxy-Webhook-Event'' | Name of the event that triggered this payload. Currently ''validation/payment'' or ''validation/3ds''. | 
 +| ''Foxy-Store-ID'' | The ID of the store that this webhook was triggered for. | 
 +| ''Foxy-Store-Domain'' | The current Foxy store domain that this webhook was triggered for. | 
 + 
 +==== Events ==== 
 + 
 +The prepayment webhook is primarily triggered right before the payment is sent to your gateway for handling. For this trigger, the ''Foxy-Webhook-Event'' header will be ''validation/payment''. 
 + 
 +For a couple gateways though, we do also trigger the prepayment webhook prior to the 3DSv2 challenge occurring, which has an event header of ''validation/3ds''. These triggers exist for specific purposes, and are documented on the respective gateway wiki pages: 
 + 
 +  * [[gateways:opayo#special_considerationprepayment_webhook|Opayo]] 
 +  * [[gateways:barclaycard#special_considerationprepayment_webhook|Barclaycard]] 
 +==== Example Payload ====
  
 When the customer attempts to complete their purchase, after the Google reCAPTCHA is validated (if active), a POST request is sent off to your custom post-checkout hook endpoint with a JSON payload representing the current cart. It follows the same structure as our [[https://api.foxycart.com|Hypermedia API]], as the majority of the data comes from there. When the customer attempts to complete their purchase, after the Google reCAPTCHA is validated (if active), a POST request is sent off to your custom post-checkout hook endpoint with a JSON payload representing the current cart. It follows the same structure as our [[https://api.foxycart.com|Hypermedia API]], as the majority of the data comes from there.
Line 270: Line 289:
 </code> </code>
  
-=== Notes ===+==== Notes ====
  
   * The payload includes several ''_links'' arrays. These contain helpful URI's that could be used through the Hypermedia API if you're also making use of that. If not, these can be safely ignored.   * The payload includes several ''_links'' arrays. These contain helpful URI's that could be used through the Hypermedia API if you're also making use of that. If not, these can be safely ignored.
Line 281: Line 300:
  
  
-==== Sending a response ====+===== Sending a response =====
  
 In response, FoxyCart expects a JSON payload in the following format to be output on the page (prettified for display purposes): In response, FoxyCart expects a JSON payload in the following format to be output on the page (prettified for display purposes):
  
-=== Approve ===+==== Approve ====
  
 <code javascript> <code javascript>
Line 294: Line 313:
 </code> </code>
  
-=== Reject ===+Note that if you're using [[/gateways:square_platform|the Square Platform payment splitting integration]], an additional parameter of ''payment_logic'' can be passed through as well. 
 + 
 +==== Reject ====
  
 <code javascript> <code javascript>
Line 309: Line 330:
 </WRAP> </WRAP>
  
-==== Example Endpoint ====+===== Example Endpoint =====
  
 The following is an example PHP endpoint that could be used to handle the pre-payment hook. Note that this is for illustrative purposes only. It'll work as is, but blocking based on IP or email isn't necessarily a recommended approach: The following is an example PHP endpoint that could be used to handle the pre-payment hook. Note that this is for illustrative purposes only. It'll work as is, but blocking based on IP or email isn't necessarily a recommended approach:
Line 373: Line 394:
 </code> </code>
  
-==== Debugging Errors ====+===== Debugging Errors =====
  
 If your pre-payment hook endpoint fails to return a response, or returns a non-JSON response, a error will be added to your store's error log in the administration.  If your pre-payment hook endpoint fails to return a response, or returns a non-JSON response, a error will be added to your store's error log in the administration. 

Page Tools

Site Tools