Wiki source code of Vipps direct API

Last modified by Asbjørn Ulsberg on 2019/07/11 15:00
Show last authors
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
9 == Introduction ==
10
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.
13 * PayEx will handle the dialogue with Vipps and the consumer will have to confirm the purchase in the Vipps app.
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.
15 * The flow is explained in the picture below:
16
17 [[image:Vipps_flow_directAPI.png||width="850"]]
18
19 (% id="HAPIRequests" %)
20 == API Requests ==
21
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]].
23
24 (% id="HOptionsbeforepostingapayment" %)
25 === Options before posting a payment ===
26
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]].
28
29 (% id="HTypeofauthorization28Intent29." %)
30 ==== Type of authorization (Intent). ====
31
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.
33
34 ==== General ====
35
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"]]
37
38 == Purchase flow ==
39
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
76 Participant PayEx.FrontEnd
77 Participant PayEx.BackEnd
78 participant Vipps.API
79 'participant TSP
80
81 '------------------------------------------------------------------------------------------------------------------------------------------------------------
82 Browser -> Merchant: start purchase (pay with VIPPS)
83 Activate Merchant
84
85 Merchant -> PayEx.FrontEnd: POST [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HCreate Vipps payments]]
86 note left: First API request
87 Activate PayEx.FrontEnd
88 PayEx.FrontEnd --> Merchant: payment resource
89 Deactivate PayEx.FrontEnd
90 Merchant --> Browser: Collect mobile number in UI
91 Browser -> Browser: Enter mobile number
92 Browser -> Merchant: Mobile number
93 Merchant -> PayEx.FrontEnd: POST [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HAuthorizations Vipps authorizations]]
94 note left: Second API request
95 Activate PayEx.FrontEnd
96 PayEx.FrontEnd -> Vipps.API: Initialize Vipps payment
97 Activate Vipps.API
98 Vipps.API --> PayEx.FrontEnd: HTTP response
99 'Deactivate PayEx.FrontEnd
100 PayEx.FrontEnd --> Merchant: Authorization response (State=AwaitingActivity)
101 Merchant --> Browser: Response (check your phone)
102 Deactivate Merchant
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
104
105 ...
106 Vipps.API -> Vipps_App: Confirm Payment UI
107 Vipps_App -> Vipps_App: Confirmation Dialogue
108 Vipps_App --> Vipps.API: Confirmation
109 Vipps.API -> PayEx.BackEnd: make payment
110 activate PayEx.BackEnd
111 PayEx.BackEnd -> PayEx.BackEnd: execute payment
112 PayEx.BackEnd --> Vipps.API: response
113 Deactivate Vipps.API
114 PayEx.BackEnd -/ PayEx.FrontEnd: payment result
115 deactivate PayEx.BackEnd
116 'Activate PayEx.FrontEnd
117 PayEx.FrontEnd -/ Merchant: Payment Callback
118 Activate Merchant
119 Merchant -> PayEx.FrontEnd: GET [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments Vipps payments]]
120 note left: Third API request
121 PayEx.FrontEnd-->Merchant: Payment resource
122 'Deactivate PayEx.FrontEnd
123 Merchant-->Browser: Display purchase result
124 Deactivate Merchant
125
126 @enduml
127 {{/plantuml}}
128
129 == Options after posting a payment ==
130
131 * **Abort:** It is possible to [[abort a payment>>doc:Main.ecommerce.technical-reference.WebHome||anchor="HAbort"]] if the payment has no successful transactions.
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.
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.
135
136 === Capture Sequence ===
137
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.
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
170 Participant PayEx.FrontEnd
171 Participant PayEx.BackEnd
172 Merchant->PayEx.FrontEnd: POST [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HCaptures Vipps captures]]
173 Activate Merchant
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
182 Deactivate Merchant
183 @enduml
184 {{/plantuml}}
185
186 === Cancel Sequence ===
187
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.
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
220 Participant PayEx.FrontEnd
221 Participant PayEx.BackEnd
222 Merchant->PayEx.FrontEnd: POST [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HCancellations Vipps cancellations]]
223 Activate Merchant
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
232 Deactivate Merchant
233 @enduml
234 {{/plantuml}}
235
236 === Reversal Sequence ===
237
238 Reversal can only be done on a payment where there are some captured amount not yet reversed.
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
270 Participant PayEx.FrontEnd
271 Participant PayEx.BackEnd
272 Merchant->PayEx.FrontEnd: POST [[/xwiki/wiki/developer/view/Main/ecommerce/technical-reference/core-payment-resources/vipps-payments/#HReversals Vipps reversals]]
273 Activate Merchant
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
282 Deactivate Merchant
283 @enduml
284 {{/plantuml}}

Tips

Jump to any page in the wiki with Ctrl+G or Meta+G.
See more shortcuts.

Need help?

If you need help with XWiki you can contact: