-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathpaysafeembeddedfinanceapis-apiary.apib
2090 lines (1830 loc) · 117 KB
/
paysafeembeddedfinanceapis-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.paysafe.com/
# Paysafe - Embedded Finance APIs v2.2
Paysafe's platform offering caters to merchants that need to implement embedded finance services into their products,
such as marketplaces, e-commerce, electronic goods and more.
## Authentication
In order for you to use the Paysafe REST API, Paysafe must first set you up on their system and provide you with an API key.
Your API key looks something like this:
* Key Username – MerchantXYZ </li>
* Key Password – B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702151182fdc952272661d290ab2e5849e31bb03deede7e
Note that this is not the same as your Merchant Back Office username and password.
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.
3. The authorization method and a 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:
`Authorization: Basic TWVyY2hhbnRYWVo6Qi10c3QxLTAtNTFlZDM5ZTQtMzEyZDAyMzQ1ZDNmMTIzMTIwODgxZGZmOWJiNDAyMGE4OWU4YWM0NGNkZmRjZWNkNzAyMTUxMTgyZmRjOTU yMjcyNjYxZDI5MGFiMmU1ODQ5ZTMxYmIwM2RlZWRlN2U=`
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
<a name="apikeys" title="Get your API Keys"></a>
The API uses a distinct API key:<br/>
* The Secret Key – used for all server-to-server API requests.
You can retrieve your Secret key for your account via the [Business Portal](https://merchant.paysafe.com/portal/login).
<a name="secretapikey" title="Secret API Key"></a>
#### Secret API Key
You use the Secret API key in all your server-to-server API requests.
> **Note:** You must Base64 Encode your Secret API key before using it in your API requests.
To retrieve your Secret API key from the Business Portal:
1. Go to **Integrate>API Keys**.
2. Under **Secret Key**, click **Authenticate Now**.
3. Enter your Business Portal password and click **Authenticate**.
4. You can now access your Secret API key.
> **Note:** All your APIs will use the same API key.
Your API key will have the following format:
* Key Username – MerchantXYZKey
* Password – B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702151182fdc952272661d290ab2e5849e31bb03deede7e
The API key is case-sensitive and sent using HTTP Basic Authentication.
To use HTTP Basic Authentication, you must send the API key credentials using the Authorization header with every request.
You must construct the Authorization header as follows:
1. Combine the Key Username and Key Password into a string separated by a colon, for example, “Key Username:Key Password”.
2. The resulting string literal is then encoded using Base64.
3. The authorization method and space (That is, “Basic”) are then put before the encoded string.
For example, using the above Key Username and Password, the header is formed as follows:
```Authorization: Basic TWVyY2hhbnRYWVo6Qi10c3QxLTAtNTFlZDM5ZTQtMzEyZDAyMzQ1ZDNmMTIzMTIwODgxZGZmOWJiNDAyMGE4OWU4YWM0NGNkZmRjZWNkNzAyMTUxMTgyZmRjOTU yMjcyNjYxZDI5MGFiMmU1ODQ5ZTMxYmIwM2RlZWRlN2U=```
For additional details, please refer [Authentication](https://developer.paysafe.com/en/rest-apis/reference-information/important-integration-concepts/authentication/).
## API Overview
Built on top of Paysafe's solid API infrastructure, it requires minimal enhancement in terms of integration, authentication and monitoring.
The service can easily and securely process payments & wallet requests from your customers using a single API.
Paysafe's all-in-one Business Portal
allows the merchant to access transaction analytics and manage the merchant account.
### API Endpoints
**URL** `https://api2.paysafe.com/digitalwallet/v1`
|Endpoint URL|Description|Action|
|:--- |:--- | :---|
|/wallets|Onboard a customer|POST|
|/customers|Lookup a customer's details|GET|
|/accounts|Lookup a customer's account details|GET|
|/rapidTransferBanks|Lookup banks supported for a countryamount|GET|
|/transactions|Lookup a transaction details|GET|
**URL** `https://api2.paysafe.com/paymenthub/v1`
|Endpoint URL|Description|Action|
|:--- |:--- | :---|
|/paymenthandles|Initiate a payment request|POST|
|/payments|Finalize a payment request|POST|
|/standaloneCredits|Standalone Credits allow merchants to issue payouts to customers|POST|
### 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/).
<a name="globalinvalidcharacters" title="Global Invalid Characters"></a>
### 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.
<a name="isostandards" title="ISO Standards"></a>
### 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 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, Country Codes.
## Error Summary
### Common Errors
| HTTP Status Code | Error Code | Description |
|------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 500 | 1000 | An internal error occurred. |
| 502 | 1001 | An error occurred with the external processing gateway. |
| 500 | 1002 | An internal error occurred. |
| 500 | 1003 | An internal error occurred. |
| 500 | 1007 | An internal error occurred. |
| 500 | 1008 | An internal error occurred. |
| 429 | 1200 | The API call has been denied as it has exceeded the permissible call rate limit. |
| 401 | 5000 | Your merchant account authentication failed. Either your store ID/password is invalid or the IP address from which you are sending the transaction has not been authorized. |
| 400 | 5001 | The submitted currency code is invalid or your account does not support this currency. |
| 400 | 5003 | You submitted an invalid amount with your request. |
| 400 | 5004 | You submitted an invalid account type with your request. |
| 400 | 5005 | You submitted an invalid operation type with your request. |
| 400 | 5010 | The submitted country code is invalid. |
| 400 | 5016 | The merchant account you provided cannot be found. |
| 400 | 5017 | The merchant account you provided is disabled. |
| 402 | 5021 | Your transaction request has been declined. |
| 400 | 5023 | The request is not parseable. |
| 409 | 5031 | The transaction you have submitted has already been processed. |
| 401 | 5040 | Your merchant account is not configured for the transaction you attempted. |
| 400 | 5042 | The merchant reference number is missing or invalid or it exceeds the maximum permissible length. |
| 400 | 5068 | Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. |
| 404 | 5269 | The ID(s) specified in the URL do not correspond to the values in the system. |
| 403 | 5270 | The credentials provided with the request do not have permission to access the requested data. |
| 406 | 5271 | You requested a response in the 'Accept' header that is in an unsupported format. |
| 406 | 5272 | The 'Content-Type' you specified in request header was submitted in an unsupported format. |
| 404 | 5273 | Your client reached our application but we were unable to service your request due to an invalid URL. |
| 401 | 5275 | The authentication credentials provided with the request have expired. |
| 401 | 5276 | The authentication credentials provided with the request provided have been disabled. |
| 401 | 5277 | The authentication credentials provided with the request have been locked due to multiple authentication failures. |
| 401 | 5278 | The authentication credentials provided with the request were not accepted for an unknown reason. |
| 401 | 5279 | The authentication credentials are invalid. |
| 401 | 5280 | The required authentication credentials were not provided. |
| 405 | 5281 | The request uses an action (for example, GET, POST, or PUT) that is not supported by the resource. |
| 400 | 5283 | The requested operation can only be executed on a Payment Handle with the status of *PAYABLE*. |
| 400 | 5501 | The profile does not have an active credit card. |
| 400 | 5502 | Either the payment token is invalid or the corresponding profile or bank account is not active. |
### Payment Errors
| HTTP Status Code | Error Code | Description |
|------------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 400 | PAYMENTHUB-1 | The submitted payment type and currency code combination is not supported. |
| 400 | 3002 | You submitted an invalid card number or brand or combination of card number and brand with your request. |
| 400 | 3004 | The zip/postal code must be provided for an AVS check request. |
| 400 | 3005 | You submitted an incorrect CVV value with your request. |
| 400 | 3006 | You submitted an expired credit card number with your request. |
| 402 | 3007 | Your request has failed the AVS check. Note that the amount has still been reserved on the customer's card and will be released in 3–5 business days. Please ensure the billing address is accurate before retrying the transaction. |
| 400 | 3008 | You submitted a card type for which the merchant account is not configured. |
| 402 | 3009 | Your request has been declined by the issuing bank. |
| 402 | 3011 | Your request has been declined by the issuing bank because the card used is a restricted card. Contact the cardholder's credit card company for further investigation. |
| 402 | 3012 | Your request has been declined by the issuing bank because the credit card expiry date submitted is invalid. |
| 402 | 3013 | Your request has been declined by the issuing bank due to problems with the credit card account. |
| 402 | 3014 | Your request has been declined - the issuing bank has returned an unknown response. Contact the card holder's credit card company for further investigation. |
| 402 | 3015 | The bank has requested that you process the transaction manually by calling the cardholder's credit card company. |
| 402 | 3016 | The bank has requested that you retrieve the card from the cardholder – it may be a lost or stolen card. |
| 402 | 3017 | You submitted an invalid credit card number with your request. |
| 402 | 3018 | The bank has requested that you retry the transaction. |
| 402 | 3019 | Your request has failed the CVV check. Please note that the amount may still have been reserved on the customer's card, in which case it will be released in 3–5 business days. |
| 402 | 3020 | The bank has requested that you retry the transaction. |
| 404 | 3021 | The confirmation number included in this request could not be found. |
| 402 | 3022 | The card has been declined due to insufficient funds. |
| 402 | 3023 | Your request has been declined by the issuing bank due to its proprietary card activity regulations. |
| 402 | 3024 | Your request has been declined because the issuing bank does not permit the transaction for this card. |
| 400 | 3025 | The external processing gateway has reported invalid data. |
| 400 | 3026 | The external processing gateway has reported the account type is invalid. |
| 402 | 3027 | The external processing gateway has reported a limit has been exceeded. |
| 502 | 3028 | The external processing gateway has reported a system error. |
| 402 | 3029 | The external processing gateway has rejected the transaction. |
| 402 | 3030 | The external processing gateway has reported the transaction is unauthorized. |
| 400 | 3031 | The confirmation number you submitted with your request references a transaction that is not on hold. |
| 402 | 3032 | Your request has been declined by the issuing bank or external gateway because the card is probably in one of their negative databases. |
| 402 | 3035 | Your request has been declined due to exceeded PIN attempts. |
| 402 | 3036 | Your request has been declined due to an invalid issuer. |
| 402 | 3037 | Your request has been declined because it is invalid. |
| 402 | 3038 | Your request has been declined due to customer cancellation. |
| 402 | 3039 | Your request has been declined due to an invalid authentication value. |
| 402 | 3040 | Your request has been declined because the request type is not permitted on the card. |
| 402 | 3041 | Your request has been declined due to a timeout. |
| 402 | 3042 | Your request has been declined due to a cryptographic error. |
| 402 | 3044 | You have submitted a duplicate request. |
| 402 | 3045 | You submitted an invalid date format for this request. |
| 402 | 3046 | The transaction was declined because the amount was set to zero. |
| 402 | 3047 | The transaction was declined because the amount exceeds the floor limit. |
| 402 | 3048 | The transaction was declined because the amount is less than the floor limit. |
| 402 | 3049 | The bank has requested that you retrieve the card from the cardholder – the credit card has expired. |
| 402 | 3050 | The bank has requested that you retrieve the card from the cardholder – fraudulent activity is suspected. |
| 402 | 3051 | The bank has requested that you retrieve the card from the cardholder – contact the acquirer for more information. |
| 402 | 3052 | The bank has requested that you retrieve the card from the cardholder – the credit card is restricted. |
| 402 | 3053 | The bank has requested that you retrieve the card from the cardholder – please call the acquirer. |
| 402 | 3054 | The transaction was declined due to suspected fraud. |
| 402 | 3055 | This type of transaction is not supported. |
| 402 | 3056 | The original transaction type does not match. |
| 402 | 3057 | Please tell cardholder to call the issuer – do not retry transaction. |
| 409 | 5284 | An entity with the specified identifier(s) already exists. |
| 400 | 5286 | Card with the specified identifier(s) does not exist. |
| 404 | 5288 | Card does not belong to consumer. |
| 400 | 5303 | Payment instrument already exists. |
| 400 | 5304 | Expired card. |
| 403 | 5309 | The maximum amount of money allowed for the requested operation is exceeded. |
### Alternate Payments Errors
| HTTP Status | Error Code | Message | Details |
|-------------|-------------------------------|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| 402 | ALTERNATE-PAYMENTS-GATEWAY-1 | Transaction cancelled at the gateway | The transaction was cancelled at the gateway. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-4 | Transaction declined by the gateway | The transaction declined by the gateway. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-5 | Incomplete transaction | The requested operation can only be executed on a completed transaction. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-6 | Over refund | The total refund amount cannot exceed the original payment amount. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-7 | Payment expired | The payment has expired. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-8 | Over settlement | The total Settlement amount cannot exceed the authorized (payment) amount. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-9 | Risk gateway error | A risk issue was reported by the gateway. |
| 502 | ALTERNATE-PAYMENTS-GATEWAY-10 | Payment type temporarily unavailable | The gateway is temporarily unavailable due to system maintenance activities. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-11 | Over voidauth | The void authorization cannot exceed the amount remaining to settle for the corresponding payment. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-12 | Payment already settled | The payment is already partially/fully settled. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-13 | Transaction not refundable yet | The transaction is not refundable yet. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-14 | Partial settlements not possible | Partial Settlements are not possible with the selected payment method. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-16 | The requested amount exceeds the allowed maximum for the specified payment type. | The requested amount exceeds the allowed maximum for the specified payment type. |
| 504 | ALTERNATE-PAYMENTS-GATEWAY-17 | Your request timed out before it could be completed. | Your request timed out before it could be completed. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-19 | The payment instrument does not have sufficient funds. | The payment instrument does not have sufficient funds. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-20 | The third-party account has not been activated. | The third-party account has not been activated. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-21 | The requested amount is under the allowed minimum amount for the specified payment type. | The requested amount is under the allowed minimum amount for the specified payment type. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-22 | The provided identity details do not match the identity details already present. | The provided identity details do not match the identity details already present. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-23 | The KYC documents provided could not be verified. | The KYC documents provided could not be verified. |
| 402 | ALTERNATE-PAYMENTS-GATEWAY-24 | There is an already existing third-party account with the details provided. | There is an already existing third-party account with the details provided. |
### Wallet Errors
| HTTP Status Code | Error Code | Message |
|------------------|---------------------------------------------|------------------------------------------------------------------|
| 400 | DW-CUSTOMER-ACCOUNT-ID-SHOULD-BE-NUMERIC | AccountId should be numeric value |
| 400 | DW-CUSTOMER-BAD-REQUEST | Bad request for customer operation. |
| 400 | DW-CUSTOMER-BIRTH-DATE-CHANGE-NOT-SUPPORTED | Birth date change is not supported |
| 400 | DW-CUSTOMER-COUNTRY-NOT-SUPPORTED | Country is not supported |
| 400 | DW-CUSTOMER-CURRENCY-NOT-SUPPORTED | Currency is not supported for the specified country |
| 400 | DW-CUSTOMER-EMAIL-CHANGE-NOT-SUPPORTED | Email change is not supported |
| 400 | DW-CUSTOMER-ID-SHOULD-BE-NUMERIC | CustomerId should be numeric value |
| 400 | DW-TERMS-AND-CONDITIONS-NOT-ACCEPTED | Terms and conditions are not accepted. |
| 409 | DW-CUSTOMER-ALREADY-ACTIVATED | Customer is already activated. |
| 409 | DW-CUSTOMER-ALREADY-DEACTIVATED | Customer is already deactivated. |
| 409 | DW-CUSTOMER-ALREADY-ONBOARDED | Customer with the same details has already been onboarded. |
| 409 | DW-CUSTOMER-CONFLICT | There was a conflict (validation error). Check body for details. |
| 500 | DW-CUSTOMER-INTERNAL-SERVER-ERROR | There was an error while processing the customer operation. |
| 503 | DW-SERVICE-UNAVAILABLE | Service Unavailable |
## 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 URL:
`https://api2.test.paysafe.com/digitalwallets/v1/`
For example:
`https://api2.test.paysafe.com/digitalwallet/v1/customers/{customer_id}`
# Group Digital Wallet
Paysafe's provides ledger, multiple currencies, multiple region coverage, risk
and AML monitoring and a multitude of payment options providing an out-of-the-box, compliant e-money platform.
## Wallets [/digitalwallets/v1/wallets]
Create a customer and their account(s) through a single request
+ Attributes (Wallet)
### Onboard a Customer [POST]
Business requirements for creating a new wallet:
* KYC verifications passed - a flag must be passed when creating a customer wallet that denotes that, and is the proof that Paysafe accepts that the customer was indeed verified. If the value of this flag is different than ``, the wallet creation will fail
* Paysafe requires certain mandatory data points about the customer and identity metadata to be provided for a customer wallet account to be created. The details are documented in the API documentation.
* The currency of a wallet can only be created in EUR for the EEA and in GBP for the UK.
Call **Onboard a customer**, with 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.
* `accounts` - at least one account object has to be populated; please refer to Merchant's agreement with Paysafe for a list of supported wallet currencies. 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` must be equal
* 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.
> NOTE: Assigning virtual IBAN will be different due to differences in the region and bank used. Paysafe will try to return the information as soon as possible.
><br>
> When creating a new customer, the response man include a virtual IBAN assigned to the account. This means that Paysafe managed to assign the virtual IBAN to the customer, and no subsequent webhooks will be sent.
><br>
> If the response DOES NOT contain a value for the account's `iban`, this means that the virtual IBAN will be assigned asynchronously. In this case the Merchant must wait for a webhook that will notify the availability of the virtual IBAN for this customer. When the webhook received, the Merchant must fetch the IBAN via the get Accounts API (due to information security requirements, Paysafe should not send the IBAN via a webhook).
When creating a wallet for an **newly signed-up customer**, the `totalBalance` and `availableBalance` fields for all `account` objects must be set to 0.
To migrate the balance, Merchant calls 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 email provided is not unique and a wallet is already created
using this email address, the creation of a new wallet will fail.
After creating the wallet, the customer could be restricted on Paysafe side
based on regulatory and risk checks.
+ Request Onboard a Customer (application/json)
+ Headers
Authorization: "Basic YOUR-BASE64-ENCODED-API-KEY"`
+ Body
{
"customer": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"address1": "23 Four Street",
"zip": "LE14",
"countryCode": "BG",
"birthDate": "1999-08-24",
"registrationIp": "192.0.250",
"nationality": "EU",
"externalId": "d6f475fe-57c9-4865-9316-0c3b8e8128d4",
"kyc": {
"status": "COMPLETED"
},
"type": "PERSON"
},
"accounts": [
{
"externalId": "merchant-id",
"currencyCode": "EUR",
"hasIban": true
}
],
"risk": {
"customerRiskRating": 50
},
"customerIp": "192.0.250"
}
+ Response 200 (application/json)
+ Body
{
"customer": {
"id": "5435323362",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"address1": "23 Four Street",
"zip": "LE14",
"countryCode": "BG",
"birthDate": "1999-08-24",
"registrationIp": "192.0.250",
"nationality": "EU",
"externalId": "d6f475fe-57c9-4865-9316-0c3b8e8128d4",
"kyc": {
"status": "COMPLETED",
},
"type": "PERSON",
},
"accounts": [
{
"id": "42342355",
"externalId": "merchant-id",
"currencyCode": "EUR",
"hasIban": true,
"iban": "NL74ABNA1231242344",
"totalBalance": 0,
"availableBalance": 0,
"creationTime": "2019-08-24T14:15:22Z"
}
],
"risk": {
"customerRiskRating": 50,
"isScaPerformed": false,
"isCustomerIPTrusted": false,
"isBeneficiaryTrusted": false
},
"customerIp": "192.0.250"
}
## Customers [/digitalwallets/v1/customers/{customerId}]
Manage and get details about a customer
+ Attributes (Customer)
### Lookup a Customer [GET]
+ Request Look up a customer's details
+ Headers
Authorization: "Basic YOUR-BASE64-ENCODED-API-KEY"
+ Parameters
+ customerId: 5435323362 (string, required)
+ Response 200 (application/json)
+ Body
{
"id": "5435323362",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"address1": "23 Four Street",
"zip": "LE14",
"countryCode": "GB",
"birthDate": "1999-08-24",
"registrationIp": "192.0.250",
"nationality": "GB",
"externalId": "d6f475fe-57c9-4865-9316-0c3b8e8128d4",
"kyc": {
"status": "COMPLETED",
},
"type": "PERSON"
}
## Accounts [/digitalwallets/v1/accounts/{accountId}]
Manage and get details about a customer account
+ Attributes (Account)
### Lookup a Customer Account[GET]
+ Request Look up a customer's account details
+ Headers
Authorization: "Basic YOUR-BASE64-ENCODED-API-KEY"
+ Parameters
+ accountId: 5435323362 (string, required)
+ Response 200 (application/json)
+ Body
{
"id": "509876034",
"customerId": "5435323362",
"externalId": "22e8b836-2302-49f5-b13d-537ccdbbb41d",
"currencyCode": "GBP",
"totalBalance": 55000,
"availableBalance": 50000,
"iban": "NL74ABNA1231242344",
"bic": "ABNANL2A",
"creationTime": "2019-08-24T14:15:22Z",
"hasIban": true
}
## Rapid Transfer Banks [/digitalwallets/v1/rapidtransferbanks/?{country}&{amount}]
### Get available banks for Rapid Transfer [GET]
Returns a list of supported banks for instant bank transfers for the country specified, along with additional information
+ Request Get available banks for Rapid Transfer
+ Headers
Authorization: "Basic YOUR-BASE64-ENCODED-API-KEY"
+ Parameters
+ country: DE (string, required)
ISO Alpha2 country code
+ amount: 25000 (number, optional)
Transaction amounts
+ Response 200 (application/json)
+ Body
{
"rapidTransferBanks": [
{
"id": "1000203",
"bic": "NWBKGB2L",
"name": "Natwest uk",
"isAccountRequiredBeforeInitialization": true,
"limit": "15000000",
"country": "GB"
}
]
}
# Group Payment Hub
Connect your application directly with our payment engine to process a full suite of methods that are REST-based – designed to be easy to
understand and use.
- Choose an efficient, lightweight, and fast integration method to access our API.
- Implement a wide variety of REST-based API requests – including Payment Handles, Purchases and Standalone Credits.
## Payment Handles [/paymenthub/v1/paymenthandles]
A Payment Handle represents tokenized information about the payment method that you set up for your customer. Once the Payment Handle is created, you can then include the *paymentHandleToken* returned in the Payment Handle request response in a new [payment request](#paymentrequest).
<br>
> **Note:** A Payment Handle can be used in a [Payment request](#paymentrequest) only if it has the status of **PAYABLE**.
+ Attributes (PaymentHandle)
### Create a Payment Handle [POST]
* A Payment Handle for a standard credit card authorization
* A Payment Handle for a credit card that is registered for 3D Secure - the response for this request will contain a redirect to present to the customer so they can validate their 3D Secure credentials
* A Payment Handle for a credit card Standalone Credit
> **Note:** The *status* of Payment Handles will remain INITIATED for the following cases:
* When the customer is redirected to a *redirect_payment* URL until the customer verifies the payment instrument.
* When the requested amount is more than the maximum amount configured in the Business Portal.
* When Alternate Payment Methods like RapidTransfer, Paysafecash, Paysafecards are selected by the customer.
+ Request Create Payment Handle for Rapid Transfer for Payment (application/json)
+ Headers
Authorization: "Basic YOUR-BASE64-ENCODED-API-KEY"
+ Body
{
"merchantRefNum": "merchantRefNum-124",
"transactionType": "PAYMENT",
"rapidTransfer" : {
"sepa": {
"accountHolderName": "John Doe",
"rapidTransferBankId": "1000203"
}
},
"paymentType": "RAPID_TRANSFER",
"amount": 3000,
"currencyCode": "GBP",
"customerIp": "73.82.192.17",
"billingDetails": {
"street": "100 Queen",
"street2": "Unit 201",
"city": "Toronto",
"zip": "M5H 2N2",
"country": "CA"
},
"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 200 (application/json)
+ Body
{
"id": "372b5ee7-6360-4403-b444-164f8f1d2709",
"amount": 3000,
"merchantRefNum": "merchantRefNum-124",
"action": "REDIRECT",
"currencyCode": "GBP",
"usage": "SINGLE_USE",
"status": "INITIATED",
"paymentType": "RAPID_TRANSFER",
"executionMode": "SYNCHRONOUS",
"customerIp": "73.82.192.17",
"paymentHandleToken": "SCyGZDlUuZ9zxjyd",
"billingDetails": {
"street": "100 Queen",
"street2": "Unit 201",
"city": "Toronto",
"country": "CA",
"zip": "M5H 2N2"
},
"rapidTransfer" : {
"sepa": {
"accountHolderName": "John Doe",
"rapidTransferBankId": "1000203",
"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"
}
+ Request Create Payment Handle for Bank Wire Transfer for Standalone Credit (application/json)
+ Headers
Authorization: "Basic YOUR-BASE64-ENCODED-API-KEY"
Simulator: "EXTERNAL"
+ Body
{
"merchantRefNum": "merchantRefNum-124",
"transactionType": "STANDALONE_CREDIT",
"sepa": {
"nickName": "Sally's Barclays Account",
"accountHolderName": "John Doe",
"bic": "ABNANL2APIP",
"iban": "DE89370400440532013000"
},
"paymentType": "BANK_TRANSFER",
"amount": 3000,
"currencyCode": "EUR",
"customerIp": "73.82.192.17",
"billingDetails": {
"nickName": "Home",
"street": "100 Queen",
"street2": "Unit 201",
"city": "Toronto",
"zip": "M5H 2N2",
"country": "CA"
},
"wallet":{
"customerId" : "GGG",
"verifiedInstrument" : false,
"customerAccount" : {
"id":"abc"
}
}
}
+ Response 200 (application/json)
+ Body
{
"id": "372b5ee7-6360-4403-b444-164f8f1d2709",
"amount": 3000,
"merchantRefNum": "merchantRefNum-124",
"action": "NONE",
"currencyCode": "EUR",
"usage": "SINGLE_USE",
"status": "PAYABLE",
"paymentType": "BANK_TRANSFER",
"executionMode": "SYNCHRONOUS",
"customerIp": "73.82.192.17",
"paymentHandleToken": "SCyGZDlUuZ9zxjyd",
"billingDetails": {
"nickName": "Home",
"street": "100 Queen",
"street2": "Unit 201",
"city": "Toronto",
"country": "CA",
"zip": "M5H 2N2"
},
"sepa": {
"nickName": "Sally's Barclays Account",
"accountHolderName": "John Doe",
"bic": "ABNANL2APIP",
"lastDigits": "00"
},
"wallet":{
"customerId" : "GGG",
"slipId" : "100753",
"verifiedInstrument" : false,
"customerAccount" : {
"id":"abc"
}
},
"timeToLiveSeconds": 899,
"transactionType": "STANDALONE_CREDIT"
}
+ Request Create Payment Handle for Faster Payments for Standalone Credit (application/json)
+ Headers
Authorization: "Basic YOUR-BASE64-ENCODED-API-KEY"
Simulator: "EXTERNAL"
+ Body
{
"merchantRefNum": "merchantRefNum-124",
"transactionType": "STANDALONE_CREDIT",
"fasterPayments": {
"accountHolderName": "John Doe",
"sortCode": "321654",
"accountNumber": "98877219"
},
"paymentType": "BANK_TRANSFER",
"amount": 3000,
"currencyCode": "GBP",
"customerIp": "73.82.192.17",
"billingDetails": {
"nickName": "Home",
"street": "100 Queen",
"street2": "Unit 201",
"city": "Toronto",
"zip": "M5H 2N2",
"country": "CA"
},
"wallet":{
"customerId" : "GGG",
"verifiedInstrument" : true,
"customerAccount" : {
"id":"abc"
}
}
}
+ Response 200 (application/json)
+ Body
{
"id": "372b5ee7-6360-4403-b444-164f8f1d2709",
"amount": 3000,
"merchantRefNum": "merchantRefNum-124",
"action": "NONE",
"currencyCode": "GBP",
"usage": "SINGLE_USE",
"status": "PAYABLE",
"paymentType": "BANK_TRANSFER",
"executionMode": "SYNCHRONOUS",
"customerIp": "73.82.192.17",
"paymentHandleToken": "SCyGZDlUuZ9zxjyd",
"billingDetails": {
"nickName": "Home",
"street": "100 Queen",
"street2": "Unit 201",
"city": "Toronto",
"country": "CA",
"zip": "M5H 2N2"
},
"fasterPayments": {
"accountHolderName": "John Doe",
"sortCode": "321654",
"lastDigits": "19"
},
"wallet":{
"customerId" : "GGG",
"slipId" : "100753",
"verifiedInstrument" : true,
"customerAccount" : {
"id":"abc"
}
},
"timeToLiveSeconds": 899,
"transactionType": "STANDALONE_CREDIT"
}
## Payments [/paymenthub/v1/payments]
Process a payment using the paymentHandleToken.
+ Attributes (Payment)
### Process a payment [POST]
+ Request Process a Rapid Transfer (application/json)
+ Headers
Authorization: "Basic YOUR-BASE64-ENCODED-API-KEY"
+ Body
{
"merchantRefNum": "merchantRefNum-123",
"amount": 1000,
"currencyCode": "GBP",
"paymentHandleToken": "SCyGZDlUuZ9zxjyd",
"description": "Consumer Purchase",
"customerIp": "73.82.192.17"
}
+ Response 201 (application/json)
+ Body
{
"id": "3aeb9c63-6386-46a3-9f8e-f452e722228a",
"merchantRefNum": "merchantRefNum-123",
"amount": 1000,
"currencyCode": "GBP",
"paymentHandleToken": "SCyGZDlUuZ9zxjyd",
"paymentType": "RAPID_TRANSFER",
"rapidTranfer": {
"sepa": {
"nickName": "Sally's Barclays Account",
"accountHolderName": "XYZ Company",
"bic": "ABNANL2APIP",
"lastDigits": "11"
}
},
"description": "Consumer Purchase",
"customerIp": "73.82.192.17",
"availableToSettle": 0,
"status": "PROCESSING",
"wallet": {
"customerId": "abc",
"slipId": "100753",
"customerAccount": {
"id": "xyz",
"transactions": [
{
"id": "12321",
"type": "DEPOSIT",
"amount": 1000,
"currencyCode": "GBP",
"creationTime": "2021-07-15T17:54:12Z",
"direction": "CREDIT",
"paymentType": "RAPID_TRANSFER",
"status": "PROCESSING",
"merchantRefNum": "merchantRefNum-123"
}
]
}
},
"txnTime": "2018-12-11T16:33:49Z"
}
### Lookup a Payment [/paymenthub/v1/payments/{paymentId}]
#### Lookup a Payment [GET]
+ Request Look up a Payment details
+ Headers
Authorization: "Basic YOUR-BASE64-ENCODED-API-KEY"
+ Parameters
+ paymentId: 3aeb9c63-6386-46a3-9f8e-f452e722228a (string, required)
+ Response 200 (application/json)
+ Body
{
"id": "3aeb9c63-6386-46a3-9f8e-f452e722228a",
"merchantRefNum": "merchantRefNum-123",
"amount": 1000,
"currencyCode": "GBP",
"paymentHandleToken": "SCyGZDlUuZ9zxjyd",
"paymentType": "RAPID_TRANSFER",
"rapidTranfer": {
"sepa": {
"nickName": "Sally's Barclays Account",
"accountHolderName": "XYZ Company",
"bic": "ABNANL2APIP",
"lastDigits": "11"
}
},
"description": "Consumer Purchase",
"customerIp": "73.82.192.17",
"availableToSettle": 0,
"status": "PROCESSING",
"wallet": {
"customerId": "abc",
"slipId": "100753",
"customerAccount": {
"id": "xyz",
"transactions": [
{
"id": "12321",
"type": "DEPOSIT",
"amount": 1000,
"currencyCode": "GBP",
"creationTime": "2021-07-15T17:54:12Z",
"direction": "CREDIT",
"paymentType": "RAPID_TRANSFER",
"status": "PROCESSING",
"merchantRefNum": "merchantRefNum-123"
}
]
}
},
"txnTime": "2018-12-11T16:33:49Z"
}
## Standalone Credits [/paymenthub/v1/standalonecredits]
Standalone Credits allow merchants to issue payouts to customers.
**Note:** If your merchant category code (MCC) is listed to [process Original Credits](#originalcreditrequest), you must not use Standalone Credits with credit cards.
+ Attributes (StandaloneCredit)
### Process Standalone Credit [POST]
+ Request Process a Standalone Credit Using a Bank wire Transfer Payment Handle Token (application/json)
+ Headers
Authorization: "Basic YOUR-BASE64-ENCODED-API-KEY"
+ Body
{
"amount": 400,
"merchantRefNum": "merchantRefNum-151",
"currencyCode": "EUR",
"paymentHandleToken": "SC9mbfZSITB5OwDJ",
"customerIp": "73.82.192.17",
"description": "Pay surplus"
}
+ Response 200 (application/json)
+ Body
{
"id": "e075f2ae-dfc4-4f6d-8d89-61158367b6a6",
"amount": 400,
"merchantRefNum": "merchantRefNum-151",
"paymentHandleToken": "SC9mbfZSITB5OwDJ",
"customerIp": "73.82.192.17",
"currencyCode": "EUR",
"paymentType": "BANK_TRANSFER",
"status": "PROCESSING",
"description": "Pay surplus",
"sepa": {
"nickName": "Sally's Barclays Account",
"accountHolderName": "John Doe",
"bic": "ABNANL2APIP",
"lastDigits": "00"
},
"wallet":{
"customerId" : "abc",
"slipId" : "100753",
"verifiedInstrument" : true,
"customerAccount" : {
"id":"xyz",
"transactions": [{
"id": "12321",
"type": "TRANSFER_IN",
"amount": 400,
"currencyCode": "EUR",
"creationTime": "2021-07-15T17:54:12Z",
"direction": "CREDIT",
"paymentType": "BANK_TRANSFER",
"status": "COMPLETED",