Wiki source code of Vipps direct API

Last modified by Asbjørn Ulsberg on 2019/07/11 15:00
Hide last authors
Fredrik Köhler 80.11 1 (% class="jumbotron" %)
2 (((
3 (% class="container" %)
4 (((
5 Vipps is a two-phase payment method supported by the major norwegian banks. In the direct API scenario, PayEx receives a mobile number (MSISDN) directly from the merchant UI. PayEx performs a payment that the consumer must confirm in the Vipps mobile app.
6 )))
7 )))
8
Fredrik Köhler 80.2 9 == Introduction ==
10
Fredrik Köhler 80.4 11 * When the consumer/end-user starts the purchase process, you make a {{code}}POST{{/code}} request towards PayEx with the collected ##Purchase## information.
12 * After that, you need to collect the consumer's mobile number and make a {{code}}POST{{/code}} request towards PayEx.
Helge Dahl 57.1 13 * PayEx will handle the dialogue with Vipps and the consumer will have to confirm the purchase in the Vipps app.
Kim Fjellbo 80.16 14 * If CallbackURL is set you will receive a payment callback when the Vipps dialogue is completed, and you will have to make a {{code}}GET{{/code}}request to check the payment status.
Helge Dahl 57.1 15 * The flow is explained in the picture below:
16
17 [[image:Vipps_flow_directAPI.png||width="850"]]
18
Fredrik Köhler 80.12 19 (% id="HAPIRequests" %)
20 == API Requests ==
Helge Dahl 57.1 21
Asbjørn Ulsberg 80.18 22 The API requests are displayed in the [[purchase flow>>doc:Main.ecommerce.payex-payment-instruments.vipps-payments.vipps-direct-api.WebHome||anchor="HPurchaseflow"]]. The options you can choose from when creating a payment with key ##operation## set to Value ##Purchase## are listed below. The general REST based API model is described in the [[technical reference>>doc:Main.ecommerce.technical-reference.WebHome]].
Helge Dahl 57.1 23
Fredrik Köhler 80.4 24 (% id="HOptionsbeforepostingapayment" %)
25 === Options before posting a payment ===
Fredrik Köhler 76.1 26
Fredrik Köhler 80.7 27 All valid options when posting a payment with operation equal to Purchase, are described in [[the technical reference>>doc:Main.ecommerce.technical-reference.core-payment-resources.vipps-payments.WebHome]].
Fredrik Köhler 76.1 28
Fredrik Köhler 80.4 29 (% id="HTypeofauthorization28Intent29." %)
30 ==== Type of authorization (Intent). ====
Fredrik Köhler 76.1 31
Fredrik Köhler 80.8 32 * **Authorization (two-phase)**: The intent of a Vipps purchase is always ##Authorization##. The amount will be reserved but not charged. You will later (i.e. if a physical product, when you are ready to ship the purchased products) have to make a [[Capture>>doc:Main.ecommerce.technical-reference.core-payment-resources.vipps-payments.WebHome||anchor="HCaptures"]] or [[Cancel>>doc:Main.ecommerce.technical-reference.core-payment-resources.vipps-payments.WebHome||anchor="HCancellations"]] request.
Helge Dahl 57.1 33
Fredrik Köhler 80.5 34 ==== General ====
35
Kim Fjellbo 80.16 36 * **Defining CallbackURL**: When implementing a scenario, it is optional to set a [[##CallbackURL## >>doc:Main.ecommerce.technical-reference.core-payment-resources.WebHome||anchor="HURLs"]]in the {{code}}POST{{/code}} request. If callbackURL is set PayEx will send a postback request to this URL when the consumer has fulfilled the payment. [[See the Callback API description here.>>doc:Main.ecommerce.technical-reference.WebHome||anchor="HCallback"]]
Fredrik Köhler 80.5 37
Fredrik Köhler 80.13 38 == Purchase flow ==
Fredrik Köhler 80.4 39
Helge Dahl 57.1 40 The sequence diagram below shows the two requests you have to send to PayEx to make a purchase. The links will take you directly to the API description for the specific request.
41
42 {{plantuml}}
43 @startuml
44 skinparam sequence{
45 ArrowColor #2DA944
46
47 ActorFontColor #333333
48 ActorFontStyle bold
49 ActorFontSize 15
50 ActorBackgroundColor #fefefe
51 ActorBorderColor #2DA944
52
53 LifeLineBorderColor #999999
54 LifeLineBackgroundColor #dddddd
55
56 ParticipantBorderColor #2DA944
57 ParticipantBackgroundColor #ffffff
58 ParticipantFontColor #333333
59 ParticipantFontStyle bold
60 }
61 skinparam Roundcorner 10
62 skinparam Shadowing false
63
64 skinparam ActivityBorderColor #123123
65
66 skinparam NoteBackgroundColor white
67 skinparam NoteBorderColor #999999
68 skinparam NoteFontColor #333333
69
70 box "Consumer"
71 Actor Vipps_App
72 Actor Browser
73 end box
74
75 Participant Merchant
Fredrik Köhler 80.4 76 Participant PayEx.FrontEnd
77 Participant PayEx.BackEnd
Helge Dahl 57.1 78 participant Vipps.API
79 'participant TSP
80
81 '------------------------------------------------------------------------------------------------------------------------------------------------------------
82 Browser -> Merchant: start purchase (pay with VIPPS)
83 Activate Merchant
84
Fredrik Köhler 80.9 85 Merchant -> PayEx.FrontEnd: POST [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HCreate Vipps payments]]
Helge Dahl 57.1 86 note left: First API request
Fredrik Köhler 80.4 87 Activate PayEx.FrontEnd
88 PayEx.FrontEnd --> Merchant: payment resource
89 Deactivate PayEx.FrontEnd
Helge Dahl 57.1 90 Merchant --> Browser: Collect mobile number in UI
91 Browser -> Browser: Enter mobile number
92 Browser -> Merchant: Mobile number
Fredrik Köhler 80.9 93 Merchant -> PayEx.FrontEnd: POST [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HAuthorizations Vipps authorizations]]
Helge Dahl 57.1 94 note left: Second API request
Fredrik Köhler 80.4 95 Activate PayEx.FrontEnd
96 PayEx.FrontEnd -> Vipps.API: Initialize Vipps payment
Helge Dahl 57.1 97 Activate Vipps.API
Fredrik Köhler 80.4 98 Vipps.API --> PayEx.FrontEnd: HTTP response
99 'Deactivate PayEx.FrontEnd
100 PayEx.FrontEnd --> Merchant: Authorization response (State=AwaitingActivity)
Helge Dahl 57.1 101 Merchant --> Browser: Response (check your phone)
102 Deactivate Merchant
Fredrik Köhler 80.9 103 note left: Merchant should wait for [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HCallback Vipps Callback]] before proceeding
Helge Dahl 57.1 104
105 ...
106 Vipps.API -> Vipps_App: Confirm Payment UI
107 Vipps_App -> Vipps_App: Confirmation Dialogue
108 Vipps_App --> Vipps.API: Confirmation
Fredrik Köhler 80.4 109 Vipps.API -> PayEx.BackEnd: make payment
110 activate PayEx.BackEnd
111 PayEx.BackEnd -> PayEx.BackEnd: execute payment
112 PayEx.BackEnd --> Vipps.API: response
Helge Dahl 57.1 113 Deactivate Vipps.API
Fredrik Köhler 80.4 114 PayEx.BackEnd -/ PayEx.FrontEnd: payment result
115 deactivate PayEx.BackEnd
116 'Activate PayEx.FrontEnd
117 PayEx.FrontEnd -/ Merchant: Payment Callback
Helge Dahl 57.1 118 Activate Merchant
Fredrik Köhler 80.9 119 Merchant -> PayEx.FrontEnd: GET [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments Vipps payments]]
Helge Dahl 57.1 120 note left: Third API request
Fredrik Köhler 80.4 121 PayEx.FrontEnd-->Merchant: Payment resource
122 'Deactivate PayEx.FrontEnd
Helge Dahl 57.1 123 Merchant-->Browser: Display purchase result
124 Deactivate Merchant
125
126 @enduml
127 {{/plantuml}}
128
129 == Options after posting a payment ==
130
Fredrik Köhler 80.7 131 * **Abort:** It is possible to [[abort a payment>>doc:Main.ecommerce.technical-reference.WebHome||anchor="HAbort"]] if the payment has no successful transactions.
Fredrik Köhler 80.4 132 * Vipps only support two-phase transactions (##Authorize##), which mean that you must implement the Capture and Cancel requests.
133 * For reversals, you will need to implement the Reversal request.
Kim Fjellbo 80.16 134 * **If CallbackURL is set: **Whenever changes to the payment occur a [[Callback request>>doc:Main.ecommerce.technical-reference.WebHome||anchor="HCallback"]] will be posted to the callbackUrl, generated when the payment was created.
Helge Dahl 57.1 135
136 === Capture Sequence ===
137
Fredrik Köhler 69.1 138 Capture can only be perfomed on a payment with a successfully authorized transaction. It is possible to do a part-capture where you capture a smaller amount than the authorized amount. You can later do more captures on the same payment up to the total authorization amount.
Helge Dahl 57.1 139
140 {{plantuml}}
141 @startuml
142
143 skinparam sequence{
144 ArrowColor #2DA944
145
146 ActorFontColor #333333
147 ActorFontStyle bold
148 ActorFontSize 15
149 ActorBackgroundColor #fefefe
150 ActorBorderColor #2DA944
151
152 LifeLineBorderColor #999999
153 LifeLineBackgroundColor #dddddd
154
155 ParticipantBorderColor #2DA944
156 ParticipantBackgroundColor #ffffff
157 ParticipantFontColor #333333
158 ParticipantFontStyle bold
159 }
160 skinparam Roundcorner 10
161 skinparam Shadowing false
162
163 skinparam ActivityBorderColor #123123
164
165 skinparam NoteBackgroundColor white
166 skinparam NoteBorderColor #999999
167 skinparam NoteFontColor #333333
168
169 Actor Merchant
Fredrik Köhler 80.4 170 Participant PayEx.FrontEnd
171 Participant PayEx.BackEnd
Fredrik Köhler 80.9 172 Merchant->PayEx.FrontEnd: POST [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HCaptures Vipps captures]]
Helge Dahl 57.1 173 Activate Merchant
Fredrik Köhler 80.4 174 Activate PayEx.FrontEnd
175 PayEx.FrontEnd->PayEx.FrontEnd: validate input
176 PayEx.FrontEnd -> PayEx.BackEnd: call capture method
177 Activate PayEx.BackEnd
178 PayEx.BackEnd-->PayEx.FrontEnd: capture result
179 Deactivate PayEx.BackEnd
180 PayEx.FrontEnd-->Merchant: transaction resource
181 Deactivate PayEx.FrontEnd
Helge Dahl 57.1 182 Deactivate Merchant
183 @enduml
184 {{/plantuml}}
185
186 === Cancel Sequence ===
187
Fredrik Köhler 69.1 188 Cancel can only be done on a authorized transaction. If you do cancel after doing a part-capture you will cancel the different between the capture amount and the authorization amount.
Helge Dahl 57.1 189
190 {{plantuml}}
191 @startuml
192
193 skinparam sequence{
194 ArrowColor #2DA944
195
196 ActorFontColor #333333
197 ActorFontStyle bold
198 ActorFontSize 15
199 ActorBackgroundColor #fefefe
200 ActorBorderColor #2DA944
201
202 LifeLineBorderColor #999999
203 LifeLineBackgroundColor #dddddd
204
205 ParticipantBorderColor #2DA944
206 ParticipantBackgroundColor #ffffff
207 ParticipantFontColor #333333
208 ParticipantFontStyle bold
209 }
210 skinparam Roundcorner 10
211 skinparam Shadowing false
212
213 skinparam ActivityBorderColor #123123
214
215 skinparam NoteBackgroundColor white
216 skinparam NoteBorderColor #999999
217 skinparam NoteFontColor #333333
218
219 Actor Merchant
Fredrik Köhler 80.4 220 Participant PayEx.FrontEnd
221 Participant PayEx.BackEnd
Fredrik Köhler 80.9 222 Merchant->PayEx.FrontEnd: POST [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HCancellations Vipps cancellations]]
Helge Dahl 57.1 223 Activate Merchant
Fredrik Köhler 80.4 224 Activate PayEx.FrontEnd
225 PayEx.FrontEnd->PayEx.FrontEnd: validate input
226 PayEx.FrontEnd-> PayEx.BackEnd: call cancel method
227 Activate PayEx.BackEnd
228 PayEx.BackEnd-->PayEx.FrontEnd: cancel result
229 Deactivate PayEx.BackEnd
230 PayEx.FrontEnd-->Merchant: transaction resource
231 Deactivate PayEx.FrontEnd
Helge Dahl 57.1 232 Deactivate Merchant
233 @enduml
234 {{/plantuml}}
235
236 === Reversal Sequence ===
237
Fredrik Köhler 69.1 238 Reversal can only be done on a payment where there are some captured amount not yet reversed.
Helge Dahl 57.1 239
240 {{plantuml}}
241 @startuml
242
243 skinparam sequence{
244 ArrowColor #2DA944
245
246 ActorFontColor #333333
247 ActorFontStyle bold
248 ActorFontSize 15
249 ActorBackgroundColor #fefefe
250 ActorBorderColor #2DA944
251
252 LifeLineBorderColor #999999
253 LifeLineBackgroundColor #dddddd
254
255 ParticipantBorderColor #2DA944
256 ParticipantBackgroundColor #ffffff
257 ParticipantFontColor #333333
258 ParticipantFontStyle bold
259 }
260 skinparam Roundcorner 10
261 skinparam Shadowing false
262
263 skinparam ActivityBorderColor #123123
264
265 skinparam NoteBackgroundColor white
266 skinparam NoteBorderColor #999999
267 skinparam NoteFontColor #333333
268
269 Actor Merchant
Fredrik Köhler 80.4 270 Participant PayEx.FrontEnd
271 Participant PayEx.BackEnd
Fredrik Köhler 80.9 272 Merchant->PayEx.FrontEnd: POST [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HReversals Vipps reversals]]
Helge Dahl 57.1 273 Activate Merchant
Fredrik Köhler 80.4 274 Activate PayEx.FrontEnd
275 PayEx.FrontEnd ->PayEx.FrontEnd: validate input
276 PayEx.FrontEnd -> PayEx.BackEnd: call credit method
277 Activate PayEx.BackEnd
278 PayEx.BackEnd-->PayEx.FrontEnd: credit result
279 Deactivate PayEx.BackEnd
280 PayEx.FrontEnd-->Merchant: transaction resource
281 Deactivate PayEx.FrontEnd
Helge Dahl 57.1 282 Deactivate Merchant
283 @enduml
284 {{/plantuml}}