PayEx Developer Portal

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" %)

== Changelog ==

2023-01-17

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.

2024-04-26

Added TaxIdentificationNumber to the Customer resource with planned release 2024-05-28

2024-05-15

Added Consent and underlying resources with planned release 2024-05-28. Updated Introduction API overview visual.

2025-02-14

Added operation Update-Kyc-Answers and updates to the Customer resource Operations list to reflect that. Planned release 2025-03-04

57

58

Added resource Kyc-Questions. Planned release 2025-03-04

== Customer ==

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.

64

65

==== (% style="color:inherit; font-family:inherit" %)Get a specific customer(%%) ====

66

67

68

GET /ledger/customer/v1/XXX/customers/NNN HTTP/1.1

69

Host: -

70

Authorization: Bearer <Token>

71

Content-Type: application/json

==== ====

HTTP/1.1 200 OK

Content-Type: application/json

79

80

{

81

"@id" : "/ledger/customer/v1/XXX/customers/9999",

82

"customerNo" : "9999",

83

"nationalIdentifier": {

84

"regNo" : "YYYYMMDD-NNNN",

85

"countryCode" : "SE"

86

},

87

"vatNo" : "SE101010101001",

88

"legalEntity" : "consumer|business",

89

"name" : "Britt-Marie Axelstopp",

90

"emailAddress" : "britt@axelstopp.com",

91

"protectedIdentity": false,

92

"preferredLanguageCode": "SV",

93

"legalStatus": "active",

94

"msisdn" : "+91485918841",

"activeConsents": [

"Betalingsservice",

"Avtalegiro"

],

"eDIAddressInfo" : {

"VAN": "ABCXYZ",

"InterChangeRecipient": "Recipient_ID1",

102

"BuyerId": "123465"

103

},

104

"legalAddress" : "/ledger/customer/v1/XXX/customers/9999/legal-address",

105

"billingAddress" : "/ledger/customer/v1/XXX/customers/9999/billing-address",

106

"surpluses": "/ledger/customer/v1/XXX/customers/9999/surpluses",

"operations" :

[

{

"rel": "partial-update-customer",

111

"method": "PATCH",

112

"href": "/ledger/customer/v1/XXX/customers/9999"

113

},

114

{

115

"rel": "add-billing-address",

116

"method": "POST",

117

"href": "/ledger/customer/v1/XXX/customers/9999/billing-address"

118

},

119

{

120

"rel": "update-kyc-answers",

121

"method": "POST",

122

"href": "/ledger/customer/v1/XXX/customers/9999/update-kyc-answers"

}

]

}

==== Get a specific customer using $expand ====

129

130

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.

131

132

(% class="box infomessage" %)

133

(((

134

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.

)))

GET /ledger/customer/v1/XXX/customers/NNN?$expand=legaladdress,billingaddress HTTP/1.1

139

Host: -

140

Authorization: Bearer <Token>

141

Content-Type: application/json

HTTP/1.1 200 OK

Content-Type: application/json

148

149

{

150

"@id" : "/ledger/customer/v1/XXX/customers/9999",

151

"customerNo" : "9999",

152

"nationalIdentifier": {

153

"regNo" : "YYYYMMDD-NNNN",

154

"countryCode" : "SE"

155

},

156

"vatNo" : "SE101010101001",

157

"legalEntity" : "consumer|business",

158

"name" : "Britt-Marie Axelstopp",

159

"emailAddress" : "britt@axelstopp.com",

160

"protectedIdentity": false,

161

"preferredLanguageCode": "SV",

162

"legalStatus": "active",

163

"msisdn" : "+91485918841",

"activeConsents": [

"Betalingsservice",

"Avtalegiro"

],

"eDIAddressInfo" : {

"VAN": "ABCXYZ",

"InterChangeRecipient": "Recipient_ID1",

"BuyerId": "123456"

},

"legalAddress" : {

"addressee" : "Britt-Marie Axelstopp",

175

"streetAddress" : "The street 18",

176

"coAddress" : "c/o Jansson",

177

"city" : "STOCKHOLM",

178

"zipCode" : "15961",

179

"countryCode" : "SE",

"operations" :

[

{

"rel" : "update",

"href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",

"method" : "PUT"

},

{

"rel" : "update-legal-address-from-population-register",

189

"href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",

"method" : "POST"

}

]

},

"billingAddress" : {

"addressee" : "Kalle Axelstopp",

196

"streetAddress" : "Axelgatan 18",

197

"city" : "STOCKHOLM",

198

"zipCode" : "16872",

199

"countryCode" : "se",

"operations" :

[

{

"rel" : "update",

"href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",

"method" : "PUT"

},

{

"rel" : "delete",

"href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",

"method" : "DELETE"

}

]

},

"surpluses": "/ledger/customer/v1/XXX/customers/9999/surpluses",

"operations" :

[

{

"rel" : "add-billing-address",

219

"href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",

"method" : "POST"

}

]

}

----

==== Create new customer ====

230

231

232

(% id="HImportanttonote21" %)

233

===== Important to note! =====

234

235

* Standard length of customerNo in Norway and Denmark is 7 characters (numeric only).

236

* Only use numeric characters and not with a leading zero for customerNo in Sweden, in order to use AutoGiro (Direct Debit).

237

* Dependency to legalEntity:

238

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

239

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

240

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

241

** Finland only: Different claim processes will be used depending on "consumer" or "business".

242

243

A new customer is created by making a POST call to the API.

244

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.

245

246

(% class="table-bordered table-striped" %)

247

|=(% style="width: 509px;" %)Property|=(% style="width: 161px;" %)Required|=(% style="width: 1852px;" %)Comment *

248

