forked from paysafecard/api-documentation
-
Notifications
You must be signed in to change notification settings - Fork 59
/
paysafecashlvl1-apiary.apib
133 lines (82 loc) · 8.37 KB
/
paysafecashlvl1-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
FORMAT: 1A
HOST: http://polls.apiblueprint.org/
# Paysafecash Link or QR code / Manual payment processing (MSC)
Paysafecash offers the possibility for business partners to start processing payments with minimal or no technical integration.
Business partners can use a light version of the integration, as described in this documentation, and step-by-step extend it to support heavier usage and automated processing of goods and services.
## Integration prerequisites
The business partner is provided access to the Merchant Service Center. When using the MSC, the business partner complies with the provisions of the user manual for the MSC (downloadable from https://www.paysafecash.com/en/business/downloads).
<br><br>
Paysafecash must be implemented accordingly to the interface guidelines (downloadable from https://www.paysafecash.com/business/downloads) and the instructions in this technical integration document.
## Transaction Flow
A Paysafecash Transaction is processed as follows:
+ The business partner displays the payment hyperlink or QR-Code to the customer, using the correct Merchant ID and amount, as specified in the next section.
+ The customer initiates the payment by clicking the hyperlink or by scanning the QR-code.
+ The customer verifies that the payment details (including, but not limited to: payee, amount and payment reference) are correct and confirms the transaction.
+ The Paysafecash payment is created on the behalf of the business partner according to the payment details in the confirmation page and the customer is redirected to the barcode panel.
+ The barcode is displayed to the customer and it will only be valid for this specific transaction. The barcode can be viewed in various ways (e.g. online, Paysafecash app, download, e-mail, SMS or iOS / Android passbook file). A predefined time frame ("Transaction Timeout”) will be available to the customer to pay the transaction amount at a payment point. The duration of this time is by default 72 hours, unless specified otherwise by the business partner.
+ To complete the Paysafecash payment, the customer must head to a payment point, have it scanned and pay the transaction amount. If the customer does not pay within the Transaction Timeout, the Paysafecash Transaction expires. If the payment is successful, the customer receives a receipt confirming the payment.
+ The Paysafecash payment is captured on behalf of the business partner.
In the rare occasion that the Paysafecash payment system is down due to an outage or any other technical circumstance, the capture of the payment will be delayed but it will be executed.
+ A successful payment notification email is sent to the business partner. To prevent fraudulent activities, the notification does not include the payment details.
+ Upon receiving the notification, the business partner must log into the Merchant Service Center within 24 hours, verify the payment and deliver the product.
**Important:** Captured payments are irreversible. The business partner cannot cancel the Paysafecash payment at any time during the transaction process.
# Group How to create a Paysafecash hyperlink
Creating a payment link for Paysafecash is easy. The link always start with https://paysafecash.com/pay/?
After the "?" symbol, the first parameter used is always displayed and all subsequent parameters are separated by an ampersand "&" symbol.
<br><br>
Ex: *https://paysafecash.com/pay/?mid=102000XXXX&amount=10.99&validUntil=1605092589000&reference=0-1-4578545*
<br><br>
**IMPORTANT:** To avoid payments credited to an account they were not intended for, or unallocated payments, the **Merchant ID (mid)**, the **amount** and **reference** should always be provided by the Busines partner in the payment link:
# Group All Paysafecash hyperlink parameters
|Parameter |Constraint |Visibility |Description
|--- |--- |--- |---
|`mid` |mandatory |enabled |The Merchant ID provided for the allocation of the payment. |
|`amount` |mandatory |enabled |The payment amount. It can be provided as a parameter or filled by the customer in the confirmation page. |
|`currency` |prefilled |enabled |The currency of the payment. This value is always taken from the `mid`. |
|`validUntil` |prefilled |enabled |The expiration time of the transaction (Unix timestamp in milliseconds). The value provided in this parameter overrides the Merchant ID setting in the system. If this parameter it's not provided, the setting will be resolved from the Merchant ID (72 hours by default). |
|`recipientName`|optional |enabled |The recipient name provided for the allocation of the payment. <br></br> The recipient name overrides the `mid`value. |
|`reference` |optional |enabled |A payment reference should always be provided to facilitate the identification of the payment. The value passed in this parameter will be reflected in the [transaction Id](#transaction_id). |
|`iban` |mandatory |disabled |The IBAN provided for the allocation of the payment. <br></br> This parameter can only be enabled visible upon agreement between paysafecard and the business partner.|
|`bic` |mandatory |disabled |The BIC provided for the allocation of the payment. <br></br> This parameter onlyl only be enabled upon agreement between paysafecard and the business partner.|
# Group How to create a Paysafecash QR-code
The Merchant should use any libraries or online tool to create the QR-code, using the payment link as source.
Please make sure to display the QR-code in a way that it can be easily read by any smartphone or QR-code reader - good contrast between the background and the bar color and size depending on the targeted scan distance.
# Group Ways to initiate a payment
The link or QR-code can be displayed to the customer using any medium that applies to the partner business type.
<br><br>
<br><br>
**Hyperlink - Internet connection**
Digital invoice e-mail / invite by email from the Merchant Service Center, SMS, Skype, WhatsApp, Facebook, Web Checkout Page
**Text to be used:** *"PAY WITH CASH: Generate a barcode and go to a payment point near you to <a href="https://test.paysafecash.com/pay/?mid=1090001964&amount=499.99" target="blank">complete the payment</a>."* (HTML embedded payment hyperlink)
<br><br>
<br><br>
**QR-Code - Offline or devices without easy input (mouse, keyboard)**
Paper invoice, Erlagschein (stuzza), Consoles, Smart TVs
**Text to be used:** *"PAY WITH CASH: Scan the QR code with the app or go to paysafecash.com/pay to complete the payment."*
<br><br>
<br><br>
**Redirect - Webshop**
In the business partner webshop, as a payment method. Link with redirection as shown below
**Text to be used:** *"PAY WITH CASH: Generate a barcode and go to a <a href="https://www.paysafecash.com/pos" target="blank">payment point near you</a> to complete the payment."*
# Group Transaction Id Structure
The *Transaction ID (TID)*<a name="transaction_id"></a> can take different formats, depending on the amount of information provided in the payment link/QR code.
The *Transaction ID (TID)* can take the following formats:
1. When a **paymentReference** is provided:
typeOfPayment_mid_*paymentReference*_shortRandomlyGeneratedString_currency
Ex: *pay_1000000007_123541256_8dlkFg1F_EUR*
<br><br>
2. When a **paymentReference** is not provided:
typeOfPayment_mid_longRandomlyGeneratedString_currency
Ex: pay_1000000007_8dlkFg1Fjd8s3agz_EUR
# Group Business Partner Branding
Paysafecash gives the possibility for the business partner to display its ICON and/or LOGO in the payment confirmation page and barcode application page.
Requirements:
- ICON (1:1); should be square
- LOGO (3:1); should be rectangular
- Both must be in Vector format (SVG)
- No size limits