forked from paysafecard/api-documentation
-
Notifications
You must be signed in to change notification settings - Fork 59
/
Copy pathpaysafecardsafetypayintegration-apiary.apib
1705 lines (1408 loc) · 91.1 KB
/
paysafecardsafetypayintegration-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://apitest.paysafecard.com/v1
# PaysafeCard SafetyPay integration
This documentation explains how to start accepting <a href="https://www.safetypay.com/en/">SafetyPay</a> payments.
It is an add-on to the classic PaysafeCard integration:
**REST API**:
<br><br>https://www.paysafecard.com/en/business/downloads/
**SOAP API**:
<br><br>
https://www.paysafecard.com/en/business/downloads/
<br><br>
https://www.paysafecard.com/fileadmin/api/paysafecardsopg.html
## Where to start?
To initiate the process of accepting SafetyPay, the business partner must contact the account manager directly or at [*sales@paysafecard.com*]().
Once the business process is finished, the feature will be activated from PaysafeCard side. The feature will be activated per MID (Merchant ID).
There are also some technical integration changes necessary, which will be described in detail [here](#technical_changes).
## Introduction
There are alternative payment flows to integrate SafetyPay into your payment ecosystem. In the following section we will describe the general customer flow for each of the alternatives.
<a name="existing_MID"></a>
# Technical changes
<a name="technical_changes"></a>
1. The logo must be changed accordingly at the checkout page
* Logos for the banks can be found here: https://www.paysafecard.com/fileadmin/api/images/Banks_logo.zip
2. Transactions must stay open for 48 hours before you can consider them incomplete
3. (Optional) The payment must be created accordingly to the choice of the customer at the checkout page. The integrations supports the usage of choosing the Payment Method during the Payment request. See section [Initiating a SafetyPay Payment - REST](#restrictions_REST) or [Creating a SafetyPay Disposition - SOAP](#restrictions_SOPG)
* [Initiating a SafetyPay Payment - REST](#restrictions_REST)
* [Creating a SafetyPay Disposition - SOAP](#restrictions_SOPG)
4. (Optional) Integrating the payment notification payload in JSON
* The [JSON payment notification](#payment_notification) enables the business partner to distinguish which payment instrument subtype was used for the transaction.
# Payment Process with intermediary PaysafeCard redirection
## SafetyPay payment option on the PaysafeCard Payment Panel
### [Customer Flow](#customer_flows)
1. The customer selects PaysafeCard/SafetyPay as the preferred payment method at the business partner checkout page
2. The businesss partner initiates the payment with the correct amount, currency and other necessary parameters
3. The customer is redirected to the PaysafeCard hosted payment panel
4. The customer sees PaysafeCard and SafetyPay payment option on the payment panel
5. The customer selects SafetyPay and is redirected to the SafetyPay payment page
6. The customer is presented with 2 options to complete their payment: Cash or Online
* "online" - Flow:
5. The customer completes the payment with one of the presented online Payment Methods
6. PaysafeCard sends a notification to the notification URL once the payment is complete
7. The business partner captures the payment
8. The customer may return to the success_url/okURL provided during the payment request. This is optional.
* "cash" - Flow:
5. The customer receives a SafetyPay operation ID and pays for it at a point of collection
6. PaysafeCard sends a notification to the notification URL once the payment is complete
7. The business partner captures the payment
## Cash payment - with PaysafeCard redirection
[Cash Payment process - REST](#cash_payment_REST_PP)<br>
[Cash Payment process - SOAP](#cash_payment_SOAP_PP)
## Online Payment - with PaysafeCard redirection
[Online Payment process - REST](#online_payment_REST_PP)<br>
[Online Payment process - SOAP](#cash_payment_SOAP_PP)
<a name="separate_MID"></a>
# Payment Process with immediate redirection to SafetyPay
## SafetyPay payment option with immediate redirection to SafetyPay
### [Customer Flow](#customer_flows)
1. The customer selects SafetyPay as the preferred payment method at the business partner checkout page
2. The businesss partner initiates the payment with "payment_instrument" & "payment_instrument_subtype" parameters set. "payment_instrument" is mandatory when providing "payment_instrument_subtype"
3. The customer is redirected to the SafetyPay hosted payment page
4. The customer is presented with the selected option to complete their payment depening on the "payment_instrument_subtype" set during the request: Cash or Online
* "online" - Flow:
5. The customer completes the payment with one of the presented online Payment Methods
6. PaysafeCard sends a notification to the notification URL once the payment is complete
7. The business partner captures the payment
8. The customer may return to the success_url/okURL provided during the payment request. This is optional.
* "cash" - Flow:
5. The customer receives a SafetyPay operation ID and pays for it at a point of collection
6. PaysafeCard sends a notification to the notification URL once the payment is complete
7. The business partner captures the payment
## Cash payment with immediate redirection to SafetyPay
[Cash Payment process - REST](#cash_payment_REST_noPP)<br>
[Cash Payment process - SOAP](#cash_payment_SOAP_noPP)
## Online Payment with immediate redirection to SafetyPay
[Cash Payment process - REST](#online_payment_REST_noPP)<br>
[Cash Payment process - SOAP](#online_payment_SOAP_noPP)
# Customer Data Takeover
Using the `customer_data_takeover` parameters in the payment creation, the merchant can pre-fill some data to improve the customer flow.
- Adding the `tax_id` and `tax_id_type` fields will pre-fill the CFP field for transactions in Brazil
- Adding the `account_registration_date`, `account_KYC_level` and `account_registration_country` is mandatory in order to be able to perform SafetyPay payouts!
Below, you can find an example with all fields for REST:
```
{
"type": "PAYSAFECARD",
"amount": 2000.00,
"currency": "BRL",
"redirect": {
"success_url": "https://www.paysafecard.com/okURL",
"failure_url": "https://www.paysafecard.com/nokURL"
},
"notification_url": "https://www.paysafecard.com/pnUrl",
"customer": {
"id": "customer_id2"
},
"shop_id":"test123",
"restrictions": {
"payment_instrument": "safetypay",
"payment_instrument_subtype": "online",
"bank_ids": ["8439","8382"]
},
"customer_takeover_data": {
"email": "test@test.com",
"tax_id": "0123059433817717",
"tax_id_type": "BRA_CPF",
"account_registration_date": "1997-05-15",
"account_KYC_level":"FULL",
"account_registration_country":"MX"
}
}
```
More on the parameters you can find here:
[Initiating a SafetyPay Payment - REST](#customer_data_takeover_REST)
[Initiating a SafetyPay Payment - SOPG](#customerTakeoverData_SOPG)
# SafetyPay Payouts integration
This documentation explains how to start creating SafetyPay Payouts. SafetyPay Payout allows the transfer of funds to bank account holders in Peru, Mexico and Brazil. The Payout is executed by the business partner at the
demand of the customer. This documentation is an add-on to the classic PaysafeCard integration:
**REST API**:
https://www.paysafecard.com/en/business/downloads/
**SOAP API**:
https://www.paysafecard.com/en/business/downloads/
https://www.paysafecard.com/fileadmin/api/paysafecardsopg.html
## Where to start with SafetyPay payouts?
To initiate the process of creating a SafetyPay payouts, the business partner must contact the account manager directly or at sales@paysafecard.com. Once the business process is finished, the feature will be activated from PaysafeCard side. The feature will be activated per MID (Merchant ID).There are also some technical integration changes necessary, which will be described in detail here.
## Payout Process
1. Customer creates a payout request on business partner’s checkout
2. Business partner validates and completes the request and forwards it to PaysafeCard
The business partner provides the customer’s personal details as well as other information like payout amount and beneficiary account information to PaysafeCard during the payout call.
3. PaysafeCard and SafetyPay performs validations and send the request to the Partner bank
PaysafeCard performs validation of the available balance of the business partner's account. SafetyPay executes an AML screening using an international AML blacklists. This means every transaction request will be screened and blocked if the beneficiary is present on the blacklist. If all validations are succesfull, the payout request is send to the partner bank
4. Partner bank validates the payee and executes a payout
Partner bank compares the personal information provided by the business partner with the records owned by the bank. If the information does not match, the payout transaction is rejected.
5. PaysafeCard notifies the Merchant of the payout result
PaysafeCard notifies the merchant about the result of the payout operation via API.
## Exchange of customer data
Following are mandatory and optional attributes that merchant must capture and provide within the Payout request.
|Attribute|Mexico|Brazil|Peru|
|-|-|-|-|
|First Name|Mandatory|Mandatory|Mandatory|
|Middle Name|Optional|Optional|Optional|
|Last Names|Mandatory|Mandatory|Mandatory|
|Date of Birth|Mandatory|Mandatory|Mandatory|
|Document ID Type|Mandatory|Mandatory|Mandatory|
|Document IT Number|Mandatory|Mandatory|Mandatory|
|Bank Name|N/A|N/A|N/A|
|Bank Account Format|Mandatory|N/A|Mandatory|
|Bank Account Number|Mandatory|N/A|Mandatory|
|Disbursement Amount + Currency|Mandatory|Mandatory|Mandatory|
|Mobile|Optional|N/A|N/A|
|Email|Optional|Optional|Optional|
|Country|Mandatory|Mandatory|Mandatory|
|IP address|Optional|Optional|Optional|
## 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.
## 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>.*
## Country specific requirements and limitations
<b>Supported countries and their currencies with minumim and maximum amounts</b>
|Country|Field Name|Min/Max|Amount|Currency|
|-------|-------|-------|-------|-------|
|MEX|payout_amount|Min|10.00|MXN|
|MEX|payout_amount|Max|18000.00|MXN|
|BRA|payout_amount|Min|5.00|BRL|
|BRA|payout_amount|Max|5500.00|BRL|
|PER|payout_amount|Min|5.00|PEN|
|PER|payout_amount|Max|4000.00|PEN|
> Please note that the maxiumum payout limit is the equivalent of 1000 USD but we have made adjustments for the volatility of the currencies. Partners should keep to the current equivalent of 1000 USD.
<b>Mexico</b>
1. Customer must accept SafetyPay’s T&C and Privacy Policies(provided by account manager).
2. Business partner must mention in its Terms & Conditions (T&C) that Payouts are executed by SafetyPay
## Payout implementation
- Prerequisites
- SOPG Username and Password/API Key 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.
- For all deposits passing the parameters `account_registration_date`, `account_KYC_level` and `account_registration_country` in `the customer_data_takeover`/customerDataTakeover object for this customer and initiating the payout with the same `id`/merchantClientId for them.^1^
> ^1^ Customers with a completed successful deposit will not need to make a new one before receiving a payout but any further deposits will need to contain the parameters.
# Group Initiating a SafetyPay Payment - REST
<a name="initiate_payment"></a>
## restrictions [/payments]
<a name="restrictions_REST"></a>
The array `restrictions` containing the `payment_instrument`, `payment_instrument_subtype` & `bank_ids` parameters gives the possibility to initiate a payment for the specific option chosen by the customer
at the merchant's checkout. When choosing the `payment_instrument`, the customer will be redirected to the SafetyPay payment page immediately.
| Parameter | Type | Description | Possible values
| --- | --- | --- | ---
| `restrictions` | Array | The payment restrictions array.
| `payment_instrument` | String | The payment instrument gives the possibility to initiate the payment for the specific option chosen at the merchant's checkout page. "payment_instrument" is mandatory when providing "payment_instrument_subtype" |`paysafecard`, `safetypay`
| `payment_instrument_subtype` | String | The payment instrument subtype gives the possibility to initiate the payment for the specific option chosen at the merchant's checkout page. |`cash`,`online`
| `bank_ids` | Numerical Array | The bank ID restriction gives the possibility to only show certain bank options. It is an array that allows multiple options. Only 74 characters can be sent (14 bank IDs). Providing "bank_id" without providing the "payment_instrument" will show all the available payment methods. | A list of bank IDs can be found at the bottom under ["Bank IDs"](#bank_ids)
## customer_data_takeover
<a name="customer_data_takeover_REST"></a>
The array `customer_data_takeover` containing the `tax_id`, `tax_id_type`, `account_registration_date`, `account_KYC_level` & `account_registration_country` parameters gives the possibility to specify parameters that ease the customer journey such as tax ID and its type (for Brazilian customers) as well as ones mandatory for Payouts such as the account details ones.
| Parameter | Type | Description | Possible values
| --- | --- | --- | ---
| `customer_data_takeover` | Array | The customer data takeover array.
| `tax_id` | String | The tax ID of the customer. Required if you want to prefill the CFP field for transactions in Brazil. |0123059433817717
| `tax_id_type` | String | The type of the tax ID. | BRA_CPF
| `account_registration_date` | String | The registration date of the customer with the partner. Mandatory to be included in a deposit to do payouts to this customer | 2018-05-03
| `account_KYC_level` | String | The KYC level of the customer with the partner. Mandatory to be included in a deposit to do payouts to this customer | FULL, SIMPLE
| `account_registration_country` | String | The country of registration of the customer with the partner. Mandatory to be included in a deposit to do payouts to this customer | MX,PE
### Initiate Payment Example
```
{
"type": "PAYSAFECARD",
"amount": 2000.00,
"currency": "BRL",
"redirect": {
"success_url": "https://www.paysafecard.com/okURL",
"failure_url": "https://www.paysafecard.com/nokURL"
},
"notification_url": "https://www.paysafecard.com/pnUrl",
"customer": {
"id": "customer_id2"
},
"shop_id":"test123",
"customer_takeover_data": {
"email": "test@test.com",
"account_registration_date": "1997-05-15",
"account_KYC_level":"FULL",
"account_registration_country":"MX"
},
"restrictions": {
"payment_instrument": "safetypay",
"payment_instrument_subtype": "online",
"bank_ids": ["8439","8382"]
}
}
```
### New Error Code
Error number "2039" indicates that the one of the values passed in `payment_instrument` <!--or `payment_instrument_subtype`,--> is not a valid value.
```
{
"code": "invalid_restriction",
"message": "Could not convert restriction value 'giftcard_test'!",
"number": 2039
}
```
## retrieve payment details
When using the GET request `retrieve payment details`, you can also receive information which bank was used. If you want to use this feature, please contact us.
```
{
"object": "PAYMENT",
"id": "pay_1100000000_KLeati7txeyNIsw9vf1erkzKMjmlltoH_USD",
"created": 1652888898010,
"updated": 1652888980033,
"currency": "USD",
"status": "SUCCESS",
"type": "PAYSAFECARD",
"redirect": {
"success_url": "https://www.paysafecard.com/success/pay_1100000000_KLeati7txeyNIsw9vf1erkzKMjmlltoH_USD",
"failure_url": "https://www.paysafecard.com/failure/pay_1100000000_KLeati7txeyNIsw9vf1erkzKMjmlltoH_USD",
"auth_url": "https://customer.test.at.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=1100000000&mtid=pay_1100000000_KLeati7txeyNIsw9vf1erkzKMjmlltoH_USD&amount=1.00¤cy=USD"
},
"customer": {
"id": "MCID_limit_test",
"ip": "***.***.***.***"
},
"amount": 1.00,
"notification_url": "https://www.paysafecard.com/pnUrl",
"submerchant_id": "1",
"card_details": [
{
"serial": "1421456550",
"currency": "USD",
"amount": 1.00,
"type": "00109",
"country": "BR"
}
],
"payment_instrument": "safetypay",
"payment_instrument_subtype": "online",
"bank_id": "9999"
}
```
<a name="initiate_payment"></a>
### initiate payment request [POST]
+ Request (application/json)
Authorization: Basic cHNjX25wZ0g2THkxa3NXMS1CZzBQaURDNGZ0dzliSWtzQkY=
+ Attributes (PaymentRequest)
+ Response 201 (application/json)
{
"object": "PAYMENT",
"id": "pay_1100000000_v2Pa0tDn0tr1CppVkSQ0yjY77eVOO5Pl_USD",
"created": 1607074107062,
"updated": 1607074107062,
"currency": "USD",
"status": "INITIATED",
"type": "PAYSAFECARD",
"redirect": {
"success_url": "https://ok.com/pay_1100000000_v2Pa0tDn0tr1CppVkSQ0yjY77eVOO5Pl_USD",
"failure_url": "https://nok.com/pay_1100000000_v2Pa0tDn0tr1CppVkSQ0yjY77eVOO5Pl_USD",
"auth_url": "https://customer.test.at.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=1100000000&mtid=pay_1100000000_v2Pa0tDn0tr1CppVkSQ0yjY77eVOO5Pl_USD&amount=1.00¤cy=USD"
},
"customer": {
"id": "test_dev"
}, "customer_takeover_data": {
"email": "test@test.com",
"account_registration_date": "1997-05-15",
"account_KYC_level":"FULL",
"account_registration_country":"MX"
}, "restrictions": {
"payment_instrument":"safetypay",
"payment_instrument_subtype":"cash"
}
"amount": 1.00,
"notification_url": "https://9fc7622ff6a8995a8919be9c134d39a5.m.pipedream.net"
}
# Group Creating a SafetyPay Disposition - SOAP
## restrictions
<a name="restrictions_SOPG"></a>
The disposition restriction `INSTRUMENT` & `INSTRUMENT_SUBTYPE` gives the possibility to create a disposition for the specific option chosen by the customer at the merchant's checkout. The customer will be redirected to the SafetyPay payment page immediately.
| Parameter | Type | Description | Possible values
| --- | --- | --- | ---
| `dispositionRestrictions` | Array | The payment restrictions array.
| `key` | String | Value to specify what type of restriction should be applied for the transaction.| `INSTRUMENT`,`INSTRUMENT_SUBTYPE`,`BANK_IDS`
| `value` | String | Value to define the available options for a certain restriction. | `INSTRUMENT`:`paysafecard`, `safetypay`<br>`INSTRUMENT_SUBTYPE`:`cash`,`online`<br>`BANK_IDS`: A list of bank IDs can be found at the bottom under ["Bank IDs"](#bank_ids)
## customerTakeoverData
<a name="customerTakeoverData_SOPG"></a>
The array `customerTakeoverData` containing the `registrationDate`, `kycLevel` & `countryIso2` parameters gives the possibility to specify parameters that ease the customer journey such as email to skip the intermediary page for SafetyPay as well as ones mandatory for Payouts such the account details ones.
| Parameter | Type | Description | Possible values
| --- | --- | --- | ---
| `customerTakeoverData` | Array | The payment restrictions array.
| `registrationDate` | String | The registration date of the customer with the partner. Mandatory to be included in a deposit to do payouts to this customer | 2018-05-03
| `kycLevel` | String | The KYC level of the customer with the partner. Mandatory to be included in a deposit to do payouts to this customer | FULL, SIMPLE
| `countryIso2` | String | The country of registration of the customer with the partner. Mandatory to be included in a deposit to do payouts to this customer | MX,PE
| `hash` | String | The hash key used for the details to be securely transferred | 123%asd
<a name="createDisposition"></a>
##createDisposition Example
```
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:pscservice">
<soapenv:Header/>
<soapenv:Body>
<urn:createDisposition>
<urn:username>username_SOAP</urn:username>
<urn:password>password_SOAP</urn:password>
<urn:mtid>mtid_soap</urn:mtid>
<urn:amount>10.00</urn:amount>
<urn:currency>USD</urn:currency>
<urn:merchantclientid>customer1</urn:merchantclientid>
<urn:okUrl>https://www.paysafecard.com/okURL</urn:okUrl>
<urn:nokUrl>https://www.paysafecard.com/nokURL</urn:nokUrl>
<urn:pnUrl>https://www.paysafecard.com/pnURL</urn:pnUrl>
<urn:customerDetail>customer_id</urn:customerDetail>
<urn:subId>reporting_criteria</urn:subId>
<urn:customerTakeoverData>
<urn:registrationDate>1997-04-10</urn:registrationDate>
<urn:countryIso2>MX</urn:countryIso2>
<urn:kycLevel>FULL</urn:kycLevel>
<urn:hash>123</urn:hash>
</urn:customerTakeoverData>
<urn:dispositionRestrictions>
<urn:key>INSTRUMENT</urn:key>
<urn:value>safetypay</urn:value>
<urn:key>INSTRUMENT_SUBTYPE</urn:key>
<urn:value>cash</urn:value>
<urn:key>BANK_IDS</urn:key>
<urn:value>"8382,4087"</urn:value>
</urn:dispositionRestrictions>
</urn:createDisposition>
</soapenv:Body>
</soapenv:Envelope>
```
### New Error Code
Error code "2039" indicates that the value passed in `instrument` is not a valid value.
```
<ns1:createDispositionResponse>
<ns1:createDispositionReturn>
<ns1:mtid>1607092862</ns1:mtid>
<ns1:resultCode>1</ns1:resultCode>
<ns1:errorCode>2039</ns1:errorCode>
</ns1:createDispositionReturn>
</ns1:createDispositionResponse>
```
## getSerialNumbers Example
When using the request `getSerialNumbers`, you can also receive information which bank was used. If you want to use this feature, please contact us.
```
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:pscservice">
<soap:Body>
<ns1:getSerialNumbersResponse>
<ns1:getSerialNumbersReturn>
<ns1:mtid>pay_1000067571_T23Gn1TLmSQ3Aj3im7kwFvAPrUgkCxmJ_BRL</ns1:mtid>
<ns1:resultCode>0</ns1:resultCode>
<ns1:errorCode>0</ns1:errorCode>
<ns1:amount>2000.0</ns1:amount>
<ns1:currency>BRL</ns1:currency>
<ns1:dispositionState>S</ns1:dispositionState>
<ns1:serialNumbers>1421456559;2000.00</ns1:serialNumbers>
<ns1:paymentInstrument>safetypay</ns1:paymentInstrument>
<ns1:paymentInstrumentSubtype>online</ns1:paymentInstrumentSubtype>
<ns1:bankId>9999</ns1:bankId>
</ns1:getSerialNumbersReturn>
</ns1:getSerialNumbersResponse>
</soap:Body>
</soap:Envelope>
```
# Group JSON Payment notification
<a name="payment_notification"></a>
The payment notification is used to notify the business partner independently of the customer’s behaviour after the payment authorization.
This service ensures that payments can be completed before the top-up of the customer’s account and is, therefore, highly recommended in order to avoid incomplete payments.
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).
A JSON version of the payment notification with all the possible parameters, including the "*payment_instrument*" used, is now available. Example of the body:
```
{
"timestamp": 1607017210793,
"eventType": "ASSIGN_CARDS",
"version": "1",
"data": {
"mid": "1100000000",
"customer": {
"id": "kfoLkCq3RBIJiJF6sJWBeYA4tnfsCms2"
},
"payment_id": "pay_1100000000_XdyBD9FuEJVhpX3hctwJzCB8W1rEzqTo_USD",
"payment_instrument": "safetypay",
"payment_instrument_subtype":"cash",
"card_details": [
{
"serial": "1420271325",
"currency": "USD",
"amount": 10,
"type": "00094",
"country": "XX"
}
]
}
}
```
**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.
| `payment_id` | String | The sub-merchant id. Also knows as reporting criteria.
| `payment_instrument` | String | The payment method used. <br><br> Possible values: paysafecard or safetypay
| `payment_instrument_subtype` | String | The type of payment option. <br><br> Possible values: cash, online
| `bank_id` | String | The type bank used for SafetyPay <br><br> Possible values: See [*here*](https://www.paysafecard.com/fileadmin/api/paysafecardsafetypay.html#/reference/bank-ids) <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.
# Group Payment processes
<a name="cash_payment_REST_PP"></a>
## Cash Payment process - REST - intermediary PaysafeCard redirection
1. The customer selects the payment method at the business partner checkout page: PaysafeCard and/or SafetyPay
1. [Initiate Payment](#initiate_payment): Send POST request `initiate Payment`
* 2.1. If the response gives back http20x, the business partner redirects 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 `auth_url`: The customer reaches the PaysafeCard payment panel
* 3.1. The customer selects SafetyPay Cash Payment
* 3.2. The customer is redirected to the SafetyPay hosted payment page
1. The customer receives a operation ID code
* 4.1. The customer has to go to a Point of Collection and complete their payment
1. Payment notification delivery: A card will be assigned once the customer completes the payment (transaction status "AUTHORIZED"), PaysafeCard sends a notification to the `notification_url`
1. `notification_url` handling: Right after the payment notification delivery, the business partner performs the GET request `Retrieve payment details` to check the status of the transaction
* 6.1. If the GET request `retrieve payment details` returns the status "AUTHORIZED", immediately perform the POST request `capture Payment`
* 6.2. If the response to `capture payment` is http20X and the status returned is "SUCCESS", the business partner makes a user account top up accordingly or deliver the goods
<a name="online_payment_REST_PP"></a>
## Online Payment process - REST - intermediary PaysafeCard redirection
1. The customer selects the payment method at the business partner checkout page: PaysafeCard and/or SafetyPay
1. [Initiate Payment](#initiate_payment): Send POST request `initiate Payment`
* 2.1. If the response gives back http20x, the business partner redirects 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 `auth_url`: The customer reaches the PaysafeCard payment panel
* 3.1. The customer selects SafetyPay Online Payment
* 3.2. The customer is redirected to the SafetyPay hosted payment page
1. The customer continues with their preferred choice of online payment methods and completes the payment
1. Payment notification delivery: A card will be assigned once the customer completes the payment (transaction status "AUTHORIZED"), PaysafeCard sends a notification to the `notification_url`
1. `notification_url` handling: Right after the payment notification delivery, the business partner performs the GET request `Retrieve payment details` to check the status of the transaction
* 6.1. If the GET request `retrieve payment details` returns the status "AUTHORIZED", immediately perform the POST request `capture Payment`
* 6.2. If the response to `capture payment` is http20X and the status returned is "SUCCESS", the business partner makes a user account top up accordingly or deliver the goods
1. `success_url` handling: The customer may return to the `success_url`. This step is optional.
<a name="cash_payment_REST_noPP"></a>
## Cash Payment process - REST - immediate SafetyPay redirection
1. The customer selects SafetyPay at the business partner checkout page
1. [Initiate Payment](#initiate_payment): Send POST request `initiate Payment` with "payment_instrument" & "payment_instrument_subtype" parameters set to "safetypay" & "cash": [Initiating a SafetyPay Payment - REST](#restrictions_REST)
* 2.1. If the response gives back http20x, the business partner redirects 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 `auth_url`: The customer reaches the SafetyPay Cash Payment Page
1. The customer receives a operation ID code
* 4.1. The customer has to go to a Point of Collection and complete their payment
1. Payment notification delivery: A card will be assigned once the customer completes the payment (transaction status "AUTHORIZED"), PaysafeCard sends a notification to the `notification_url`
1. `notification_url` handling: Right after the payment notification delivery, the business partner performs the GET request `Retrieve payment details` to check the status of the transaction
* 6.1. If the GET request `retrieve payment details` returns the status "AUTHORIZED", immediately perform the POST request `capture Payment`
* 6.2. If the response to `capture payment` is http20X and the status returned is "SUCCESS", the business partner makes a user account top up accordingly or deliver the goods
<a name="online_payment_REST_noPP"></a>
## Online Payment process - REST - immediate SafetyPay redirection
1. The customer selects the payment method at the business partner checkout page: PaysafeCard and/or SafetyPay
1. [Initiate Payment](#initiate_payment): Send POST request `initiate Payment` with "payment_instrument" & "payment_instrument_subtype" parameters set:[Initiating a SafetyPay Payment - REST](#restrictions_REST)
* 2.1. If the response gives back http20x, the business partner redirects 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 `auth_url`: The customer reaches the SafetyPay Online Payment Page
1. The customer continues with their preferred choice of online payment methods and completes the payment
1. Payment notification delivery: A card will be assigned once the customer completes the payment (transaction status "AUTHORIZED"), PaysafeCard sends a notification to the `notification_url`
1. `notification_url` handling: Right after the payment notification delivery, the business partner performs the GET request `Retrieve payment details` to check the status of the transaction
* 6.1. If the GET request `retrieve payment details` returns the status "AUTHORIZED", immediately perform the POST request `capture Payment`
* 6.2. If the response to `capture payment` is http20X and the status returned is "SUCCESS", the business partner makes a user account top up accordingly or deliver the goods
1. `success_url` handling: The customer may return to the `success_url`. This step is optional.
<a name="cash_payment_SOAP_PP"></a>
## Cash Payment process - SOAP - intermediary PaysafeCard redirection
1. The customer selects the payment method at the business partner checkout page: PaysafeCard or SafetyPay
1. [create Disposition](#createDisposition): the business partner makes the SOAP request `createDisposition`
* 2.1. If the result and error code is `0`, the business partner redirects the customer to the payment panel
* 2.2. If the result or error code is not `0`, the business partners shows an error message to the customer:
*"Transaction could not be intitiated due to connection problems. If the problem persists, please contact our (business partner) support."*
1. Redirection to the payment panel with `getCustomerPanel`: The customer reaches the PaysafeCard payment panel
* 3.1. The customer selects SafetyPay Cash Payment
* 3.2. The customer is redirected to the SafetyPay hosted payment page
1. The customer receives a operation ID code
* 4.1. The customer has to go to a Point of Collection to complete the payment
1. Payment notification delivery: Since the card is assigned to the transaction (transaction status "S"), PaysafeCard sends a notification to the `pn_url`
1. `pnUrl` handling: Right after the payment notification delivery, the business partner performs the request `getSerialNumbers` to check the status of the transaction
* 6.1. If `getSerialNumbers`returns the status "S", immediately perform the `executeDebit` request
* 6.2. If the response to `executeDebit` is result and error code is `0`, the business partner makes a user account top up accordingly or deliver the goods
<a name="online_payment_SOAP_PP"></a>
## Online Payment process - SOAP - intermediary PaysafeCard redirection
1. The customer selects the payment method at the business partner checkout page: PaysafeCard or SafetyPay
1. [create Disposition](#createDisposition): the business partner makes the SOAP request `createDisposition`
* 2.1. If the result and error code is `0`, the business partner redirects the customer to the payment panel
* 2.2. If the result or error code is not `0`, the business partners shows an error message to the customer:
*"Transaction could not be intitiated due to connection problems. If the problem persists, please contact our (business partner) support."*
1. Redirection to the payment panel with `getCustomerPanel`: The customer reaches the PaysafeCard payment panel
* 3.1. The customer selects SafetyPay Online Payment
* 3.2. The customer is redirected to the SafetyPay hosted payment page
1. The customer continues with their preferred choice of online payment methods and completes the payment
1. Payment notification delivery: Since the card is assigned to the transaction (transaction status "S"), PaysafeCard sends a notification to the `pn_url`
1. `pnUrl` handling: Right after the payment notification delivery, the business partner performs the request `getSerialNumbers` to check the status of the transaction
* 6.1. If `getSerialNumbers`returns the status "S", immediately perform the `executeDebit` request
* 6.2. If the response to `executeDebit` is result and error code is `0`, the business partner makes a user account top up accordingly or deliver the goods
1. `okUrl` handling: The customer may return to the `okUrl`. This step is optional.
<a name="cash_payment_SOAP_noPP"></a>
## Cash Payment process - SOAP - immediate SafetyPay redirection
1. The customer selects the payment method at the business partner checkout page: PaysafeCard or SafetyPay
1. [create Disposition](#createDisposition): the business partner makes the SOAP request `createDisposition`
* 2.1. If the result and error code is `0`, the business partner redirects the customer to the payment panel
* 2.2. If the result or error code is not `0`, the business partners shows an error message to the customer:
*"Transaction could not be intitiated due to connection problems. If the problem persists, please contact our (business partner) support."*
1. Redirection to the payment panel with `getCustomerPanel`: The customer reaches the SafetyPay Cash Payment Page
1. The customer receives a operation ID code
* 4.1. The customer has to go to a Point of Collection or pay for the operation ID code with one of the available payment options
1. Payment notification delivery: Since the card is assigned to the transaction (transaction status "S"), PaysafeCard sends a notification to the `pn_url`
1. `pnUrl` handling: Right after the payment notification delivery, the business partner performs the request `getSerialNumbers` to check the status of the transaction
* 6.1. If `getSerialNumbers`returns the status "S", immediately perform the `executeDebit` request
* 6.2. If the response to `executeDebit` is result and error code is `0`, the business partner makes a user account top up accordingly or deliver the goods
<a name="online_payment_SOAP_noPP"></a>
## Online Payment process - SOAP - immediate SafetyPay redirection
1. The customer selects the payment method at the business partner checkout page: PaysafeCard or SafetyPay
1. [create Disposition](#createDisposition): the business partner makes the SOAP request `createDisposition`
* 2.1. If the result and error code is `0`, the business partner redirects the customer to the payment panel
* 2.2. If the result or error code is not `0`, the business partners shows an error message to the customer:
*"Transaction could not be intitiated due to connection problems. If the problem persists, please contact our (business partner) support."*
1. Redirection to the payment panel with `getCustomerPanel`: : The customer reaches the SafetyPay Online Payment Page
1. The customer continues with their preferred choice of online payment methods and completes the payment
1. Payment notification delivery: Since the card is assigned to the transaction (transaction status "S"), PaysafeCard sends a notification to the `pn_url`
1. `pnUrl` handling: Right after the payment notification delivery, the business partner performs the request `getSerialNumbers` to check the status of the transaction
* 6.1. If `getSerialNumbers`returns the status "S", immediately perform the `executeDebit` request
* 6.2. If the response to `executeDebit` is result and error code is `0`, the business partner makes a user account top up accordingly or deliver the goods
1. `okUrl` handling: The customer may return to the `okUrl`. This step is optional.
<!--!
<a name="customer_flows"></a>
# Group Customer Flows
## Brazil
<!--
## Colombia
<!--
## Chile
<!--
## Mexico
<!--
-->
<a name="bank_ids"></a>
# 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
## SOPG
### 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: MXN
+ merchantClientId - unique customer identified provided by the merchant. Must line up with the merchantClientId used during a previous deposit.
* max. length: 200 characters
+ clientIp (OPTIONAL) - IP address of the customer
+ countryCode - ISO 3166-1 alpha-2 country code
* example: MX, PE, BR
+ payoutInstrument - always "SAFETYPAY"
+ 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
+ notificationUrl (OPTIONAL) - An url, where PaysafeCard will send a notification request after the payout has been finalized (either successfully or unsuccessfully)
+ firstName (subelement of CustomerDetailsBasic): the first name of the customer
* max. length: 60 characters
* example: John
+ middleName (OPTIONAL) (subelement of CustomerDetailsBasic): the middle name of the customer
* max. length: 60 characters
* example: William
+ lastName (subelement of CustomerDetailsBasic): the last name of the customer customer
* max. length: 60 characters
* example: Doe
+ dateOfBirth (sub-element of CustomerDetailsBasic): the date of birth of the payout customer in YYYY-MM-DD format
* example: 1979-12-20
+ phoneNumber (OPTIONAL) (sub-element of CustomerDetailsBasic): the phone number of the payout customer
* max. length: 20 characters
+ email (OPTIONAL) (sub-element of CustomerDetailsBasic): valid email adress of the payout customer
* max. length 255 characters
* example: john.wdoe@gmail.com
+ registrationDate (sub-element of CustomerDetailsBasic): customer's merchant account creation date
* example: 2021-12-31
+ country (sub-element of CustomerDetailsBasic): customer's country
+ kycLevel (sub-element of CustomerDetailsBasic): KYC status of the account with the merchant (SIMPLE/FULL)
* SIMPLE = account is not verified
* FULL = account is verified
+ bankAccount - contains sub-elements:
* type - Type of the customer's bank account (example: CLABE) See section "Code books" for more information.
* number - Bank account number (max length: 50 characters)
+ idDocument - contains sub-elements:
* type - Type of customer's ID document (example: RFC). See section "Code books" for more information.
* number - Customer's ID document number (max length: 50 characters)
+ 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
### Validating a payout
Upon successful execution of this request, the status of the SafetyPay is set to VALIDATION_SUCCESSFUL
+ Request:
```
<urn:payout>
<urn:username>USER</urn:username>
<urn:password>PASSWORD</urn:password>
<urn:ptid>abcd12345678efgh</urn:ptid>
<urn:amount>1234.56</urn:amount>
<urn:currency>MXN</urn:currency>
<urn:merchantClientId>unique-mcid-1</urn:merchantClientId>
<urn:clientIp>123.45.67.89</urn:clientIp>
<urn:validationOnly>true</urn:validationOnly>
<urn:utcOffset>+09:00</urn:utcOffset>
<urn:customerDetailsBasic>
<urn:firstName>John</urn:firstName>
<urn:lastName>Doe</urn:lastName>
<urn:dateOfBirth>1999-12-31</urn:dateOfBirth>
<urn:middleName>William</urn:middleName>
<urn:phoneNumber>+527729871234</urn:phoneNumber>
<urn:email>joh.wdoe@customer.com</urn:email>
<urn:registrationDate>2021-12-12</urn:registrationDate>
<urn:country>PT</urn:country>
<urn:kycLevel>SIMPLE</urn:kycLevel>
</urn:customerDetailsBasic>
<urn:payoutInstrument>SAFETYPAY</urn:payoutInstrument>
<urn:countryCode>MX</urn:countryCode>
<urn:bankAccount>
<urn:type>CLABE</urn:type>
<urn:number>012345678910111216</urn:number>
</urn:bankAccount>
<urn:idDocument>
<urn:type>RFC</urn:type>
<urn:number>XAXX010101000</urn:number>
</urn:idDocument>
<urn:notificationUrl>https://www.merchantsite.com/transaction/abcd12345678efgh/notification</urn:notificationUrl>
<urn:description>description</urn:description>
</urn:payout>
```
+ Response:
```
<ns1:payoutResponse>
<ns1:PayoutReturn>
<ns1:ptid>abcd12345678efgh</ns1:ptid>
<ns1:requestedCurrency>MXN</ns1:requestedCurrency>
<ns1:requestedAmount>1234.56</ns1:requestedAmount>
<ns1:validationOnly>true</ns1:validationOnly>
<ns1:resultCode>0</ns1:resultCode>
<ns1:errorCode>0</ns1:errorCode>
<ns1:errorCodeDescription></ns1:errorCodeDescription>
</ns1:PayoutReturn>
</ns1:payoutResponse>
```
### Capturing a pre validated payout
Upon successful execution of this request, the status of the SafetyPay Payout transitions to PENDING.
+ Request:
```
<urn:payout>
<urn:username>USER</urn:username>
<urn:password>PASSWORD</urn:password>
<urn:ptid>abcd12345678efgh</urn:ptid>
<urn:amount>1234.56</urn:amount>
<urn:currency>MXN</urn:currency>
<urn:merchantClientId>unique-mcid-1</urn:merchantClientId>
<urn:clientIp>123.45.67.89</urn:clientIp>
<urn:validationOnly>false</urn:validationOnly>
<urn:utcOffset>+09:00</urn:utcOffset>
<urn:customerDetailsBasic>
<urn:firstName>John</urn:firstName>
<urn:lastName>Doe</urn:lastName>
<urn:dateOfBirth>1999-12-31</urn:dateOfBirth>
<urn:middleName>William</urn:middleName>
<urn:phoneNumber>+527729871234</urn:phoneNumber>
<urn:email>joh.wdoe@customer.com</urn:email>
<urn:registrationDate>2021-12-12</urn:registrationDate>
<urn:country>PT</urn:country>
<urn:kycLevel>SIMPLE</urn:kycLevel>
</urn:customerDetailsBasic>
<urn:payoutInstrument>SAFETYPAY</urn:payoutInstrument>
<urn:countryCode>MX</urn:countryCode>
<urn:bankAccount>
<urn:type>CLABE</urn:type>
<urn:number>012345678910111216</urn:number>
</urn:bankAccount>
<urn:idDocument>
<urn:type>RFC</urn:type>
<urn:number>XAXX010101000</urn:number>
</urn:idDocument>
<urn:notificationUrl>https://www.merchantsite.com/transaction/abcd12345678efgh/notification</urn:notificationUrl>
<urn:description>description</urn:description>
</urn:payout>
```
+ Response:
```
<ns1:payoutResponse>
<ns1:PayoutReturn>
<ns1:ptid>abcd12345678efgh</ns1:ptid>
<ns1:requestedCurrency>MXN</ns1:requestedCurrency>
<ns1:requestedAmount>1234.56</ns1:requestedAmount>