|(% 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.//

249

|(% 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.//

250

|(% style="width:509px" %) nationalIdentifier.regNo|(% style="width:161px" %)Yes|(% style="width:1852px" %)

251

|(% style="width:509px" %) nationalIdentifier.countryCode|(% style="width:161px" %)Yes|(% style="width:1852px" %)

252

|(% style="width:509px" %)vatNo|(% style="width:161px" %)No*|(% style="width:1852px" %)Required if reverse tax is used

253

|(% style="width:509px" %)legalEntity|(% style="width:161px" %)No|(% style="width:1852px" %)

254

|(% style="width:509px" %)name|(% style="width:161px" %)Yes|(% style="width:1852px" %)

255

|(% style="width:509px" %)preferredLanguageCode|(% style="width:161px" %)No|(% style="width:1852px" %)

256

|(% style="width:509px" %)emailAddress|(% style="width:161px" %)No|(% style="width:1852px" %)

257

|(% style="width:509px" %)msisdn|(% style="width:161px" %)No|(% style="width:1852px" %)

258

|(% style="width:509px" %)protectedIdentity|(% style="width:161px" %)No|(% style="width:1852px" %)

259

|(% style="width:509px" %)distributionType|(% style="width:161px" %)No|(% style="width:1852px" %)

260

|(% style="width:509px" %)taxIdentificationNumber|(% style="width:161px" %)No|(% style="width:1852px" %)

261

|(% style="width:509px" %)__**eDIAddressInfo**__|(% style="width:161px" %)No|(% style="width:1852px" %)

262

|(% style="width:509px" %) eDIAddressInfo.van|(% style="width:161px" %)No*|(% style="width:1852px" %)This field is required for distribution method EInvoiceB2B (EDI) to be used

263

|(% style="width:509px" %) eDIAddressInfo.interChangeRecipient|(% style="width:161px" %)No|(% style="width:1852px" %)

264

|(% style="width:509px" %) eDIAddressInfo.BuyerId|(% style="width:161px" %)Yes|(% style="width:1852px" %)

265

|(% style="width:509px" %)**__legalAddress__**|(% style="width:161px" %)Yes|(% style="width:1852px" %)

266

|(% style="width:183px" %) addressee|(% style="width:1602px" %)Yes|(% style="width:1852px" %)

267

|(% style="width:183px" %) streetAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)

268

|(% style="width:183px" %) coAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)

269

|(% style="width:183px" %) city|(% style="width:1602px" %)Yes|(% style="width:1852px" %)

270

|(% style="width:183px" %) zipCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)

271

|(% style="width:183px" %) countryCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)

272

|(% style="width:509px" %)**__billingAddress__**|(% style="width:161px" %)No|(% style="width:1852px" %)

273

|(% style="width:183px" %) addressee|(% style="width:1602px" %)Yes|(% style="width:1852px" %)

274

|(% style="width:183px" %) streetAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)

275

|(% style="width:183px" %) coAddress|(% style="width:1602px" %)No|(% style="width:1852px" %)

276

|(% style="width:183px" %) city|(% style="width:1602px" %)Yes|(% style="width:1852px" %)

277

|(% style="width:183px" %) zipCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)

278

|(% style="width:183px" %) countryCode|(% style="width:1602px" %)Yes|(% style="width:1852px" %)

===== Examples =====

(% class="wikigeneratedid" %)

283

Standard create customer

284

285

286

POST /ledger/customer/v1/XXX/customers HTTP/1.1

287

Host: -

288

Authorization: Bearer <Token>

289

Content-Type: application/json

290

291

{

292

"customerNo" : "9999",

293

"nationalIdentifier": {

294

"regNo" : "YYYYMMDD-NNNN",

295

"countryCode" : "SE"

296

},

297

"vatNo" : "SE101010101001",

298

"legalEntity" : "consumer|business",

299

"name" : "Britt-Marie Axelstopp",

300

"emailAddress" : "britt@axelstopp.com",

301

"msisdn" : "+91485918841",

302

"eDIAddressInfo" : {

303

"VAN": "ABCXYZ",

304

"InterChangeRecipient": "Recipient_ID1",

"BuyerId": "123456"

},

"legalAddress" : {

"addressee" : "Britt-Marie Axelstopp",

309

"streetAddress" : "The street 18",

310

"coAddress" : "c/o Jansson",

311

"city" : "STOCKHOLM",

"zipCode" : "15961",

"countryCode" : "SE"

},

"distributionType": "postal",

316

"taxIdentificationNumber" : "123456789"

}

(% id="HAccountresourceproperties" %)

==== ====

HTTP/1.1 201 CREATED

Content-Type: application/json

326

327

{

328

"@id" : "/ledger/customer/v1/XXX/customers/9999",

329

"customerNo" : " 9999"

}

(% class="wikigeneratedid" id="HCreatecustomerwithbilling-address" %)

334

Create customer with billing-address

335

336

337

POST /ledger/customer/v1/XXX/customers HTTP/1.1

338

Host: -

339

Authorization: Bearer <Token>

340

Content-Type: application/json

341

342

{

343

"customerNo" : "9999",

344

"nationalIdentifier": {

345

"regNo" : "YYYYMMDD-NNNN",

346

"countryCode" : "SE"

347

},

348

"vatNo" : "SE101010101001",

349

"legalEntity" : "consumer|business",

350

"name" : "Britt-Marie Axelstopp",

351

"emailAddress" : "britt@axelstopp.com",

352

"msisdn" : "+91485918841",

353

"eDIAddressInfo" : {

354

"VAN": "ABCXYZ",

355

"InterChangeRecipient": "Recipient_ID1",

"BuyerId": "123456"

},

"legalAddress" : {

"addressee" : "Britt-Marie Axelstopp",

360

"streetAddress" : "The street 18",

361

"coAddress" : "c/o Jansson",

362

"city" : "STOCKHOLM",

"zipCode" : "15961",

"countryCode" : "SE"

},

"billingAddress" : {

"addressee" : "Kalle Axelstopp",

368

"streetAddress" : "Axelgatan 18",

369

"city" : "STOCKHOLM",

"zipCode" : "16872",

"countryCode" : "SE"

}

}

(% id="HAccountresourceproperties" %)

==== ====

HTTP/1.1 201 CREATED

Content-Type: application/json

382

383

{

384

"@id" : "/ledger/customer/v1/XXX/customers/9999",

385

"customerNo" : " 9999"

}

==== ====

----

==== Update customer ====

394

395

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). //

396

397

The following customer properties is possible to update through a patch call

398

399

(% class="table-bordered table-striped" %)

400

|=(% style="width: 509px;" %)Property

401

|(% style="width:509px" %)emailAddress

402

|(% style="width:509px" %)legalStatus

403

|(% style="width:509px" %)preferredLanguageCode

404

|(% style="width:509px" %)protectedIdentity

405

|(% style="width:509px" %)msisdn

406

|(% style="width:509px" %)distributionType

407

|(% style="width:509px" %)taxIdentificationNumber

408

|(% style="width:509px" %)__**eDIAddressInfo**__

409

|(% style="width:509px" %) eDIAddressInfo.van

410

|(% style="width:509px" %) eDIAddressInfo.interChangeRecipient

