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

You can click on the arrows next to the breadcrumb elements to quickly navigate to sibling and children pages.

Need help?

If you need help with XWiki you can contact: