# Wiki source code of Vipps direct API

Last modified by Asbjørn Ulsberg on 2019/07/11 15:00

#### Export

#### Office Formats

Export as PDF Export as ODT Export as RTF

#### Other Formats

Select the pages to export:

select all / none

Export as HTML
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}}

# Applications

# Tips

Did you know that you can improve XWiki? Take 5 minutes to fill this survey and help this open source project!

# Need help?

If you need help with XWiki you can contact:

- Community Support
- Professional Support