411

|(% style="width:509px" %) eDIAddressInfo.BuyerId

===== Examples =====

Update all properties

416

417

418

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1

419

Host: -

420

Authorization: Bearer <Token>

421

Content-Type: application/json

422

423

{

424

"emailAddress" : "britt@axelstopp.com",

425

"protectedIdentity": false,

426

"preferredLanguageCode": "SV",

427

"legalStatus": "active",

428

"msisdn" : "+91485918841",

429

"eDIAddressInfo" : {

430

"VAN": "ABCXYZ",

431

"InterChangeRecipient": "Recipient_ID1",

432

"BuyerId": "123456"

433

},

434

"distributionType": "postal",

435

"taxIdentificationNumber" : "987654321"

}

Update only emailAddress

440

441

442

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1

443

Host: -

444

Authorization: Bearer <Token>

445

Content-Type: application/json

446

447

{

448

"emailAddress" : "britt@axelstopp.com"

}

Update emailAddress and delete msisdn

453

454

455

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1

456

Host: -

457

Authorization: Bearer <Token>

458

Content-Type: application/json

459

460

{

461

"emailAddress" : "britt@axelstopp.com",

"msisdn" : null

}

Remove EDIAddressInfo on a customer

467

468

469

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1

470

Host: -

471

Authorization: Bearer <Token>

472

Content-Type: application/json

473

474

{

475

"eDIAddressInfo" : null

}

----

(% id="HAccountresourceproperties" %)

483

==== Customer resource properties ====

484

485

(% class="table-bordered table-striped" %)

486

|=(% style="width: 343px;" %)Property|=(% style="width: 137px;" %)Data type|=(% style="width: 230px;" %)Format|=(% style="width: 1076px;" %)Description

487

|(% style="width:343px" %)@id |(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)Uri of the specific customer

488

|(% style="width:343px" %)customerNo|(% style="width:137px" %)string|(% style="width:230px" %)MinLength: 1

489

MaxLength: 15*

490

numeric, 1-9 |(% style="width:1076px" %)The unique identifier of the customer

491

MaxLength may differ depending on configuration

492

KID (Norway)

493

|(% style="width:343px" %)__**nationalIdentifier**__|(% style="width:137px" %)object|(% style="width:230px" %) |(% style="width:1076px" %)

494

|(% style="width:343px" %) nationalIdentifier.regNo|(% style="width:137px" %)string|(% style="width:230px" %)Country specific|(% style="width:1076px" %)Sweden: YYYYMMDD-NNNC

495

Norway: DDMMYYNNNNN

496

|(% 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" %)

497

|(% style="width:343px" %)vatNo|(% style="width:137px" %)string|(% style="width:230px" %)MinLength: 7

498

MaxLength: 17

499

Regex pattern:

500

[A-Z]{2}.*|(% style="width:1076px" %)Customer VAT registration number. Mandatory if reverse tax is used. Must conform to country specific algorithm

501

|(% style="width:343px" %)legalEntity|(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)Valid values:

502

"consumer"

503

"business"

504

|(% style="width:343px" %)name|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 72

505

Regex?|(% style="width:1076px" %)Full name of end-customer

506

|(% style="width:343px" %)emailAddress|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 254

507

Regex pattern: [^@]+@[^\.]+\..+|(% style="width:1076px" %)

508

|(% style="width:343px" %)protectedIdentity|(% style="width:137px" %)bool|(% style="width:230px" %) |(% style="width:1076px" %)Set to true if the customer has protected identity

509

Postal distribution will be handled by "Skatteverket". **Only supported in Sweden**

510

|(% style="width:343px" %)preferredLanguageCode|(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)(((

Valid values:

* **SV**

* **NO**

* **DA**

* **FI**

* **EN**

)))

|(% style="width:343px" %)legalStatus|(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)(((

Valid values:

* active

* deceased

)))

|(% style="width:343px" %)msisdn|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 15

526

Minlength: 5

527

+NNNN|(% style="width:1076px" %) "Mobile Subscriber Integrated Services Digital Network Number", ie. Cellphone number

528

Countrycode is always required as the example below

529

+46720000000

530

|(% style="width:343px" %)distributionType|(% style="width:137px" %)string|(% style="width:230px" %) |(% style="width:1076px" %)Sets distribution type. Allowed values are:(((

531

* **postal **

532

* **noDistribution **

533

)))

534

|(% style="width:343px" %)taxIdentificationNumber|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 20

535

Minlength: 1|(% style="width:1076px" %)Is an identification number used by the Internal Revenue Service (IRS) in the administration of tax laws

536

|(% style="width:343px" %)**activeConsents**|(% style="width:137px" %)object|(% style="width:230px" %) |(% style="width:1076px" %)List of strings with possible values:(((

537

* (((

538

(% 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}]" %)

**Autogiro**

)))

* (((

(% 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}]" %)

**Avtalegiro**

)))

* (((

(% 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}]" %)

**Betalingsservice**

)))

* (((

(% 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}]" %)

**RecurringCard**

)))

* (((

(% 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}]" %)

555

**RecurringInvoiceToken**

556

)))

557

* (((

558

(% 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}]" %)

**EInvoice**

)))

* (((

(% 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}]" %)

**Kivra**

)))

* (((

(% 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}]" %)

**EBoks**

)))

)))

|(% style="width:343px" %)__**eDIAddressInfo**__|(% style="width:137px" %)object|(% style="width:230px" %) |(% style="width:1076px" %)EDI addressing info

571

|(% style="width:343px" %) eDIAddressInfo.van|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 255|(% style="width:1076px" %)(((

572

Buyer VAN identifier (OperatorId)

573

)))

574

|(% style="width:343px" %) eDIAddressInfo.interChangeRecipient|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 13|(% style="width:1076px" %)Routing address. EAN

575

|(% style="width:343px" %) eDIAddressInfo.BuyerId|(% style="width:137px" %)string|(% style="width:230px" %)Maxlength: 13|(% style="width:1076px" %)NAD_BY/Buyerparty. EAN/Corporate identity number

576

|(% style="width:343px" %)legalAddress|(% style="width:137px" %)uri|(% style="width:230px" %) |(% style="width:1076px" %)reference to the customers legal address

577

|(% style="width:343px" %)billingAddress|(% style="width:137px" %)uri|(% style="width:230px" %) |(% style="width:1076px" %)reference to the customer billing address

578

