Changes for page Frontend API

Last modified by Asbjørn Ulsberg on 2018/07/05 12:48
From empty
To version 91.1
edited by Helge Dahl
on 2017/12/13 12:41
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Frontend API
Parent
... ... @@ -1,0 +1,1 @@
1 +Panels.PayExCheckoutNavigation
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +xwiki:XWiki.hde
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,222 @@
1 +(% id="H" %)
2 +**Table of contents**
3 +
4 +{{toc start="2"/}}
5 +
6 +
7 +== Add JavaScript reference ==
8 +
9 +Before implementing PayEx Checkout on your web site, you need to add a reference to the PayEx Checkout script to your page:
10 +
11 +{{code language="html"}}
12 +<script src="https://checkout.payex.com/js/payex-checkout.min.js"></script>
13 +{{/code}}
14 +
15 +Please note that the above URL points to **PayEx Checkout's production environment**. If you want to integrate with PayEx' test environment, [[please refer to the FAQ for the correct URLs>>doc:ecommerce.PayEx Checkout.FAQ.WebHome]].
16 +
17 +== Basic usage ==
18 +
19 +The simplest way to implement PayEx Checkout in your frontend is with the {{code}}data-payex-checkout{{/code}} attribute.
20 +
21 +Choose the button you want to open the PayEx Checkout modal and add the attribute {{code}}data-payex-checkout{{/code}} with the value returned {{code}}paymentSessionUrl{{/code}} from the [[initial POST>>ecommerce.PayEx Checkout.Implementation.WebHome||anchor="HStep1:InitialPOST2CBackend"]]. Then add the {{code}}disable{{/code}} attribute - the PayEx Checkout script will enable it when it is properly loaded. The button should be wrapped inside a form that posts to your server.
22 +
23 +The PayEx Checkout script will submit the {{code}}<form>{{/code}} when the PayEx Checkout user flow is complete.
24 +
25 +HTML
26 +
27 +{{code language="html"}}
28 +<form action="<url_to_your_server>" method="post">
29 + <!-- ... -->
30 + <button data-payex-checkout="<payment_session_url>" disabled>Pay</button>
31 +</form>
32 +{{/code}}
33 +
34 +== Basic usage with options ==
35 +
36 +(% id="H" %)
37 +The PayEx Checkout script can be configured with options to get callbacks on certain events in the checkout user flow.
38 +
39 +Availialbe callbacks:
40 +
41 +* {{code}}onOpen{{/code}} // - Callback called when the PayEx Checkout modal is opened.//
42 +* {{code}}onClose{{/code}} // - Callback called when the PayEx Checkout modal is closed.//
43 +* {{code}}onError{{/code}} //- Callback called when PayEx Checkout is unable to open or complete a session.//
44 +* {{code}}onComplete{{/code}} // - Callback called when PayEx Checkout user flow is completed.//
45 +
46 +HTML
47 +
48 +{{code language="html"}}
49 +<form action="<url_to_your_server>">
50 + <!-- ... -->
51 + <button data-payex-checkout="<payment_session_url>" disabled>Pay</button>
52 +</form>
53 +{{/code}}
54 +
55 +JavaScript
56 +
57 +{{code language="JavaScript"}}
58 +payex.checkout("<payment_session_url>", {
59 + onClose: function(){
60 + console.log("The modal was closed");
61 + }
62 +});
63 +
64 +{{/code}}
65 +
66 +== Flexibility usage ==
67 +
68 +If you need more flexibility in your frontend, you can open the PayEx Checkout modal and post to your server programmatically.
69 +
70 +If you have added it, start by removing the {{code}}data-payex-checkout{{/code}} attribute to prevent the PayEx Checkout script to open and post automatically.
71 +
72 +You can open the checkout modal on demand with the {{code}}"open"{{/code}} argument and use the {{code}}onComplete{{/code}} callback to post to your server when the PayEx Checkout user flow is completed to continue with the [[Get Payment Status>>ecommerce.PayEx Checkout.Implementation.WebHome||anchor="HStep4:GetPaymentStatus2CBackend"]] step.
73 +
74 +Please note that Checkout must be opened with a [[trusted context>>https://developer.mozilla.org/en-US/docs/Web/API/Event/isTrusted]] in order to prevent pop-up blockers. The code has a trusted context when it runs as result of an user action. Code running within async callbacks such as ajax and timeout loses trusted context, so make sure you have acquired a payment session url before the user click on your buy button.
75 +
76 +
77 +JavaScript
78 +
79 +{{code language="JavaScript"}}
80 +// Remember to remove the data-payex-checkout attribute if you implemented it.
81 +
82 +payex.checkout("<payment_session_url>", {
83 + onComplete: function() {
84 + // Post or send a ajax request to your server to get the payment status step
85 + }
86 +}, "open");
87 +{{/code}}
88 +
89 +== Reference ==
90 +
91 +=== payex.checkout(paymentSessionUrl, options) ===
92 +
93 +Sets options for a payment session.
94 +
95 +==== Arguments ====
96 +
97 +|(% style="text-align:right; width:126px" %)**Param**|(% style="width:1764px" %)**Details**
98 +|(% style="text-align:right; width:126px" %)(((
99 +{{code}}paymentSessionUrl{{/code}}
100 +(% style="color:LightGrey" %)string
101 +)))|(% style="width:1764px" %)A string of the URL to the Payment Session. This URL should be retrieved before page is rendered in the browser by completing the [[intial server-to-server POST request>>ecommerce.PayEx Checkout.Implementation.WebHome||anchor="HStep1:InitialPOST2CBackend"]].
102 +|(% style="text-align:right; width:126px" %)(((
103 +{{code}}options{{/code}}
104 +(% style="color:LightGrey" %)object(%%)
105 +
106 +)))|(% style="width:1764px" %)(((
107 +Set options for the payment session.
108 +
109 +* {{code}}onClose{{/code}} // function - Callback called when the PayEx Checkout modal is closed.//
110 +* {{code}}onOpen{{/code}} // function - Callback called when the PayEx Checkout modal is opened.//
111 +* {{code}}onError{{/code}} // function - Callback called when PayEx Checkout is unable to open or complete a session.//
112 +* {{code}}onComplete{{/code}} // function - Callback called when PayEx Checkout user flow is completed.//
113 +)))
114 +
115 +==== Example ====
116 +
117 +{{code language="JavaScript"}}
118 +payex.checkout("<payment_session_url>", {
119 + onClose: function(){
120 + console.log("The modal was closed");
121 + }
122 +});
123 +{{/code}}
124 +
125 +=== payex.checkout(paymentSessionUrl, command) ===
126 +
127 +Executes a PayEx Checkout action, such as opening the PayEx Checkout user flow.
128 +
129 +==== Arguments ====
130 +
131 +|(% style="text-align:right; width:126px" %)**Param**|(% style="width:1764px" %)**Details**
132 +|(% style="text-align:right; width:126px" %)(((
133 +{{code}}paymentSessionUrl{{/code}}
134 +(% style="color:LightGrey" %)string
135 +)))|(% style="width:1764px" %)A string of the URL to the Payment Session. This URL should be retrieved before page is rendered in the browser by completing the [[intial server-to-server POST request>>ecommerce.PayEx Checkout.Implementation.WebHome||anchor="HStep1:InitialPOST2CBackend"]].
136 +|(% style="text-align:right; width:126px" %)(((
137 +{{code}}command{{/code}}
138 +(% style="color:LightGrey" %)string(%%)
139 +
140 +)))|(% style="width:1764px" %)(((
141 +The command to be excuted
142 +
143 +* {{code}}"open"{{/code}} // //- //Opens the PayEx Checkout user flow.//
144 +)))
145 +
146 +==== Example ====
147 +
148 +{{code language="JavaScript"}}
149 +payex.checkout("<payment_session_url>", "open");
150 +{{/code}}
151 +
152 +=== ===
153 +
154 +=== payex.checkout(paymentSessionUrl, options, command) ===
155 +
156 +Sets options for a payment session and executes a PayEx Checkout action.
157 +
158 +==== Arguments ====
159 +
160 +|(% style="text-align:right; width:126px" %)**Param**|(% style="width:1764px" %)**Details**
161 +|(% style="text-align:right; width:126px" %)(((
162 +{{code}}paymentSessionUrl{{/code}}
163 +(% style="color:LightGrey" %)string
164 +)))|(% style="width:1764px" %)A string of the URL to the Payment Session. This URL should be retrieved before page is rendered in the browser by completing the [[intial server-to-server POST request>>ecommerce.PayEx Checkout.Implementation.WebHome||anchor="HStep1:InitialPOST2CBackend"]].
165 +|(% style="text-align:right; width:126px" %)(((
166 +{{code}}options{{/code}}
167 +(% style="color:LightGrey" %)object(%%)
168 +
169 +)))|(% style="width:1764px" %)(((
170 +Set options for the payment session.
171 +
172 +* {{code}}onClose{{/code}} // function - Callback called when the PayEx Checkout modal is closed.//
173 +* {{code}}onOpen{{/code}} // function - Callback called when the PayEx Checkout modal is opened.//
174 +* {{code}}onError{{/code}} // function - Callback called when PayEx Checkout is unable to open or complete a session.//
175 +* {{code}}onComplete{{/code}} // function - Callback called when PayEx Checkout user flow is completed.//
176 +)))
177 +|(% style="text-align:right; width:126px" %){{code}}command{{/code}}
178 +(% style="color:LightGrey" %)string|(% style="width:1764px" %)(((
179 +The command to be excuted
180 +
181 +* {{code}}"open"{{/code}} // //- //Opens the PayEx Checkout user flow.//
182 +)))
183 +
184 +==== Example ====
185 +
186 +{{code language="JavaScript"}}
187 +payex.checkout("<payment_session_url>", {
188 + onComplete: function() {
189 + // Your code goes here.
190 + }
191 +}, "open");
192 +{{/code}}
193 +
194 +=== payex.checkout(options) ===
195 +
196 +Sets defaults options for all Payment Sessions.
197 +
198 +==== Arguments ====
199 +
200 +|(% style="text-align:right; width:156px" %)**Param**|(% style="width:1322px" %)**Details**
201 +|(% style="text-align:right; width:156px" %)(((
202 +{{code}}options{{/code}}
203 +(% style="color:LightGrey" %)object(%%)
204 +
205 +)))|(% style="width:1322px" %)(((
206 +Set options for the payment session.
207 +
208 +* {{code}}onClose{{/code}} // function - Callback called when the PayEx Checkout modal is closed.//
209 +* {{code}}onOpen{{/code}} // function - Callback called when the PayEx Checkout modal is opened.//
210 +* {{code}}onError{{/code}} // function - Callback called when PayEx Checkout is unable to open or complete a session.//
211 +* {{code}}onComplete{{/code}} // function - Callback called when PayEx Checkout user flow is completed.//
212 +)))
213 +
214 +==== Example ====
215 +
216 +{{code language="JavaScript"}}
217 +payex.checkout({
218 + onOpen: function(){
219 + console.log("The modal was opened");
220 + }
221 +});
222 +{{/code}}