Wiki source code of 2. Customer

Last modified by David Persson on 2024/11/14 13:41
Show last authors
1 (% class="jumbotron" %)
2 (((
3 (% class="container" %)
4 (((
5 Integrate to **PayEx Customer API **
6 )))
7 )))
8
9 == Introduction ==
10
11 (% class="lead" %)
12 This api is used to create/read customers or change properties related to the customer.
13
14 [[image:PayEx - Ledger API's - Customer Wiki Visual(1).png||alt="1612164561442-820.png"]]
15
16
17 Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below
18
19 The below route is an example of a route towards resource2Id, to operate on this resource you must also include the ids of its parentresources in the route.
20 //lf-api.payex.com/ledger/**{Subdomain}**/v1/**{LedgerNumber}**/resource1/**{resource1Id}**/resource2/**{resource2Id}**//
21
22 (% class="table-bordered table-striped" %)
23 |=(% style="width: 604px;" %)Route segment|=(% style="width: 2790px;" %)Description
24 |(% style="width:604px" %)Subdomain|(% style="width:2790px" %)In this part of the API it will be **customer**
25 |(% style="width:604px" %)LedgerNumber|(% style="width:2790px" %)The ledger identifier/number at PayEx
26 |(% style="width:604px" %)resource1Id|(% style="width:2790px" %)Identifier of resource1
27 |(% style="width:604px" %)resource2Id|(% style="width:2790px" %)identifier of resource2, subresource to resource1
28
29 (% class="wikigeneratedid" %)
30 Routes that occurs in examples of this documentation will use the following identifiers
31
32 (% class="table-bordered table-striped" %)
33 |=(% style="width: 488px;" %)Resource|=(% style="width: 2271px;" %)Identifier
34 |(% style="width:488px" %)LedgerNumber|(% style="width:2271px" %)XXX
35 |(% style="width:488px" %)Customer|(% style="width:2271px" %)NNN (CustomerNo)
36
37 (% id="HChangelog" %)
38 == Changelog ==
39
40 2023-01-17
41 Added //surpluses// property to the Customer resource with planned release 2024-01-23
42
43 2023-11-27
44 Added new resource Surpluses & added a general 404 not-found to problems list.
45
46 2024-04-26
47
48 Added TaxIdentificationNumber to the Customer resource with planned release 2024-05-28
49
50 2024-05-15
51
52 Added Consent and underlying resources with planned release 2024-05-28. Updated Introduction API overview visual.
53
54 == Customer ==
55
56 The **customer **resource is located under **ledger/customer/v1/ **api**. **The customer- and its sub-resources are used to create, read and modify information related to customers.
57
58 ==== (% style="color:inherit; font-family:inherit" %)Get a specific customer(%%) ====
59
60 {{code language="http" title="**Request**"}}
61 GET /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
62 Host: -
63 Authorization: Bearer <Token>
64 Content-Type: application/json
65 {{/code}}
66
67 ==== ====
68
69 {{code language="http" title="**Response**"}}
70 HTTP/1.1 200 OK
71 Content-Type: application/json
72
73 {
74 "@id" : "/ledger/customer/v1/XXX/customers/9999",
75 "customerNo" : "9999",
76 "nationalIdentifier": {
77 "regNo" : "YYYYMMDD-NNNN",
78 "countryCode" : "SE"
79 },
80 "vatNo" : "SE101010101001",
81 "legalEntity" : "consumer|business",
82 "name" : "Britt-Marie Axelstopp",
83 "emailAddress" : "britt@axelstopp.com",
84 "protectedIdentity": false,
85 "preferredLanguageCode": "SV",
86 "legalStatus": "active",
87 "msisdn" : "+91485918841",
88 "activeConsents": [
89 "Betalingsservice",
90 "Avtalegiro"
91 ],
92 "eDIAddressInfo" : {
93 "VAN": "ABCXYZ",
94 "InterChangeRecipient": "Recipient_ID1",
95 "BuyerId": "123465"
96 },
97 "legalAddress" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
98 "billingAddress" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
99 "surpluses": "/ledger/customer/v1/XXX/customers/9999/surpluses",
100 "operations" :
101 [
102 {
103 "rel" : "add-billing-address",
104 "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
105 "method" : "POST"
106 }
107 ]
108 }
109 {{/code}}
110
111 ==== Get a specific customer using $expand ====
112
113 if the entire customer model is needed, you can expand property references to other resources, in this example to get the customer model including the addresses on a single call.
114
115 (% class="box infomessage" %)
116 (((
117 Performance is affected when expand is used as more resources are retrieved. Only use $expand if you always need the referenced properties, otherwise it should be retrevied on demand.
118 )))
119
120 {{code language="http" title="**Request**"}}
121 GET /ledger/customer/v1/XXX/customers/NNN?$expand=legaladdress,billingaddress HTTP/1.1
122 Host: -
123 Authorization: Bearer <Token>
124 Content-Type: application/json
125 {{/code}}
126
127
128 {{code language="http" title="**Response**"}}
129 HTTP/1.1 200 OK
130 Content-Type: application/json
131
132 {
133 "@id" : "/ledger/customer/v1/XXX/customers/9999",
134 "customerNo" : "9999",
135 "nationalIdentifier": {
136 "regNo" : "YYYYMMDD-NNNN",
137 "countryCode" : "SE"
138 },
139 "vatNo" : "SE101010101001",
140 "legalEntity" : "consumer|business",
141 "name" : "Britt-Marie Axelstopp",
142 "emailAddress" : "britt@axelstopp.com",
143 "protectedIdentity": false,
144 "preferredLanguageCode": "SV",
145 "legalStatus": "active",
146 "msisdn" : "+91485918841",
147 "activeConsents": [
148 "Betalingsservice",
149 "Avtalegiro"
150 ],
151 "eDIAddressInfo" : {
152 "VAN": "ABCXYZ",
153 "InterChangeRecipient": "Recipient_ID1",
154 "BuyerId": "123456"
155 },
156 "legalAddress" : {
157 "addressee" : "Britt-Marie Axelstopp",
158 "streetAddress" : "The street 18",
159 "coAddress" : "c/o Jansson",
160 "city" : "STOCKHOLM",
161 "zipCode" : "15961",
162 "countryCode" : "SE",
163 "operations" :
164 [
165 {
166 "rel" : "update",
167 "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
168 "method" : "PUT"
169 },
170 {
171 "rel" : "update-legal-address-from-population-register",
172 "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
173 "method" : "POST"
174 }
175 ]
176 },
177 "billingAddress" : {
178 "addressee" : "Kalle Axelstopp",
179 "streetAddress" : "Axelgatan 18",
180 "city" : "STOCKHOLM",
181 "zipCode" : "16872",
182 "countryCode" : "se",
183 "operations" :
184 [
185 {
186 "rel" : "update",
187 "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
188 "method" : "PUT"
189 },
190 {
191 "rel" : "delete",
192 "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
193 "method" : "DELETE"
194 }
195 ]
196 },
197 "surpluses": "/ledger/customer/v1/XXX/customers/9999/surpluses",
198 "operations" :
199 [
200 {
201 "rel" : "add-billing-address",
202 "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
203 "method" : "POST"
204 }
205 ]
206 }
207 {{/code}}
208
209
210 ----
211
212 ==== Create new customer ====
213
214
215 (% id="HImportanttonote21" %)
216 ===== Important to note! =====
217
218 * Standard length of customerNo in Norway and Denmark is 7 characters (numeric only).
219 * Only use numeric characters and not with a leading zero for customerNo in Sweden, in order to use AutoGiro (Direct Debit).
220 * Dependency to legalEntity:
221 ** [[Late fee>>url:https://developer.payex.com/xwiki/wiki/developer/view/Main/Invoicing/invoice-service/invoice-service-apis/Supplementary%20features/?HLatefee]] will be added instead of reminder fee or collection claim fee when legalEntity is set to "business" (if specially contracted with PayEx and configured in ledger).
222 ** SSN (regNo) for private individuals will not be displayed in ledger reports due to GDPR. regNO will only be displayed when legalEntity is set till "business".
223 ** When invoice/claim is distributed by e-mail: If legalEntity is set to "consumer" the e-mail message will only include a link to PayEx Invoice Portal where the invoice/claim is available, otherwise a copy of the invoice/claim will be added in the e-mail message as a pdf-file.
224 ** Finland only: Different claim processes will be used depending on "consumer" or "business".
225
226 A new customer is created by making a POST call to the API.
227 See below table of properties that is supported when creating a new customer. The table below also reflects what properties you can expect when retreiving a customer through a "GET" request.
228
229 (% class="table-bordered table-striped" %)
230 |=(% style="width: 509px;" %)Property|=(% style="width: 161px;" %)Required|=(% style="width: 1852px;" %)Comment *
231 |(% style="width:509px" %)customerNo|(% style="width:161px" %)Yes*|(% style="width:1852px" %)Normally required, //exception is when the configuration on the ledger is set for payex to generate customer numbers, in that case CustomerNo must not be set in request.//
232 |(% style="width:509px" %)__**nationalIdentifier**__|(% style="width:161px" %)No*|(% style="width:1852px" %)Normally optional, //exception is when the configuration on the ledger is set for payex to generate customer numbers, in that case nationalIdentifier is required.//
233 |(% style="width:509px" %) nationalIdentifier.regNo|(% style="width:161px" %)Yes|(% style="width:1852px" %)
234 |(% style="width:509px" %) nationalIdentifier.countryCode|(% style="width:161px" %)Yes|(% style="width:1852px" %)
235 |(% style="width:509px" %)vatNo|(% style="width:161px" %)No*|(% style="width:1852px" %)Required if reverse tax is used
236 |(% style="width:509px" %)legalEntity|(% style="width:161px" %)No|(% style="width:1852px" %)
237 |(% style="width:509px" %)name|(% style="width:161px" %)Yes|(% style="width:1852px" %)
238 |(% style="width:509px" %)preferredLanguageCode|(% style="width:161px" %)No|(% style="width:1852px" %)
239 |(% style="width:509px" %)emailAddress|(% style="width:161px" %)No|(% style="width:1852px" %)
240 |(% style="width:509px" %)msisdn|(% style="width:161px" %)No|(% style="width:1852px" %)
241 |(% style="width:509px" %)protectedIdentity|(% style="width:161px" %)No|(% style="width:1852px" %)
242 |(% style="width:509px" %)distributionType|(% style="width:161px" %)No|(% style="width:1852px" %)
243 |(% style="width:509px" %)taxIdentificationNumber|(% style="width:161px" %)No|(% style="width:1852px" %)
244 |(% style="width:509px" %)__**eDIAddressInfo**__|(% style="width:161px" %)No|(% style="width:1852px" %)
245 |(% style="width:509px" %) eDIAddressInfo.van|(% style="width:161px" %)No*|(% style="width:1852px" %)This field is required for distribution method EInvoiceB2B (EDI) to be used
246 |(% style="width:509px" %) eDIAddressInfo.interChangeRecipient|(% style="width:161px" %)No|(% style="width:1852px" %)
247 |(% style="width:509px" %) eDIAddressInfo.BuyerId|(% style="width:161px" %)Yes|(% style="width:1852px" %)
248 |(% style="width:509px" %)**__legalAddress__**|(% style="width:161px" %)Yes|(% style="width:1852px" %)
249 |(% style="width:183px" %) addressee|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
250 |(% style="width:183px" %) streetAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)
251 |(% style="width:183px" %) coAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)
252 |(% style="width:183px" %) city|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
253 |(% style="width:183px" %) zipCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
254 |(% style="width:183px" %) countryCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
255 |(% style="width:509px" %)**__billingAddress__**|(% style="width:161px" %)No|(% style="width:1852px" %)
256 |(% style="width:183px" %) addressee|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
257 |(% style="width:183px" %) streetAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)
258 |(% style="width:183px" %) coAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)
259 |(% style="width:183px" %) city|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
260 |(% style="width:183px" %) zipCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
261 |(% style="width:183px" %) countryCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)
262
263 ===== Examples =====
264
265 (% class="wikigeneratedid" %)
266 Standard create customer
267
268 {{code language="http" title="**Request**"}}
269 POST /ledger/customer/v1/XXX/customers HTTP/1.1
270 Host: -
271 Authorization: Bearer <Token>
272 Content-Type: application/json
273
274 {
275 "customerNo" : "9999",
276 "nationalIdentifier": {
277 "regNo" : "YYYYMMDD-NNNN",
278 "countryCode" : "SE"
279 },
280 "vatNo" : "SE101010101001",
281 "legalEntity" : "consumer|business",
282 "name" : "Britt-Marie Axelstopp",
283 "emailAddress" : "britt@axelstopp.com",
284 "msisdn" : "+91485918841",
285 "eDIAddressInfo" : {
286 "VAN": "ABCXYZ",
287 "InterChangeRecipient": "Recipient_ID1",
288 "BuyerId": "123456"
289 },
290 "legalAddress" : {
291 "addressee" : "Britt-Marie Axelstopp",
292 "streetAddress" : "The street 18",
293 "coAddress" : "c/o Jansson",
294 "city" : "STOCKHOLM",
295 "zipCode" : "15961",
296 "countryCode" : "SE"
297 },
298 "distributionType": "postal",
299 "taxIdentificationNumber" : "123456789"
300 }
301 {{/code}}
302
303 (% id="HAccountresourceproperties" %)
304 ==== ====
305
306 {{code language="http" title="**Response**"}}
307 HTTP/1.1 201 CREATED
308 Content-Type: application/json
309
310 {
311 "@id" : "/ledger/customer/v1/XXX/customers/9999",
312 "customerNo" : " 9999"
313 }
314 {{/code}}
315
316 (% class="wikigeneratedid" id="HCreatecustomerwithbilling-address" %)
317 Create customer with billing-address
318
319 {{code language="http" title="**Request**"}}
320 POST /ledger/customer/v1/XXX/customers HTTP/1.1
321 Host: -
322 Authorization: Bearer <Token>
323 Content-Type: application/json
324
325 {
326 "customerNo" : "9999",
327 "nationalIdentifier": {
328 "regNo" : "YYYYMMDD-NNNN",
329 "countryCode" : "SE"
330 },
331 "vatNo" : "SE101010101001",
332 "legalEntity" : "consumer|business",
333 "name" : "Britt-Marie Axelstopp",
334 "emailAddress" : "britt@axelstopp.com",
335 "msisdn" : "+91485918841",
336 "eDIAddressInfo" : {
337 "VAN": "ABCXYZ",
338 "InterChangeRecipient": "Recipient_ID1",
339 "BuyerId": "123456"
340 },
341 "legalAddress" : {
342 "addressee" : "Britt-Marie Axelstopp",
343 "streetAddress" : "The street 18",
344 "coAddress" : "c/o Jansson",
345 "city" : "STOCKHOLM",
346 "zipCode" : "15961",
347 "countryCode" : "SE"
348 },
349 "billingAddress" : {
350 "addressee" : "Kalle Axelstopp",
351 "streetAddress" : "Axelgatan 18",
352 "city" : "STOCKHOLM",
353 "zipCode" : "16872",
354 "countryCode" : "SE"
355 }
356 }
357 {{/code}}
358
359 (% id="HAccountresourceproperties" %)
360 ==== ====
361
362 {{code language="http" title="**Response**"}}
363 HTTP/1.1 201 CREATED
364 Content-Type: application/json
365
366 {
367 "@id" : "/ledger/customer/v1/XXX/customers/9999",
368 "customerNo" : " 9999"
369 }
370 {{/code}}
371
372 ==== ====
373
374 ----
375
376 ==== Update customer ====
377
378 Some properties of the customer can be updated through this API. Properties will only be updated if included in the request. //To delete a property, for example, the property must be included in the request and have the value set to null (see examples below). //
379
380 The following customer properties is possible to update through a patch call
381
382 (% class="table-bordered table-striped" %)
383 |=(% style="width: 509px;" %)Property
384 |(% style="width:509px" %)emailAddress
385 |(% style="width:509px" %)legalStatus
386 |(% style="width:509px" %)preferredLanguageCode
387 |(% style="width:509px" %)protectedIdentity
388 |(% style="width:509px" %)msisdn
389 |(% style="width:509px" %)distributionType
390 |(% style="width:509px" %)taxIdentificationNumber
391 |(% style="width:509px" %)__**eDIAddressInfo**__
392 |(% style="width:509px" %) eDIAddressInfo.van
393 |(% style="width:509px" %) eDIAddressInfo.interChangeRecipient
394 |(% style="width:509px" %) eDIAddressInfo.BuyerId
395
396 ===== Examples =====
397
398 Update all properties
399
400 {{code language="http" title="**Request**"}}
401 PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
402 Host: -
403 Authorization: Bearer <Token>
404 Content-Type: application/json
405
406 {
407 "emailAddress" : "britt@axelstopp.com",
408 "protectedIdentity": false,
409 "preferredLanguageCode": "SV",
410 "legalStatus": "active",
411 "msisdn" : "+91485918841",
412 "eDIAddressInfo" : {
413 "VAN": "ABCXYZ",
414 "InterChangeRecipient": "Recipient_ID1",
415 "BuyerId": "123456"
416 },
417 "distributionType": "postal",
418 "taxIdentificationNumber" : "987654321"
419 }
420 {{/code}}
421
422 Update only emailAddress
423
424 {{code language="http" title="**Request**"}}
425 PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
426 Host: -
427 Authorization: Bearer <Token>
428 Content-Type: application/json
429
430 {
431 "emailAddress" : "britt@axelstopp.com"
432 }
433 {{/code}}
434
435 Update emailAddress and delete msisdn
436
437 {{code language="http" title="**Request**"}}
438 PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
439 Host: -
440 Authorization: Bearer <Token>
441 Content-Type: application/json
442
443 {
444 "emailAddress" : "britt@axelstopp.com",
445 "msisdn" : null
446 }
447 {{/code}}
448
449 Remove EDIAddressInfo on a customer
450
451 {{code language="http" title="**Request**"}}
452 PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
453 Host: -
454 Authorization: Bearer <Token>
455 Content-Type: application/json
456
457 {
458 "eDIAddressInfo" : null
459 }
460 {{/code}}
461
462
463 ----
464
465 (% id="HAccountresourceproperties" %)
466 ==== Customer resource properties ====
467
468 (% class="table-bordered table-striped" %)
469 |=(% style="width: 343px;" %)Property|=(% style="width: 137px;" %)Data type|=(% style="width: 230px;" %)Format|=(% style="width: 1076px;" %)Description
470 |(% style="width:343px" %)@id |(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)Uri of the specific customer
471 |(% style="width:343px" %)customerNo|(% style="width:137px" %)string|(% style="width:230px" %)MinLength: 1
472 MaxLength: 15*
473 numeric, 1-9 |(% style="width:1076px" %)The unique identifier of the customer
474 MaxLength may differ depending on configuration
475 KID (Norway)
476 |(% style="width:343px" %)__**nationalIdentifier**__|(% style="width:137px" %)object|(% style="width:230px" %) |(% style="width:1076px" %)
477 |(% style="width:343px" %) nationalIdentifier.regNo|(% style="width:137px" %)string|(% style="width:230px" %)Country specific|(% style="width:1076px" %)Sweden: YYYYMMDD-NNNC
478 Norway: DDMMYYNNNNN
479 |(% style="width:343px" %) nationalIdentifier.countryCode|(% style="width:137px" %)string|(% style="width:230px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1076px" %)
480 |(% style="width:343px" %)vatNo|(% style="width:137px" %)string|(% style="width:230px" %)MinLength: 7
481 MaxLength: 17
482 Regex pattern:
483 [A-Z]{2}.*|(% style="width:1076px" %)Customer VAT registration number. Mandatory if reverse tax is used. Must conform to country specific algorithm
484 |(% style="width:343px" %)legalEntity|(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)Valid values:
485 "consumer"
486 "business"
487 |(% style="width:343px" %)name|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 72
488 Regex?|(% style="width:1076px" %)Full name of end-customer
489 |(% style="width:343px" %)emailAddress|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 254
490 Regex pattern: [^@]+@[^\.]+\..+|(% style="width:1076px" %)
491 |(% style="width:343px" %)protectedIdentity|(% style="width:137px" %)bool|(% style="width:230px" %) |(% style="width:1076px" %)Set to true if the customer has protected identity
492 Postal distribution will be handled by "Skatteverket". **Only supported in Sweden**
493 |(% style="width:343px" %)preferredLanguageCode|(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)(((
494 Valid values:
495
496 * **SV**
497 * **NO**
498 * **DA**
499 * **FI**
500 * **EN**
501 )))
502 |(% style="width:343px" %)legalStatus|(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)(((
503 Valid values:
504
505 * active
506 * deceased
507 )))
508 |(% style="width:343px" %)msisdn|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 15
509 Minlength: 5
510 +NNNN|(% style="width:1076px" %) "Mobile Subscriber Integrated Services Digital Network Number", ie. Cellphone number
511 Countrycode is always required as the example below
512 +46720000000
513 |(% style="width:343px" %)distributionType|(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)Sets distribution type. Allowed values are:(((
514 * **postal **
515 * **noDistribution **
516 )))
517 |(% style="width:343px" %)taxIdentificationNumber|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 20
518 Minlength: 1|(% style="width:1076px" %)Is an identification number used by the Internal Revenue Service (IRS) in the administration of tax laws
519 |(% style="width:343px" %)**activeConsents**|(% style="width:137px" %)object|(% style="width:230px" %) |(% style="width:1076px" %)List of strings with possible values:(((
520 * (((
521 (% data-pm-slice="1 1 [~"table~",{~"isNumberColumnEnabled~":false,~"layout~":~"default~",~"__autoSize~":false,~"localId~":~"c8de3c26-1280-4cb1-a8ea-e56f5b08d910~"},~"tableRow~",null,~"tableCell~",{~"colspan~":1,~"rowspan~":1,~"colwidth~":null,~"background~":null}]" %)
522 **Autogiro**
523 )))
524 * (((
525 (% data-pm-slice="1 1 [~"table~",{~"isNumberColumnEnabled~":false,~"layout~":~"default~",~"__autoSize~":false,~"localId~":~"c8de3c26-1280-4cb1-a8ea-e56f5b08d910~"},~"tableRow~",null,~"tableCell~",{~"colspan~":1,~"rowspan~":1,~"colwidth~":null,~"background~":null}]" %)
526 **Avtalegiro**
527 )))
528 * (((
529 (% data-pm-slice="1 1 [~"table~",{~"isNumberColumnEnabled~":false,~"layout~":~"default~",~"__autoSize~":false,~"localId~":~"c8de3c26-1280-4cb1-a8ea-e56f5b08d910~"},~"tableRow~",null,~"tableCell~",{~"colspan~":1,~"rowspan~":1,~"colwidth~":null,~"background~":null}]" %)
530 **Betalingsservice**
531 )))
532 * (((
533 (% data-pm-slice="1 1 [~"table~",{~"isNumberColumnEnabled~":false,~"layout~":~"default~",~"__autoSize~":false,~"localId~":~"c8de3c26-1280-4cb1-a8ea-e56f5b08d910~"},~"tableRow~",null,~"tableCell~",{~"colspan~":1,~"rowspan~":1,~"colwidth~":null,~"background~":null}]" %)
534 **RecurringCard**
535 )))
536 * (((
537 (% data-pm-slice="1 1 [~"table~",{~"isNumberColumnEnabled~":false,~"layout~":~"default~",~"__autoSize~":false,~"localId~":~"c8de3c26-1280-4cb1-a8ea-e56f5b08d910~"},~"tableRow~",null,~"tableCell~",{~"colspan~":1,~"rowspan~":1,~"colwidth~":null,~"background~":null}]" %)
538 **RecurringInvoiceToken**
539 )))
540 * (((
541 (% data-pm-slice="1 1 [~"table~",{~"isNumberColumnEnabled~":false,~"layout~":~"default~",~"__autoSize~":false,~"localId~":~"c8de3c26-1280-4cb1-a8ea-e56f5b08d910~"},~"tableRow~",null,~"tableCell~",{~"colspan~":1,~"rowspan~":1,~"colwidth~":null,~"background~":null}]" %)
542 **EInvoice**
543 )))
544 * (((
545 (% data-pm-slice="1 1 [~"table~",{~"isNumberColumnEnabled~":false,~"layout~":~"default~",~"__autoSize~":false,~"localId~":~"c8de3c26-1280-4cb1-a8ea-e56f5b08d910~"},~"tableRow~",null,~"tableCell~",{~"colspan~":1,~"rowspan~":1,~"colwidth~":null,~"background~":null}]" %)
546 **Kivra**
547 )))
548 * (((
549 (% data-pm-slice="1 1 [~"table~",{~"isNumberColumnEnabled~":false,~"layout~":~"default~",~"__autoSize~":false,~"localId~":~"c8de3c26-1280-4cb1-a8ea-e56f5b08d910~"},~"tableRow~",null,~"tableCell~",{~"colspan~":1,~"rowspan~":1,~"colwidth~":null,~"background~":null}]" %)
550 **EBoks**
551 )))
552 )))
553 |(% style="width:343px" %)__**eDIAddressInfo**__|(% style="width:137px" %)object|(% style="width:230px" %) |(% style="width:1076px" %)EDI addressing info
554 |(% style="width:343px" %) eDIAddressInfo.van|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 255|(% style="width:1076px" %)(((
555 Buyer VAN identifier (OperatorId)
556 )))
557 |(% style="width:343px" %) eDIAddressInfo.interChangeRecipient|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 13|(% style="width:1076px" %)Routing address. EAN
558 |(% style="width:343px" %) eDIAddressInfo.BuyerId|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 13|(% style="width:1076px" %)NAD_BY/Buyerparty. EAN/Corporate identity number
559 |(% style="width:343px" %)legalAddress|(% style="width:137px" %)uri|(% style="width:230px" %) |(% style="width:1076px" %)reference to the customers legal address
560 |(% style="width:343px" %)billingAddress|(% style="width:137px" %)uri|(% style="width:230px" %) |(% style="width:1076px" %)reference to the customer billing address
561 |(% style="width:343px" %)surpluses|(% style="width:137px" %)uri|(% style="width:230px" %) |(% style="width:1076px" %)reference to the customer surpluses
562
563 ==== Operations ====
564
565 Depending on the current permissions the following operations is supported on the customer resource
566
567 ===== add-billing-address =====
568
569 Method: POST
570 This operation will be available if no billing-address exists on the customer, see [[billing-address>>Main.Invoicing.invoice-service.Implementation guide.Technical reference.API.CustomerApi.WebHome||anchor="HAddabilling-address"]] resource for more details
571
572 ----
573
574 == Surpluses ==
575
576 A surplus is the remaining value from a payment that was greater than the current debt, also referred as an 'overpayment'. Each instance of an overpayment will create a new surplus. A surplus will often have a connection to an account or invoice based of where the payment was placed but surpluses without connection to an account or invoice also exist. Surpluses can be used to settle upcoming debt or be disbursed.
577
578 ==== Get specified Surplus information ====
579
580 {{code language="http" title="**Request**"}}
581 GET /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY HTTP/1.1
582 Host: -
583 Authorization: Bearer <Token>
584 Content-Type: application/json
585 {{/code}}
586
587
588 {{code language="http" title="**Response**"}}
589 HTTP/1.1 200 OK
590 Content-Type: application/json
591
592 {
593 "surplusId": "YYY",
594 "balance": 10.00,
595 "currency": "SEK",
596 "date": "2023-01-01T00:00:00",
597 "status": "open",
598 "invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
599 "account": "/ledger/account/v1/XXX/accounts/BBB",
600 "operations": [],
601 "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/YYY"
602
603 {{/code}}
604
605 ==== Get list of Surpluses Information ====
606
607 {{code language="http" title="**Request**"}}
608 GET /ledger/customer/v1/XXX/customers/NNN/surpluses HTTP/1.1
609 Host: -
610 Authorization: Bearer <Token>
611 Content-Type: application/json
612 {{/code}}
613
614
615 {{code language="http" title="**Response**"}}
616 HTTP/1.1 200 OK
617 Content-Type: application/json
618
619 {
620 "items": [
621 {
622 "surplusId": "123",
623 "balance": 10.00,
624 "currency": "SEK",
625 "date": "2023-01-01T00:00:00",
626 "status": "open",
627 "invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
628 "operations": [],
629 "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/123"
630
631 },
632 {
633 "surplusId": "456",
634 "balance": 20.00,
635 "currency": "SEK",
636 "date": "2023-01-02T00:00:00",
637 "status": "pending-disbursement",
638 "account": "/ledger/account/v1/XXX/accounts/BBB",
639 "operations": [],
640 "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/456"
641
642 },
643 {
644 "surplusId": "789",
645 "balance": 30.00,
646 "currency": "SEK",
647 "date": "2023-01-03T00:00:00",
648 "status": "pending-regulate",
649 "invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
650 "operations": [],
651 "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/789"
652
653 }
654 ],
655 "navigation": {
656 "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses",
657 "first": "/ledger/customer/v1/XXX/customers/NNN/surpluses?skip=0",
658 "previous": "/ledger/customer/v1/XXX/customers/NNN/surpluses?skip=0"
659 }
660 }
661 {{/code}}
662
663
664 ==== Surpluses resource properties ====
665
666 (% class="table-bordered table-striped" %)
667 |=(% style="width: 248px;" %)Property|=(% style="width: 108px;" %)Data type|=(% style="width: 233px;" %)Format|=(% style="width: 1196px;" %)Description
668 |(% style="width:248px" %)@id |(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: |(% style="width:1196px" %)Uri of the specific surplus
669 |(% style="width:248px" %)surplusId|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 50|(% style="width:1196px" %)Value is not considered case sensitive
670 |(% style="width:248px" %)balance|(% style="width:108px" %)string|(% style="width:233px" %) |(% style="width:1196px" %)Amount value for the surplus, always a positive value
671 |(% style="width:248px" %)currency|(% style="width:108px" %)string|(% style="width:233px" %)[[ISO 4217>>https://sv.wikipedia.org/wiki/ISO_4217]]|(% style="width:1196px" %)
672 |(% style="width:248px" %)date|(% style="width:108px" %)date|(% style="width:233px" %)yyyy-MM-ddTHH:mm:ss|(% style="width:1196px" %)Surplus creation date
673 |(% style="width:248px" %)status|(% style="width:108px" %)string|(% style="width:233px" %) |(% style="width:1196px" %)Expected statuses: open ~| pending-disbursement ~| pending-regulate
674 After a surplus has been depleted it will no longer be returned from the API
675 |(% style="width:248px" %)invoice|(% style="width:108px" %)string|(% style="width:233px" %) |(% style="width:1196px" %)Relative Uri to the connected source of the surplus through the Invoice API. A surplus can have a connection to an account or invoice but not both.
676 |(% style="width:248px" %)account|(% style="width:108px" %)string|(% style="width:233px" %) |(% style="width:1196px" %)Relative Uri to the connected source of the surplus through the Account API. A surplus can have a connection to an account or invoice but not both.
677
678 ----
679
680 == (% style="color:inherit; font-family:inherit" %)Active-Disbursement-Orders(%%) ==
681
682 This shows if current surplus has been ordered to disburse the surplus to the end customer.
683
684 ==== Get active disbursement orders ====
685
686
687 {{code language="http" title="**Request**"}}
688 GET /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1
689 Host: -
690 Authorization: Bearer <Token>
691 Content-Type: application/json
692 {{/code}}
693
694
695 {{code language="http" title="**Response**"}}
696 HTTP/1.1 200 OK
697 Content-Type: application/json
698
699 {
700 "items": [
701 {
702 "operations": [],
703 "swedishBankAccount": {
704 "accountNo": "3300-1010101010",
705 "accountType": "BKSE"
706 }
707 }
708 ],
709 "navigation": {
710 "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders"
711 }
712 }
713 {{/code}}
714
715 (% id="HOperations" %)
716 ==== Operations ====
717
718 Depending on the current permissions the following operations is supported on the surplus resource
719
720 (% id="Hadd-billing-address" %)
721 ===== add-disbursement-orders =====
722
723 Method: POST
724 This operation will be available if agreed with payex.
725
726 (% id="HActive-payment-ordersresourceproperties" %)
727 ==== request properties ====
728
729 (% class="table-bordered table-striped" %)
730 |=Property|=Data type|=Required|=Description
731 |__**norwegianBankAccount**__|object|No*|
732 | accountNo|string|Yes|
733 |__**swedishBankAccount**__|object|No*|
734 | clearingNo|string|Yes|
735 | accountNo|string|Yes|
736 |__**international**__|object|No*|
737 | iban|string|Yes|
738 | bic|string|Yes|
739 |__**swedishSus**__|object|No*|
740 |**nationalIdentifier**|object|Yes|
741 | regNo|string|Yes|
742 | countryCode|string|Yes|
743 |**address**|object|Yes|
744 | addressee|string|Yes|
745 | streetAddress|string|No|
746 | coAddress|string|No|
747 | city|string|Yes|
748 | zipCode|string|Yes|
749 | countryCode|string|Yes|
750 | | | |
751
752 //* One and only one of the specified objects can be set at each request//
753
754 Examples
755
756 Create disbursement with swedish bank account
757
758 {{code language="http" title="**Request**"}}
759 POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1
760 Host: -
761 Authorization: Bearer <Token>
762 Content-Type: application/json
763
764 {
765 "SwedishBankAccount" : {
766 "AccountNo":"944-1049000",
767 "AccountType":"BGSE"
768 }
769 }
770 {{/code}}
771
772 Create a disbursement order with a norwegian bankaccount
773
774 {{code language="http" title="**Request**"}}
775 POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1
776 Host: -
777 Authorization: Bearer <Token>
778 Content-Type: application/json
779
780 {
781 "norwegianBankAccount" : {
782 "accountNo" : "1234"
783 }
784 }
785 {{/code}}
786
787 Create a disbursement order with an international bankaccount
788
789 {{code language="http" title="**Request**"}}
790 POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1
791 Host: -
792 Authorization: Bearer <Token>
793 Content-Type: application/json
794
795 {
796 "international" : {
797 "iban" : "123456",
798 "bic" : "SWED..."
799 }
800 }
801 {{/code}}
802
803 Create disbursement order using "Swedbanks lön- och utbetalningssystem (SUS)"
804
805 {{code language="http" title="**Request**"}}
806 POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1
807 Host: -
808 Authorization: Bearer <Token>
809 Content-Type: application/json
810
811 {
812 "swedishSus" : {
813 "nationalIdentifier": {
814 "regNo" : "YYYYMMDD-NNNN",
815 "countryCode" : "SE"
816 },
817 "address" : {
818 "addressee" : "Kalle Axelstopp",
819 "streetAddress" : "Axelgatan 18",
820 "coAddress" : null,
821 "city" : "STOCKHOLM",
822 "zipCode" : "16872",
823 "countryCode" : "se",
824 }
825 }
826 }
827 {{/code}}
828
829 (% aria-label="macro:code widget" contenteditable="false" role="region" tabindex="-1" %)
830 (((
831
832 )))
833
834 == (% style="color:inherit; font-family:inherit" %)Legal-address(%%) ==
835
836 The legal address is where claims is normally sent to. It is required for a customer to have a legal address registered
837
838 ==== Get the legal address of the customer ====
839
840 {{code language="http" title="**Request**"}}
841 GET /ledger/customer/v1/XXX/customers/NNN/legal-address HTTP/1.1
842 Host: -
843 Authorization: Bearer <Token>
844 Content-Type: application/json
845 {{/code}}
846
847
848 {{code language="http" title="**Response**"}}
849 HTTP/1.1 200 OK
850 Content-Type: application/json
851
852 {
853 "addressee" : "Britt-Marie Axelstopp",
854 "streetAddress" : "The street 18",
855 "coAddress" : "c/o Jansson",
856 "city" : "STOCKHOLM",
857 "zipCode" : "15961",
858 "countryCode" : "SE",
859 "operations" :
860 [
861 {
862 "rel" : "update",
863 "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
864 "method" : "PUT"
865 },
866 {
867 "rel" : "update-legal-address-from-population-register",
868 "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address/update-legal-address-from-population-register",
869 "method" : "POST"
870 }
871 ]
872 }
873 {{/code}}
874
875 ==== Operations ====
876
877 Depending on the current permissions the following operations is supported on the legal address resource
878
879 ===== Update (replace) =====
880
881 Method: PUT
882 Use this operation to update the address, this "PUT" operation will replace the existing billing-address with the address specified in the request body.
883
884 (% class="table-bordered table-striped" %)
885 |=(% style="width: 183px;" %)Property|=(% style="width: 1602px;" %)Required
886 |(% style="width:183px" %)addressee|(% style="width:1602px" %)Yes
887 |(% style="width:183px" %)streetAddress|(% style="width:1602px" %)No
888 |(% style="width:183px" %)coAddress|(% style="width:1602px" %)No
889 |(% style="width:183px" %)city|(% style="width:1602px" %)Yes
890 |(% style="width:183px" %)zipCode|(% style="width:1602px" %)Yes
891 |(% style="width:183px" %)countryCode|(% style="width:1602px" %)Yes
892
893 Example
894
895 {{code language="http" title="**Request**"}}
896 PUT /ledger/customer/v1/XXX/customers/NNN/legal-address HTTP/1.1
897 Host: -
898 Authorization: Bearer <Token>
899 Content-Type: application/json
900
901 {
902 "addressee" : "Kalle Axelstopp",
903 "streetAddress" : "Axelgatan 18",
904 "city" : "STOCKHOLM",
905 "zipCode" : "16872",
906 "countryCode" : "SE"
907 }
908 {{/code}}
909
910
911 ----
912
913 ===== update-legal-address-from-population-register =====
914
915 Method: POST
916 Execution of this operation will result in an attempt to retrieve (and replace) the customer's legal address from the population registry.
917
918 (% class="box infomessage" %)
919 (((
920 Access to this operation is not normally granted, unless otherwise agreed.
921 )))
922
923 {{code language="http" title="**Request**"}}
924 POST /ledger/customer/v1/XXX/customers/NNN/legal-address/update-legal-address-from-population-register HTTP/1.1
925 Host: -
926 Authorization: Bearer <Token>
927 Content-Type: application/json
928
929 {
930 }
931 {{/code}}
932
933 ----
934
935 ==== Legal-address resource properties ====
936
937 (% class="table-bordered table-striped" %)
938 |=(% style="width: 161px;" %)Property|=(% style="width: 121px;" %)Data type|=(% style="width: 195px;" %)Format|=(% style="width: 1309px;" %)Description
939 |(% style="width:161px" %)addressee|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 72|(% style="width:1309px" %)Fullname
940 |(% style="width:161px" %)streetAddress|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 72|(% style="width:1309px" %)
941 |(% style="width:161px" %)coAddress|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 72|(% style="width:1309px" %)Care of (C/O) name. This is optional.
942 |(% style="width:161px" %)city|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 27|(% style="width:1309px" %)
943 |(% style="width:161px" %)zipCode|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 9|(% style="width:1309px" %)ZipCode without whitespaces
944 |(% style="width:161px" %)countryCode|(% style="width:121px" %)string|(% style="width:195px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1309px" %)
945
946 ----
947
948 == Billing-address ==
949
950 The billing address is where invoices/bills/letters etc. is normally sent to.This address is optional
951
952 ==== Get the billing address of the customer ====
953
954 {{code language="http" title="**Request**"}}
955 GET /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
956 Host: -
957 Authorization: Bearer <Token>
958 Content-Type: application/json
959 {{/code}}
960
961
962 {{code language="http" title="**Response**"}}
963 HTTP/1.1 200 OK
964 Content-Type: application/json
965
966 {
967 "addressee" : "Kalle Axelstopp",
968 "streetAddress" : "Axelgatan 18",
969 "coAddress" : "c/o Jansson",
970 "city" : "STOCKHOLM",
971 "zipCode" : "16872",
972 "countryCode" : "SE",
973 "operations" :
974 [
975 {
976 "rel" : "update",
977 "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
978 "method" : "PUT"
979 },
980 {
981 "rel" : "delete",
982 "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
983 "method" : "DELETE"
984 }
985 ]
986 }
987 {{/code}}
988
989 ==== Add a billing-address ====
990
991 (% class="table-bordered table-striped" %)
992 |=(% style="width: 183px;" %)Property|=(% style="width: 1602px;" %)Required
993 |(% style="width:183px" %)addressee|(% style="width:1602px" %)Yes
994 |(% style="width:183px" %)streetAddress|(% style="width:1602px" %)No
995 |(% style="width:183px" %)coAddress|(% style="width:1602px" %)No
996 |(% style="width:183px" %)city|(% style="width:1602px" %)Yes
997 |(% style="width:183px" %)zipCode|(% style="width:1602px" %)Yes
998 |(% style="width:183px" %)countryCode|(% style="width:1602px" %)Yes
999
1000 {{code language="http" title="**Request**"}}
1001 POST /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
1002 Host: -
1003 Authorization: Bearer <Token>
1004 Content-Type: application/json
1005
1006 {
1007 "addressee" : "Kalle Axelstopp",
1008 "streetAddress" : "Axelgatan 18",
1009 "city" : "STOCKHOLM",
1010 "zipCode" : "16872",
1011 "countryCode" : "SE"
1012 }
1013 {{/code}}
1014
1015 ==== Operations ====
1016
1017 Depending on the current permissions the following operations is supported on the billing address resource
1018
1019 ===== Update (replace) =====
1020
1021 Method: PUT
1022 Use this operation to update the address, the "PUT" body of the request should be accoring to the properties of the resource.
1023
1024 (% class="table-bordered table-striped" %)
1025 |=(% style="width: 183px;" %)Property|=(% style="width: 1602px;" %)Required
1026 |(% style="width:183px" %)addressee|(% style="width:1602px" %)Yes
1027 |(% style="width:183px" %)streetAddress|(% style="width:1602px" %)No
1028 |(% style="width:183px" %)coAddress|(% style="width:1602px" %)No
1029 |(% style="width:183px" %)city|(% style="width:1602px" %)Yes
1030 |(% style="width:183px" %)zipCode|(% style="width:1602px" %)Yes
1031 |(% style="width:183px" %)countryCode|(% style="width:1602px" %)Yes
1032
1033 {{code language="http" title="**Request**"}}
1034 PUT /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
1035 Host: -
1036 Authorization: Bearer <Token>
1037 Content-Type: application/json
1038
1039 {
1040 "addressee" : "Kalle Axelstopp",
1041 "streetAddress" : "Axelgatan 18",
1042 "city" : "STOCKHOLM",
1043 "zipCode" : "16872",
1044 "countryCode" : "SE"
1045 }
1046 {{/code}}
1047
1048 ===== Delete =====
1049
1050 Method: DELETE
1051 Use this operation to delete the billing address.
1052
1053 {{code language="http" title="**Request**"}}
1054 DELETE /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
1055 Host: -
1056 Authorization: Bearer <Token>
1057 Content-Type: application/json
1058
1059 {
1060 }
1061 {{/code}}
1062
1063 ==== Billing-address resource properties ====
1064
1065 (% class="table-bordered table-striped" %)
1066 |=Property|=(% style="width: 94px;" %)Data type|=(% style="width: 255px;" %)Format|=(% style="width: 1053px;" %)Description
1067 |addressee|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 72|(% style="width:1053px" %)Fullname
1068 |streetAddress|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 72|(% style="width:1053px" %)
1069 |coAddress|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 72|(% style="width:1053px" %)Care of (C/O) name. This is optional.
1070 |city|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 27|(% style="width:1053px" %)
1071 |zipCode|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 9|(% style="width:1053px" %)ZipCode without whitespaces
1072 |countryCode|(% style="width:94px" %)string|(% style="width:255px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1053px" %)
1073
1074 ----
1075
1076 == Consent ==
1077
1078 The consent resource is used to get the underlying resources that display information or enable registration of a customer's consent.
1079
1080 ==== Get the underlying consent resources of the customer ====
1081
1082 {{code language="http" title="**Request**"}}
1083 GET /ledger/customer/v1/XXX/customers/NNN/consent HTTP/1.1
1084 Host: -
1085 Authorization: Bearer <Token>
1086 Content-Type: application/json
1087 {{/code}}
1088
1089
1090 {{code language="http" title="**Response**"}}
1091 HTTP/1.1 200 OK
1092 Content-Type: application/json
1093
1094 {
1095 "recurringCard": "/ledger/customer/v1/XXX/customers/NNN/consent/recurring-card",
1096 "recurringCardRedirectRegistration": "/ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration"
1097 }
1098 {{/code}}
1099
1100 ==== Consent resource properties ====
1101
1102 (% class="table-bordered table-striped" %)
1103 |=Property|=(% style="width: 94px;" %)Data type|=(% style="width: 255px;" %)Format|=(% style="width: 1053px;" %)Description
1104 |recurringCard|(% style="width:94px" %)string|(% style="width:255px" %)Path|(% style="width:1053px" %)Endpoint to resource
1105 |recurringCardRedirectRegistration|(% style="width:94px" %)string|(% style="width:255px" %)Path|(% style="width:1053px" %)Endpoint to resource
1106
1107 ----
1108
1109 ==== Recurring-card ====
1110
1111 This resource provides details about the customer's active Recurring Card Consent and the ability to remove it.
1112
1113 ===== Get customer active Recurring Card Consent =====
1114
1115 {{code language="http" title="**Request**"}}
1116 GET /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card HTTP/1.1
1117 Host: -
1118 Authorization: Bearer <Token>
1119 Content-Type: application/json
1120 {{/code}}
1121
1122
1123 {{code language="http" title="**Response**"}}
1124 HTTP/1.1 200 OK
1125 Content-Type: application/json
1126
1127 {
1128 "cardToken": "2eb28854-07ec-4e88-b672-7c61cc54b461",
1129 "consentExpiryDate": "04-2035",
1130 "instrumentDisplayName": "551000******1232",
1131 "cardExpiryDate": "04/2035"
1132 }
1133 {{/code}}
1134
1135 ===== Delete customer active Recurring Card Consent =====
1136
1137 {{code language="http" title="**Request**"}}
1138 DELETE /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card HTTP/1.1
1139 Host: -
1140 Authorization: Bearer <Token>
1141 Content-Type: application/json
1142
1143 {
1144 }
1145 {{/code}}
1146
1147 {{code language="http" title="**Response**"}}
1148 HTTP/1.1 204 NoContent
1149 Content-Type: application/json
1150
1151 {
1152 }
1153 {{/code}}
1154
1155 ===== Recurring-card resource properties =====
1156
1157 (% class="table-bordered table-striped" %)
1158 |=Property|=(% style="width: 94px;" %)Data type|=(% style="width: 255px;" %)Format|=(% style="width: 1053px;" %)Description
1159 |cardToken|(% style="width:94px" %)string|(% style="width:255px" %)Guid|(% style="width:1053px" %)Card Token Id
1160 |consentExpiryDate|(% style="width:94px" %)string|(% style="width:255px" %)Date (MM-yyyy)|(% style="width:1053px" %)Expiry date of the consent
1161 |instrumentDisplayName|(% style="width:94px" %)string|(% style="width:255px" %)Masked number|(% style="width:1053px" %)Masked card number used in the presentation layer
1162 |cardExpiryDate|(% style="width:94px" %)string|(% style="width:255px" %)Date (MM/yyyy)|(% style="width:1053px" %)Expiry date of the card
1163
1164 ----
1165
1166 ==== Recurring-card-redirect-registration ====
1167
1168 Initializes the customer's Recurring Card registration with redirect to SwedbankPay. The resource should be inquired until the status reaches an end status. Only one registration can be active at a time.
1169
1170 ===== Start a Recurring Card registration =====
1171
1172 (% class="table-bordered table-striped" %)
1173 |=(% style="width: 509px;" %)Property|=(% style="width: 161px;" %)Required|=(% style="width: 1852px;" %)Comment
1174 |(% style="width:509px" %)completeUrl|(% style="width:161px" %)Yes|(% style="width:1852px" %)Redirect Url to be used if the user completes the card verification process.
1175 |(% style="width:509px" %)cancelUrl|(% style="width:161px" %)Yes|(% style="width:1852px" %)Redirect Url to be used if the user cancels the card verification process.
1176 |(% style="width:509px" %)language|(% style="width:161px" %)Yes|(% style="width:1852px" %)A language specified in the ISO 639-1 language code and with two letter country codes in the format "xx-YY". The following pairs are available: "en-US", "sv-SE", "nb-NO", "da-DK" and "fi-FI".
1177
1178 {{code language="http" title="**Request**"}}
1179 POST /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration HTTP/1.1
1180 Host: -
1181 Authorization: Bearer <Token>
1182 Content-Type: application/json
1183
1184 {
1185 "completeUrl": "https://www.google.com/search?q=cancelurl",
1186 "cancelUrl": "https://www.google.com/search?q=completeurl",
1187 "language": "en-US"
1188 }
1189 {{/code}}
1190
1191
1192 {{code language="http" title="**Response**"}}
1193 HTTP/1.1 200 OK
1194 Content-Type: application/json
1195
1196 {
1197 "redirectUrl": "https://ecom.externalintegration.payex.com/checkout/abc123",
1198 "status": "Initialized",
1199 "@id": "/ledger/customer/v1/xxx/customers/yyy/consent/recurring-card-redirect-registration"
1200 }
1201 {{/code}}
1202
1203 ===== Get Recurring Card Redirect Registration =====
1204
1205 {{code language="http" title="**Request**"}}
1206 GET /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration HTTP/1.1
1207 Host: -
1208 Authorization: Bearer <Token>
1209 Content-Type: application/json
1210
1211 {
1212 }
1213 {{/code}}
1214
1215
1216 {{code language="http" title="**Response**"}}
1217 HTTP/1.1 200 OK
1218 Content-Type: application/json
1219
1220 {
1221 "redirectUrl": "https://ecom.externalintegration.payex.com/checkout/abc123",
1222 "status": "Initialized"
1223 }
1224 {{/code}}
1225
1226 ===== Recurring-card-redirect-registration resource properties =====
1227
1228 (% class="table-bordered table-striped" %)
1229 |=Property|=(% style="width: 94px;" %)Data type|=(% style="width: 255px;" %)Format|=(% style="width: 1053px;" %)Description
1230 |redirectUrl|(% style="width:94px" %)string|(% style="width:255px" %)Url|(% style="width:1053px" %)The redirect url to a flow that confirms the validity of card information without reserving or charging any amount.
1231 |status|(% style="width:94px" %)string|(% style="width:255px" %) |(% style="width:1053px" %)Status of the card validity verification process. One of the following: "Initialized", "Completed", "Aborted" or "Failed".
1232
1233 ----
1234
1235 == Find customer ==
1236
1237 The **find customer **resource is located under **ledger/customer/v1/ **api**. **It is used to find customer with nationalIdentifier.
1238
1239 (% class="table-bordered table-striped" %)
1240 |=(% style="width: 222px;" %)Property|=(% style="width: 1562px;" %)Required
1241 |(% style="width:222px" %)nationalIdentifier.regNo|(% style="width:1562px" %)Yes
1242 |(% style="width:222px" %)nationalIdentifier.countryCode|(% style="width:1562px" %)Yes
1243
1244 {{code language="http" title="**Request**"}}
1245 POST /ledger/customer/v1/XXX/find-customer HTTP/1.1
1246 Host: -
1247 Authorization: Bearer <Token>
1248 Content-Type: application/json
1249
1250 {
1251 "nationalIdentifier": {
1252 "regNo" : "YYYYMMDD-NNNN",
1253 "countryCode" : "SE"
1254 }
1255 }
1256 {{/code}}
1257
1258 {{code language="http" title="**Response**"}}
1259 HTTP/1.1 200 OK
1260 Content-Type: application/json
1261
1262 {
1263 "@id" : "/ledger/customer/v1/XXX/customers/9999",
1264 "customerNo" : " 9999"
1265 }
1266 {{/code}}
1267
1268 (% id="HAccountresourceproperties" %)
1269 ==== Find customer resource properties ====
1270
1271 (% class="table-bordered table-striped" %)
1272 |=(% style="width: 248px;" %)Property|=(% style="width: 108px;" %)Data type|=(% style="width: 233px;" %)Format|=(% style="width: 1196px;" %)Description
1273 |(% style="width:248px" %)@id |(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: |(% style="width:1196px" %)Uri of the specific customer
1274 |(% style="width:248px" %)customerNo|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 15|(% style="width:1196px" %)
1275 |(% style="width:248px" %)nationalIdentifier.regNo|(% style="width:108px" %)string|(% style="width:233px" %)Country specific|(% style="width:1196px" %)Sweden: YYYYMMDD-NNNC
1276 Norway: DDMMYYNNNNN
1277 |(% style="width:248px" %)nationalIdentifier.countryCode|(% style="width:108px" %)string|(% style="width:233px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1196px" %)
1278
1279 ----
1280
1281 == Generate customer ==
1282
1283 The **generate consumer customer by reg no **resource is located under **ledger/customer/v1/ **api**. **It is used to genarate a customer with a nationalIdentifier. It will retreive an legal address from the population register and create a consumer customer.
1284
1285 (% class="box infomessage" %)
1286 (((
1287 Access to this operation is not normally granted, unless otherwise agreed.
1288 )))
1289
1290 (% class="table-bordered table-striped" %)
1291 |=(% style="width: 222px;" %)Property|=(% style="width: 1562px;" %)Required
1292 |(% style="width:222px" %)customerNo|(% style="width:1562px" %)No
1293 |(% style="width:222px" %)nationalIdentifier.regNo|(% style="width:1562px" %)Yes
1294 |(% style="width:222px" %)nationalIdentifier.countryCode|(% style="width:1562px" %)Yes
1295 |(% style="width:222px" %)emailAddress|(% style="width:1562px" %)No
1296 |(% style="width:222px" %)msisdn|(% style="width:1562px" %)No
1297
1298 {{code language="http" title="**Request**"}}
1299 POST /ledger/customer/v1/XXX/generate-consumer-customer-by-reg-no HTTP/1.1
1300 Host: -
1301 Authorization: Bearer <Token>
1302 Content-Type: application/json
1303
1304 {
1305 "nationalIdentifier": {
1306 "regNo" : "YYYYMMDD-NNNN",
1307 "countryCode" : "SE"
1308 },
1309 "emailAddress" : "britt@axelstopp.com",
1310 "msisdn" : "+91485918841",
1311 "customerNo" : "9999"
1312 }
1313 {{/code}}
1314
1315 {{code language="http" title="**Response**"}}
1316 HTTP/1.1 201 CREATED
1317 Content-Type: application/json
1318
1319 {
1320 "@id" : "/ledger/customer/v1/XXX/customers/9999",
1321 "customerNo" : " 9999"
1322 }
1323 {{/code}}
1324
1325 (% id="HAccountresourceproperties" %)
1326 ==== Generate customer resource properties ====
1327
1328 (% class="table-bordered table-striped" %)
1329 |=(% style="width: 248px;" %)Property|=(% style="width: 108px;" %)Data type|=(% style="width: 233px;" %)Format|=(% style="width: 1196px;" %)Description
1330 |(% style="width:248px" %)@id |(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: |(% style="width:1196px" %)Uri of the specific customer
1331 |(% style="width:248px" %)customerNo|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 15|(% style="width:1196px" %)
1332 |(% style="width:248px" %)nationalIdentifier.regNo|(% style="width:108px" %)string|(% style="width:233px" %)Country specific|(% style="width:1196px" %)Sweden: YYYYMMDD-NNNC
1333 Norway: DDMMYYNNNNN
1334 |(% style="width:248px" %)nationalIdentifier.countryCode|(% style="width:108px" %)string|(% style="width:233px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1196px" %)
1335 |(% style="width:248px" %)emailAddress|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 254
1336 Regex pattern: [^@]+@[^\.]+\..+|(% style="width:1196px" %)
1337 |(% style="width:248px" %)msisdn|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 15|(% style="width:1196px" %) "Mobile Subscriber Integrated Services Digital Network Number", ie. Cellphone number
1338 +46720000000
1339
1340 {{display reference="developer:Main.Invoicing.ledger-api-general-docs.api-section-problems.WebHome"/}}
1341
1342 === Problem types ===
1343
1344 (% class="box infomessage" %)
1345 (((
1346 Note, each problem typecode is preceded by "ledger/customer/v1/problems/" in this API, e.g. the error "validation" in the table below will appear as typecode "ledger/customer/v1/problems/validation".
1347 )))
1348
1349 (% class="table-bordered table-striped" %)
1350 |=(% style="width: 537px;" %)Problem type (code)|=(% style="width: 172px;" %)Httpstatus|=(% style="width: 796px;" %)Description
1351 |(% style="width:537px" %)validation|(% style="width:172px" %)400|(% style="width:796px" %)occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
1352 |(% style="width:537px" %)forbidden|(% style="width:172px" %)403|(% style="width:796px" %)occurs if access to method is not allowed.
1353 |(% style="width:537px" %)not-found|(% style="width:172px" %)404|(% style="width:796px" %)specified resource not found
1354 |(% style="width:537px" %)customer-not-found|(% style="width:172px" %)404|(% style="width:796px" %)specified customer number does not exists
1355 |(% style="width:537px" %)legal-address-does-not-exists|(% style="width:172px" %)404|(% style="width:796px" %)legal address does not exists for the specified customer
1356 |(% style="width:537px" %)billing-address-does-not-exists|(% style="width:172px" %)404|(% style="width:796px" %)billing address does not exists for the specified customer
1357 |(% style="width:537px" %) |(% style="width:172px" %) |(% style="width:796px" %)