|(% style="width:343px" %)surpluses|(% style="width:137px" %)uri|(% style="width:230px" %) |(% style="width:1076px" %)reference to the customer surpluses

==== Operations ====

Depending on the current permissions the following operations is supported on the customer resource

583

584

===== add-billing-address =====

585

586

Method: POST

587

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

----

== Update-kyc-answers ==

592

593

594

==== Create Update-kyc-answer ====

595

596

When exposed on customer resources operations list it's a indication previous KYC answers up for renewal. Able update KYC with this operation even if current aren't expired but won't be suggested on the customer resource

597

598

599

POST /ledger/customer/v1/{ownerNo}/customers/{customerNo}/update-kyc-answers HTTP/1.1

600

Host: -

601

Authorization: Bearer<Token>

602

Content-Type: application/json

{

"answers": [

{

"questionCode": "taxable_outside_sweden",

"answerCode": "no"

},

{

"questionCode": "multiple_citizenship",

"answerCode": "yes"

},

{

"questionCode": "citizen_ship_country_codes",

"answerCode": "SWE"

},

{

"questionCode": "citizen_ship_country_codes",

"answerCode": "NOR"

}

]

}

**Request object specification**

628

629

(% class="table-bordered table-striped" %)

HTTP/1.1 204 NoContent

637

Content-Type: application/json

{}

**Possible problems**

643

644

(% class="table-bordered table-striped" %)

645

|=Http status |=Problem type |=Description

646

|400 |validation |Occurs if the validation of the request fails, it is described in the problem why the input is invalid.

647

|404 |not-found |Occurs if the customer found or if kyc is not configured on this ledger.

648

|409 |kyc-configuration |Occurs if ledger is not currently configured for KYC

649

|500 |fatal |Unexpected error, logs may give details about the problem

== Surpluses ==

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.

654

655

==== Get specified Surplus information ====

656

657

658

GET /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY HTTP/1.1

659

Host: -

660

Authorization: Bearer <Token>

661

Content-Type: application/json

HTTP/1.1 200 OK

Content-Type: application/json

