forked from paysafecard/api-documentation
-
Notifications
You must be signed in to change notification settings - Fork 59
/
Copy pathpaysafecardsopgen-apiary.apib
1248 lines (1047 loc) · 73.1 KB
/
paysafecardsopgen-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://soatest.paysafecard.com/psc/services/PscService
# Integrating the PaysafeCard SOPG API
# Integration Process Overview
The following provides the necessary steps that need to be completed in order to integrate PaysafeCard in a webshop.
+ **Test Data**: PaysafeCard provides the test data package. This contains an SOPG username together with the matching password (technical authentication), information of the merchant account, the documentation, a link to the logo and to the sample codes.
+ **Integration in Test Environment**: The webshop needs to integrate PaysafeCard into their test system. For this, the sample codes might be used. Detailed information on the payment flow and the API calls are to be found in the documentation.
+ **Integration Test**: As soon as the integration is completed on the test environment, the webshop needs to provide a URL and 2 test users to PaysafeCard, so the technical support team can test the integration (technical payment flow and brand assurance)
+ **Production Data**: If the test is finished successfully, PaysafeCard provides the productive data (SOPG credentials)
+ **Switch Integration to Production**: The webshop needs to switch the PaysafeCard integration to the production system (change API endpoints and the SOPG credentials)
+ **IP whitelisting**: The webshop needs to provide their IPs, so PaysafeCard can whitelist them on their system
+ **Final Check**: When this setup is done, the webshop needs to provide a URL and 2 test users to PaysafeCard. The technical support team will then process a real money End-to-End test
+ **Go-Live**: As soon as this last test is completed successfully, the integration is finished and can be used for customers
# Technical introduction
This section provides a technical introduction of PaysafeCard. PaysafeCard is based on the PaysafeCard SOPG API. The gateway is a SOAP XML Web Service which exposes API client functionalities that can be used with any SOAP capable client system, regardless of the programming language used.
## About the API
The PaysafeCard SOPG (**S**ervice **O**riented **P**ayment **G**ateway) API is based on the <a href="https://en.wikipedia.org/wiki/SOAP" target="_blank">*SOAP*</a> protocol. SOPG provides payment features as a web service.
## Endpoints:
- The endpoint for the *test environment* is: https://soatest.paysafecard.com
| Hostname | IP address |
|---|---|
| soatest.paysafecard.com | 13.248.157.194<br>76.223.29.211 |
- The endpoint for the *production environment* is: https://soa.paysafecard.com
| Hostname | IP address |
|---|---|
| soa.paysafecard.com | 75.2.1.208<br>99.83.185.216 |
## Prerequisites
You can only connect to the PaysafeCard system if the following prerequisites are fulfilled:
- SOPG Username and Password for request authentication provided by PaysafeCard. User will have functions for payment and refund available.
- Authorization of the payment server IP address in the production environment (if a 403 error is received when trying to access the service, it is likely that the IP address is not yet allowed to access).
- Content-type: Please make sure that the content type in the HTTP header, when submitting requests, is set to Content-Type: application/xml
- Character encoding needs to be in UTF-8.
##Error Handling
All SOPG operations will return an ‘errorCode’ and ‘resultCode’. A ‘resultCode’ can have a value of ‘0’ (successful), ‘1’ (logical problem) or ‘2’ (technical problem). In general, the following rules can be applied:
- ‘1’ indicates that there is a problem with the submitted data (e.g., wrong credentials, transaction has expired, etc.) retries with the same request data won’t be successful.
- ‘2’ (technical problem) means that the service is temporarily not available – the request can be retried.
##Operation details and WSDL contract
Although the SOPG WSDL service contract includes many more operations, all required operations for the basic payment process are described in this document. All mandatory payment parameters are required, and a transmission is obligatory although the value remains NULL. If the webservice framework requires a WSDL at runtime, the SOPG WSDL from the WSDL URL needs to be downloaded and provided in the local environment. NOTE: WSDL must not be fetched from PaysafeCard servers at runtime.
##Command and Query Operations
The operations can be divided into query (Q) and command (C) operations. A command operation will modify the state of an object, whereas a query operation will return details about the current state of an object. Command operations in SOPG are protected against unwanted side-effects of repeated executions (e.g., calling ‘executeDebit’ twice on a transaction will return an error code on the second invocation).
##Functions
####createDisposition
+ Type: C
+ Description: The business partner initiates the payment process by sending a ‘createDisposition’ request to PaysafeCard to create a disposition at the server. Maximum allowed amount is 1000.00 EUR (or equivalent in different transaction currency).
+ Request Elements: username, password, mtid, subId, amount, currency, okUrl, nokUrl, merchantclientId, pnUrl, clientIp, shopId, shoplabel
+ Response Elements: mtid, subId, mid, resultCode, errorCode
####getCustomerPanel
+ Type: C
+ Description: Allows the business partner to deliver the PaysafeCard payment panel application to the customer.
+ Request Elements: mid, mtid, amount, currency
+ Response Elements: -
####executeDebit
+ Type: C
+ Description: Finishes the transaction by debiting money from the customer’s account after the customer paid at the Point of Sales. This step concludes the payment as the 'close' flag is mandatory to be set to '1'. The business partner can keep the transaction open (while the full amount is reserved) until the end of the disposition time.
+ Request Elements: username, password, mtid, subId, amount, currency, close
+ Response Elements: mtid, subId, resultCode, errorCode
####getSerialNumbers
+ Type: Q
+ Description: Gets the state of the disposition to verify the expected state before calling the next function.
+ Request Elements: username, password, mtid, subId, currency
+ Response Elements: mtid, subId, resultCode, errorCode, amount, currency, dispositionState, serialNumbers. paymentInstrument and paymentInstrument only when enabled by Paysafe
####getMID (optional)
+ Type: Q
+ Desciption: The business partner can query the assigned MID (unique ID of the business partner) for the requested currency.
+ Request Elements: username, password, currency
+ Response Elements: currency, mid, resultCode, errorCode
##Description of Parameters
+ username – business partner account username
* provided by PaysafeCard for the authentication.
+ password – business partner account password
* provided by PaysafeCard for the authentication
+ mtid – transaction id, unique identifier for each disposition.
* max. length: 60 characters
* recommended value: up to 20 characters
* provided by business partner
* only the following is allowed: A-Z, a-z, 0-9 as well as – (hyphen) and _ (underline)
* example: 3516-6s4dfsad41
+ subId – value must be left empty if nothing else is agreed.
* so-called ‘reporting criteria’, offers the possibility to classify transactions
* max. length: 8 characters (case sensitive)
* agreement with PaysafeCard needed
* example: shop1
+ amount – disposition amount
* requested amount is not allowed to exceed 1000.00 EUR (or equivalent in a different transaction currency) in value
* max. 11 digits before – exactly 2 digits after the decimal point
* use a point as a decimal separator
* Valid example:
* 100.00
* 1000.00
* Invalid example:
* 1,000.00
+ currency – disposition currency
* max. length: 3 characters, all uppercase
* ISO Currency Code
* example: EUR
+ pnUrl – payment notification URL at which PaysafeCard notifies the business partner as soon as an assignment was successfully performed (more details in chapter "payment notification").
* URL has to be absolute and URL encoded as it is sent as a parameter
* max. length: 765 characters
+ okUrl – is the URL to which the customers are forwarded by PaysafeCard after they click on "Back to Shop". This URL should point to the merchant homepage/the shopping basket. Please make sure that the shopping basket is emptied as soon as the customer is redirected to the bar code application. The business partner may include some information in the URL.
* URL has to be absolute and URL encoded as it is sent as a parameter
* max. length: 765 characters
+ nokUrl – this is the URL to which customers are forwarded by PaysafeCard when they hit ‘cancel’ button on the PaysafeCard bar code application.
* URL has to be absolute and URL encoded as it is sent as a parameter
* max. length: 765 characters
*NOTE: It is crucial to send the ‘okURL’, ‘nokURL’ and ‘pnUrl’ in an URL encoded (also called percentencoding) form. Otherwise, the result will be a wrong redirect of the customer to the confirmation page, in addition to a possible failure of the payment.*
+ merchantclientId - the merchantclientId identifies the Customer on our business partners side.
The most optimal merchantclientId is a completely random value. A value that uniquely identifies the customer and is disconnected from any personal information.
This merchantclientId value should be the same for all transactions of the customer.
Here are Guidelines for possible Customer IDs:
<br><br/>
<a name="MCID"></a>
*Valid Values:*
|Value |Type
|--- |---
`2c3be0b50c7a5f1964a63d78f38a6ffc41c027e9` |SHA1 - [email protected]
`742f2b1a55cd5d606ea44b4fcb54646a` | MD5 - [email protected]
`3a5b0d0777dead9df93d502df85c8180e53804eb`|SHA1 - UsernameValue1
`3192481752123`| Random Customer Identifier
`CustomerID1`| Customer Identifier free of personal information
*Invalid Values:*
`Username_1`
`FirstName123`
`LastName123`
`Timestamp`
`IP Address`
Please note that sending any form of the invalid values will not be accepted.
If you intend to process PaysafeCard transactions on multiple brands, please inquire about the possibilities of separating multiple entities for your account.
+ clientIp – the IP address of the PaysafeCard customer.
+ shopId – identification of the shop which is the originator of the request. This is most likely used by payment service providers who act as a proxy for other payment methods as well.
* max. length: 60 characters
* recommended value: up to 20 characters
* provided by business partner
* only the following is allowed A-Z, a-z, 0-9 as well as – (hyphen) and (underline)
* example: 2568-B415rh_785
+ shopLabel – label or URL of the shop which is the originator of the request, related to the ‘shopId’. This is most likely used by payment service providers which act as a proxy for other payment methods as well.
* max. length: 60 characters
* example: www.foodstore.com
+ mid – merchant ID, unique ID of the merchant/currency pair.
* 10 digits long
* provided by PaysafeCard
* example: 1000001234
+ dispositionState – current state of the disposition (see chapter **Disposition states** for more details).
+ serial number of assigned PaysafeCard by PaysafeCard (semicolon separated details).
* currency: ISO Currency Code
* disposition amount: amount customer paid for the transaction
* cardTypeId: PaysafeCards are grouped into card types: e.g., junior_PaysafeCard; adult_PaysafeCard; inhouse_PaysafeCard
* examples: 0000000001200000;EUR;7.50;00002;
* close – the close flag of the disposition has to be set to '1' in the executeDebit request. By doing so the transaction is closed and its status cannot be changed.
* resultCode – result code of the operation (see the result codes chapter for details).
* errorCode – error code of the operation (see the error codes chapter for details).
* dispositionRestrictions – disposition restrictions can be set by the business partner in order to restrict a
payment transaction, according to their individual needs.
* Multiple repeats possible
* Each restriction consists of a „key“ and a „value“:
* „key“ - the key of the restriction
* „value“ - the value of the restriction
## Restrictions
### Country restrictions
| Key | Example value | Possible values | Description
|---------|---------------|-----------------|---------------------------------------------------------------------------------------------------
| COUNTRY | DE | <a href="https://www.paysafecard.com/fileadmin/Website/Dokumente/B2B/availability-of-products-en.pdf">ISO 3166-1 codes</a> | Restricts the processing of payments to Germany only. The value accepts ISO 3166-1 country codes.
Please transmit a country code (ISO 3166-1) via the createDisposition API request to restrict payments to the
specified country. Please do not define a country restriction in the „create disposition“ API Request (COUNTRY)
during the integration test in the Merchant Service Center. The integration test uses only one card type (AT_
Classic).
### Account restrictions
| Key | Example value | Possible values | Description
|---------------|---------------|------------------------|--------------------------------------------------------------------------------
| MIN_AGE | 18 | Positive integer value | Restricts PaysafeCard account holders to only those aged 18 years or older.
| MIN_KYC_LEVEL | FULL | SIMPLE or FULL | Restricts PaysafeCard account holders to only those of a given status.
## Reporting Criteria
Offers the possibility to classify sub-merchants. Agreement with PaysafeCard needed - not agreed values lead to a failed payment.
<br>Reporting Criterias add an additional layer to an MID and allow for a logical separation of brands and merchants on our side.
| Parameter | Description | Format |
|------------------|---------------------------------------------------------------------------------------------------------------------------------|---------------------------------|
| `subId` | The Reporting Criteria (or subId) is used to classify sub-merchants. The setup of RCs must be agreed with PaysafeCard. | Up to 8 alphanumeric characters |
*Please note: When integrating as a <b>Payment Service Provider</b> payments will be processed on behalf of merchants. In this case this <b>parameter is mandatory</b>. The parameter has to be included in all PaysafeCard Payment, Payout and Refund requests for <b>Payment Service Providers</b>.*
## Test Environment and Endpoint
- PaysafeCard provides the ‘PaysafeCard test system’, a test environment for integration of new business partners.
Every new business partner needs to integrate the payment platform first on the test system.
Once the integration on your system is finished a UAT(UserAcceptanceTest) needs to be done in order to ensure a seemless integration flow.
+ Test Environment: https://soatest.paysafecard.com/psc/services/PscService
+ Productive Environment: https://soa.paysafecard.com/psc/services/PscService
<a name="payment_notification"></a>
##Payment Notification
The payment notification is used to notify the business partner that the customer has paid the transaction. It is a plain text POST request sent to your pnURL (specified in createDisposition).
* payment notification is only delivered in case the customer entered a PIN on the payment panel and the transaction is ready to be executed.
* In case of technical errors (e.g. socket timeout), or application errors (e.g. HTTP 500 response), the payment notification is resubmitted at a regular interval until one of the following criteria is fulfilled:
- The payment notification is successfully delivered (i.e. HTTP 200 response from payment server)
- The maximum number of retry attempts has been reached (currently configured at 5 retries)
- The payment has been closed successfully without answering to the payment notification, independent of the transaction status
- The payment status changes to "X"
* included parameters: mtid, eventType (always ASSIGN_CARDS), serialNumbers, currency, disposition amount, cardTypeID (country code + ID of the card (e.g. AT_classic))
* Business partner has to respond with http200 upon receival of the payment notification
* The payment notification will be sent from either of the below IP addresses:
| IP addresses |
|---|
| 18.197.120.90 <br>18.158.237.76 <br>3.64.155.76 <br>3.76.4.148 <br>3.127.123.143 <br>176.34.172.250 <br>54.228.173.185 <br>52.48.213.182 <br>18.200.202.144 |
Example:
```
mtid=3516-6s4dfsad41&eventType=ASSIGN_CARDS&serialNumbers=1888540789315005%3BEUR%3B1.00%3BAT00002%3B
```
<br><br>
A JSON version with all the possible parameters, is also available.
<br>Example:
```
"body": {
"timestamp": 1601916702012,
"eventType": "ASSIGN_CARDS",
"version": "1",
"data": {
"mid": "1090002661",
"customer": {
"id": "kfoLkCq3RBIJiJF6sJWBeYA4tnfsCms2"
"payment_id": "3516-6s4dfsad41",
"payment_instrument": "paysafecard",
"payment_instrument_subtype": "code",
"card_details": [
{
"serial": "1888540789315005",
"currency": "EUR",
"amount": 1,
"type": "00002",
"country": "AT"
}
]
}
}
```
**JSON payment notification response objects**
| Parameter | Type | Description
| --- | --- | ---
| `timestamp` | Unix timestamp (in ms) | The time of the card assign event.
| `eventType` | String | The event type that triggered the payment notification.
| `version` | String | API version number.
| `data` | Array | Contains the data of the transaction.
| `mid` | String | The 10-digit Merchant ID.
| `customer` | Array | Contains the customer data.
| `id` | String | The unique customer identifier provided by the business partner.
| `submerchant_id` | String | The sub-merchant id. Also known as reporting criteria. <br>*Only returned if provided during payment request*
| `payment_id` | String | The PaysafeCard transaction ID. Unique identifier for a payment.
| `payment_instrument` | String | The payment method used. <br><br> Possible values: `paysafecard`; `paysafecash`, `giftcard`, `pagoefectivo` or `safetypay` <br>*Contact PaysafeCard if you want this parameter*
| `payment_instrument_subtype` | String | The type of giftcard used. <br><br> Possible values: for `giftcard`->`cvspharmacy`, `dollargeneral`, `openbuckscard`. For `safetypay` and `pagoefectivo`->`cash`, `online`. For `PaysafeCard`->`code` or `account` <br>*Contact PaysafeCard if you want this paramater*
| `card_details` | Array | Contains the details of the card used for the transaction (up to 10 iterations - max. number of cards that can be used in a single transaction) with the card information.
| `serial` | String | The serial number that identifies the card.
| `currency` | String | The currency code of the card in ISO 4217 3-digit format.
| `amount` | float | The amount used from the card (with 2 decimal numbers).
| `type` | String | The 5 characters code that identifies the card type.
| `country` | Array | The country code of the card in ISO 3166-1 2-digit format.
**NOTE:** The business partner must contact the PaysafeCard integration team at [*[email protected]*](), in case this version is preferred.
## Disposition States
|One letter code|Meaning|Description|
|---|---|---|
|R|Created|The disposition has been successfully created. If nothing happens within 30 minutes, the disposition will be transferred to state ‘X’ by the PaysafeCard cleanup job.|
|S|Disposed|The customer successfully assigned a PIN to the transaction. The business partner can ‘executeDebit’.|
|O|Consumed|executeDebit was successful, the money is correclty debited and the transaction is closed. The business partner has to mark the transaction as successful in their system|
|L|Canceled|The disposition has been actively cancelled by the customer.|
|X|Expired|The time window for this disposition has ended (either before the customer entered a PIN or before ‘executeDebit’ was called).
##Disposition Time Windows
There are 2 time windows:
+ Payment expiration window: <br></br>
Each initiated transaction remains in „R“ („CREATED“) status for 30 minutes. If the transaction does not receive a valid PaysafeCard PIN, the transaction is set to „X“ („EXPIRED“) and has therefore expired.
+ Disposition time window: <br></br>
Once a disposition is in status „S“ („DISPOSED“), the business partners must carry out their debits as per their
settings. Fundamentally, the disposition time window is 60 seconds. In consultation with the PaysafeCard
integration team, this setting can be changed anywhere up to 10 minutes, as per the T&Cs. If this time frame is
exceeded, the disposition will automatically expire, and the amount will be available again on the customer‘s
PaysafeCard. Furthermore, all dispositions which have been created, but not successfully debited, will be set to
„EXPIRED“.
<strong>NOTE:</strong> These jobs are only active on the PaysafeCard productive server. On the test system, transactions
and reserved amounts in the „S“ („DISPOSED“) state are committed until the transaction completes with
executeDebit.
### Integration on desktop devices
The PaysafeCard payment application should be displayed as a redirect in the same window, on a new browser tab or a new browser window.
Always allow vertical scrolling or dynamic sizing.
### Integration on mobile devices
PaysafeCard payment application is optimised automatically for mobile devices.
# Customer product introduction
This section provides an overview of those PaysafeCard's products relevant in the context of the PaysafeCard SOAP API.
## PaysafeCard
PaysafeCard gives customers the possibility to pay safely online without a bank account or credit card. The customer buys PaysafeCard at a point of sales in the form of a printout with a 16-digit PIN and pays by entering the PIN using your device's screen.
# Paying with PaysafeCard
This area provides information about the PaysafeCard payment flow from a business partner's point of view.
## Functional payment flow
The functional payment flow works as follows:
1. The customer selects PaysafeCard as the preferred payment option in your webshop.
2. You initiate a payment with the correct amount, currency and other parameters(<a href="createDisposition">createDisposition</a>).
3. You re-direct the customer to PaysafeCard's hosted payment panel, where the customer has 30 minutes to enter the 16-digit PaysafeCard PIN. In the section "Payment page details" below you can find additional information important for the correct integration of PaysafeCard's hosted payment page.
4. PaysafeCard sends a notification to the notification URL("pnURL").
5. PaysafeCard re-directs the customer back to the success URL("okURL").
6. You capture the payment (additional information can be found in the section "Capturing a payment" below).
## Technical Payment Process
1. The customer selects the payment method PaysafeCard.
1. Initiate Payment: Send POST request `createDisposition`.
* 2.1. If the response gives back http20x, redirect the customer to the payment panel.
* 2.2. If the response gives back http40x or htp50x, show an error message to the customer.
Inititate Payment error message: "Transaction could not be intitiated due to connection problems. If the problem persists, please contact our (businessparter)support."
1. Redirection to the payment panel`getCustomerPanel`: The customer reaches the [payment panel](#payment_panel).
1. PIN entry(by customer): The customer enters a valid PIN and clicks pay.
* 4.1. Verification on PaysafeCard´s side if the entered PINs are valid.
If the customer cancels the transaction on the payment panel, please show the following error message: "Transaction aborted by user"
1. Payment notification delivery: Since the card is assigned to the transaction(transaction status "S"), we send a notification to your `pnUrl`.
1. `pnUrl` handling: Right after payment notification delivery you perform the GET request `getSerialNumbers`to check the state of the transaction.
* 6.1. If the GET request `getSerialNumbers` returns the according status "S", immediately perform the POST request `executeDebit`.
* 6.2. If the response of `executeDebit`is http20X && the resultCode == 0 && the errorCode == 0, make a user account top up.
1. Redirection to the `okUrl`: We redirect the customer to your`okUrl`.
1. `okUrl` handling: Query the state of the transaction with the GET request`getSerialNumbers` once the customer lands on the `okUrl`.
* 8.1. If the GET request `getSerialNumbers` returns the status "O“, show a success message to the customer.
* 8.2. if the status is "S", perform the POST request `executeDebit`.
* 8.2.1. If the response gives back http20X && the resultCode == 0 && the errorCode == 0, make a user account top up and show a success message to the customer.
* 8.2.2. If the response gives back http40X or http50X and/or result/errorCode != 0, show an error message to the customer.
* 8.3. If the response from `getSerialNumbers` gives back http40X or http50X, show an error message to the customer.
Retrieve Payment Details error message: "The transaction could not be completed. This may have happened due to a temporary connection problem. Please press the "reload" button in your browser to retry completing your transaction. If the problem persists, please contact our (businesspartner)support.
# PaysafeCard brand guidelines and logos
The PaysafeCard integration must be done accordingly to the brand guidelines outlined in the [*Partner Marketing Center*](https://marketingcenter.paysafe.com/login/). Once one there a business partner will need to register a new account. For further assistance or help the business partner can contact an account manager.
#Group Payment
In this chapter a test scenario is presented using example data.
Do not use the enclosed example data! Each business partner will receive a consistent set of test data for testing
purposes.
##<a name="createDisposition">createDisposition</a>
The business partner initiates the payment process by sending a ‘createDisposition’ request.
####example request:
+ username:USER
+ password:PASSWORD
+ mtid:18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4
+ subId:
+ amount:10.00
+ currency:EUR
+ okUrl:http%3a%2f%2fwww%2epaysafecardokURL%2ecom
+ nokUrl:http%3a%2f%2fwww%2epaysafecardnokURL%2ecom
+ merchantclientid:cID_919191
+ pnUrl:http%3a%2f%2fwww%2emerchantpnURL%2ecom
+ shopId:3516-6s4dfsad41
+ shopLabel:www.foodstore.com
```
<urn:createDisposition>
<urn:username>USER</urn:username>
<urn:password>PASSWORD</urn:password>
<urn:mtid>18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</urn:mtid>
<urn:subId></urn:subId> <!-- Optional -->
<urn:amount>10.00</urn:amount>
<urn:currency>EUR</urn:currency>
<urn:okUrl>http%3a%2f%2fwww%2epaysafecardokURL%2ecom</urn:okUrl>
<urn:nokUrl>http%3a%2f%2fwww%2epaysafecardnokURL%2ecom</urn:nokUrl>
<urn:merchantclientid>cID_919191</urn:merchantclientid>
<urn:pnUrl> http%3a%2f%2fwww%2emerchantpnURL%2ecom </urn:pnUrl>
<!--Zero or more repetitions:-->
<urn:dispositionRestrictions>
<urn:value>FR</urn:value>
<urn:dispositionRestrictions>
<urn:key>MIN_AGE</urn:key>
<urn:value>18</urn:value>
</urn:dispositionRestrictions>
</urn:createDisposition>
```
####example response:
+ mtid:18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</br>
+ mid:1000001234
+ resultCode:0
+ errorCode:0
```
<ns1:createDispositionReturn>
<ns1:mtid>18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</ns1:mtid>
<ns1:mid>1000001234</ns1:mid>
<ns1:resultCode>0</ns1:resultCode>
<ns1:errorCode>0</ns1:errorCode>
</ns1:createDispositionReturn>
```
##getMid (optional)
With ‘getMid’, the business partner can query the assigned unique merchant identifier (MID) for the requested currency.
####example request:
+ username:USER
+ password:PASSWORD
+ currency:EUR
<br><br>
```
<urn:getMid>
<urn:username>USER</urn:username>
<urn:password>PASSWORD</urn:password>
<urn:currency>EUR</urn:currency>
</urn:getMid>
```
####example response:
+ currency:EUR
+ mid:1000001234
+ resultCode:0
+ errorCode:0
<br><br>
```
<urn:GetMidReturn>
<urn:currency>EUR</urn:currency>
<urn:mid>1000001234</urn:mid>
<ns1:resultCode>0</ns1:resultCode>
<ns1:errorCode>0</ns1:errorCode>
</urn:GetMidReturn>
```
<a name="payment_panel"></a>
##getCustomerPanel
The command ‘createDisposition’ was successfully executed. Thus, the customer can be forwarded to the PaysafeCard payment application.
####URL:
https://customer.cc.at.paysafecard.com/psccustomer/GetCustomerPanelServlet<br>
After the URL, the transaction data (MID, MTID, amount and currency) are added to the URL as parameter, using `?`.
<br>The final URL will look as follows: <br>
https://customer.cc.at.PaysafeCard.com/psccustomer/GetCustomerPanelServlet?mid=testmid&mtid=testmtid&amount=test.amount¤cy=testcurrency
##pnURL request
PaysafeCard system sends an ‘HTTP POST’ request to the business partners’s system (‘pnUrl’) in order to give notice of the customer's PIN having been entered. The PIN has successfully been assigned to the transaction. The transaction is ready to be completed.
####[example POST request body](#payment_notification):
```
mtid=18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4&eventType=ASSIGN_CARDS&serialNumbers=0000000001200000;EUR;100.00;DE00002
```
####example response:
http 200
##executeDebit
After the customer successfully assigned money to the transaction, the business partner executes the debit. The relevant amount is deducted from the PaysafeCard PIN.
####Example Request:
+ username:USER
+ password:PASSWORD
+ mtid:18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4
+ subId:
+ amount:10.00
+ currency:EUR
+ close:1
```
</urn:executeDebit>
<urn:username>USER</urn:username>
<urn:password>PASSWORD</urn:password>
<urn:mtid>18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</urn:mtid>
<urn:subId></urn:subId> <!-- Optional -->
<urn:amount>10.00</urn:amount>
<urn:currency>EUR</urn:currency>
<urn:close>1</urn:close>
</urn:executeDebit>
```
####Example Response:
+ mtid:18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4
+ subId:
+ resultCode:0
+ errorCode:0
```
<ns1:ExecuteDebitReturn>
<ns1:mtid>18b02d230-a6822f-4cbb-aee9-0bc07d90cfa4</ns1:mtid>
<ns1:subId></ns1:subId>
<ns1:resultCode>0</ns1:resultCode>
<ns1:errorCode>0</ns1:errorCode>
</ns1:ExecuteDebitReturn>
```
# Group Payment Errors
If an error code appears that is not listed here, please contact [email protected]
###Result Codes:
|Result Name|Value|Description|
|---|---|---|
|resultCode|0|successful|
|resultCode|1|logical problem|
|resultCode|2|technical problem|
|errorCode|Contains an error number if the resultcode is not equal to 0.|
####Error codes
|Code |Number (optional) |HTTP Status |Description |
|--- |--- |--- |--- |
|`General technical order` |10007 |500 |General technical error.|
|`Invalid API credentials` |10008 |401 |Authentication failed due to a wrong or invalid SOPG Username/Password.|
|`Duplicate transaction id` |2001 |400 |Transaction already exists.|
|`Payment is in invalid state.` |2017 |400 |The payment is in an invalid state, e.g. you tried to capture a payment that is in state `R` instead of `S`.|
|`Merchant with Id XXXXXXXXXX is not active.` |3001 |400 |Merchant is not active.|
|`Merchant with Id XXXXXXXXXX is not allowed to perform this debit any more`|3007 |400 |Debit attempt after expiry of dispo time window.|
|`Reporting criterion not found` |3014 |400 |The `subId` specified has not been configured on PaysafeCard side.|
|`General error` |3017 |400 |[It is mandatory to send an MCID.](#MCID)|
|`General error` |3019 |400 |[MCID contains invalid values.](#MCID)|
# Group Gift Card Integration
PaysafeCard has expanded its portfolio of cash-based payment methods in the United States, adding the acceptance of popular retail gift cards such as CVS/pharmacy and Dollar General, as well as oBucks cards
<br><br>
The gift card integration guidelines can be found [*here*](https://www.paysafecard.com/fileadmin/api/paysafecardgiftcards.html):
https://www.paysafecard.com/fileadmin/api/paysafecardgiftcards.html
# Group PagoEfectivo Integration
PaysafeCard has expanded its portfolio of cash-based payment methods in Latin America, adding the acceptance of popular customer brand PagoEfectivo.
<br><br>
The PagoEfectivo integration guidelines can be found [*here*](https://www.paysafecard.com/fileadmin/api/paysafecardpagoefectivo.html):
https://www.paysafecard.com/fileadmin/api/paysafecardpagoefectivo.html
# Group SafetyPay Integration
PaysafeCard has expanded its portfolio of cash-based payment methods in Latin America, adding the acceptance of SafetyPay payments.
<br><br>
The SafetyPay integration guidelines can be found [*here*](https://www.paysafecard.com/fileadmin/api/paysafecardsafetypay.html):
https://www.paysafecard.com/fileadmin/api/paysafecardsafetypay.html
# Group Payout
# Group Payout Process
Payout allows the transfer of funds to PaysafeCard account holders. Payout is executed by the business partner at the
demand of the customer. Payout is only available for PaysafeCard account holders in the following countries: Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Rep., Denmark, Finland, France, Georgia, Germany, Greece, Hungary, Ireland, Italy, Latvia, Luxemburg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, Switzerland, United Kingdom.
- Step 1: Customer payout request and validation
1. On the website of the business partner (merchant), the customer requests a payout.
1.1 The payout request is validated with PaysafeCard system in real-time (no money is transferred).
1.1.1 PaysafeCard validates the request (can the payout take place, does the customer exist etc..)
1.1.1.1 the merchant puts the payout request in the back office queue, to be approved manually later.
1.1.1.2 The customer is informed that the request is accepted and the payout is pending (or is refused because the validation failed).
- Step 2: Payout capture by the Business Partner
2. The back office employee at the business partner manually approves the payout request from the queue.
2.1 The employee confirms the payout (or rejects it).
2.1.1 the business partner captures the payout.
2.1.1.1 PaysafeCard transfers the money to the customer PaysafeCard account.
# Group Importance of the merchantclientId parameter
Please refer to [this section](#MCID) to view valid values for the merchantclientId parameter
<a name="MCID2"></a>
## Background and explanation of the MCID
On 1 MID/RC combination(i.e. MID 1000000098/i.e. RC NULL) we expect 1 customer to have only 1 MCID. <br>
The MCID identifies a customer on the business partner side. <br>
On our side we go by the following logic:<br>
2,3,4,... transactions using 1 MCID imply 1 customer using their Merchant account for all of these transactions. <br>
2,3,4,... transactions using 2,3,4,... MCIDs imply 2,3,4,... customers using their distinct Merchant accounts for these transactions.<br><br>
### Important
We are necessarily looking for a correct representation of the customer accounts used on the business partner side.
Every re-curring Merchant customer, using their same account, has to have the same MCID as when they last requested a payout.
Example:Merchant Account X must always have MCID X for every transaction initiated/requested from Merchant Account X, Merchant Account Y must always have MCID Y for every transaction initiated/requested from Merchant Account Y, Account Z -> MCID Z for all transactions done with Account Z, etc.
<br>
Every new Merchant customer has to have a new MCID.
<br>
### What does that mean for payouts?<br>
The first payout establishes an association between MCID and PaysafeCard account. All subsequent payouts on that same MID/RC combination have to be performed with that same association going forward. Taking the example from above, every payout by Merchant Account X has to be requested by MCID X. MCID X is now associated to PaysafeCard account X. The association is also enforced in the other direction from this point on. Every payout requested by MCID X has to be requested for PaysafeCard account X.
# Exchange of customer data
- For each payout request the business partner needs to provide the customer’s personal details (first name, last
name, date of birth) to PaysafeCard during the payout call. Customer's first and last name must be provided in
the original alphabet characters (i.e. Greek Cyrillic alphabet). PaysafeCard automatically validates the provided data
against the registered PaysafeCard account data.The payout will automatically be refused if the data does not match.
- If the data does not match 100%; the automatic validation cannot proceed and the payout will be refused
automatically. The input will be normalized before the comparison starts by PaysafeCard.
# Getting the MID limits
- The business partner has one MID (for each currency, each MID has its own payout limit - the amount that still can
be paid out by the merchant), information about the financial condition of a MID can be retrieved real-time via [getPayoutState](#retrieve_limits). Automatically all associated MID’s will be returned.
- As soon as a MID limit is reached, payout on this MID is not possible for this time-period.
This information is also available by logging in to the web-interface for business partner (the merchant reporting
tool or “MRT”), but will only return the payout state for the current MID and not for associated MID’s.
# The payout report
- For reconciliation purposes the business partner can download a CSV file containing all possible information for
payments and payouts, this file is called the “payout report”. The payout report can be downloaded in the MRT.
# Settlement
- All payout transactions need to be paid by the business partner. The total monthly payout amount is automatically deducted (netted) from the monthly payment amount.
- The total amount of payout money may exceed the total amount of payment money up to a certain level.
- Detailed information on this level can be retrieved with the function [getPayoutState](#retrieve_limits).
## Reporting Criteria
Offers the possibility to classify sub-merchants. Agreement with PaysafeCard needed - not agreed values lead to a failed payment.
<br>Reporting Criterias add an additional layer to an MID and allow for a logical separation of brands and merchants on our side.
| Parameter | Description | Format |
|------------------|---------------------------------------------------------------------------------------------------------------------------------|---------------------------------|
| `subId` | The Reporting Criteria (or submerchant Id) is used to classify sub-merchants. The setup of RCs must be agreed with PaysafeCard. | Up to 8 alphanumeric characters |
*Please note: When integrating as a <b>Payment Service Provider</b> payments will be processed on behalf of merchants. In this case this <b>parameter is mandatory</b>. The parameter has to be included in all PaysafeCard Payment, Payout and Refund requests for <b>Payment Service Providers</b>.*
## Payout implementation
- Prerequisites
- SOPG Username and Password for request authentication provided by PaysafeCard. User will have functions for payment and refund available.
- Authorization of the payment server IP address in the production environment (if a 403 error is received when trying to access the service, it is likely that the IP address is not yet allowed to access).
- Content-type: Please make sure that the content type in the HTTP header, when submitting requests, is set to Content-Type: application/xml
- Character encoding needs to be in UTF-8.
- The business partner received a PaysafeCard account for testing purposes.
- Interface guidelines
- How the PaysafeCard payout implementation ideally should look like from a customer perspective is
documented in the <a href="https://www.paysafecard.com/fileadmin/Website/Dokumente/B2B/paysafecard_payout_InterfaceGuidelines_EN.pdf" target="_blank">*Interface guidelines*</a> document.
- Note: It is obligatory to implement all the required error messages shown in the document above.
##Description of Parameters
+ username – business partner account username
* provided by PaysafeCard for the authentication.
+ password – business partner account password
* provided by PaysafeCard for the authentication
+ ptid – transaction id, unique identifier for each disposition.
* must be unique, also if the transaction failed
* must be different from mtid used during payment
* max. length: 90 characters
* recommended value: up to 20 characters
* provided by business partner
* only the following is allowed: A-Z, a-z, 0-9 as well as – (hyphen) and _ (underline)
* example: 3516-6s4dfsad41
+ subId – Mandatory parameter for PSP’s (payment service providers), to distinguish multiple websites
* value must be left empty if nothing else is agreed.
* so-called ‘reporting criteria’, offers the possibility to classify transactions
* max. length: 8 characters (case sensitive)
* agreement with PaysafeCard needed
* example: shop1
+ amount – payout amount
* requested amount is not allowed to exceed 2500.00 EUR (or equivalent in a different transaction currency) in value
* max. 11 digits before – exactly 2 digits after the decimal point
* use a point as a decimal separator
* Valid example:
* 100.00
* 1000.00
* Invalid example:
* 1,000.00
+ currency – disposition currency
* max. length: 3 characters, all uppercase
* ISO Currency Code
* example: EUR
+ customerIdType – used method for identification of the PaysafeCard account
* Fixed value: EMAIL or CUSTOMERID
+ customerId – related value to customerIdType
* Max. length: 90 characters
* The PaysafeCard e-mail address or account ID of the customer
+ merchantclientID - a unique end customer identifier (the unique ID of the end customer as registered at the merchant’s database)
* [MCID](#MCID)
* max. length: 50 characters
* example: hashed values, Random customer Identifier
* after a successful Payout, every additional Payout request requires the same merchantclientID and PaysafeCard combination
+ ValidationOnly – Validate the payout without transferring the funds
* value true: Test payout request for validity
* value false: Execute payout
+ utcOffset – the difference in hours and minutes from Coordinated Universal Time (UTC)
* Example: -03:00
+ firstName – (subelement of CustomerDetailsBasic): the first name of the customer example: John
* max. length. 40 characters
+ lastName – (subelement of CustomerDetailsBasic): the last name of the customer customer example: Do
* max. length. 40 characters
+ dateOfBirth – (sub-element of CustomerDetailsBasic): the date of birth of the payout customer in YYYY-MM-DD format
* example: 1979-12-20
+ subId – Mandatory parameter for PSP’s (payment service providers), to distinguish multiple websites
* So-called “reporting criteria” to classify transactions
* Max. length: 8 characters (case sensitive)
* Agreement with PaysafeCard needed Example : webshop1
+ comment – Reason for the payout request
* Max. length: 90 characters
* Only the following is allowed A-Z, a-z, 0-9 as well as ' . , - / \ : ? ! ( ) + & _ (space)
* example: payout winnings
+ resultCode – type of error
* 0 indicates that no error occurred
* 1 indicates that there is a problem with the submitted data (e.g., wrong credentials, transaction has expired, etc.)
* 2 (technical problem) means that the service is temporarily not available
+ errorCode – the error that occurred - “complete list of error codes” at the bottom of this document
* 0 indicates that no error occurred
* Any other value indicates an error occurred
+ errorCodeDescription – provides a detailed description of the errorcode NULL in case of no error
* In case of an error a string value will be returned
### getPayoutState Parameters
+ MID – merchant ID, unique ID of the merchant/currency pair 10 digits long
+ totalpayoutAmount – The total amount of payouts that were executed on this MID within the current billing cycle
* Double value Example: 50000,00
+ totalPaymentAmount – The total amount of payments that were executed on this MID within the current billing cycle in the currency of the MID
* Double value Example : 300000,00
+ creditLine – An extra payout credit line provided by PaysafeCard to support payout in case an MID is out of balance in the currency of the MID
* Double value Example 5000,00
+ totalpayoutBalance – The total amount that can still be paid out this billing cycle (in MID currency) Double value
* 10000,00
+ dailypayoutLimit – the maximum amount of money that can be paid out on this MID for the current day (24 hour), in the currency of the MID (only if configured by PaysafeCard)
* Double value if configured Example : 0,00
+ dailypayoutAmount – the total amount that has been paid out on this MID today (in MID currency) MID Double value
* Example : 5000,00
+ dailypayoutBalance – the total amount that still can be paid out on this MID today (in MID currency) MID Double value if the dailypayoutlimit is configured
* Example : 0,00
# Group Payout API Calls
Payout API allows you to:
- validate a payout
- capture a payout in two ways
- retrieve payouts by id
- retrieve payout limits by currency
## Validating a payout
+ Request:
```
<urn:payout>
<urn:username>USER</urn:username>
<urn:password>PASSWORD</urn:password>
<urn:ptid>matthias123623se</urn:ptid>
<urn:utcOffset>+03:00</urn:utcOffset>
<urn:amount>10.00</urn:amount>
<urn:currency>EUR</urn:currency>
<urn:customerIdType>EMAIL</urn:customerIdType>
<urn:customerId>[email protected]</urn:customerId>
<urn:merchantClientId>customer12</urn:merchantClientId>
<urn:validationOnly>true</urn:validationOnly>
<urn:customerDetailsBasic>
<urn:firstName>broJgMuzErVuJLQjJJBIsMvfal</urn:firstName>
<urn:lastName>DQunWSfgpAcNRUvCwEhsPwPHQJ</urn:lastName>
<urn:dateOfBirth>1991-01-22</urn:dateOfBirth>
</urn:customerDetailsBasic>
<urn:comment>payout winnings</urn:comment>
</urn:payout>
```
+ Response:
```
<ns1:PayoutReturn>
<ns1:ptid>matthias1231623se</ns1:ptid>
<ns1:requestedCurrency>EUR</ns1:requestedCurrency>
<ns1:requestedAmount>10.0</ns1:requestedAmount>
<ns1:payedInCurrency>EUR</ns1:payedInCurrency>
<ns1:payedAmount>10.0</ns1:payedAmount>
<ns1:validationOnly>true</ns1:validationOnly>
<ns1:resultCode>0</ns1:resultCode>
<ns1:errorCode>0</ns1:errorCode>
<ns1:errorCodeDescription></ns1:errorCodeDescription>
</ns1:PayoutReturn>
```
## Capturing a pre validated payout
+ Request:
```
<urn:payout>
<urn:username>USER</urn:username>
<urn:password>PASSWORD</urn:password>
<urn:ptid>matthias123623se</urn:ptid>
<urn:utcOffset>+03:00</urn:utcOffset>
<urn:amount>10.00</urn:amount>
<urn:currency>EUR</urn:currency>
<urn:customerIdType>EMAIL</urn:customerIdType>
<urn:customerId>[email protected]</urn:customerId>
<urn:merchantClientId>customer12</urn:merchantClientId>
<urn:validationOnly>false</urn:validationOnly>
<urn:customerDetailsBasic>
<urn:firstName>broJgMuzErVuJLQjJJBIsMvfal</urn:firstName>
<urn:lastName>DQunWSfgpAcNRUvCwEhsPwPHQJ</urn:lastName>
<urn:dateOfBirth>1991-01-22</urn:dateOfBirth>
</urn:customerDetailsBasic>
<urn:comment>payout winnings</urn:comment>
</urn:payout>
```
+ Response:
```
<ns1:payoutResponse>
<ns1:PayoutReturn>
<ns1:ptid>matthias1231623se</ns1:ptid>
<ns1:requestedCurrency>EUR</ns1:requestedCurrency>
<ns1:requestedAmount>10.0</ns1:requestedAmount>
<ns1:payedInCurrency>EUR</ns1:payedInCurrency>
<ns1:payedAmount>10.0</ns1:payedAmount>
<ns1:validationOnly>false</ns1:validationOnly>
<ns1:resultCode>0</ns1:resultCode>
<ns1:errorCode>0</ns1:errorCode>
<ns1:errorCodeDescription></ns1:errorCodeDescription>
</ns1:PayoutReturn>
</ns1:payoutResponse>
```
## Capturing a payout without validation
+ Request:
```
<urn:payout>
<urn:username>USER</urn:username>
<urn:password>PASSWORD</urn:password>
<urn:ptid>matthias123623se</urn:ptid>
<urn:utcOffset>+03:00</urn:utcOffset>
<urn:amount>10.00</urn:amount>
<urn:currency>EUR</urn:currency>
<urn:customerIdType>EMAIL</urn:customerIdType>
<urn:customerId>[email protected]</urn:customerId>
<urn:merchantClientId>customer12</urn:merchantClientId>
<urn:validationOnly>false</urn:validationOnly>
<urn:customerDetailsBasic>
<urn:firstName>broJgMuzErVuJLQjJJBIsMvfal</urn:firstName>
<urn:lastName>DQunWSfgpAcNRUvCwEhsPwPHQJ</urn:lastName>
<urn:dateOfBirth>1991-01-22</urn:dateOfBirth>
</urn:customerDetailsBasic>
<urn:comment>payout winnings</urn:comment>
</urn:payout>
```
+ Response:
```
<ns1:payoutResponse>
<ns1:PayoutReturn>
<ns1:ptid>matthias1231623se</ns1:ptid>
<ns1:requestedCurrency>EUR</ns1:requestedCurrency>
<ns1:requestedAmount>10.0</ns1:requestedAmount>
<ns1:payedInCurrency>EUR</ns1:payedInCurrency>
<ns1:payedAmount>10.0</ns1:payedAmount>
<ns1:validationOnly>false</ns1:validationOnly>
<ns1:resultCode>0</ns1:resultCode>
<ns1:errorCode>0</ns1:errorCode>
<ns1:errorCodeDescription></ns1:errorCodeDescription>
</ns1:PayoutReturn>
</ns1:payoutResponse>
```
<a name="retrieve_limits"></a>
## Retrieve limits
Used to retrieve limits information for a specific `currency`. All associated MID’s limits infromation will be returned.
### getPayoutState
+ Request:
```
<urn:getPayoutState>
<urn:username>USER</urn:username>
<urn:password>PASSWORD</urn:password>
</urn:getPayoutState>
```
+ Response:
```
<ns1:getPayoutStateResponse>
<ns1:getPayoutStateReturn>
<ns1:resultCode>0</ns1:resultCode>
<ns1:errorCode>0</ns1:errorCode>
<ns1:errorCodeDescription></ns1:errorCodeDescription>
<ns1:payoutState>
<ns1:mid>9000000008</ns1:mid>
<ns1:currency>PYG</ns1:currency>
<ns1:totalPayoutAmount>0.0</ns1:totalPayoutAmount>
<ns1:totalPaymentAmount>0.0</ns1:totalPaymentAmount>
<ns1:creditLine>10000.0</ns1:creditLine>
<ns1:totalPayoutBalance>10000.0</ns1:totalPayoutBalance>
<ns1:dailyPayoutLimit>10000.0</ns1:dailyPayoutLimit>
<ns1:dailyPayoutAmount>0.0</ns1:dailyPayoutAmount>
<ns1:dailyPayoutBalance>10000.0</ns1:dailyPayoutBalance>
</ns1:payoutState>
<ns1:payoutState>
<ns1:mid>9000000007</ns1:mid>
<ns1:currency>EUR</ns1:currency>
<ns1:totalPayoutAmount>30.0</ns1:totalPayoutAmount>
<ns1:totalPaymentAmount>2.2</ns1:totalPaymentAmount>
<ns1:creditLine>10000.0</ns1:creditLine>
<ns1:totalPayoutBalance>9972.2</ns1:totalPayoutBalance>
<ns1:dailyPayoutLimit>10000.0</ns1:dailyPayoutLimit>
<ns1:dailyPayoutAmount>10.0</ns1:dailyPayoutAmount>
<ns1:dailyPayoutBalance>9990.0</ns1:dailyPayoutBalance>
</ns1:payoutState>
</ns1:getPayoutStateReturn>
</ns1:getPayoutStateResponse>
```
# Group Payout Error Codes
|Code |Number (optional) |HTTP Status |Description |
|--- |--- |--- |--- |
|`Customer balance exceeded` |3167 |400 |By executing this payout, the customer's account balance would be exceeded. |
|`Top-up limit exceeded` |3170 |400 |By executing this payout, the customer's account top up limit would be exceeded.|
|`Customer yearly payout limit exceeded`|3194 |400 | The customer already performed payouts leading to his yearly payout limit being reached. No more payouts will be possible for this customer account until the limit resets.|
|`Customer account details do not match` |3195 |400 |The provided customer details by the business partner do not match with the customer's details of their PaysafeCard account. We only allow payouts if details of business partner request and that of the PaysafeCard account match.|
|`PaysafeCard account not found by provided credentials` |3162 |400 |We could not find a customer matching the provided customerId.|
|`There is already the maximum number of pay-out merchant clients assigned to this account`|3198 |400 | The MCID does not match with the previously used MCID for that PaysafeCard account. We only allow 1:1 relationships for MCID: PaysafeCard account. Please refer to this [Section](#MCID2) to find out more.|
|`There is already the maximum number of pay-out accounts assigned to this merchantClient` |3197 |400 | The PaysafeCard account does not match with the previously used PaysafeCard account for that MCID. We only allow 1:1 relationships for MCID: PaysafeCard account. Please refer to this [Section](#MCID2) to find out more.|
|`payout rejected - account registration not completed` |3168 |400 |The customer did not complete their registration yet and is not eligible to receive a payout.|
|`Missing mandatory parameter` |3150 |400 |Self explanatory - I.E:"Missing mandatory parameter CustomerIdentifier" if the parameter "CustomerIdentfier" is missing in the payout request|
|`Merchant not allowed to perform this action` |3161 |400 |The merchant account has not been activated for the usage of payouts. Please contact your account manager or the integration team to inquire about the status of payout activation for your account.|
|`Duplicate payout request` |3164 |400 |Transaction already exists. We only allow unique values for payout requests.|
|`Invalid amount` |3165 |400 |Invalid amount.|
|`Merchant limit reached` |3166 |400 |Merchants payout limit reached. You can inquire the current limits of your account using the [getPayoutState](#retrieve_limits) call. |
|`Payout id collides with existing disposition id` |3169 |400 |We do not allow the payout ID to be the same as a previously used payment ID. Please use unique identifiers always.|
|`Payout amount is below minimum payout amount of the merchant` |3171 |400 |Self explanatory|
|`Customer not active` |3193 |400 |The customer's PaysafeCard account is not active and therefore not eligible to receive payouts.|
|`Payout blocked due to security reasons` |3199 |400 |Self explanatory|