# 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
Hide last authors

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