forked from paysafecard/api-documentation
-
Notifications
You must be signed in to change notification settings - Fork 59
/
Copy pathpaysafecardpagoefectivo-apiary.apib
310 lines (235 loc) · 17.7 KB
/
paysafecardpagoefectivo-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
FORMAT: 1A
HOST: https://apitest.paysafecard.com/v1
# paysafecard PagoEfectivo integration
PagoEfectivo is a market leader in the provision of eCash and open banking solutions in Latin America.
This documentation explains how to start accepting <a href="https://www.youtube.com/watch?v=N1NJabZgUKQ">PagoEfectivo</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 PagoEfectivo, the business partner must contact the account manager directly or at [*[email protected]*]().
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).
## Group Payment flow
### On an existing paysafecard MID
1. The customer selects paysafecard 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 PagoEfectivo payment option on the payment panel
5. The customer selects PagoEfectivo and is redirected to the PagoEfectivo payment page
6. The customer receives a PagoEfectivo CIP code and pays for it with one of the available payment methods
7. paysafecard sends a notification to the notification URL once the payment is complete
8. The business partner captures the payment
### On a new MID where only PagoEfectivo is activated
1. The customer selects PagoEfectivo 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 PagoEfectivo hosted payment page
4. The customer receives a PagoEfectivo CIP code and pays for it with one of the available payment methods
5. paysafecard sends a notification to the notification URL once the payment is complete
6. The business partner captures the payment
# Group Technical changes
<a name="technical_changes"></a>
1. The logo must be changed accordingly at the checkout page
2. (Optional) The payment must be created accordingly to the choice of the customer at the checkout page. The REST integration supports the usage of choosing the Payment Method during the Payment request. See section [Initiating a PagoEfectivo Payment - REST](#restrictions)
3. (Optional) Integrating the payment notification payload in JSON
* The [JSON payment notification](#payment_notification) enables the business partner to distinguish which payment instrument was used for the transaction.
## Group Payment process - Diagram
## Group Payment process - REST
1. The customer selects the payment method at the business partner checkout page: paysafecard and/or PagoEfectivo
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 or the PagoEfectivo panel
* 3.1. The customer selects PagoEfectivo on the paysafecard payment panel
* 3.2. The customer is redirected to the PagoEfectivo hosted payment page
1. The customer receives a CIP code
* 4.1. The customer has to go to a Point of Collection or pay for the CIP code with one of the available payment options
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
## Group Payment Process - SOAP
1. The customer selects the payment method at the business partner checkout page: paysafecard or PagoEfectivo
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 or the PagoEfectivo panel
* 3.1. The customer selects PagoEfectivo on the paysafecard payment panel
* 3.2. The customer is redirected to the PagoEfectivo hosted payment page
1. The customer receives a CIP code
* 4.1. The customer has to go to a Point of Collection or pay for the CIP 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
# Group Initiating a PagoEfectivo Payment - REST
<a name="initiate_payment"></a>
## restrictions [/payments]
<a name="restrictions"></a>
The array `restrictions` containing the `payment_instrument` parameter 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`, `pagoefectivo`
### 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
}
```
<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"
},
"amount": 1.00,
"notification_url": "https://9fc7622ff6a8995a8919be9c134d39a5.m.pipedream.net"
}
# Group Creating a PagoEfectivo Disposition - SOAP
The disposition restriction `instrument` gives 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`
| `value` | String | Value to define the available options for a certain restriction. |`paysafecard`, `pagoefectivo`
<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>pagoefectivo</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>
```
# 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 body:
```
{
"timestamp": 1607017210793,
"eventType": "ASSIGN_CARDS",
"version": "1",
"data": {
"mid": "1100000000",
"customer": {
"id": "kfoLkCq3RBIJiJF6sJWBeYA4tnfsCms2"
},
"payment_id": "pay_1100000000_XdyBD9FuEJVhpX3hctwJzCB8W1rEzqTo_USD",
"payment_instrument": "pagoefectivo",
"card_details": [
{
"serial": "1420271325",
"currency": "PEN",
"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 giftcard or pagoefectivo
| `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.
| `channelType` | Array | Channel Type that identifies how the CIP was paid. <br><br> Possible values: Online or Cash
<!--!
# Group Alternative Payment Flows
-->
# 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.