forked from Paysafecard-DEV/api-documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
paysafecardgiftcard-apiary.apib
375 lines (284 loc) · 26.1 KB
/
paysafecardgiftcard-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
FORMAT: 1A
HOST: https://apitest.paysafecard.com/v1
# Gift cards integration
paysafecard has expanded its portfolio of cash-based payment methods in the United States, adding the acceptance of popular retail gift cards such as CVS/pharmacy and Dollar General, as well as oBucks cards.
<br><br>
**This documentation explains how to start accepting gift card payment options as an add-on to the classic paysafecard integrations below:**
**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
<br><br>
**IMPORTANT: New merchants must integrate paysafecard first via REST API or SOAP API.**
<br><br>
For any technical questions about this documentation or the integration, the merchant must contact the paysafecard integration team at: [*integration@paysafecard.com*]().
## Where to start
To accept gift card payments on your U.S. checkout:
1. In case you are an existing paysafecard merchant, please contact your account manager for further guidance on the activation process and contractual steps. If you are not yet transacting with us, become a partner [here](https://www.paysafecard.com/en/business/online-partner/become-a-partner/).
2. Upon completion of the above, paysafecard will activate the gift cards on your USD MID (Merchant ID) and, if applicable, RC (Reporting Criteria).
3. You will need to complete two [technical integration changes](#technical_changes) as listed below.
## Gift card payment flow
1. The customer selects a gift card button at the merchant checkout (i.e. CVS, Dollar General, Circle K or oBucks)
2. The merchant initiates the payment by passing the amount, currency, payment instrument and other necessary parameters
3. paysafecard redirects the customer to the payment panel, where the customer completes the payment by entering the gift card number and PIN
4. Once the payment is completed, paysafecard sends a payment notification to the merchant via the notification URL
5. paysafecard redirects the customer back to the merchant via the success URL
6. The merchant captures the payment and delivers the goods to the customer
###Payment panel gift card redemption
## Technical changes
<a name="technical_changes"></a>
**Technical changes needed (for U.S. checkouts only):**
1. **Required:** The button must be changed on the merchant checkout by [configuring the button endpoints](#button_endpoint) which dynamically changes the button based on the MID, RC, country, instrument type and subtype.
2. **Required**: The payment must be created based on the option chosen by the customer at the checkout and achieved by passing the correct instrument type and subtype when [initiating the payment](#initiate_payment).
3. **Optional**: Integrate the [payment notification payload in JSON](#payment_notification) which enables the merchant to distinguish which payment instrument was used for the transaction.
## Configuring the button endpoints
<a name="button_endpoint"></a>
**paysafecard provides .svg buttons via the following endpoints described in the section below:**
| Environment | Url
|---------------|------------------------------------------------------
| Test | https://customer.test.at.paysafecard.com/rest/payment/logo.svg?`mid`=MID&`submerchant_id`=SUBMERCHANT_ID&`country`=COUNTRY&`payment_instrument`=PAYMENT_INSTRUMENT&`payment_instrument_subtype`=PAYMENT_INSTRUMENT_SUBTYPE
| Production | https://customer.cc.at.paysafecard.com/rest/payment/logo.svg?`mid`=MID&`submerchant_id`=SUBMERCHANT_ID&`country`=COUNTRY&`payment_instrument`=PAYMENT_INSTRUMENT&`payment_instrument_subtype`=PAYMENT_INSTRUMENT_SUBTYPE
**To get the correct button by type of integration and country, the following parameters must be specified:**
| Parameter | Description | Format
|---------------------------------------------------------------|----------------------------------------|---------
| `mid` (mandatory) | The Merchant ID is the unique merchant identifier and also defines the currency being used for a transaction. |default value of 10 digits
| `submerchant_id` (mandatory - only if any is set for the MID) | The Reporting Criteria (or submerchant id) is used to classify sub-merchants. The setup of a reporting criteria must be agreed with paysafecard. |max. value of 8 alphanumeric characters
| `country` (mandatory) | The target country. |2-digit ISO 3166-1
| `payment_instrument` (optional) | The payment instrument gives the possibility to split the logo shown between paysafecard or the gift card options. |"*paysafecard*" **or** "*giftcard*"
| `payment_instrument_subtype` (optional) | If a gift card was used for the payment instrument, the logo for each gift card option can be shown separately by defining a subtype. |"*cvspharmacy*" **or** "*dollargeneral*" **or** "*openbuckscard*"
**Below is a list of payment buttons and text options to use:**
| <center>Button configuration options | <center> Button / Text Requirements
|----------------------------------------|------------------------------------------------------
| https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=giftcard&payment_instrument_subtype=cvspharmacy |  <center>**CVS gift card**
| https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=giftcard&payment_instrument_subtype=dollargeneral |  <center>**Dollar General gift card**
| https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=giftcard&payment_instrument_subtype=openbuckscard |  <center>**oBucks gift card**
| https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=giftcard&payment_instrument_subtype=circlek |  <center>**Circle K gift card**
| https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=HK&payment_instrument=giftcard&payment_instrument_subtype=pacificcoffee |  <center>**Pacfific Coffee gift card**
| https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=paysafecard |  <center>**paysafecard**
| https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=giftcard |  <center>**gift cards**
| https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US |  <center>**Cash and gift cards**
**IMPORTANT:**
For production, change the following in the button endpoints:
https://customer.test.at.paysafecard.com to https://customer.cc.at.paysafecard.com
## Brand guidelines
When implementing the button, graphics or text, please follow each [*brand guideline*](https://www.paysafecard.com/fileadmin/Website/Dokumente/B2B/2018-paysafecard-brand-guidelines-partners.pdf)
or as indicated in the [button configurations](#button_endpoint).
<br><br>
**Examples of merchant checkout button and text variations:**
<center></center>
**IMPORTANT:**
For alternative button layouts, dimensions, file formats or text please contact your paysafecard account manager.
## Group REST Payment Process
1. The customer selects the payment method at the merchant's checkout: paysafecard or one of the gift card options (CVS, Dollar General, Circle K or oBucks)
1. The merchant initiates the payment by sending the POST request `initiate payment` using the correct *payment_instrument* and *payment_instrument_subtype*
* If the response gives back http20x, the merchant redirect the customer to the payment panel
* If the response gives back http40x or htp50x, show an error message to the customer:
"*Transaction could not be initiated due to connection problems. If the problem persists, please contact our (merchant) support.*"
1. paysafecard redirects the customer to the payment panel with `auth_url`: The customer reaches the payment panel and enters a valid paysafecard PIN, or gift card number and PIN and clicks “Pay”
* Verification on paysafecard or Openbucks side if the data entered is valid
* If the customer cancels the transaction on the payment panel, please show the following error message: "*Transaction cancelled by user*"
1. Payment notification delivery: Since the card is assigned to the transaction (transaction status "AUTHORIZED"), paysafecard sends a notification to the `notification_url`
1. `notification_url` handling: Right after the payment notification delivery, the merchant performs the GET request `retrieve payment details` to check the status of the transaction
* If the GET request `retrieve payment details` returns the status "AUTHORIZED", immediately perform the POST request `capture Payment`
* If the response to `capture payment` is http20X and the status returned is "SUCCESS", the merchant makes a user account top up accordingly or deliver the goods
1. Redirection to the `success_url`: paysafecard redirects the customer to the `success_url`
1. `success_url` handling: The merchant partner checks on the `success_url` with the GET request `retrieve payment details`, the status of the transaction
* If the GET request `retrieve payment details` return "SUCCESS“, the merchant shows a success message to the customer
* If the status is "AUTHORIZED", the merchant performs the POST request `capture Payment`
* If the response gives back http20X and the status is "SUCCESS", the merchant makes a user account top up accordingly or delivers the goods and shows a success message to the customer
* If the response gives back http40X or http50X, the merchant shows an error message to the customer
* If the response from `retrieve payment details` gives back http40X or http50X, the merchant shows an error message to the customer:
"*The transaction could not be completed. This may have happened due to a temporary connection problem. Please press the "reload" button in your browser to retry completing your transaction. If the problem persists, please contact our (merchant) support*.
## Group SOAP Payment Process
1. The customer selects the payment method at the merchant's checkout: paysafecard or one of the gift card options (CVS, Dollar General, Circle K or oBucks)
1. The merchant creates a disposition: the merchant makes the SOAP request `createDisposition` using the correct *instrument* and *instrument_subtype*
* If the result and error code is `0`, the merchant redirects the customer to the payment panel
* If the result or error code is not `0`, the merchants shows an error message to the customer:
*"Transaction could not be initiated due to connection problems. If the problem persists, please contact our (merchant) support."*
1. Redirection to the payment panel with `getCustomerPanel`: The customer reaches the payment panel and enters a valid paysafecard PIN, or gift card number and PIN and clicks “Pay”
* Verification on paysafecard or Openbucks side if the data entered is valid
* If the customer cancels the transaction on the payment panel, please show the following error message: "*Transaction cancelled by user*"
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 merchant performs the request `getSerialNumbers` to check the status of the transaction
* If `getSerialNumbers`returns the status "S", immediately perform the `executeDebit` request
* If the response to `executeDebit` is result and error code is `0`, the merchant makes a user account top up accordingly or deliver the goods
1. Redirection to the `okUrl`: paysafecard redirects the customer to the `okUrl`
1. `okUrl` handling: The merchant checks with `retrieve payment details`, the status of the transaction
* If `getSerialNumbers` returns "O", the merchant shows a success message to the customer
* If the status is "S", the merchant performs `executeDebit`
* If the result and error code is `0`, the merchant makes a user account top up accordingly or delivers the goods and shows a success message to the customer
* If the result or error code is not `0`, the merchant shows an error message to the customer
* If the response to `getSerialNumbers` result or error code is not `0` , the merchant shows an error message to the customer:
* "*The transaction could not be completed. This may have happened due to a temporary connection problem. Please press the "reload" button in your browser to retry completing your transaction. If the problem persists, please contact our (merchant)support*.
# Group Initiating a gift card payment - REST
<a name="initiate_payment"></a>
## restrictions [/payments]
The array `restrictions` containing the `payment_instrument` and `payment_instrument_subtype` gives the possibility to initiate a payment for the specific option chosen by the customer
at the merchant's checkout.
| 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*" **or** "*giftcard*"
| `payment_instrument_subtype` | String | If "giftcard" was used for the `payment_instrument` parameter, the payment can be initiated for a specific gift card option by defining a subtype. |"*cvspharmacy*" **or** "*dollargeneral*" **or** "*circlek*" **or** "*openbuckscard*"
### 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
}
```
### initiate payment request [POST]
+ Request (application/json)
+ Headers
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"
},
"amount": 1.00,
"notification_url": "https://9fc7622ff6a8995a8919be9c134d39a5.m.pipedream.net"
}
# Group Creating a gift card disposition - SOAP
The disposition restrictions (`instrument` and `instrument_subtype`) give the possibility to create a disposition for the specific option chosen by the customer at the merchant's checkout.
| 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*" **or** "*INSTRUMENT_SUBTYPE*"
| `value` | String | Value to define the available options for a certain restriction. | `INSTRUMENT`:"*paysafecard*", "*giftcard*"<br>`INSTRUMENT_SUBTYPE`: "*cvspharmacy*","*openbuckscard*", "*dollargeneral*","*circlek*"
##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>giftcard</urn:value>
</urn:dispositionRestrictions>
<urn:dispositionRestrictions>
<urn:key>instrument_subtype</urn:key>
<urn:value>openbuckscard</urn:value>
</urn:dispositionRestrictions>
</urn:createDisposition>
</soapenv:Body>
</soapenv:Envelope>
```
### New Error Code
Error code "2039" indicates that the one of the values passed in `instrument` or `instrument_subtype`, 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>
```
# Group JSON Payment notification
<a name="payment_notification"></a>
The payment notification is used to notify the merchant independently of the customer’s behavior 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:
```
{
"timestamp": 1607017210793,
"eventType": "ASSIGN_CARDS",
"version": "1",
"data": {
"mid": "1100000000",
"customer": {
"id": "kfoLkCq3RBIJiJF6sJWBeYA4tnfsCms2"
},
"payment_id": "pay_1100000000_XdyBD9FuEJVhpX3hctwJzCB8W1rEzqTo_USD",
"payment_instrument": "giftcard",
"payment_instrument_subtype":"cvspharmacy",
"card_details": [
{
"serial": "1888540789315005",
"currency": "USD",
"amount": 10,
"type": "00086",
"country": "US"
}
]
}
}
```
**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 merchant.
| `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 giftcard
| `payment_instrument_subtype` | String | The type of giftcard used. <br><br> Possible values: cvspharmacy, dollargeneral, circlek, openbuckscard
| `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 gift card payment Limits
The current **minimum** amount for gift card payments is: **0.10 USD**
The current **maximum** amount for gift card payments is: **1000.00 USD**
If a gift card payment is created for an amount smaller than 0.10 USD, the customer will see an error message in the payment panel.
# 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 chosen 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 gift card 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.