PayEx Developer Portal - Vipps direct API

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.

)))

)))

== Introduction ==

* 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.

==== General ====

* **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"]]

== Purchase flow ==

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.

@startuml

skinparam sequence{

ArrowColor #2DA944

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

box "Consumer"

Actor Vipps_App

Actor Browser

end box

Participant Merchant

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

Deactivate Merchant

@enduml

== 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.

@startuml

skinparam sequence{

ArrowColor #2DA944

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

Deactivate Merchant

@enduml

=== 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.

@startuml

skinparam sequence{

ArrowColor #2DA944

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

Deactivate Merchant

@enduml

=== Reversal Sequence ===

237

238

Reversal can only be done on a payment where there are some captured amount not yet reversed.

@startuml

skinparam sequence{

ArrowColor #2DA944

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