forked from Paysafecard-DEV/api-documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
paysafecashlvl2-apiary.apib
241 lines (165 loc) · 14.4 KB
/
paysafecashlvl2-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
FORMAT: 1A
HOST: http://polls.apiblueprint.org/
# Paysafecash Link or QR code / Automated payment processing
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 to support heavier usage and the creation of payments via API.
This provides the business partners with full control over the transaction cycle as well as stock management, customer flow and customer data takeover.
## 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/business/downloads).
<br><br>
Paysafecash must be implemented accordingly to the interface guidelines (downloadable from https://www.paysafecash.com/en/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 webhook notification request is sent to the business partner. The business partner must verify the webhook notification as described [here](#capture_notification).
+ Upon successfuly verifying the webhook notification, the business partner must 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 Webhook notification
<a name="webhook_notification"></a> The *webhook notification* is an HTTP `POST` request sent to the business partner endpoint (provided to the paysafecard team during the integration), as soon as a payment is captured by paysafecard or the payment expires.
The business partner payment server must respond with *HTTP 200* and the authenticity of the webhook notification must be verified, as well as process the payment matching the details in the body of the message.
<br><br>
During the onboarding, the paysafecard team will provide a public key to the business partner which can be used to verifiy the authenticity of the webhook notification.
<br><br>
In case of technical errors (e.g. socket timeout) or application errors, the webhook notification is resubmitted at a regular interval of 1 minute until one of the following criteria is fulfilled:
- The 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).
# Group How to verifiy the webhook notification
The webhook notification is signed with "rsa-sha256" and the signature can be found in the HTTP "Authorization" header.
<br><br>
HTTP headers
```http
Content-Type: application/json
Authorization: keyId="1",algorithm="rsa-sha256",signature="OFPVO1uqac0U18LlEedwfdYaIPuuCIsvSxuDRV+nsU33F2TVYapR/JHR0mvJSAZUJWUTJk60PZXPhGF9eQLeIidxX1yJg8JA0pC0/CAt7JbiF39KsjMYMkCPp51q84s1RqAa23D2sljJuvPQYiDJLPlZ7PRSxYaIfmJ6MWzRq4Ku4XVi6OpqgAkO5V205UsDBmp8mxc00w1Eu5yAPoUjelZfxqHl/G2D0e5hWPuggtx/3hx2szFQDJzfHdRBhrlSqcU2WGzByXhy6A6FzeOQVysQNAR1/i+ztlhfCotY11Usb+Uh4yUVwi/I0pbKL+UJZ2VZlI6++SAO7CoQVkBAiw=="
```
|Parameter |Description |
|--- |--- |
|`keyId` |The signature key version id. It has always the value "1" except if communicated otherwise by the paysafecard integration team. |
|`algorithm` |The algorithm used for the signature. A Paysafecash webhook notification will always be signed with "rsa-sha256".|
|`signature` |The signature of the webhook notification.|
<br><br>
HTTP body
```http
{
"timestamp":1539920400647,
"eventType":"PAYMENT_CAPTURED",
"version":"1",
"data": {
"mid":"1000000312",
"mtid":"pay_1000000312_kvQwaSARVDlZm2yxRVNaCYZObI5Xcd40_EUR"
}
}
```
|Parameter |Description |
|--- |--- |
|`timestamp` |The Unix timestamp of the payment. |
|`eventType` |The event that triggered the webhook notification. There are only two event types: "PAYMENT_CAPTURED" or "PAYMENT_EXPIRED" |
|`version` |The signature key version.|
|`mid` |The Merchant ID and/or Sub-merchant ID provided for the allocation of the payment. |
|`mtid` |The payment ID.|
<br><br>
The signature is created as follows:
```
signature = base64encode(rsa_encrypt(sha256(body), merchantPrivateKey))
```
And it is verified as follows:
```
rsa_decrypt(base64decode(signature), merchantPublicKey) == sha256(body)
```
<br><br>
###Using the *[openssl dgst](https://www.openssl.org/docs/man1.0.2/man1/dgst.html)* function to verify the signature
The digest functions can be used to verify digital signatures using message digests. The three steps below ilustrate how this can be done:
1. Extract the public key from the rsa key file sent with the data package
```
openssl rsa -RSAPublicKey_in -in webhook_signer_MANXXXXXXXXXX_1.rsa -out webhook_signer_MANXXXXXXXXXX_1_extracted.pem
```
2. Decode the signature of the webhook notification with base64
Linux: ```base64 --decode signature.txt > signature_debase64.txt```
Windows: ```certutil.exe -decode signature.txt signature_debase64.txt```
3. Verify the signature using the *[openssl dgst](https://www.openssl.org/docs/man1.0.2/man1/dgst.html)* function
The generic name, dgst, may be used with an option specifying the algorithm to be used. The default digest is sha256.
```
openssl dgst -sha256 -verify webhook_signer_MANXXXXXXXXXX_1_extracted.pem -signature signature_debase64.txt plaintext_payload.txt
```
|Parameter |Description |
|--- |--- |
|`-verify webhook_signer_MANXXXXXXXXXX_1_extracted.pem.pem` |Verifies the signature using the public key extracted in step 1. The output is either `Verification OK` or `Verification Failure`. |
|`-signature signature_debase64.txt` |The actual signature to verify in plain text, obtained in step 2. |
|`plaintext_payload.txt` |The body of the request in plain text. |
<br><br>
###Using the **openssl digest function** to verify the signature
The digest functions can be used to verify digital signatures using message digests.
The generic name, dgst, may be used with an option specifying the algorithm to be used. The default digest is sha256.
```
openssl dgst -sha256 -verify paysafePublicKeyForAP.pem -signature sign.sha256 payload.json
```
|Parameter |Description |
|--- |--- |
|`-verify paysafePublicKeyForAP.pem` |Verify the signature using the public key in "paysafePublicKeyForAP.pem". The output is either "Verification OK" or "Verification Failure". |
|`-signature sign.sha256 payload.json` |The actual signature to verify and the body of the request. |
# 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