{

"surplusId": "YYY",

"balance": 10.00,

"currency": "SEK",

"date": "2023-01-01T00:00:00",

674

"status": "open",

675

"invoice": "/ledger/invoice/v1/XXX/invoices/AAA",

676

"account": "/ledger/account/v1/XXX/accounts/BBB",

677

"operations": [],

678

"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/YYY"

==== Get list of Surpluses Information ====

683

684

685

GET /ledger/customer/v1/XXX/customers/NNN/surpluses HTTP/1.1

686

Host: -

687

Authorization: Bearer <Token>

688

Content-Type: application/json

HTTP/1.1 200 OK

Content-Type: application/json

{

"items": [

{

"surplusId": "123",

"balance": 10.00,

"currency": "SEK",

"date": "2023-01-01T00:00:00",

703

"status": "open",

704

"invoice": "/ledger/invoice/v1/XXX/invoices/AAA",

705

"operations": [],

706

"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/123"

},

{

"surplusId": "456",

"balance": 20.00,

"currency": "SEK",

"date": "2023-01-02T00:00:00",

714

"status": "pending-disbursement",

715

"account": "/ledger/account/v1/XXX/accounts/BBB",

716

"operations": [],

717

"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/456"

},

{

"surplusId": "789",

"balance": 30.00,

"currency": "SEK",

"date": "2023-01-03T00:00:00",

725

"status": "pending-regulate",

726

"invoice": "/ledger/invoice/v1/XXX/invoices/AAA",

727

"operations": [],

728

"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/789"

}

],

"navigation": {

"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses",

734

"first": "/ledger/customer/v1/XXX/customers/NNN/surpluses?skip=0",

735

"previous": "/ledger/customer/v1/XXX/customers/NNN/surpluses?skip=0"

}

}

==== Surpluses resource properties ====

742

743

(% class="table-bordered table-striped" %)

744

|=(% style="width: 248px;" %)Property|=(% style="width: 108px;" %)Data type|=(% style="width: 233px;" %)Format|=(% style="width: 1196px;" %)Description

745

|(% style="width:248px" %)@id |(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: |(% style="width:1196px" %)Uri of the specific surplus

746

|(% style="width:248px" %)surplusId|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 50|(% style="width:1196px" %)Value is not considered case sensitive

747

|(% style="width:248px" %)balance|(% style="width:108px" %)string|(% style="width:233px" %) |(% style="width:1196px" %)Amount value for the surplus, always a positive value

748

|(% style="width:248px" %)currency|(% style="width:108px" %)string|(% style="width:233px" %)[[ISO 4217>>https://sv.wikipedia.org/wiki/ISO_4217]]|(% style="width:1196px" %)

749

|(% style="width:248px" %)date|(% style="width:108px" %)date|(% style="width:233px" %)yyyy-MM-ddTHH:mm:ss|(% style="width:1196px" %)Surplus creation date

750

751

After a surplus has been depleted it will no longer be returned from the API

752

|(% 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.

753

|(% 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.

----

== (% style="color:inherit; font-family:inherit" %)Active-Disbursement-Orders(%%) ==

758

759

This shows if current surplus has been ordered to disburse the surplus to the end customer.

760

761

==== Get active disbursement orders ====

GET /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1

766

Host: -

767

Authorization: Bearer <Token>

768

Content-Type: application/json

HTTP/1.1 200 OK

Content-Type: application/json

{

"items": [

{

"operations": [],

"swedishBankAccount": {

781

"accountNo": "3300-1010101010",

782

"accountType": "BKSE"

}

}

],

"navigation": {

"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders"

}

}

(% id="HOperations" %)

793

==== Operations ====

794

795

Depending on the current permissions the following operations is supported on the surplus resource

796

797

(% id="Hadd-billing-address" %)

798

===== add-disbursement-orders =====

799

800

Method: POST

801

This operation will be available if agreed with payex.

802

803

(% id="HActive-payment-ordersresourceproperties" %)

804

==== request properties ====

805

806

(% class="table-bordered table-striped" %)

807

|=Property|=Data type|=Required|=Description

808

|__**norwegianBankAccount**__|object|No*|

809

| accountNo|string|Yes|

810

|__**swedishBankAccount**__|object|No*|

811

| clearingNo|string|Yes|

812

| accountNo|string|Yes|

813

|__**international**__|object|No*|

814

| iban|string|Yes|

815

| bic|string|Yes|

816

|__**swedishSus**__|object|No*|

817

|**nationalIdentifier**|object|Yes|

818

| regNo|string|Yes|

819

| countryCode|string|Yes|

820

|**address**|object|Yes|

821

| addressee|string|Yes|

822

| streetAddress|string|No|

823

| coAddress|string|No|

824

| city|string|Yes|

825

| zipCode|string|Yes|

826

| countryCode|string|Yes|

827

| | | |

828

829

//* One and only one of the specified objects can be set at each request//

Examples

Create disbursement with swedish bank account

834

835

836

POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1

837

Host: -

838

Authorization: Bearer <Token>

839

Content-Type: application/json

840

841

{

842

"SwedishBankAccount" : {

843

"AccountNo":"944-1049000",

"AccountType":"BGSE"

}

}

Create a disbursement order with a norwegian bankaccount

850

851

852

POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1

853

Host: -

854

Authorization: Bearer <Token>

855

Content-Type: application/json

856

857

{

858

"norwegianBankAccount" : {

"accountNo" : "1234"

}

}

Create a disbursement order with an international bankaccount

865

866

867

POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1

868

Host: -

869

Authorization: Bearer <Token>

870

Content-Type: application/json

{

"international" : {

"iban" : "123456",

"bic" : "SWED..."

}

}

Create disbursement order using "Swedbanks lön- och utbetalningssystem (SUS)"

881

882

883

POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1

884

Host: -

885

Authorization: Bearer <Token>

886

Content-Type: application/json

{

"swedishSus" : {

"nationalIdentifier": {

891

"regNo" : "YYYYMMDD-NNNN",

"countryCode" : "SE"

},

"address" : {

"addressee" : "Kalle Axelstopp",

896

"streetAddress" : "Axelgatan 18",

897

"coAddress" : null,

898

"city" : "STOCKHOLM",

899

"zipCode" : "16872",

900

"countryCode" : "se",

}

}

}

(% aria-label="macro:code widget" contenteditable="false" role="region" tabindex="-1" %)

(((

)))

== (% style="color:inherit; font-family:inherit" %)Legal-address(%%) ==

912

913

The legal address is where claims is normally sent to. It is required for a customer to have a legal address registered

914

915

==== Get the legal address of the customer ====

916

917

918

GET /ledger/customer/v1/XXX/customers/NNN/legal-address HTTP/1.1

919

Host: -

920

Authorization: Bearer <Token>

921

Content-Type: application/json

HTTP/1.1 200 OK

Content-Type: application/json

928

929

{

930

"addressee" : "Britt-Marie Axelstopp",

931

"streetAddress" : "The street 18",

932

"coAddress" : "c/o Jansson",

933

"city" : "STOCKHOLM",

934

"zipCode" : "15961",

935

"countryCode" : "SE",

"operations" :

[

{

"rel" : "update",

"href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",

"method" : "PUT"

},

{

"rel" : "update-legal-address-from-population-register",

945

"href" : "/ledger/customer/v1/XXX/customers/9999/legal-address/update-legal-address-from-population-register",

"method" : "POST"

}

]

}

==== Operations ====

Depending on the current permissions the following operations is supported on the legal address resource

955

956

===== Update (replace) =====

957

958

Method: PUT

959

Use this operation to update the address, this "PUT" operation will replace the existing billing-address with the address specified in the request body.

960

961

(% class="table-bordered table-striped" %)

962

|=(% style="width: 183px;" %)Property|=(% style="width: 1602px;" %)Required

963

|(% style="width:183px" %)addressee|(% style="width:1602px" %)Yes

964

|(% style="width:183px" %)streetAddress|(% style="width:1602px" %)No

965

|(% style="width:183px" %)coAddress|(% style="width:1602px" %)No

966

|(% style="width:183px" %)city|(% style="width:1602px" %)Yes

967

|(% style="width:183px" %)zipCode|(% style="width:1602px" %)Yes

968

|(% style="width:183px" %)countryCode|(% style="width:1602px" %)Yes

Example

PUT /ledger/customer/v1/XXX/customers/NNN/legal-address HTTP/1.1

974

Host: -

975

Authorization: Bearer <Token>

976

Content-Type: application/json

977

978

{

979

"addressee" : "Kalle Axelstopp",

980

"streetAddress" : "Axelgatan 18",

981

"city" : "STOCKHOLM",

"zipCode" : "16872",

"countryCode" : "SE"

}

----

===== update-legal-address-from-population-register =====

991

992

Method: POST

993

Execution of this operation will result in an attempt to retrieve (and replace) the customer's legal address from the population registry.

994

995

(% class="box infomessage" %)

996

(((

997

Access to this operation is not normally granted, unless otherwise agreed.

)))

POST /ledger/customer/v1/XXX/customers/NNN/legal-address/update-legal-address-from-population-register HTTP/1.1

1002

Host: -

1003

Authorization: Bearer <Token>

1004

Content-Type: application/json

{

}

----

==== Legal-address resource properties ====

1013

1014

(% class="table-bordered table-striped" %)

1015

|=(% style="width: 161px;" %)Property|=(% style="width: 121px;" %)Data type|=(% style="width: 195px;" %)Format|=(% style="width: 1309px;" %)Description

1016

|(% style="width:161px" %)addressee|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 72|(% style="width:1309px" %)Fullname

1017

|(% style="width:161px" %)streetAddress|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 72|(% style="width:1309px" %)

1018

|(% style="width:161px" %)coAddress|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 72|(% style="width:1309px" %)Care of (C/O) name. This is optional.

1019

|(% style="width:161px" %)city|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 27|(% style="width:1309px" %)

1020

|(% style="width:161px" %)zipCode|(% style="width:121px" %)string|(% style="width:195px" %)Maxlength: 9|(% style="width:1309px" %)ZipCode without whitespaces

1021

|(% 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" %)

----

== Billing-address ==

1026

1027

The billing address is where invoices/bills/letters etc. is normally sent to.This address is optional

1028

1029

==== Get the billing address of the customer ====

1030

1031

1032

GET /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1

1033

Host: -

1034

Authorization: Bearer <Token>

1035

Content-Type: application/json

HTTP/1.1 200 OK

Content-Type: application/json

1042

1043

{

1044

"addressee" : "Kalle Axelstopp",

1045

"streetAddress" : "Axelgatan 18",

1046

"coAddress" : "c/o Jansson",

1047

"city" : "STOCKHOLM",

1048

"zipCode" : "16872",

1049

"countryCode" : "SE",

"operations" :

[

{

"rel" : "update",

"href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",

"method" : "PUT"

},

{

"rel" : "delete",

"href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",

"method" : "DELETE"

}

]

}

==== Add a billing-address ====

1067

1068

(% class="table-bordered table-striped" %)

1069

|=(% style="width: 183px;" %)Property|=(% style="width: 1602px;" %)Required

1070

|(% style="width:183px" %)addressee|(% style="width:1602px" %)Yes

1071

|(% style="width:183px" %)streetAddress|(% style="width:1602px" %)No

1072

|(% style="width:183px" %)coAddress|(% style="width:1602px" %)No

1073

|(% style="width:183px" %)city|(% style="width:1602px" %)Yes

1074

|(% style="width:183px" %)zipCode|(% style="width:1602px" %)Yes

1075

|(% style="width:183px" %)countryCode|(% style="width:1602px" %)Yes

1076

1077

1078

POST /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1

1079

Host: -

1080

Authorization: Bearer <Token>

1081

Content-Type: application/json

1082

1083

{

1084

"addressee" : "Kalle Axelstopp",

1085

"streetAddress" : "Axelgatan 18",

1086

"city" : "STOCKHOLM",

"zipCode" : "16872",

"countryCode" : "SE"

}

==== Operations ====

Depending on the current permissions the following operations is supported on the billing address resource

1095

1096

===== Update (replace) =====

1097

1098

Method: PUT

1099

Use this operation to update the address, the "PUT" body of the request should be accoring to the properties of the resource.

1100

1101

(% class="table-bordered table-striped" %)

1102

|=(% style="width: 183px;" %)Property|=(% style="width: 1602px;" %)Required

1103

|(% style="width:183px" %)addressee|(% style="width:1602px" %)Yes

1104

|(% style="width:183px" %)streetAddress|(% style="width:1602px" %)No

1105

|(% style="width:183px" %)coAddress|(% style="width:1602px" %)No

1106

|(% style="width:183px" %)city|(% style="width:1602px" %)Yes

1107

|(% style="width:183px" %)zipCode|(% style="width:1602px" %)Yes

1108

|(% style="width:183px" %)countryCode|(% style="width:1602px" %)Yes

1109

1110

1111

PUT /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1

1112

Host: -

1113

Authorization: Bearer <Token>

1114

Content-Type: application/json

1115

1116

{

1117

"addressee" : "Kalle Axelstopp",

1118

"streetAddress" : "Axelgatan 18",

1119

"city" : "STOCKHOLM",

"zipCode" : "16872",

"countryCode" : "SE"

}

===== Delete =====

Method: DELETE

Use this operation to delete the billing address.

1129

1130

1131

DELETE /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1

1132

Host: -

1133

Authorization: Bearer <Token>

1134

Content-Type: application/json

{

}

==== Billing-address resource properties ====

1141

1142

(% class="table-bordered table-striped" %)

1143

|=Property|=(% style="width: 94px;" %)Data type|=(% style="width: 255px;" %)Format|=(% style="width: 1053px;" %)Description

1144

|addressee|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 72|(% style="width:1053px" %)Fullname

1145

|streetAddress|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 72|(% style="width:1053px" %)

1146

|coAddress|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 72|(% style="width:1053px" %)Care of (C/O) name. This is optional.

1147

|city|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 27|(% style="width:1053px" %)

1148

|zipCode|(% style="width:94px" %)string|(% style="width:255px" %)Maxlength: 9|(% style="width:1053px" %)ZipCode without whitespaces

1149

|countryCode|(% style="width:94px" %)string|(% style="width:255px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1053px" %)

----

== Consent ==

The consent resource is used to get the underlying resources that display information or enable registration of a customer's consent.

1156

1157

==== Get the underlying consent resources of the customer ====

1158

1159

1160

GET /ledger/customer/v1/XXX/customers/NNN/consent HTTP/1.1

1161

Host: -

1162

Authorization: Bearer <Token>

1163

Content-Type: application/json

HTTP/1.1 200 OK

Content-Type: application/json

1170

1171

{

1172

"recurringCard": "/ledger/customer/v1/XXX/customers/NNN/consent/recurring-card",

1173

"recurringCardRedirectRegistration": "/ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration"

}

==== Consent resource properties ====

1178

1179

(% class="table-bordered table-striped" %)

1180

|=Property|=(% style="width: 94px;" %)Data type|=(% style="width: 255px;" %)Format|=(% style="width: 1053px;" %)Description

1181

|recurringCard|(% style="width:94px" %)string|(% style="width:255px" %)Path|(% style="width:1053px" %)Endpoint to resource

1182

|recurringCardRedirectRegistration|(% style="width:94px" %)string|(% style="width:255px" %)Path|(% style="width:1053px" %)Endpoint to resource

----

==== Recurring-card ====

1187

1188

This resource provides details about the customer's active Recurring Card Consent and the ability to remove it.

1189

1190

===== Get customer active Recurring Card Consent =====

1191

1192

1193

GET /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card HTTP/1.1

1194

Host: -

1195

Authorization: Bearer <Token>

1196

Content-Type: application/json

HTTP/1.1 200 OK

Content-Type: application/json

1203

1204

{

1205

"cardToken": "2eb28854-07ec-4e88-b672-7c61cc54b461",

1206

"consentExpiryDate": "04-2035",

1207

"instrumentDisplayName": "551000******1232",

1208

"cardExpiryDate": "04/2035"

}

===== Delete customer active Recurring Card Consent =====

1213

1214

1215

DELETE /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card HTTP/1.1

1216

Host: -

1217

Authorization: Bearer <Token>

1218

Content-Type: application/json

{

}

HTTP/1.1 204 NoContent

1226

Content-Type: application/json

{

}

===== Recurring-card resource properties =====

1233

1234

(% class="table-bordered table-striped" %)

1235

|=Property|=(% style="width: 94px;" %)Data type|=(% style="width: 255px;" %)Format|=(% style="width: 1053px;" %)Description

1236

|cardToken|(% style="width:94px" %)string|(% style="width:255px" %)Guid|(% style="width:1053px" %)Card Token Id

1237

|consentExpiryDate|(% style="width:94px" %)string|(% style="width:255px" %)Date (MM-yyyy)|(% style="width:1053px" %)Expiry date of the consent

1238

|instrumentDisplayName|(% style="width:94px" %)string|(% style="width:255px" %)Masked number|(% style="width:1053px" %)Masked card number used in the presentation layer

1239

|cardExpiryDate|(% style="width:94px" %)string|(% style="width:255px" %)Date (MM/yyyy)|(% style="width:1053px" %)Expiry date of the card

----

==== Recurring-card-redirect-registration ====

1244

1245

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.

1246

1247

===== Start a Recurring Card registration =====

1248

1249

(% class="table-bordered table-striped" %)

1250

|=(% style="width: 509px;" %)Property|=(% style="width: 161px;" %)Required|=(% style="width: 1852px;" %)Comment

1251

|(% style="width:509px" %)completeUrl|(% style="width:161px" %)Yes|(% style="width:1852px" %)Redirect Url to be used if the user completes the card verification process.

1252

|(% style="width:509px" %)cancelUrl|(% style="width:161px" %)Yes|(% style="width:1852px" %)Redirect Url to be used if the user cancels the card verification process.

1253

|(% 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".

1254

1255

1256

POST /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration HTTP/1.1

1257

Host: -

1258

Authorization: Bearer <Token>

1259

Content-Type: application/json

1260

1261

{

1262

"completeUrl": "https://www.google.com/search?q=cancelurl",

1263

"cancelUrl": "https://www.google.com/search?q=completeurl",

"language": "en-US"

}

HTTP/1.1 200 OK

Content-Type: application/json

1272

1273

{

1274

"redirectUrl": "https://ecom.externalintegration.payex.com/checkout/abc123",

1275

"status": "Initialized",

1276

"@id": "/ledger/customer/v1/xxx/customers/yyy/consent/recurring-card-redirect-registration"

}

===== Get Recurring Card Redirect Registration =====

1281

1282

1283

GET /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration HTTP/1.1

1284

Host: -

1285

Authorization: Bearer <Token>

1286

Content-Type: application/json

{

}

HTTP/1.1 200 OK

Content-Type: application/json

1296

1297

{

1298

"redirectUrl": "https://ecom.externalintegration.payex.com/checkout/abc123",

1299

"status": "Initialized"

}

===== Recurring-card-redirect-registration resource properties =====

1304

1305

(% class="table-bordered table-striped" %)

1306

|=Property|=(% style="width: 94px;" %)Data type|=(% style="width: 255px;" %)Format|=(% style="width: 1053px;" %)Description

1307

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

1308

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

----

== Find customer ==

The **find customer **resource is located under **ledger/customer/v1/ **api**. **It is used to find customer with nationalIdentifier.

1315

1316

(% class="table-bordered table-striped" %)

1317

|=(% style="width: 222px;" %)Property|=(% style="width: 1562px;" %)Required

1318

|(% style="width:222px" %)nationalIdentifier.regNo|(% style="width:1562px" %)Yes

1319

|(% style="width:222px" %)nationalIdentifier.countryCode|(% style="width:1562px" %)Yes

1320

1321

1322

POST /ledger/customer/v1/XXX/find-customer HTTP/1.1

1323

Host: -

1324

Authorization: Bearer <Token>

1325

Content-Type: application/json

1326

1327

{

1328

"nationalIdentifier": {

1329

"regNo" : "YYYYMMDD-NNNN",

"countryCode" : "SE"

}

}

HTTP/1.1 200 OK

Content-Type: application/json

1338

1339

{

1340

"@id" : "/ledger/customer/v1/XXX/customers/9999",

1341

"customerNo" : " 9999"

}

(% id="HAccountresourceproperties" %)

1346

==== Find customer resource properties ====

1347

1348

(% class="table-bordered table-striped" %)

1349

|=(% style="width: 248px;" %)Property|=(% style="width: 108px;" %)Data type|=(% style="width: 233px;" %)Format|=(% style="width: 1196px;" %)Description

1350

|(% style="width:248px" %)@id |(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: |(% style="width:1196px" %)Uri of the specific customer

1351

|(% style="width:248px" %)customerNo|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 15|(% style="width:1196px" %)

1352

|(% style="width:248px" %)nationalIdentifier.regNo|(% style="width:108px" %)string|(% style="width:233px" %)Country specific|(% style="width:1196px" %)Sweden: YYYYMMDD-NNNC

1353

Norway: DDMMYYNNNNN

1354

|(% 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" %)

----

== Generate customer ==

1359

1360

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.

1361

1362

(% class="box infomessage" %)

1363

(((

1364

Access to this operation is not normally granted, unless otherwise agreed.

1365

)))

1366

1367

(% class="table-bordered table-striped" %)

1368

|=(% style="width: 222px;" %)Property|=(% style="width: 1562px;" %)Required

1369

|(% style="width:222px" %)customerNo|(% style="width:1562px" %)No

1370

|(% style="width:222px" %)nationalIdentifier.regNo|(% style="width:1562px" %)Yes

1371

|(% style="width:222px" %)nationalIdentifier.countryCode|(% style="width:1562px" %)Yes

1372

|(% style="width:222px" %)emailAddress|(% style="width:1562px" %)No

1373

|(% style="width:222px" %)msisdn|(% style="width:1562px" %)No

1374

1375

1376

POST /ledger/customer/v1/XXX/generate-consumer-customer-by-reg-no HTTP/1.1

1377

Host: -

1378

Authorization: Bearer <Token>

1379

Content-Type: application/json

1380

1381

{

1382

"nationalIdentifier": {

1383

"regNo" : "YYYYMMDD-NNNN",

1384

"countryCode" : "SE"

1385

},

1386

"emailAddress" : "britt@axelstopp.com",

1387

"msisdn" : "+91485918841",

1388

"customerNo" : "9999"

}

HTTP/1.1 201 CREATED

Content-Type: application/json

1395

1396

{

1397

"@id" : "/ledger/customer/v1/XXX/customers/9999",

1398

"customerNo" : " 9999"

}

(% id="HAccountresourceproperties" %)

1403

==== Generate customer resource properties ====

1404

1405

(% class="table-bordered table-striped" %)

1406

|=(% style="width: 248px;" %)Property|=(% style="width: 108px;" %)Data type|=(% style="width: 233px;" %)Format|=(% style="width: 1196px;" %)Description

1407

|(% style="width:248px" %)@id |(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: |(% style="width:1196px" %)Uri of the specific customer

1408

|(% style="width:248px" %)customerNo|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 15|(% style="width:1196px" %)

1409

|(% style="width:248px" %)nationalIdentifier.regNo|(% style="width:108px" %)string|(% style="width:233px" %)Country specific|(% style="width:1196px" %)Sweden: YYYYMMDD-NNNC

1410

Norway: DDMMYYNNNNN

1411

|(% 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" %)

1412

|(% style="width:248px" %)emailAddress|(% style="width:108px" %)string|(% style="width:233px" %)Maxlength: 254

1413

Regex pattern: [^@]+@[^\.]+\..+|(% style="width:1196px" %)

1414

|(% 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

1415

+46720000000

1416

1417

{{display reference="developer:Main.Invoicing.ledger-api-general-docs.api-section-problems.WebHome"/}}

----

== Kys-Questions ==

The **Kys-Questions** resource is located under **ledger/customer/v1/ **api**. **Get the company Know-your-customer(KYC) questions and possible answers, if company no configured questions then it returns Http Status 404

1424

1425

(% class="box infomessage" %)

1426

(((

1427

This endpoint has an optional query parameter **Language**, used to set desired translations for the questions by **Language Code(ISO 639-1)**. If not set or if language code is not supported then translations defaults to EN(English).

1428

Just as the questions, accepted languages differs by configurations, if you are missing a translation please contact our support.

1429

1430

Example: ///ledger/customer/v1/{ledgerNo}/Kyc-Questions?**language=sv **//

1431

)))

1432

1433

Get KYC questions from ledger using company number as identifier

1434

1435

==== Get list of Kyc-questions ====

1436

1437

1438

GET /ledger/customer/v1/{ownerNo}/kyc-questions?language={language} HTTP/1.1

1439

Host: -

1440

Authorization: Bearer<Token>

1441

Content-Type: application/json

Get CompanyInstance KYC questions if configured or a 404 company-kyc-questions-not-configured response if not

HTTP/1.1 200 OK

Content-Type: application/json

{

"kycQuestions": [

{

"questionText": "What is your current employment?",

"answer": {

"type": "single",

"required": true,

"possibleAnswers": [

{

"answerCode": "selfemployed",

1461

"answerText": "Own business"

1462

},

1463

{

1464

"answerCode": "private_employee",

1465

"answerText": "Private employee"

1466

},

1467

{

1468

"answerCode": "goverment_employee",

1469

"answerText": "Government employee"

}

]

},

"questionCode": "employment"

1474

},

1475

{

1476

"questionText": "What is your yearly income",

"answer": {

"type": "single",

"required": true,

"possibleAnswers": [

{

"answerCode": "incomeinterval1",

1483

"answerText": "0-100 000 SEK"

1484

},

1485

{

1486

"answerCode": "incomeinterval2",

1487

"answerText": "100 001-200 000 SEK"

1488

},

1489

{

1490

"answerCode": "incomeinterval3",

1491

"answerText": "200 001-300 000 SEK"

1492

},

1493

{

1494

"answerCode": "incomeinterval4",

1495

"answerText": "Over 300 001 SEK"

}

]

},

"questionCode": "income"

}

],

"operations": []

}

**Possible problems**

1509

1510

(% class="table-bordered table-striped" %)

1511

|=Http status |=Problem type |=Description

1512

|400 |general-validation-error |Validation error when accessing resource . Please refer to the problems property for additional details.

1513

|404 |company-kyc-questions-not-configured |The requested resource '' was not found.

1514

|500 |internal-server-error |The requested resource '' could not be processed. Please contact support.

1515

|500 |handled-exception |The requested resource '' could not be processed. Please contact support.

1516

|500 |unhandled-exception |The requested resource '' could not be processed. Please contact support.

1517

1518

**Response object specification**

1519

1520

(% class="table-bordered table-striped" %)

1521

|=Property |=Data type|=Format|=Description

1522

|@id |string | |Uri identifier of the current resource

1523

|=kycQuestions |array of question's| |

1524

| question.questionCode |string | |The code definition of the question. Use this value when creating an answer request for /customers/{customerNo}/update-kyc-answers

1525

| question.questionText |string | |The translated text of the question

1526

|= answer |object | |

1527

| type |string | |(((

1528

The type of the expected answer:

1529

1530

* **single | **one answer only

1531

* **multi **| possible multiple answer

1532

* **text** | free text answer

1533

)))

1534

| required |boolean | |If the answer is required

1535

| textValidationRegEx |string | |The regex the answer should match, not all answers has a defined RegEx.

1536

|= possibleAnswers |array of possibleAwnser's| |

1537

| possibleAwnser.answerCode |string | |The code definition of the answer. Use this value when creating an answer request for /customers/{customerNo}/update-kyc-answers

1538

| possibleAwnser.answerText |string | |The translated text of the answer

1539

|= subQuestions |array of question's| |Is recursive structure of **kycQuestions** but limited to depth of 1, meaning a sub question can't have sub questions.

1540

|operations |array | |List of operations that is possible to perform on the current resource, read more about the ~[~[hypermedia part of the response>>https://developer.payex.com/xwiki/wiki/developer/view/Main/Invoicing/ledger-api-general-docs/restful-pattern-guideline/#HHyper-mediaresponse]]

1541

1542

{{display reference="developer:Main.Invoicing.ledger-api-general-docs.api-section-problems.WebHome"/}}

1543

1544

1545

=== Problem types ===

1546

1547

(% class="box infomessage" %)

1548

(((

1549

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

1550

)))

1551

1552

(% class="table-bordered table-striped" %)

1553

|=(% style="width: 537px;" %)Problem type (code)|=(% style="width: 172px;" %)Httpstatus|=(% style="width: 796px;" %)Description

1554

|(% 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

1555

|(% style="width:537px" %)forbidden|(% style="width:172px" %)403|(% style="width:796px" %)occurs if access to method is not allowed.

1556

|(% style="width:537px" %)not-found|(% style="width:172px" %)404|(% style="width:796px" %)specified resource not found

1557

|(% style="width:537px" %)customer-not-found|(% style="width:172px" %)404|(% style="width:796px" %)specified customer number does not exists

1558

|(% style="width:537px" %)legal-address-does-not-exists|(% style="width:172px" %)404|(% style="width:796px" %)legal address does not exists for the specified customer

1559

|(% style="width:537px" %)billing-address-does-not-exists|(% style="width:172px" %)404|(% style="width:796px" %)billing address does not exists for the specified customer

1560

|(% style="width:537px" %) |(% style="width:172px" %) |(% style="width:796px" %)

Wiki source code of 2. Customer