Wiki source code of ../credit-account-onboarding

Last modified by David Persson on 2020/04/21 08:18
Show last authors
1 (% class="jumbotron" %)
2 (((
3 (% class="container" %)
4 (((
5 Integrate to **PayEx Credit Account Onboarding API **
6 )))
7 )))
8
9 (% id="HChangelog" %)
10 = Changelog =
11
12 2020-03-02
13
14 * Added statuses on applicationresource: "InitializedSigning" and "SigningFailed"
15
16 2020-02-28
17
18 * minor changes in kyc object structure
19
20 2020-02-14
21
22 * changed KYC object in ApplicationResource
23
24 (% class="lead" id="HThisAPIisusedtolistcurrentlyavailablecreditaccountoffersaswellastheassociatedonboardingprocess" %)
25 This API is used to list currently available credit account offers as well as the associated onboarding process
26
27 == [[image:1581023587369-139.png||height="253" width="461"]] ==
28
29 == Offers ==
30
31 ==== List all offers ====
32
33 {{code language="http" title="**Response**"}}
34 GET /ledger/credit-account-onboarding/v1/XXX/offers HTTP/1.1
35 Host: -
36 Authorization: Bearer <Token>
37 Content-Type: application/json
38
39 {
40 "operations": null,
41 "items": [
42 {
43 "accountProfile" : "kontotyp-1",
44 "title" : "kontotyp 1",
45 "currency" : "SEK",
46 "maxCreditLimit" : 50000.00,
47 "interestFreePurchaseMonth" : true|false,
48 "monthlyAdminFee" : 35.00,
49 "reminderFee" : 35.00,
50 "interest" : 35.00,
51 "termsAndConditions" :
52 {
53 "standardEuropeeanAgreements" : "https://www.payex.com/term-and-conditions/no/-----.pdf",
54 "accountTerms" : "https://www.payex.com/term-and-conditions/no/-----.pdf"
55 },
56 "@id" : "/ledger/credit-account-onboarding/v1/XXX/offers/kontotyp-1",
57 },
58 {
59 "accountProfile" : "kontotyp-2",
60 "title" : "kontotyp 2",
61 "currency" : "SEK",
62 "maxCreditLimit" : 0.00,
63 "interestFreePurchaseMonth" : true|false,
64 "monthlyAdminFee" : 35.00,
65 "reminderFee" : 35.00,
66 "interest" : 35.00,
67 "termsAndConditions" :
68 {
69 "standardEuropeeanAgreements" : "https://www.payex.com/term-and-conditions/no/-----.pdf",
70 "accountTerms" : "https://www.payex.com/term-and-conditions/no/-----.pdf"
71 },
72 "@id" : "/ledger/credit-account-onboarding/v1/XXX/offers/kontotyp-2",
73 }
74 ],
75 "@id": "/ledger/credit-account-onboarding/v1/XXX/offers",
76 "view": {
77 "@id": "/ledger/credit-account-onboarding/v1/XXX/offers?$top=2&$skip=0",
78 "next": "/ledger/credit-account-onboarding/v1/XXX/offers?$top=2&$skip=2"
79 }
80 }
81 {{/code}}
82
83 ==== Offers Resource ====
84
85 {{code language="http" title="**Response**"}}
86 HTTP/1.1 200 OK
87 Content-Type: application/json
88
89 {
90 "accountProfile" : "kontotyp-1000",
91 "title" : "kontotyp 1,000",
92 "currency" : "NOK",
93 "maxCreditLimit" : 50000.00,
94 "interestFreePurchaseMonth" : true|false,
95 "monthlyAdminFee" : 35.00,
96 "reminderFee" : 35.00,
97 "interest" : 35.00,
98 "termsAndConditions" :
99 {
100 "standardEuropeeanAgreements" : "https://www.payex.com/term-and-conditions/no/-----.pdf",
101 "accountTerms" : "https://www.payex.com/term-and-conditions/no/-----.pdf"
102 },
103 "@id" : "/ledger/credit-account-onboarding/v1/XXX/offers/kontotyp-1000",
104 "operations" :
105 [
106 {
107 "rel" : "apply-for-account",
108 "href" : "/ledger/credit-account-onboarding/v1/XXX/offers/kontotyp-1000/applications",
109 "method" : "POST"
110 }
111 ]
112 }
113 {{/code}}
114
115
116 **Resource properties**
117
118 (% class="table-bordered table-striped" %)
119 |=(% style="width: 215px;" %)Property|=(% style="width: 114px;" %)Data type|=(% style="width: 118px;" %)Format|=(% style="width: 586px;" %)Description
120 |(% style="width:215px" %)@id |(% style="width:114px" %)string|(% style="width:118px" %)Uri|(% style="width:586px" %)
121 |(% style="width:215px" %)accountProfile|(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: 50|(% style="width:586px" %)
122 |(% style="width:215px" %)title|(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: 50|(% style="width:586px" %)
123 |(% style="width:215px" %)currency|(% style="width:114px" %)string|(% style="width:118px" %)[[ISO 4217>>url:https://sv.wikipedia.org/wiki/ISO_4217]]|(% style="width:586px" %)
124 |(% style="width:215px" %)maxCreditLimit|(% style="width:114px" %)decimal|(% style="width:118px" %) |(% style="width:586px" %)
125 |(% style="width:215px" %)interestFreePurchaseMonth|(% style="width:114px" %)bool|(% style="width:118px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:586px" %)
126 |(% style="width:215px" %)monthlyAdminFee|(% style="width:114px" %)decimal|(% style="width:118px" %) |(% style="width:586px" %)
127 |(% style="width:215px" %)reminderFee|(% style="width:114px" %)decimal|(% style="width:118px" %) |(% style="width:586px" %)
128 |(% style="width:215px" %)termsAndConditions.standardEuropeeanAgreements|(% style="width:114px" %)string|(% style="width:118px" %)Uri|(% style="width:586px" %)
129 |(% style="width:215px" %)termsAndConditions.accountTerms|(% style="width:114px" %)string|(% style="width:118px" %)Uri|(% style="width:586px" %)
130
131 == Applications ==
132
133 ==== Add application to offer ====
134
135 {{code language="http" title="**Request**"}}
136 POST /ledger/credit-account-onboarding/v1/XXX/offers/YYY/applications HTTP/1.1
137 Host: -
138 Authorization: Bearer <Token>
139 Content-Type: application/json
140
141 {
142 "nationalConsumerIdentifier" : {
143 "value" : "19101010-1010",
144 "countryCode" : "SE"
145 },
146 "creditLimit": 5000.00,
147 "customerNo" : "951753456",
148 "emailAddress" : "test@testshop.se",
149 "cellPhone" : "+46701234456",
150 "ipAddress": "1.1.1.1",
151 "legalAddress" : {
152 "name" : "John Smith",
153 "streetAddress" : "Teststreet",
154 "city" : "Testcity",
155 "coAddress" : "",
156 "zipCode" : "12345",
157 "countryCode" : "SE"
158 },
159 "kyc": {
160 "questions":[
161 {
162 "code": "employment",
163 "text": "Vad är din sysselsättning?",
164 "answer" : {
165 "code": "self-employed",
166 "text": "Egen företagare"
167 }
168 },
169 {
170 "code": "employment-since",
171 "text": "Hur länge har du haft denna sysselsättning?",
172 "answer" : {
173 "code": "2016-09",
174 "text": "2016-09"
175 }
176 },
177 {
178 "code": "monthlyIncome",
179 "text": "Månadsinkomst före skatt",
180 "answer" : {
181 "code": "10000.00",
182 "text": "10000"
183 }
184 },
185 {
186 "code": "monthlyPurchaseAmount",
187 "text": "Hur mycket kommer du genomsnitt att handla på ditt kort?",
188 "answer" : {
189 "code": "3000.00",
190 "text": "3000"
191 }
192 },
193 {
194 "code": "monthlyNumberOfDeposits",
195 "text": "Hur många inbetalningar kommer du att göra per månad?",
196 "answer" : {
197 "code": "1-2",
198 "text": "1-2"
199 }
200 },
201 {
202 "code": "IsPep",
203 "text": "Är du en person i politiskt utsatt ställning (PEP), det vill säga.....",
204 "answer" : {
205 "code" : "true",
206 "text" : "Ja"
207 }
208 }
209 ]
210 }
211 }
212 {{/code}}
213
214 ==== List all applications ====
215
216 {{code language="http" title="**Request**"}}
217 GET /ledger/credit-account-onboarding/v1/XXX/offers/YYY/applications HTTP/1.1
218 Host: -
219 Authorization: Bearer <Token>
220 Content-Type: application/json
221
222 {{/code}}
223
224 ==== Get a single application ====
225
226 {{code language="http" title="**Request**"}}
227 GET /ledger/credit-account-onboarding/v1/XXX/offers/YYY/applications/NNN HTTP/1.1
228 Host: -
229 Authorization: Bearer <Token>
230 Content-Type: application/json
231
232 {{/code}}
233
234 ==== Applications Resource ====
235
236 {{code language="http" title="**Response**"}}
237 HTTP/1.1 200 OK
238 Content-Type: application/json
239
240 {
241 "nationalConsumerIdentifier" : {
242 "value" : "19101010-1010",
243 "countryCode" : "SE"
244 },
245 "status" : "awaiting-sign",
246 "customerNo" : "951753456",
247 "creditLimit": 5000.00,
248 "emailAddress" : "test@testshop.se",
249 "cellPhone" : "+46701234456",
250 "ipAddress": "1.1.1.1",
251 "legalAddress" : {
252 "name" : "John Smith",
253 "streetAddress" : "Teststreet",
254 "city" : "Testcity",
255 "coAddress" : "",
256 "zipCode" : "12345",
257 "countryCode" : "SE"
258 },
259 "kyc": {
260 "questions":[
261 {
262 "code": "employment",
263 "text": "Vad är din sysselsättning?",
264 "answer" : {
265 "code": "self-employed",
266 "text": "Egen företagare"
267 }
268 },
269 {
270 "code": "employment-since",
271 "text": "Hur länge har du haft denna sysselsättning?",
272 "answer" : {
273 "code": "2016-09",
274 "text": "2016-09"
275 }
276 },
277 {
278 "code": "monthlyIncome",
279 "text": "Månadsinkomst före skatt",
280 "answer" : {
281 "code": "10000.00",
282 "text": "10000"
283 }
284 },
285 {
286 "code": "monthlyPurchaseAmount",
287 "text": "Hur mycket kommer du genomsnitt att handla på ditt kort?",
288 "answer" : {
289 "code": "3000.00",
290 "text": "3000"
291 }
292 },
293 {
294 "code": "monthlyNumberOfDeposits",
295 "text": "Hur många inbetalningar kommer du att göra per månad?",
296 "answer" : {
297 "code": "1-2",
298 "text": "1-2"
299 }
300 },
301 {
302 "code": "IsPep",
303 "text": "Är du en person i politiskt utsatt ställning (PEP), det vill säga.....",
304 "answer" : {
305 "code" : "true",
306 "text" : "Ja"
307 }
308 }
309 ]
310 },
311 "account" : null,
312 "@id" : "/ledger/credit-account-onboardings/v1/501/offers/kontotyp-10000/applications/1561561-54641515-56456",
313 "parentHREF" : "/ledger/credit-account-onboardings/v1/XXX/offers/kontotyp-10000",
314 "operations" : [
315 {
316 "rel" : "sign-agreement",
317 "href" : "/ledger/credit-account-onboardings/v1/XXX/offers/kontotyp-10000/applications/1561561-54641515-56456/sign-agreement",
318 "method" : "POST"
319 }
320 ]
321 }
322 {{/code}}
323
324 **Resource properties**
325
326 (% class="table-bordered table-striped" %)
327 |=(% style="width: 215px;" %)Property|=(% style="width: 114px;" %)Data type|=(% style="width: 133px;" %)Required in post|=(% style="width: 479px;" %)Format|=(% style="width: 586px;" %)Description
328 |(% style="width:215px" %)@id |(% style="width:114px" %)string|(% style="width:133px" %)-|(% style="width:479px" %)Maxlength: |(% style="width:586px" %)
329 |(% style="width:215px" %)nationalConsumerIdentifier.value|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %)YYYYMMDD-NNNC|(% style="width:586px" %)A valid swedish "personnummer"
330 |(% style="width:215px" %)nationalConsumerIdentifier.countryCode|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:586px" %)
331 |(% style="width:215px" %)status|(% style="width:114px" %)string|(% style="width:133px" %)-|(% style="width:479px" %)Maxlength: 25|(% style="width:586px" %)(((
332 * AwaitingSign
333 * InitializedSigning
334 * Approved
335 * Rejected
336 * SigningFailed
337 )))
338 |(% style="width:215px" %)customerNo|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %)Maxlength: 15|(% style="width:586px" %)
339 |(% style="width:215px" %)creditLimit|(% style="width:114px" %)decimal|(% style="width:133px" %)Yes|(% style="width:479px" %) |(% style="width:586px" %)
340 |(% style="width:215px" %)emailAddress|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %)Maxlength: 254
341 Regex pattern: [^@]+@[^\.]+\..+|(% style="width:586px" %)
342 |(% style="width:215px" %)cellPhone|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %)Maxlength: 15|(% style="width:586px" %)
343 |(% style="width:215px" %)ipAddress|(% style="width:114px" %)string|(% style="width:133px" %)No|(% style="width:479px" %)Maxlength: 43
344 Regex pattern: [a-z0-9.:/]*|(% style="width:586px" %)
345 |(% style="width:215px" %)legalAddress.name|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %)Maxlength: 72|(% style="width:586px" %)end-customer fullname
346 |(% style="width:215px" %)legalAddress.streetAddress|(% style="width:114px" %)string|(% style="width:133px" %)No|(% style="width:479px" %)Maxlength: 35|(% style="width:586px" %)
347 |(% style="width:215px" %)legalAddress.city|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %)Maxlength: 30|(% style="width:586px" %)
348 |(% style="width:215px" %)legalAddress.coAddress|(% style="width:114px" %)string|(% style="width:133px" %)No|(% style="width:479px" %)Maxlength: 35|(% style="width:586px" %)
349 |(% style="width:215px" %)legalAddress.zipCode|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %)Maxlength: 15|(% style="width:586px" %)ZipCode without whitespaces
350 |(% style="width:215px" %)legalAddress.countryCode|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:586px" %)
351 |(% style="width:215px" %)account|(% style="width:114px" %)string|(% style="width:133px" %)-|(% style="width:479px" %)Uri|(% style="width:586px" %)Reference to created account
352 |(% style="width:215px" %)kyc|(% style="width:114px" %)object|(% style="width:133px" %)Yes|(% style="width:479px" %) |(% style="width:586px" %)kyc (know your customer). The questions and answers in the above example are just examples of what it might look like. This API does not validate that "correct" questions are asked
353 |(% style="width:215px" %)kyc.questions|(% style="width:114px" %)list of objects|(% style="width:133px" %)Yes|(% style="width:479px" %) |(% style="width:586px" %)
354 |(% style="width:215px" %)kyc.questions.code|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %) |(% style="width:586px" %)The code definition of the question
355 |(% style="width:215px" %)kyc.questions.text|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %) |(% style="width:586px" %)The actual question text that was presented to the end-customer
356 |(% style="width:215px" %)kyc.questions.aswer.code|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %) |(% style="width:586px" %)The answered code definition from the end-customer
357 |(% style="width:215px" %)kyc.questions.aswer.text|(% style="width:114px" %)string|(% style="width:133px" %)Yes|(% style="width:479px" %) |(% style="width:586px" %)The actual displayed answertext that was presented to the customer
358
359 == Sign-agreement (Operation) ==
360
361 ==== Request ====
362
363 {{code language="http" title="**Request**"}}
364 POST /ledger/credit-account-onboarding/v1/XXX/offers/YYY/applications/NNN/sign-agreement HTTP/1.1
365 Host: -
366 Authorization: Bearer <Token>
367 Content-Type: application/json
368
369 {{/code}}
370
371 ==== Response ====
372
373 {{code language="http" title="**Request**"}}
374 HTTP/1.1 201 Created
375 Content-Type: application/json
376
377 {
378 "createdAccount" : "https://api.payex.com/ledger/credit-account/v1/XXX/accounts/123456",
379 }
380 {{/code}}
381
382 **Resource properties**
383
384 (% class="table-bordered table-striped" %)
385 |=(% style="width: 215px;" %)Property|=(% style="width: 114px;" %)Data type|=(% style="width: 118px;" %)Format|=(% style="width: 586px;" %)Description
386 |(% style="width:215px" %)createdAccount|(% style="width:114px" %)string|(% style="width:118px" %)Uri|(% style="width:586px" %)
387
388 (% id="HProblems-1" %)
389 == Problems ==
390
391 All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
392 The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
393 Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.
394
395 Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation
396
397 (% id="HExample" %)
398 === Example ===
399
400 {{code language="http" title="**Response**"}}
401 HTTP/1.1 400 Error
402 Content-Type: application/problem+json
403
404 {
405 "Type" : "ledger.credit-account-onboarding.validation",
406 "Title" : "A validation error occurred",
407 "Status" : 400,
408 "Instance" : "f1f431d7-d2b2-49ca-93e0-ffe15753610a",
409 "Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
410 "Problems" : [
411 {
412 "CellPhone" : "The CellPhone field is required."
413 },
414 {
415 "EmailAddress" : "The EmailAddress field is required."
416 },
417 {
418 "LegalAddress.Name" : "The Name field is required."
419 }
420 ]
421 }
422
423 {{/code}}
424
425 (% id="HProblemtypes" %)
426 === Problem types ===
427
428 Note, each problem typecode is preceded by "ledger.credit-account-onboarding." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.credit-account-onboarding.validation".
429
430 |=Problem type (code)|=Httpstatus|=Description
431 |validation|400|occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
432 |account-profile-exists|409|occurs if the customer already has an account with the requested account profile
433
434