forked from Paysafecard-DEV/api-documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
paysafecardsafetypayintegration-apiary.apib
819 lines (666 loc) · 45.6 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
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
## Group 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>
# Group 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>
# Group 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
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)
# Group Technical changes
<a name="technical_changes"></a>
1. The logo must be changed accordingly at the checkout page
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.
# 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. |`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. | A list of bank IDs can be found at the bottom under ["Bank IDs"](#bank_ids)
### 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",
"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"
}, "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)
<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: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 Bank IDs
You can supply one or more Bank IDs in the API request, restricting the customer to only these SafetyPay options.
Sending this parameter without "payment_instrument" does not limit the customer to SafetyPay.
|Payment Instrument Subtype | Country | Bank ID | Bank Name | Bank Provider Name
| --- | --- | --- | --- | ---
| online | BR | 8366 | Banco Itau Boleto | Banco Itau Boleto
| online | BR | 4081 | Banco Itau Robot | Banco Itau
| online | BR | 8183 | Banco do Brasil Robot | Banco do Brasil
| online | BR | 8183 | Banco do Brasil SafetyPay | Banco do Brasil
| online | BR | 8339 | Banco do Brasil Web Service | Banco do Brasil WS
| online | BR | 1022 | Banrisul | Banrisul
| online | BR | 8326 | Bradesco PagFacil | Bradesco Pagfacil
| online | BR | 8210 | Bradesco Robot | Bradesco
| online | BR | 8210 | Bradesco SafetyPay | Bradesco
| cash | BR | 8176 | Caixa Econômica Federal | Caixa Econômica Federal
| online | BR | 8439 | PIX | Bradesco PIX
| online | BR | 8042 | Santander Brasil | Santander Brasil
| online | CL | 8296 | Banco BCI One Step | Banco BCI
| online | CL | 8194 | Banco Estado | Banco Estado Recaudo Referenciado
| cash | CL | 8194 | Banco Estado | Banco Estado Recaudo Referenciado
| cash | CL | 8194 | Banco Estado | Banco Estado Recaudo Referenciado
| online | CL | 8291 | Banco Estado One Step | Banco Estado Boton de Pago
| online | CL | 8488 | Khipu | Khipu
| online | CL | 8493 | Khipu - BCI | Khipu
| online | CL | 8492 | Khipu - Banco Estado | Khipu
| online | CL | 8490 | Khipu - Banco de Chile | Khipu
| online | CL | 8494 | Khipu - Itau | Khipu
| online | CL | 8491 | Khipu - Santander | Khipu
| online | CL | 8416 | MachPay | Machpay BCI
| online | CL | 8457 | Scotiabank Chile | Scotiabank Chile
| cash | CL | 8198 | Walmart Chile | Walmart Chile
| cash | CL | 8198 | Walmart Chile | Walmart Chile
| cash | CL | 8198 | Walmart Chile | Walmart Chile
| cash | CL | 8198 | Walmart Chile | Walmart Chile
| online | CO | 8185 | Banco Agrario | Banco de Occidente COL
| online | CO | 8503 | COOFINEP | Banco de Occidente COL
| cash | CO | 8224 | Efecty | Efecty
| cash | CO | 8231 | MovilRed Colombia | MovilRed Colombia
| online | CO | 4100 | PSE - BANCOOMEVA | Banco de Occidente COL
| online | CO | 1099 | PSE - BBVA Colombia | Banco de Occidente COL
| online | CO | 8396 | PSE - Bancamía | Banco de Occidente COL
| online | CO | 4089 | PSE - Banco AV Villas | Banco de Occidente COL
| online | CO | 8185 | PSE - Banco Agrario | Banco de Occidente COL
| online | CO | 4090 | PSE - Banco Caja Social | Banco de Occidente COL
| online | CO | 4091 | PSE - Banco Colpatria | Banco de Occidente COL
| online | CO | 8163 | PSE - Banco Cooperativo Coopcentral | Banco de Occidente COL
| online | CO | 4093 | PSE - Banco Davivienda | Banco de Occidente COL
| online | CO | 5000 | PSE - Banco Falabella | Banco de Occidente COL
| online | CO | 4095 | PSE - Banco GNB Sudameris | Banco de Occidente COL
| online | CO | 4096 | PSE - Banco Pichincha COL | Banco de Occidente COL
| online | CO | 4097 | PSE - Banco Popular | Banco de Occidente COL
| online | CO | 4098 | PSE - Banco ProCredit | Banco de Occidente COL
| online | CO | 8389 | PSE - Banco Serfinanza | Banco de Occidente COL
| online | CO | 4087 | PSE - Banco de Bogota | Banco de Occidente COL
| online | CO | 4094 | PSE - Banco de Occidente | Banco de Occidente COL
| online | CO | 4099 | PSE - Bancolombia | Banco de Occidente COL
| online | CO | 4102 | PSE - Citibank Colombia | Banco de Occidente COL
| online | CO | 8372 | PSE - Confiar Cooperativa Financiera | Banco de Occidente COL
| online | CO | 8390 | PSE - Cooperativa Financiera de Antioquia | Banco de Occidente COL
| online | CO | 8475 | PSE - DALE | Banco de Occidente COL
| online | CO | 8371 | PSE - Daviplata | Banco de Occidente COL
| online | CO | 8476 | PSE - GIROS Y FINANZAS | Banco de Occidente COL
| online | CO | 8477 | PSE - IRIS | Banco de Occidente COL
| online | CO | 4092 | PSE - Itau Corpbanca Colombia S.A. | Banco de Occidente COL
| online | CO | 8474 | PSE - MOVII S.A. | Banco de Occidente COL
| online | CO | 8276 | PSE - Nequi | Banco de Occidente COL
| online | CO | 8332 | PSE - Santander COL | Banco de Occidente COL
| online | CO | 8397 | PSE – RappiPay COL | Banco de Occidente COL
| cash | CO | 8323 | SuRed | Sured
| cash | CO | 8323 | SuRed | Sured
| cash | CO | 8323 | SuRed | Sured
| cash | CO | 8323 | SuRed | Sured
| cash | CO | 8323 | SuRed | Sured
| cash | CO | 8323 | SuRed | Sured
| cash | CO | 8323 | SuRed | Sured
| cash | CO | 8323 | SuRed | Sured
| cash | CO | 8323 | SuRed | Sured
| cash | CO | 8323 | SuRed | SuRed
| cash | CO | 8323 | SuRed | Sured
| online | CR | 1021 | Banco Nacional de Costa Rica | Banco Nacional de Costa Rica
| cash | EC | 8216 | Banco Guayaquil | Banco Guayaquil
| online | EC | 8216 | Banco Guayaquil | Banco Guayaquil
| cash | EC | 8066 | Banco Pichincha ECU | Banco Pichincha ECU
| online | EC | 8066 | Banco Pichincha ECU | Banco Pichincha ECU
| cash | EC | 8458 | Facilito | Facilito
| cash | EC | 8458 | Facilito | Facilito
| cash | EC | 8458 | Facilito | Facilito
| cash | EC | 8458 | Facilito | Facilito
| cash | EC | 8458 | Facilito | Facilito
| cash | EC | 8401 | Red Activa | Red Activa
| cash | EC | 8401 | Red Activa | Red Activa
| cash | EC | 8401 | Red Activa | Red Activa
| cash | EC | 8401 | Red Activa | Red Activa
| cash | GT | 8404 | PuntoXpress GTM | Punto Xpress GTM
| cash | GT | 8404 | PuntoXpress GTM | Punto Xpress GTM
| cash | GT | 8404 | PuntoXpress GTM | Punto Xpress GTM
| cash | GT | 8404 | PuntoXpress GTM | Punto Xpress GTM
| cash | GT | 8404 | PuntoXpress GTM | Punto Xpress GTM
| online | MX | 8425 | Afirme PayCash | Paycash
| online | MX | 1020 | BBVA Bancomer | BBVA Bancomer
| cash | MX | 1020 | BBVA Bancomer | BBVA Bancomer
| cash | MX | 8186 | Banco Azteca | Banco Azteca
| cash | MX | 1026 | Banorte | Banorte
| online | MX | 1052 | HSBC Mexico | HSBC Mexico
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8178 | OpenPay | OpenPay
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| cash | MX | 8419 | PayCash | Paycash
| online | MX | 8191 | SPEI MX | OpenPay Online
| online | MX | 8400 | SPEI ROBOT | OpenPay
| online | MX | 9999 | Santander MEX | Santander
| online | MX | 8395 | Santander MEX WS | Banco Santander
| online | MX | 1007 | Scotiabank Mexico | Scotiabank Mexico
| cash | PA | 8188 | Western Union Panama | Western Union Panama
| cash | PE | 8443 | Agente Niubiz | Niubiz
| cash | PE | 8321 | Agentes Kasnet | Western Union
| online | PE | 1001 | BBVA Continental | BBVA Continental
| online | PE | 8391 | BCP Cuotéalo | Banco de Crédito Cuotealo
| online | PE | 8441 | Banco Pichincha PER | Pichincha PER
| online | PE | 1005 | Banco de Crédito | Banco de Crédito
| online | PE | 8324 | Caja Arequipa | Caja Arequipa
| online | PE | 8250 | Caja Huancayo | Caja Huancayo
| online | PE | 1024 | Caja Tacna | Caja Tacna
| online | PE | 1025 | Caja Trujillo | Caja Trujillo
| cash | PE | 8442 | Globokas - Kasnet | Globokas - Kasnet
| online | PE | 1011 | Interbank | Interbank
| cash | PE | 8444 | Red Digital | Red Digital
| online | PE | 1006 | Scotiabank Peru | Scotiabank Peru
| cash | PE | 8440 | Tambo+ | Tambo
| cash | PE | 8320 | Western Union | Western Union
| cash | PE | 8320 | Western Union | Western Union
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
| cash | SV | 8300 | Punto Xpress SLV | Punto Xpress SLV
# Data Structures
## TypedObject (object)
+ type: PAYSAFECARD (required, fixed) - Type of the product, must be set to PAYSAFECARD.
## PaymentRequest (TypedObject)
+ amount: 10.00 (number, required) - Payment amount, precision must be 2 digits after the colon.
+ currency: USD (required) - ISO 4217 - 3 letter ISO currency code.
+ redirect (object)
+ `success_url`: https://notification.com/{payment_id} (required) - URLs to redirect after successful or failed authorization. The placeholder {payment_id} in the URL is replaced with the actual ID of this payment.
+ `failure_url`: https://notification.com/{payment_id} (required) - URLs to redirect after customer clicked on cancel. The placeholder {payment_id} in the URL is replaced with the actual ID of this payment.
+ `notification_url`: https://notification.com/{payment_id} (required)- Notification URL we will contact after the authorization has been successfully completed. The placeholder {payment_id} in the URL is replaced with the actual ID of this payment.
+ customer (object)
+ id: merchantclientid5HzDvoZSodKDJ7X7VQKrtestAutomation (required) - Only the id is mandatory. It´s value uniquely identifies the customer and is provided by you. If any personal data e.g. customer´s user name, email address, is used here, it has to be encrypted or hashed for security reasons.
+ min_age: 18 (optional) - Valid for my paysafecard payments. For additional information about my paysafecard, please see the section "my paysafecard". Restricts payments to my paysafecard customers only, who are equal to or older than the specified age. Please note: This means that it is required that the customer has a registered my paysafecard account to make the payment.
+ kyc_level: SIMPLE (optional) - Valid values SIMPLE or FULL. These values refer to the KYC level of the customer's my paysafecard account. Depending on the country, my paysafecard accounts are offered with SIMPLE and/or FULL customer identification.
+ country_restriction: AT (optional) - ISO 3166-1 alpha-2 two-letter country code used to restrict payments to residents of a particular country.
+ restrictions (object)
+ payment_instrument: giftcard (optional) - The Payment instrument gives the possibility to initiate the payment for the specific option choosen at the checkout page. Possible values: "*paysafecard*" **or** "*giftcard*".
+ payment_instrument_subtype: openbuckscard (optional) - If "giftcard" was used for the `payment_instrument`, the payment can be initiated for a specific Giftcard option by defining a subtype. Possible values: "*cvspharmacy*" **or** "*dollargeneral*" **or** "*openbuckscard*".
+ submerchant_id: 1 (optional) - Also called ‘reporting criteria’, offers the possibility to classify sub-merchants. Agreement with paysafecard needed - not agreed values lead to a failed payment. max. 8 digits in alpha numeric code
+ shop_id: `shop1` (optional) - 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.