-
Notifications
You must be signed in to change notification settings - Fork 0
/
walletapi17-apiary.apib
11126 lines (9302 loc) · 583 KB
/
walletapi17-apiary.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
неFORMAT: 1A
HOST: https://api2.test.paysafe.com/
# Paysafe Wallet as a Service API
# Overview
Paysafe's digital wallet offering caters to merchants that need to implement **e-money financial services** into their products, such as marketplaces, e-commerce, electronic goods, and more.
By leveraging Paysafe's capabilities - ledger, multiple currencies within the same wallet, multiple region coverage, risk, and AML monitoring, and a multitude of payment options, a product can be easily enhanced with an out-of-the-box, compliant e-money wallet.
The service can easily and securely process payments and wallet requests from your customers using one single API – The **Payments and Wallets API**.
Paysafe's all-in-one [Business Portal](https://merchant.paysafe.com/portal) allows the merchant to access transaction analytics and manage the merchant account.
## Digital Wallet as a Service
Paysafe Digital Wallet as a Service allows merchants to provide e-money based financial services (deposits, withdraws, transactions) to end users.
Operating e-money solution imposes certain responsibilities split between merchants and Paysafe:
Merchant's responsibilities:
* Manage customer profiles
* Take the customer through KYC (Know Your Customer), and share the information with Paysafe for regulatory purposes
* Implement UI for all customer journeys
* Integrate into Paysafe's Payments and Digital Wallets API
Paysafe Digital Wallet responsibilities:
* Maintain e-money ledger
* Maintain customer details for regulatory purposes
* Monitor for Risk and AML
* Integrate additional payment methods
* Provide reporting capabilities
## Concepts in Paysafe's digital wallet
Here are the core terms of Paysafe Digital Wallets
* A **Wallet** encapsulates all data and services provided to a single entity
* A **Wallet account** is a ledger for a single currency. Each wallet account belongs to a single wallet - merchant, customer, or legal entity.
One wallet might have multiple accounts.
* **Customer** is a physical person, associated with a wallet, and is the legal owner of the e-money stored in the accounts' ledger.
* **Legal entity** is a customer who is not a physical person, but a legal entity. Legal entities have extended compliance requirements and onboarding processes.
* **Merchant** is a legal entity that provides services or goods to its customers and manages the Wallet as a Service solution. The merchant also has a wallet associated with it within the Paysafe Digital Wallet platform, and just like customers, KYB information must be collected and assessed.
* **Transaction** is a movement of money between any two accounts
Regulations require Paysafe to collect and assess KYC information, PEP checks, and in some instances - carry out EDD verifications on the customer and legal entities.
### Customer wallet
Each customer is assigned a customer wallet, and it accounts for all transactions for that customer - deposits, withdrawals, pay-in m pay-out, exchange, etc. As mentioned above, a wallet can contain multiple accounts in different currencies.
When the Merchant deems it necessary, a new Customer wallet is created. Usually, a customer wallet is registered, when the customer registers in the Merchant's system and passes the KYC verifications, as agreed between the Merchant and Paysafe.
> As the Merchant is managing all its users, Paysafe **only holds the customer personal details necessary for risk and compliance purposes** - Paysafe does not access or manage customer credentials, nor does it manage authentication and authorization. These details are associated with every wallet.
### Merchant wallet
The Merchant wallet, just like the Customer Wallet, provides ledger, transactional and multi-currency capabilities.
The Merchant can access the Merchant Wallet via the Paysafe Merchant Portal. Access to this portal is provided during the merchant onboarding process.
### Merchant fees
All Merchant fees that the Merchant needs to charge its customers are **accumulated in the Merchant Wallet at the time of customer transaction**. Paysafe's fees can either be deducted directly from the MW balance or can be settled on a monthly/quarterly basis by invoicing the Merchant.
To allow for the ultimate flexibility, all merchant fees **must be provided by the Merchant on a per-transaction basis**. This approach allows the Merchant to execute different pricing schemes based on regions, currency, customer loyalty levels, dynamic fee structures, and other information that is only available to them.
### Device information
Customer device information is critical in all risk and compliance assessments in the digital wallet offering. Paysafe uses ThreatMetrix as the preferred device intelligence solution.
The Merchant is required to pass in the data as received by ThreatMetrix, to avoid double billing in the case where Paysafe fetches the device information separately from Merchant.
## Payment methods
Payment Methods represent the supported customer's payment instruments for deposit and withdrawal operations.
The supported payment methods are:
- Cards
- Rapid Transfer (only for Deposits)
- Bank transfers
> **Note:** Bank transfers is only supported for Standalone Credits. For EUR, it should be through SEPA, and for GBP it should be through Faster Payments.
Deposits and withdraws are supported through the following transaction types:
* [Payment Handles](#paymenthandlerequest)
* [Payments](#paymentrequest)
* [Standalone Credits](#standalonecreditrequest)
# Getting Started
## API Basics
The API is constructed around REST and has the following features:
* Definite resource-oriented URLs
* Receives JSON-encoded request bodies
* Returns JSON-encoded responses
* Communicates using standard HTTP response codes, authentication, and verbs.
* **Message body**: This must contain valid Paysafe JSON objects as required for the type of request. Not all API calls require a message-body; for example, GET requests do not require a body.
* **Resource ID**: Identifies the unique ID of a resource.
## Authentication
Paysafe's REST API uses API keys to authenticate your request in the following format:
* **Key Username** – MerchantXYZ
* **Key Password** – 20881dff9bb4020a89e8ac44
The case-sensitive API key is sent using HTTP Basic Authentication. To use HTTP Basic Authentication, you must send the API key credentials
using the Authorization header with every request.
The Authorization header is constructed as follows:
1. The **Key Username** and **Key Password** are combined into a string separated by a colon, e.g.,“**Key Username**:**Key Password**”.
2. The resulting string literal is then encoded using Base64 (to allow sending of special characters).
3. The authorization method and а space (i.e., “Basic”) are then put before the encoded string.
For example, using the Key Username and Password examples above, the header is formed as follows:
```http
Authorization: Basic TWVyY2hhbnRYWVo6MjA4ODFkZmY5YmI0MDIwYTg5ZThhYzQ0
```
For additional details, please refer to http://en.wikipedia.org/wiki/Basic_access_authentication.
> **Note:** Your Production API key will be different from your Test API key. Contact your account manager for details. You must keep your API keys safe and ensure that it is used appropriately for your needs.
## Get your secret API key
Please contact your business relationship manager or reach out to [email protected] for API keys and Test/Production accounts.
> **Note:** All your APIs will use the same API key.
## Testing
Test accounts enable you to process API transactions that mirror the functionality of the Production environment.
Transactions processed in the Test environment are executed on a simulator. Depending on the information provided with the transaction request, the simulator returns either a successful (approved) or failed (declined) response.
With the API, you can:
* Verify support for all the operation types that you require.
* Review all common errors as well as unique errors that may occur for each operation.
* Verify the length and format for all attributes you send.
For access to Test accounts and credentials, contact your account manager or reach out to <[email protected]>.
Your Test account has access to the Test version of the Paysafe [Business Portal](https://merchant.test.paysafe.com/portal#/login), where you can view the status of your Test transactions.
### Test URL
To test your integration with Paysafe, use the following Test URLs:
`https://api2.test.paysafe.com/paymenthub/v1/`
`https://api2.test.paysafe.com/digitalwallets/v1/`
For example:
`https://api2.test.paysafe.com/paymenthub/v1/payments/{payment_id}`
## Going live
Once you are satisfied with your integration to the Test environment, you must repeat the configuration changes made to your Test account on your Production account.
> **Note:** You cannot use your Test credentials to process transaction requests in the Production environment.
### Go Live Checklist
1. You must have a production account and access to Business Portal.
2. You must have a Secret API Key for the production environment.
3. You must have Webhooks configured for all the events.
4. You must use the Production URL for your API calls.
### Production URL
To process live requests with Paysafe, use the following Production URL:
* `https://api2.paysafe.com/paymenthub/v1/`
* `https://api2.paysafe.com/digitalwallets/v1/`
For example:
* `https://api2.paysafe.com/paymenthub/v1/payments/{payment_id}`
* `https://api2.paysafe.com/digitalwallets/v1/customers`
## Using the Example API Calls (Console Window)
To configure and test the API examples, first, click on one of the API calls in the API Reference section and then click **Switch to Console** in the right-hand pane.
Using the Console window you can update the headers, the request body, and parts of the API endpoint. For example, for many lookup requests, you must update the endpoint to include your request ID (for example, payment_id), which you do by selecting **URI Parameters** and then updating the respective *id* value.
You must also update the Header to include your API Key by selecting **Headers** and then updating the **Authorization** value using the Base64 version of your API key.
To get your Base64 encoded API key, sign in to the Business Portal and go to **Integrate>API Keys**.
When you are ready to test your example, you can choose between the Production and Mock server environment:
- Production server – This calls the resource on Paysafe's Test system.
- Mock server – This environment simply returns the dummy values in the example response irrespective of the parameters you supply. You do not need to use your account ID or Test API key for this request.
To call the API resource, click **Call Resource**. The response is displayed in the Console window.
## Pagination
In the case where an API GET request returns multiple results, Paysafe returns the first 10 records by default and uses HATEOAS links to provide page navigation. In addition to the default behavior, it is also possible to control the number of results and starting point by passing in query parameters as described in this [section](https://developer.paysafe.com/en/resources-and-support/pagination/).
## Global Invalid Characters
You must not include any of the characters in this [table](https://developer.paysafe.com/en/resources-and-support/global-invalid-characters/) as values in any of your request parameters. Object. If you do, your request will result in an error.
## ISO Standards
ISO standards add value by providing the common business process data semantics to be used in the API based exchanges. This [section](https://developer.paysafe.com/en/resources-and-support/iso-standards/) presents you with codes for four areas - Currency, Province, State, and Country.
Please refer [Miscellaneous](https://developer.paysafe.com/en/rest-apis/paysafe-payments-api/payments-api/miscellaneous/) for Global Invalid Characters, ISO Standards, Currency Codes, Province Codes, State Codes, and Country Codes.
# Wallet operations
## Onboard a customer
Onboarding a new customer or a legal entity requires a new wallet to be created on the Paysafe side.
**Creating a new wallet for a customer** has the following requirements for the data being passed in the body of the request:
* `customer` - all required fields must be fully populated - Paysafe needs this information for regulatory purposes.
* `customer.kyc` - property tracks the customer KYC process status and data
* `kyc.status` - This flag must be passed, when creating a customer wallet. The flag denotes, that Paysafe accepts only customers, that have passed the KYC verification process. If the value of this flag is different from `COMPLETED`, then the wallet creation will fail.
* `customer.kyc.idVerification`, `customer.kyc.addressVerification`, `customer.kyc.faceMatch`, `customer.kyc.EDD` - optional objects
* `status` - Mandatory property if object is present. Accepted value on onboarding is `"COMPLETED"`.
* `date` - Optional property. Date of KYC verification completion. Current date is used if the value is not passed.
* `electronicallyVerified` - Property that shows if customer has been KYC verified by external vendor. Mandatory if
`documentUrls` is empty.
* `vendor` - Name of vendor that has done the KYC verification. Mandatory if `documentUrls` is empty.
* `documentUrls` - List of URLs of documents that customer has provided during KYC verification. Merchant is obligated
to provide them or provide `electronicallyVerified` and `vendor` to guarantee that customer has gone through KYC
verification.
* `EDD.date` - Mandatory property if `EDD.status` is `"COMPLETED"`, otherwise optional.
* `accounts` - at least one account object has to be populated and it must contain a currency code.
Please refer to Merchant's agreement with Paysafe for a list of supported wallet currencies per country.
If an unsupported currency is passed, or if two Account objects with the same currency are provided, creating the wallet will fail.
* when creating a new wallet, `totalBalance` and `availableBalance` are disregarded
* when `hasIban == true`, a new Virtual IBAN (vIBAN) will be allocated for this customer for that account and currency. The vIBAN will be provided to the Merchant in the API response.
* `termsAndConditionsAccepted` - this flag is needed as proof that the Merchant has presented the Paysafe T&Cs to the customer, and the customer has accepted these T&Cs.
If this flag has a value different than `true`, then the wallet creation will fail.
* `identityDocuments` - metadata about all documents, submitted by the Customer during the KYC & EDD process
> **Note** The wallet account can only be created in EUR for the European Economic Area and in GBP for the United Kingdom.
> **Note:** Assigning a virtual IBAN may be asynchronous due to differences in the banks that are used.
> The Merchant will receive a webhook event with `IBAN_ASSIGNED` type when the vIBAN is assigned.
>
> When the vIBAN is created and assigned, the merchant might obtain it by using the `iban` property from getAccounts API.
To migrate the balance, the Merchant must call an API endpoint to debit the amounts specified from the Merchant wallet, and credit these amounts into the customer's wallet effectively creating a starting balance.
In case the provided email provided is not unique, and a wallet is already created with this email address, the creation of a new wallet will fail.
> **Note:** Providing an email for the customer during onboarding is a configurable option per Merchant.
> If the email is not provided, Paysafe would set an autogenerated email address (e.g. [email protected]).
> The email can be updated only once with another value using update API.
After creating the wallet, the customer might be restricted on Paysafe side
based on regulatory and risk checks.
---
**POST** `https://api.paysafe.com/digitalwallets/v1/wallets`
```json
{
"customer": {
"firstName": "John",
"lastName": "Doe",
"title": "Mr",
"email": "[email protected]",
"mobile": "+443452555151",
"address1": "23 Four Str",
"city": "London",
"zip": "E17 033",
"countryCode": "GB",
"birthDate": "1999-08-24",
"registrationIp": "115.148.82.143",
"nationality": "GB",
"externalId": "d6f475fe-57c9-4865-9316-0c3b8e8128d4",
"kyc": {
"status": "COMPLETED",
"idVerification": {
"status": "COMPLETED",
"date": "2021-03-12T13:27:41Z",
"electronicallyVerified": true,
"vendor": "Vendor"
},
"addressVerification": {
"status": "COMPLETED",
"date": "2021-03-12T13:27:41Z",
"documentUrls": [
"https://documents.com/document1.png",
"https://documents.com/document2.png"
]
},
"faceMatch": {
"status": "COMPLETED",
"date": "2021-07-21T13:27:41Z",
"electronicallyVerified": true,
"vendor": "Vendor"
},
"EDD": {
"status": "COMPLETED",
"date": "2021-03-12T13:27:41Z",
"electronicallyVerified": true,
"vendor": "Vendor",
"documentUrls": [
"https://documents.com/document1.png",
"https://documents.com/document2.png"
]
},
"addressVerificationDocumentsReceived": [
"BANK_STATEMENT",
"CREDIT_CARD",
"TAX_RETURN",
"PENSION_DOCUMENT",
"PHONE_BILL",
"UNKNOWN_DOC"
]
},
"pep": {
"status": "MATCH",
"lastScreenDate": "2021-07-19T13:35:41Z",
"reason": "Matched"
},
"sanctions": {
"status": "NO_MATCH",
"lastScreenDate": "2021-07-19T13:35:41Z",
"reason": "Incorrect data"
}
}
},
"accounts": [
{
"currencyCode": "GBP",
"hasIban": true
}
],
"risk": {
"customerRiskRating": 1,
"isScaPerformed": true,
"isCustomerIPTrusted": true,
"isBeneficiaryTrusted": true
},
"termsAndConditionsAccepted": true,
"deviceInfo": {
"threatMetrixSessionId": "a71a475b-1956-4814-9c92-7faa8226b218",
"threatMetrixData": "true_ip=87%2e120%2e141%2e75&true_ip_assert_history=NEGATIVE_HISTORY&true_ip_attributes=_CHALLENGED&true_ip_attributes=_CHALLENGE_PASSED&true_ip_attributes=_TRUSTED&true_ip_attributes=_TRUSTED_CONF&...",
"appType": "WEB_APP"
},
"customerIp": "73.82.192.17"
}
```
---
## Onboard a legal entity
Onboarding a legal entity requires providing extended information since extended due diligence is required.
List of required fields for onboarding
* `legalEntity` - all required fields must be fully populated - Paysafe needs this information for regulatory purposes. List of required fields
* `externalId` - customer unique identifier at merchant site
* `email` - The field is required for legal entities
* `registrationIp` - registration ip address
* `registrationDate` - registration date
* `accounts` - at least one account object has to be populated and it must contain a currency code.
Please refer to Merchant's agreement with Paysafe for a list of supported wallet currencies per country.
If an unsupported currency is passed, or if two Account objects with the same currency are provided, creating the wallet will fail.
* `companyName` - company name
* `companyIdentifier` - company registration identifier as per local law
* `registrationAddress` - registration address
* `operatingAddress` - operating address
* `websiteUrl` - web site URL
* `representative` - main company representative
* `directors` - at least one director needs to be specified
* `ultimateBeneficialOwners` - at least one owner must be specified
* `sourceOfFunding` - source of funding
* `natureOfBusiness` - nature of business
* `reasonToApply` - reasons to apply
### Expected transaction volume for legal entities
**In Incubation**
New optional field will be introduced for legal entities upon onboarding. At some point in the future the field will be promoted to required for all legal entities.
* `expectedTransactionVolume` - Expected transaction volume of the legal entity for a rolling period of 1 year. The field contains the following properties:
* `amount` - the amount in minor units
* `currencyCode` - the amount currency code for example `EUR`. Use the same currency as the main account currency used during onboarding.
### KYC field in `representative`, `representatives`, `directors` and `ultimateBeneficialOwners`
For `representative.kyc.status` the value must be present and set to either `COMPLETED` or `NOT_COMPLETED` depending on the KYC model used for legal entities.
* `COMPLETED` - must be used if KYC process is managed by the merchant
* `NOT_COMPLETED` - must be used if KYC process is managed by Paysafe
The KYC model used depends on the contract between Paysafe and the merchant. The API will reject requests with invalid parameter value.
### Fields in KYC object
For simplicity `idVerification`, `addressVerification` and `faceMatch` in `kyc` field will be referred to as `<verification>` as they have the same structure and rules applied.
* The structure of Legal Entity KYC object is the same as Customer KYC object. The KYC object structure for
`representative`, `directors`, `ultimateBeneficialOwners`, `representatives` is the same. The `kybDocuments` array represents Business documents while `kyc.<verification>.documentUrls` represent Personal documents.
* `kyc` and `kybDocuments` are optional properties but merchant is obligated to provide KYC verification documents.
---
**POST** `https://api.paysafe.com/digitalwallets/v1/wallets`
```json
{
"legalEntity": {
"externalId": "6622429017",
"email": "[email protected]",
"mobile": "088634001917",
"registrationIp": "87.120.141.75",
"companyName": "companyName",
"companyIdentifier": "companyIdentifier",
"registrationAddress": {
"countryCode": "BG",
"stateProvince": "Sofia",
"city": "Sofia",
"postalCode": "1000",
"address1": "reg address 1",
"address2": "reg address 2"
},
"operatingAddress": {
"countryCode": "BG",
"stateProvince": "Sofia",
"city": "Sofia",
"postalCode": "1000",
"address1": "operating address 1",
"address2": "operating address 2"
},
"websiteUrl": "somecompany.com",
"expectedTransactionVolume": {
"amount": 100200300400,
"currencyCode": "EUR"
},
"representative": {
"firstName": "John",
"middleName": "Alexander",
"lastName": "Doe",
"dateOfBirth": "1961-11-11",
"countryCode": "BG",
"identificationNumber": "6111118787",
"identificationNumberIssuingCountryCode": "BG",
"kyc": {
"status": "COMPLETED",
"idVerification": {
"status": "COMPLETED",
"documentUrls": [
"https://documents.com/document.png"
]
}
},
"kybDocuments": [
{
"type": "OWNERSHIP_STRUCTURE",
"documentUrls": [
"https://documents.com/document.png"
]
},
{
"type": "STATEMENT_OF_WORK",
"documentUrls": [
"https://documents.com/document.png"
]
}
]
},
"directors": [
{
"firstName": "John",
"middleName": "A",
"lastName": "Doe",
"dateOfBirth": "1961-11-11",
"countryCode": "BG",
"identificationNumber": "6111118787",
"identificationNumberIssuingCountryCode": "BG",
"kyc": {
"status": "COMPLETED",
"idVerification": {
"status": "COMPLETED",
"documentUrls": [
"https://documents.com/document.png"
]
}
}
}
],
"ultimateBeneficialOwners": [
{
"firstName": "John",
"middleName": "Alexander",
"lastName": "Doe",
"dateOfBirth": "1961-11-11",
"countryCode": "BG",
"identificationNumber": "6111118787",
"identificationNumberIssuingCountryCode": "BG",
"kyc": {
"status": "COMPLETED",
"idVerification": {
"status": "COMPLETED",
"documentUrls": [
"https://documents.com/document.png"
]
}
}
}
],
"sourceOfFunding": "funding source",
"natureOfBusiness": "nature of business",
"reasonToApply": "application reason"
},
"deviceInfo": {
"appType": "WEB_APP"
},
"customerIp": "87.120.141.75",
"accounts": [
{
"currencyCode": "EUR",
"hasIban": true
}
],
"risk": {
"customerRiskRating": 1,
"isScaPerformed": true,
"isCustomerIPTrusted": true,
"isBeneficiaryTrusted": true
},
"termsAndConditionsAccepted": true,
"kybDocuments": [
{
"type": "ARTICLES_OF_ASSOCIATION",
"documentUrls": [
"https://documents.com/document.png"
]
},
{
"type": "CERTIFICATE_OF_INCORPORATION",
"documentUrls": [
"https://documents.com/document.png"
]
}
]
}
```
---
## Update customer details
Customer's details could be updated on the Merchant's app/portal, and these updates must be reflected on the Paysafe side, for regulatory purposes.
Customer profile information can be updated by calling the respective APIs for updating customer information - persons and legal entities.
The following fields cannot be updated, and any attempt to do so will result in an error:
* birthDate
* email - can be updated only once and only if not passed during the initial onboarding
* type - Might cause `404 Not Found` error if does not match the correct customer type
The following fields are disregarded during the update:
* registrationIp
* id
* externalId
## Update KYC
All properties are optional with the exception of `EDD.date`. `EDD.date` would be mandatory if `EDD.status` is
`"COMPLETED"`.
Providing `kyc.status` would change values of `idVerification.status`, `addressVerification.status` and `faceMatch.
status` unless they are provided.
Example:
```json
{
"kyc": {
"status": "NOT_COMPLETED",
"idVerification": {
"status": "COMPLETED"
}
}
}
```
In the above example `addressVerification.status` and `faceMatch.status` would change to `"NOT_COMPLETED"` and
`idVerification.status` to `"COMPLETED"`.
## Update a legal entity
The following specifics are valid for updating legal entities.
* partial update of `representatives`, `directors` and `ultimateBeneficialOwners` is not possible. Full list must be provided upon update. The operation replaces the existing `representatives`, `directors` and `ultimateBeneficialOwners`. Pass empty list to delete all record of specific type.
* `registrationAddress` - can be updated as long as country is not changed. Legal entities can not change country.
Main represetative can not have the same identification number as one of the additional representatives. To promote additional representative to main representative, you must remove it from the representative list and set it as main representative.
Two representatives, directors and ultimate beneficial owners can not have the same identification numbers.
The following fields can not be updated
* `email` - email is a required field for onboarding legal entities
* `type` - can not be changed from `LEGAL_ENTITY` to `PERSON`
* `id` - customer id can not be changed
* `externalId` - external customer id can not be changed
* `registrationIp`
* `restrictions` - are disregarded. Restrictions are placed using dedicated restrictions API.
* `accounts` - accounts can not be updated through this API.
* `registrationDate` - can not be updated
## Deactivate a customer
When a customer closes their account with the Merchant, the digital wallet on the Paysafe side must be deactivated.
Deactivation on Paysafe side restricts all customer operations.
The API [Deactivate Customer](#reference/customers/get-customer/deactivate-customer) must be used to achieve that.
## Customer accounts
Account information can be retrieved with the following APIs:
* Get a list of all accounts for a customer - [Get Account List](#reference/wallets/get-account-list/get-account-list)
* Get details and current balance for an account - [Get Account](#reference/wallets/get-account/get-account)
Direct update and delete accounts are not supported via API.
## Change of customer country
Changing customer country requires moving the customer account from one country jurisdiction to another.
It impacts both accounting and compliance handling.
> Legal entities can not change countries.
The process of account migration has the following prerequisites.
* Customer accounts must have zero balance
* Customer must provide address located in the new country
* Base account currency in the new country must be specified upon migration.
* One account must be provided for the initial migration. Additional accounts might be added using the Accounts API.
* The customer accounts in the old country would be deactivated
* KYC address verification information must be passed for the new address.
If not passed the account might be restricted, until the address verification is performed.
> Customer transaction history and verified instruments remain after the account migration.
For changing the customer country, you should use `customer-persons` **PATCH** request and pass all the required parameters for complying with the requirements above.
---
**PATCH** `https://api.paysafe.com/digitalwallets/v1/customer-persons/{customerId}`
```json
{
"address1": "23 Four Str",
"city": "London",
"zip": "E17 033",
"countryCode": "GB",
"kyc": {
"status": "COMPLETED",
"addressVerification": {
"status": "COMPLETED",
"date": "2021-07-15T17:54:12Z",
"documentUrls": [
"https://documents-repository.com/images/doc3"
]
}
},
"accounts": [{
"currencyCode": "GBP",
"hasIban": true
}
]
}
```
---
## Deposit with a card
* Merchant customers will be able to deposit with Visa and Mastercard credit and debit cards in EUR and GBP. Merchant will manage the user experience and can use either Paysafe integrated 3DS solution or with any other 3DS provider directly. Once card payment is processed successfully, the customers wallet balance will be increased with the deposit amount. Merchant will be able to apply a fee to the customer’s card deposits.
* Merchant customers will choose the deposit amount and will provide their card details at merchants website or mobile app.
* Merchant will send a payment request to Paysafe including deposit amount, currency, card details, customer ID and customer fee.
* Paysafe will process the card payment for deposit amount and any fees with the provider.
* Paysafe will increase the customer’s wallet balance with the deposit amount and customer fee.
* Paysafe will debit customer’s wallet with the fees and credit customer fee to Merchant merchant wallet.
## Deposit with Rapid Transfer
Paysafe offers deposits, with instant bank transfer solution [Rapid Transfer](https://www.skrill.com/en/business/rapid-transfer/).
The real-time bank transfer solution is suitable for the smaller basket size transfers. Rapid Transfer payments are normally instant however a small percentage of high risk transactions may have delayed processing for several business days.
* Transaction limits for Rapid Transfer
| Daily | Weekly | Monthly |
|-----------|-----------|------------|
| 5,000 EUR | 7,500 EUR | 25,000 EUR |
### Rapid Transfer Deposit Steps
1. Customer selects 'Rapid Transfer' as the payment type from the Merchant's website
2. (Optional) Merchant calls Paysafe to retrieve a list of available banks and displays to Customer
---
**GET** `https://api2.paysafe.com/digitalwallet/v1/rapidtransferbanks?country=GB`
```json
{
"rapidTransferBanks": [
{
"id": "1000203",
"name": "Natwest UK",
"isAccountRequiredBeforeInitialization": true,
"country": "GB"
}
]
}
```
---
3. Merchant must collect customer’s bank account details (IBAN and SWIFT code for euro payments and sort code and account number for payments in GBP).
4. Merchant calls Paysafe to create a Payment Handle and Paysafe responds with a Redirect URL
---
**POST** `https://api2.paysafe.com/paymenthub/v1/paymenthandles`
```json
{
"merchantRefNum": "merchantRefNum-124",
"transactionType": "PAYMENT",
"rapidTransfer" : {
"sepa": {
"accountHolderName": "John Doe",
"bic": "ABNANL2APIP",
"iban": "DE89370400440532013000"
}
},
"paymentType": "RAPID_TRANSFER",
"amount": 3000,
"currencyCode": "EUR",
"customerIp": "73.82.192.17",
"billingDetails": {
"street": "71 Cherry Court ",
"city": "Southhampton",
"zip": "SO53 5PD",
"country": "GB"
},
"wallet":{
"customerId" : "GGG",
},
"returnLinks": [{
"rel": "on_completed",
"href": "https://US_commerce_site/payment/return/success",
"method": "GET"
},
{
"rel": "on_failed",
"href": "https://US_commerce_site/payment/return/failed",
"method": "GET"
}
]
}
```
**Response**
```json
{
"id": "372b5ee7-6360-4403-b444-164f8f1d2709",
"amount": 3000,
"merchantRefNum": "merchantRefNum-124",
"action": "REDIRECT",
"currencyCode": "EUR",
"usage": "SINGLE_USE",
"status": "INITIATED",
"paymentType": "RAPID_TRANSFER",
"executionMode": "SYNCHRONOUS",
"customerIp": "73.82.192.17",
"paymentHandleToken": "SCyGZDlUuZ9zxjyd",
"billingDetails": {
"street": "71 Cherry Court ",
"city": "Southhampton",
"zip": "SO53 5PD",
"country": "GB"
},
"rapidTransfer" : {
"sepa": {
"accountHolderName": "John Doe",
"bic": "ABNANL2APIP",
"lastDigits": "00"
}
},
"wallet":{
"customerId" : "GGG",
"slipId" : "100753"
},
"returnLinks": [{
"rel": "on_completed",
"href": "https://US_commerce_site/payment/return/success",
"method": "GET"
},
{
"rel": "on_failed",
"href": "https://US_commerce_site/payment/return/failed",
"method": "GET"
}
],
"links": [{
"rel": "redirect_payment",
"href": "http://api.paysafe.com/rapidtransfer/redirect/372b5ee7-6360-4403-b444-164f8f1d2709",
"method": "GET"
}],
"timeToLiveSeconds": 899,
"transactionType": "PAYMENT"
}
```
---
5. Merchant redirects the Customer
6. Customer authenticates banking details and confirms the deposit operation
7. Customer is redirected back to the Merchant or **Merchant recieves a PaymentHandle webhook that is PAYABLE**
---
**POST** `https://<merchant callback URL>`
```json
{
"resourceId": "3aeb9c63-6386-46a3-9f8e-f452e722228a",
"eventDate": "2021-07-15T17:54:12Z",
"eventType": "PAYMENT_HANDLE_PAYABLE",
"payload": {
"id": "372b5ee7-6360-4403-b444-164f8f1d2709",
"amount": 3000,
"merchantRefNum": "merchantRefNum-124",
"action": "NONE",
"currencyCode": "EUR",
"usage": "SINGLE_USE",
"status": "PAYABLE",
"paymentType": "RAPID_TRANSFER",
"executionMode": "SYNCHRONOUS",
"customerIp": "73.82.192.17",
"paymentHandleToken": "SCyGZDlUuZ9zxjyd",
"billingDetails": {
"street": "71 Cherry Court ",
"city": "Southhampton",
"zip": "SO53 5PD",
"country": "GB"
},
"rapidTransfer": {
"sepa": {
"accountHolderName": "John Doe",
"bic": "ABNANL2APIP",
"lastDigits": "00"
}
},
"wallet": {
"customerId": "GGG",
"slipId": "100753"
},
"returnLinks": [
{
"rel": "on_completed",
"href": "https://US_commerce_site/payment/return/success",
"method": "GET"
},
{
"rel": "on_failed",
"href": "https://US_commerce_site/payment/return/failed",
"method": "GET"
}
],
"links": [
{
"rel": "redirect_payment",
"href": "http://api.paysafe.com/rapidtransfer/redirect/372b5ee7-6360-4403-b444-164f8f1d2709",
"method": "GET"
}
],
"timeToLiveSeconds": 899,
"transactionType": "PAYMENT"
}
}
```
---
> **NOTE** A redirect may not always occur as it is depenant on the Customer, browser and connection. The webhook shold be used as a failsafe to complete the payment to avoid reconcilliation issues.
8. Merchant looks up the status of the payment handle
> **NOTE** Only required if webhook not recieved
---
**GET** `https://api2.paysafe.com/paymenthub/v1/paymenthandles/{paymenthandleid}`
```json
{
"id": "372b5ee7-6360-4403-b444-164f8f1d2709",
"amount": 3000,
"merchantRefNum": "merchantRefNum-124",
"action": "NONE",
"currencyCode": "EUR",
"usage": "SINGLE_USE",
"status": "PAYABLE",
"paymentType": "RAPID_TRANSFER",
"executionMode": "SYNCHRONOUS",
"customerIp": "73.82.192.17",
"paymentHandleToken": "SCyGZDlUuZ9zxjyd",
"billingDetails": {
"street": "71 Cherry Court ",
"city": "Southhampton",
"zip": "SO53 5PD",
"country": "GB"
},
"rapidTransfer" : {
"sepa": {
"accountHolderName": "John Doe",
"bic": "ABNANL2APIP",
"lastDigits": "00"
}
},
"wallet":{
"customerId" : "GGG",
"slipId" : "100753"
},
"returnLinks": [{
"rel": "on_completed",
"href": "https://US_commerce_site/payment/return/success",
"method": "GET"
},
{
"rel": "on_failed",
"href": "https://US_commerce_site/payment/return/failed",
"method": "GET"
}
],
"links": [{
"rel": "redirect_payment",
"href": "http://api.paysafe.com/rapidtransfer/redirect/372b5ee7-6360-4403-b444-164f8f1d2709",
"method": "GET"
}],
"timeToLiveSeconds": 899,
"transactionType": "PAYMENT"
}
```
---
9. Merchant finalizes the payment by POST-ing a payment
> **NOTE** After the **Customer** is redirected to Rapid Transfer and Payment Handle becomes PAYABLE, the **Customer** might authorize the payment, regardless of whether the Payment is posted by the **Merchant**. That is why POST-ing Payment for PAYABLE handle is important, so the Deposit status can be tracked.
---
**POST** `https://api2.paysafe.com/paymenthub/v1/payments`
```json
{
"merchantRefNum": "merchantRefNum-123",
"amount": 3000,