paysafecarddirectandpaysafecashrestapi-apiary.apib

FORMAT: 1A
HOST: https://distributor.test.paysafecard.com/v1

# paysafecard direct and Paysafecash REST API
![direct_paysafecash_mobile](https://www.paysafecash.com/fileadmin/5_API/direct_paysafecash_mobile.png "paysafecard direct Voucher")

This document should give business partners a clear understanding of the technical integration work that needs to be carried
out to successfully implement the paysafecard direct and Paysafecash REST API.

paysafecard direct and Paysafecash are extensions of the paysafecard Pin-On-Demand (PoD) API.

In the background a regular paysafecard PIN is created, the main difference with existing PoD sales is
that there is no exposure of the 16-digit paysafecard PIN to either the customer or the POS employee.

If any questions arise, please feel free to contact us at [*integration@paysafecard.com*]().

# Products Overview
This section provides a brief description of all products supported by the API.

## paysafecard direct
paysafecard direct is the brand name for topping up a [*my paysafecard*](https://my.paysafecard.com/mypins-psc/) account at the POS with fixed amounts. 

Here the customer generates a barcode directly using the *my paysafecard* app and the money is loaded into that same account after successful order confirmation at the POS.

The big advantage is that there is no exposure of the 16-digit paysafecard PIN to either the customer or the POS employee, thus being more secure and so higher face values are possible compared to Pin-on-Demand.

<a href="http://www.youtube.com/watch?feature=player_embedded&v=agYN-NSstJ0
" target="_blank"><img src="http://img.youtube.com/vi/agYN-NSstJ0/0.jpg" 
alt="paysafecard direct" width="240" height="180" border="10" /></a>

## Paysafecash
[Paysafecash](https://www.paysafecash.com/en-gb/) is the brand name for paying orders from e-commerce web shops at the POS with variable amounts.

Here the customer initates an order at a webshop, logs in with its Paysafecash account data and a barcode is generated for the order amount.
Upon successful order confirmation at the POS, the payment is automatically completed at the web shop.

<a href="http://www.youtube.com/watch?feature=player_embedded&v=62Rl90BYu_0
" target="_blank"><img src="http://img.youtube.com/vi/62Rl90BYu_0/0.jpg" 
alt="Paysafecash" width="240" height="180" border="10" /></a>

## Paysafecash POS cashout
Paysafecash POS cashout is a cash withdrawal solution and serves as an alternative to the physical ATM machines found worldwide.

Customers can withdraw money using the paysafecard POS network.

<br><br>

# Process Description and POS Integration
The full POS integration guideline for paysafecash can be found here: [*Distributor POS integration Guideline*](https://www.paysafecash.com/fileadmin/content/Distributor_interface_guidelines_1.0.1.pdf)

![pos_integration](https://www.paysafecash.com/fileadmin/5_API/pos_integration.jpg "POS Integration")

- The customer shows a barcode at a Point of Sale (POS)
- The POS employee scans the barcode from the customer’s mobile phone or print-out (alternatively, enters the barcode number manually)
- Scanning the barcode triggers the order to be prepared
- The product and fee model is detected automatically from the barcode
- The POS employee confirms the transaction
- The voucher product and business partner receipts are printed with all the necessary information

Alternative flow without confirmation screen: 
![pos_integration_no_confirmation](https://www.paysafecash.com/fileadmin/5_API/pos_integration_no_confirmation.jpg "POS Integration without confirmation screen")

Alternative flow with manual entry:
![pos_integration_manual_input](https://www.paysafecash.com/fileadmin/5_API/pos_integration_manual_input.jpg "POS Integration with manual entry")

# Scanning the Code 128 (Set C) Barcode
The customer will show a Code 128 barcode that needs to be scanned by the POS employee.

The barcode will be shown primarly on a mobile device (smartphone) or alternatively on a printed paper.

<br><br>
**Note**: 
- The barcode does have printed numbers underneath in case the POS is unable to scan the barcode (for manual entry)
- The text underneath is split up in sections of 3 digits with a space as separator for easy reading.

## Example Barcode and Parameters
![barcode](https://www.paysafecash.com/fileadmin/5_API/ean_13_barcode.PNG "Example Barcode")
Product identifier (EAN-13): 9120005818927

Minimum transaction reference: 15684

Check digit: 4

|Parameter                              |Description    
|---                                    |---                                                                 
|`Product identifier `                  |The Product identifier (EAN-13 or different depending on the country) is added to barcode at the start. <br></br> The paysafecard system is able to support different product identifier configurations/formats per country. <br></br> <br></br> **Note:** The full list of available product identifiers per country can be found [here](https://www.paysafecash.com/fileadmin/5_API/paysafecard_direct_and_Paysafecash_product_identifiers.pdf).
|`Transaction reference` (minimum 5)    |This is a unique 5-digit minimum randomly generated transaction reference. By providing this reference, the paysafecard system validates it and knows to which customer the transaction belongs to. <br></br> <br></br> **Note:** This parameter can be increased up to 16 digits to avoid duplicates.
|`Check digit` (1)                      |Always the last digit from the barcode. This digit is for barcode number validation at the POS.

## Check Digit Calculation
Step 1: A modulo 10 with a weight of 3 is used to calculate the check digit:

```
Digit position  |  1 |  2 |  3 |  4 |  5 |  6 |  7 |  8 |  9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17  | 18 | 19
Barcode digits  |  9 |  1 |  2 |  0 |  0 |  0 |  5 |  8 |  1 |  8 |  9 |  2 |  7 |  1 |  5 |  6 |  8  |  4 |  4
Multiply with   |  1 |  3 |  1 |  3 |  1 |  3 |  1 |  3 |  1 |  3 |  1 |  3 |  1 |  3 |  1 |  3 |  1  |  3 |  -
Result          |  9 |  3 |  2 |  0 |  0 |  0 |  5 | 24 |  1 | 24 |  9 |  6 |  7 |  3 |  5 | 18 |  8  | 12 |  -
```

Step 2: The sum of the results = 136

Step 3: The sums nearest or equal or higher multiple = 140

Step 4: The difference between this 2 numbers is the check digit: 140 - 136 = 4

## Barcode Delivery Options
![barcode_options](https://www.paysafecash.com/fileadmin/5_API/barcode_options.PNG "Example Barcode")

# Voucher Print-outs
<a name="voucher_printout"></a> Each printed voucher (via the POS terminal) must contain the following data:

|Name               |Description    
|---                |---                                                                 
|BARCODE NUMBER     |The unique barcocode generated by the customer and processed at the POS. <br/><br/>  19-30 digits, numeric (preferably in 3 x 3 blocks).   
|SERIAL NUMBER      |The unique idenfication number used for customer inquiries.<br/><br/> 16 digits, numeric (leading zeros may be cut).
|CARD TYPE          |The product identifier. <br/><br/> paysafecard direct; Paysafecash; POS cashout
|AMOUNT             |The amount of the barcode processed.
|CURRENCY           |The currency of the barcode processed.
|DATE-TIME          |Date and time-stamp of the voucher print-out at the POS (e.g. YYYY:MM:DD - HH:MM:SS).
|TERMINAL ID        |The POS identifier. Must be the value of the terminal ID provided in the request to paysafecard.

**Important:** In addition, due to legal requirements the voucher print-out must contain fixed text referencing the issuer (e.g. PSC - Prepaid Services Company Ltd.),
the applicable T & C’s and the e-mail contact for any inquiries.

It must also contain a dynamic text depending on the order status.

**Note:** Full sample texts translated in all languages will be provided by paysafecard with the test data package.

## paysafecard direct Voucher Print-out
![direct_voucher](https://www.paysafecash.com/fileadmin/5_API/direct_vouchers.PNG "paysafecard direct Voucher")

## Paysafecash Voucher Print-out
![paysafecash_voucher](https://www.paysafecash.com/fileadmin/5_API/paysafecash_vouchers.PNG "Paysafecash Voucher")

## Paysafecash POS cashout Voucher Print-out
![coming_soon](https://www.paysafecash.com/fileadmin/5_API/XXX.PNG "POS cashout Voucher")

# Integration Process Overview
The following steps need to be completed in order to integrate the API.

+ **Test Data**: paysafecard provides the test data package. This contains an API key, account details, an integration checklist, voucher texts, product identifiers list and a link to the downloads page.
+ **IP whitelisting**: The business partner provides the IP(s) used to connect to the paysafecard system, to be whitelisted.
+ **Integration in the Test Environment**: The business partner integrates the API into their test environment. Detailed information about the flows and API requests are contained below in this documentation.
+ **Integration Test**: As soon as the integration is finished in the test environment and the integration checklist fulfilled, the business partner must contact the paysafecard integration team who will test the API implementation as well as verify the voucher samples.
+ **Reconciliation Test:** paysafecard provides an example of a reconciliation file from the test system that must be processed by the business partner.
+ **Productive Data**: Once the integration test is successful, paysafecard provides the productive data. This contains a productive environment API key and account details. 
+ **Switch to Production**: The business partner switches the integration to the production environment (change API endpoints and API key).
+ **Productive Check**: An end to end test must be carried out to ensure a successful connection to the productive environment. A new voucher sample must be provided as proof of a successful integration in the productive environment.
+ **Go-live**: As soon as the productive check is successful, the technical integration is finished and a date can be set for the go-live.

# Technical Integration
This section provides a technical introduction to the paysafecard direct and Paysafecash REST API. 

## Establishing a connection
A connection to the paysafecard system is successful if the following prerequisites are fulfilled:
- X.509 certificate for request authenticity (the same certificate used in the Pin-on-Demand API applies).
- API key for request authentication (the same API Key used in the Pin-on-Demand API applies).
- Authorization of the business partner server IP address (if a 403 error is received when trying to access the service, it is likely that the IP address is not yet allowed to access).
- Content-type: Please make sure that the content type in the HTTP header, when submitting requests, is set to **Content-Type: application/json**
- Character encoding needs to be in UTF-8

Connect to our services only via respective FQDNs
Do not cache DNS resolutions of paysafecard FQDNs in your infrastructure (Client servers, Resolvers etc.). The DNS resolutions should expire as soon as the TTL is reached.
In case your application is based on Java, please check your TTL setup on JVM, the DNS caching behavior needs to be adjusted to:
networkaddress.cache.ttl=60 (TTL 60 seconds). Please note that, this parameter needs to be persisted in the JVM security config
If your application is based on any other framework that caches DNS resolution, please make sure to set the DNS TTL to no more than 60 seconds or rely on the TTL set by our DNS records

Honoring DNS changes will make sure that you connect always to our active system.

## Test Environment and Endpoints
Every new business partner needs to first integrate the Paysafecash API on the test environment.
Once the integration is finished, a UAT(User Acceptance Test) needs to be done in order to ensure a seemless integration flow.

- The endpoint for the *test environment* is: https://distributor.test.paysafecard.com/v1/
- The endpoint for the *production environment* is: https://distributor.paysafecard.com/v1/

## HTTP status codes
| Code | Short Description     | Description |
| ---  | ---                   | ---         |
| 200  | OK                    | The request was successful.|
| 201  | Created               | Object successfully created.|
| 400  | Bad Request           | Invalid data provided in the request.|
| 401  | Unauthorized          | Invalid or expired API key.|
| 404  | Not Found             | cashout feature disabled.|
| 500  | Internal Server Error | This indicates a general technical error on paysafecard's end.|
| 501  | Not Implemented       | Version feature not implemented.|
| 502  | Bad Gateway           | Invalid response from upstream system.|
| 503  | Service Unavailable   | Server overloaded.|
| 504  | Gateway Timeout       | Timeout from upstream system.|

```
   400 Bad Request

    {
    "code": "invalid_request_parameter",
    "message": "Correlation-ID is invalid: 'test123!'",
    "number": 10028,
    "param": "Correlation-ID"
    }
```

# paysafecard direct and Paysafecash Flow
![transaction_flow_direct_paysafecash](https://www.paysafecash.com/fileadmin/5_API/direct_cash_flow.PNG "direct and Paysafecash Flow")

# Paysafecash POS cashout Flow
![transaction_flow_cashout](https://www.paysafecash.com/fileadmin/5_API/cashout_flow.PNG "Paysafecash POS cashout Flow")

# Group paysafecard direct and Paysafecash Process
A paysafecard direct or Paysafecash order is processed as follows:

1. The customer brings a barcode to the POS

1. The POS employee scans or enters the barcode number
    
    2.1. The product and fee model is detected from the barcode selected automatically

1. The `prepare order` is triggered and the request is sent to the paysafecard system

1. paysafecard performs validation checks (limits, account status) and a valid response is returned (status of the order is **"PREPARED"**)

1. (*Optional*) A cancellation can be made via the `cancel order` request (status of the order is **"WITHDRAWN"**)

1. The product detected from the barcode is matched agains the product returned in the `prepare order` request to avoid barcode manipulation

1. The `confirm order` request is sent to the paysafecard system, using the `order id` from the `prepare order`

1. paysafecard performs new validation checks (limits, account status) and a valid response is returned (status of the order is **"DELIVERED"**)

1. The voucher is printed by the business partner system containing all the necessary info as shown [*here*](#voucher_printout) and handed out to the customer

1. (*Optional*) The cool-down period (5 minutes by default) starts and a cancellation can be made via the `cancel order` request (status of the order is **"CANCELLED"**)
    
    10.1 A cancellation recepit is printed by the business partner system and handed out to the customer

1. paysafecard executes the payment and notifies the customer

# Group paysafecard direct and Paysafecash API Requests
This section describes in detail all the requests available in the paysafecard direct and Paysafecash REST API.

Real API request examples can be viewed in the *Mock Server* by clicking in the requests names below.

# Preparing an order [/orders/]
The `prepare order` verifies the feasibility of the request, without causing any side effects in the system. 

This request is achieved by sending the parameter `capture` with the value "*false*".

<br>
<br>

**Note:** Using the optional HEADER-Parameter `Correlation-ID` the business partner can set a part of the parameter `id` on its own.

- Max. length: 41 characters
- Allowed characters: "a-z, A-Z, 0-9,-,_"
- The value passed in this parameter must always be unique

## prepare order [POST]

```
POST /orders/
```

+ Parameters

    + `Correlation-ID`: `test_corr_001` (required) - Using the HEADER-Parameter `Correlation-ID`, the business partner can set part of the parameter `id` on its own. <br></br><br></br> - Max. length: 41 characters <br></br> - Allowed characters: "a-z, A-Z, 0-9,-,_" <br></br> - The value passed in this parameter must always be unique

+ Request (application/json)

    + Headers

               Authorization: Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=

    + Attributes (prepare order)
    

+ Response 201 (application/json)
            
        {
        "amount": 10,
        "currency": "EUR",
        "distributor_id": "0009402006",
        "order_id": "order_0009402006_test_corr_001",
        "product_id": "MERCHANT_DIRECT_LOAD"
        }


# Confirming an order [/orders/{id}/capture]
Upon a successful response to the `prepare order`request, a `confirm order` request must be called. And as the names implies, this request will effectively execute the transaction.

<br>

**Important**:
- A `confirm order` request can only be called upon a previously successful `prepare order` request

- Only successfuly confirmed transactions appear in the reconciliation file

- There is no time frame between the `prepare order` and `confirm order` requests

## confirm order [POST]

```
POST /orders/id/capture
```

+ Parameters

    + id: `order_0009402006_test_corr_001` (required) - Id of a successful `prepare order` request
    + `Correlation-ID`: `test_corr_001` (required) - The `Correlation-ID` header can be used instead of the *order id* in the uri. 
    
+ Request (application/json)

    + Headers

               Authorization: Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=
               

+ Response 200 (application/json)
            
        {
        "amount": 10,
        "currency": "EUR",
        "card": {
            "amount": 10,
            "currency": "EUR",
            "serial": 1850470751,
            "product_id": "MERCHANT_DIRECT_LOAD"
        },
        "product_id": "MERCHANT_DIRECT_LOAD",
        "distributor_id": "0009402006",
        "order_id": "order_0009402006_test_corr_001"
        }

# Cancelling an order [/orders/{id}/]
The `cancel order` request is used to undo a previous order. The amount associated with the order will be invalidated and the customer will not be able to use it.

<br><br>
A `cancel order` request is successful if:
- The cool-down period has not elapsed (i.e, the order status is "PREPARED" or "DELIVERED")

<br>
### Cool-down period
During the cool-down period the amount associated with the order is temporarily frozen (meaning that the customer cannot spend the amount or the order is yet to be completed), 
guaranteeing a successful cancellation upon the `cancel order` request.

When the cool-down period of 5 minutes (by default) elapses, the cancellation might fail since the customer might already have used the amount associated with the order.

<br><br>
**Important:** 
- The implementation of this request is mandatory to undo a previous order in case the customer cannot pay for the transaction at the POS
- A successful cancellation will not appear on the invoice to the distributor but will appear in the daily reconciliation file


## cancel order [DELETE]

```
DELETE /orders/id/
```

+ Parameters

    + id: `order_test_corr_001` (required) - Id of a successful `confirm order` request
    + `Correlation-ID`: `test_corr_001` (required) - The `Correlation-ID` header can be used instead of the *order id* in the uri.  
    
+ Request (application/json)

    + Headers

               Authorization: Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=
    

+ Response 200 (application/json)
            
        {
        "distributor_id": "0009402006",
        "order_id": "order_0009402006_test_corr_001"
        }
        
# Retrieving an order [/orders/{id}]
The `retrieve order` request is used to retrieve the status and information of an order.

This request can be done at any time by the business partner.

### Order Status

|Value          |Description    |
|---            |---                                                                 |
|`PREPARED`     |The order has been successfully prepared.|
|`DELIVERED`    |The order has been successfully confirmed.|
|`REJECTED`     |The order has failed due to a business or technical error.|
|`WITHDRAWN`    |The prepared order has been successfully cancelled.|
|`CANCELLED`    |The confirmed order has been successfully cancelled.|

## retrieve order [GET]
```
GET /orders/id/
```

+ Parameters

    + id: `order_0009402006_test_corr_001` (required) - An order `id`
    + `Correlation-ID`: `test_corr_001` (required) - The `Correlation-ID` header can be used instead of the *order id* in the uri.  
    
+ Request (application/json)

    + Headers

               Authorization: Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=
    

+ Response 201 (application/json)
            
        {
        "amount": 10,
        "currency": "EUR",
        "card": {
            "amount": 10,
            "currency": "EUR",
            "serial": 1850423010,
            "product_id": "00028"
        },
        "distributor_id": "0009402006",
        "order_id": "order_0009402006_test_corr_001",
        "product_id": "00028",
        "shop_id": "shopdid_test",
        "terminal_id": "test_terminal_123",
        "order_status": "DELIVERED",
        "delivery_type": "RETURN"
        }

# Group paysafecard direct and Paysafecash API Response Objects
Below, all possible response objects for the paysafecard direct and Paysafecash REST API are listed with the corresponding description.

|Parameter|Description|Requests|
|---|---|---|
|`amount`|The order amount.|`prepare order` `confirm order` `retrieve order`|
|`currency`|The order currency.|`prepare order` `confirm order` `retrieve order`|
|`card[amount]`|The face value of the card assigned to the order.|`confirm order` `retrieve order`|
|`card[currency]`|The currency (ISO 4217) of the order.|`confirm order` `retrieve order`|
|`card[serial]`|The serial number of the card assigned to the order.|`confirm order` `retrieve order`|
|`card[product_id]`|The product id of the card assigned to the order.|`confirm order` `retrieve order`|
|`distributor_id`|The business partner ID assigned by paysafecard.|`prepare order` `confirm order` `retrieve order` `cancel order`|
|`order_id`|Identifies the order. It is generated by the API or taken from the `Correlation-ID` header.|`prepare order` `confirm order` `retrieve order` `cancel order`|
|`shop_id`|Identifies the shop from where the request was made. |`retrieve order`|
|`terminal_id`|Identifies the terminal from where the request was made.|`retrieve order`|
|`order_status`|The status of the order (`PREPARED`, `DELIVERED`, `REJECTED`, `WITHDRAWN` or `CANCELLED`).|`retrieve order`|
|`delivery_type`|To which channel was the order be delivered. For paysafecard direct and Paysafecash the value is always "ACCOUNT".|`retrieve order`|

# Group paysafecard direct and Paysafecash Error Codes
Below, all possible error codes for the paysafecard direct and Paysafecash REST API are listed with the corresponding description.

|Code|Number|Message|
|---|---|---|
|`general_technical_error`                              |10007|General technical error
|`invalid_api_key`                                      |10008|Authentication failed
|`certificate_not_valid`                                |33003|Certificate is not valid
|`duplicate_correlation_id`                             |2001 |Correlation-ID Header must be unique
|`not_available`                                        |3100 |Product not available
|`account_not_found_for_mobile`                         |3036 |No valid Account found with '{0}'='{1}'
|`transaction_limit_reached`                            |3044|With this topup your balance would be higher than your remaining spending limit.
|`topup_limit_reached_sdd_with_amount_upgrade_possible` |3047|Topup limit for user exceeded ! Kyc level: 'Simple'. Limit Type: 'TOP_UP_TOTAL'!
|`topup_limit_reached_sdd_upgrade_useless`              |3049|Maximum balance for the user exceeded
|`transaction_limit_reached_sdd_upgrade_possible`       |3052|With this topup your balance would be higher than your remaining spending limit.
|`order_not_found`                                      |3102 |Order not found
|`product_not_allowed`                                  |3105 |Product not allowed
|`credit_limit_reached`                                 |3144 |Credit limit reached
|`invalid_currency_distributor`                         |3151 |Invalid currency
|`cancel_order_already_processed`                       |3154 |Cancel order already processed
|`cancel_order_too_late`                                |3158 |Cancel order too late
|`order_state_not_valid_for_confirmation`               |3173 |Order is in a state where it cannot be confirmed
|`terminal_limit_1_exceeded`                            |3174 |Terminal limit 1 exceeded
|`terminal_limit_2_exceeded`                            |3175 |Terminal limit 2 exceeded
|`terminal_limit_3_exceeded`                            |3176 |Terminal limit 3 exceeded
|`terminal_limit_4_exceeded`                            |3177 |Terminal limit 4 exceeded
|`terminal_limit_5_exceeded`                            |3178 |Terminal limit 5 exceeded
|`shop_limit_1_exceeded`                                |3188 |Shop limit 1 exceeded
|`shop_limit_2_exceeded`                                |3189 |Shop limit 2 exceeded
|`shop_limit_3_exceeded`                                |3190 |Shop limit 3 exceeded
|`shop_limit_4_exceeded`                                |3191 |Shop limit 4 exceeded
|`shop_limit_5_exceeded`                                |3192 |Shop limit 5 exceeded
|`fdd_limit_reached`                                    |3202 |FDD terminal limit reached
|`directload_request_not_found`                         |3251|Barcode not found
|`directload_request_expired`                           |3252 |Barcode is expired
|`directload_request_used`                              |3253|Barcode is already used
|`directload_request_invalidated`                       |3254|Barcode is invalidated
|`directload_product_identifier_invalid`                |3255|Product identifier is invalid

|Code|Number|Message|Param
|---|---|---|---
|`invalid_request_param`    |10028|Valid values are: ACCOUNT,PHONE,ATM,NONE,CIVIL_NUMBER            |`id_type`
|`invalid_request_param`    |10028|size must be between 5 and 5                                     |`product_id`
|`invalid_request_param`    |10028|Correlation-ID is invalid: 'xxxxxx%!'                            |`Correlation-ID`
|`invalid_request_param`    |10028|Correlation-ID is longer than the maximum allowed 41 characters  |`Correlation-ID`

Other errors can be communicated to the customer as “general technical error”. 

In general when one of these errors occur, the business partner should contact paysafecard for more information via [*integration@paysafecard.com*]() if the account is not live.

For live accounts, [*techsupport@paysafecard.com*]() should be contacted.

# Group Paysafecash POS cashout Process
A Paysafecash POS cashout order is processed as follows:

1. The customer brings a barcode to the POS

1. The POS employee scans or enters the barcode number
    
    2.1. The product and fee model is detected from the barcode selected automatically

1. The `prepare order` is triggered and the request is sent to the paysafecard system

1. paysafecard performs validation checks (limits, account status) and a valid response is returned (status of the order is **"PREPARED"**)

1. (*Optional*) A cancellation can be made via the `cancel order` request (status of the order is **"WITHDRAWN"**)

1. The product detected from the barcode is matched agains the product returned in the `prepare order` request to avoid barcode manipulation

1. The `confirm order` request is sent to the paysafecard system, using the `order id` from the `prepare order`

1. paysafecard performs new validation checks (limits, account status) and a valid response is returned (status of the order is **"DELIVERED"**)

1. The voucher is printed by the business partner system containing all the necessary info as shown [*here*](#voucher_printout) and handed out to the customer togehter with the correct order amount in cash

1. (*Optional*) The cool-down period (5 minutes by default) starts and a cancellation can be made via the `cancel order` request (status of the order is **"CANCELLED"**)
    
    10.1 A cancellation recepit is printed by the business partner system and handed out to the customer

# Group Paysafecash POS cashout API Requests
This section describes in detail all the requests available in the Paysafecash POS cashout REST API.

Real API request examples can be viewed in the *Mock Server* by clicking in the requests names below.

# Preparing an order [/cashouts/]
The `prepare order` verifies the feasibility of the request, without causing any side effects in the system. 

<br>
<br>

**Note:** Using the optional HEADER-Parameter `Correlation-ID` the business partner can set a part of the parameter `id` on its own.

- Max. length: 41 characters
- Allowed characters: "a-z, A-Z, 0-9,-,_"

## prepare order [POST]

```
POST /cashouts/
```

+ Parameters

    + `Correlation-ID`: `test_corr_001` (required) - Using the HEADER-Parameter `Correlation-ID`, the business partner can set part of the parameter `id` on its own. <br></br><br></br> - Max. length: 41 characters <br></br> - Allowed characters: "a-z, A-Z, 0-9,-,_" <br></br> - The value passed in this parameter must always be unique

+ Request (application/json)

    + Headers

               Authorization: Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=

    + Attributes (prepare cashout order)
    

+ Response 201 (application/json)

           {
            "amount": 9.99,
            "currency": "EUR",
            "distributor_id": "0009301013",
            "order_id": "order_0009301013_test_corr_001",
            "product_id": "MERCHANT_DIRECT_LOAD_CASHOUT"
            }

# Confirming an order [/cashouts/{id}/capture]
Upon a successful response to the `prepare order`request, a `confirm order` request must be called. 
And as the names implies, this request will effectively execute the transaction.

<br>

**Important**:
- A `confirm order` request can only be called upon a previously successful `prepare order` request

- Only successfuly confirmed transactions appear in the reconciliation file

- There is no time frame between the `prepare order` and `confirm order` requests

## confirm order [POST]

```
POST /cashouts/id/capture
```

+ Parameters

    + id: `order_0009301013_test_corr_001` (required) - Id of a successful `prepare order` request
    + `Correlation-ID`: `test_corr_001` (required) - The `Correlation-ID` header can be used instead of the *order id* in the uri.  
    
+ Request (application/json)

    + Headers

               Authorization: Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=


+ Response 201 (application/json)

        {
        "amount": 9.99,
        "currency": "EUR",
        "card": {
            "amount": 9.99,
            "currency": "EUR",
            "serial": 1850692086,
            "product_id": "MERCHANT_DIRECT_LOAD_CASHOUT"
        },
        "distributor_id": "0009301013",
        "order_id": "order_0009301013_test_corr_001"
        }

# Cancelling an order [/cashouts/{id}/]
The `cancel order` request is used to undo a previous order. 

<br><br>
A `cancel order` request is successful if:
- The cool-down period has not elapsed (i.e, the order status is "PREPARED" or "DELIVERED")

<br>
### Cool-down period
During the cool-down period the amount associated with the order is temporarily frozen (meaning that the customer cannot spend the amount or the order is yet to be completed), 
guaranteeing a successful cancellation upon the `cancel order` request.

When the cool-down period of 5 minutes (by default) elapses, the cancellation might fail since the customer might already have used the amount associated with the order.

<br><br>
**Important:** 
- The implementation of this request is mandatory to undo a previous order in case there is not enough money at the POS deliverable to the customer
- A successful cancellation will not appear on the invoice to the distributor but will appear in the daily reconciliation file

## cancel order [DELETE]

```
DELETE /cashouts/id/
```

+ Parameters

    + id: `order_0009301013_test_corr_001` (required) - Id of a successful `confirm order` request
    + `Correlation-ID`: `test_corr_001` (required) - The `Correlation-ID` header can be used instead of the *order id* in the uri.  
    
+ Request (application/json)

    + Headers

               Authorization: Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=
    

+ Response 200 (application/json)

        {
        "distributor_id": "0009301013",
        "order_id": "order_0009301013_test_corr_001"
        }

# Retrieving an order [/cashouts/{id}]
The `retrieve order` request is used to retrieve the status and information of an order.

This request can be done at any time by the business partner.

### Order Status

|Value          |Description    |
|---            |---                                                                 |
|`PREPARED`     |The order has been successfully prepared.|
|`DELIVERED`    |The order has been successfully confirmed.|
|`REJECTED`     |The order has failed due to a business or technical error.|
|`WITHDRAWN`    |The prepared order has been successfully cancelled.|
|`CANCELLED`    |The confirmed order has been successfully cancelled.|
|`EXPIRED`      |The prepared order has expired.|

## retrieve order [GET]
```
GET /cashouts/id/
```

+ Parameters

    + id: `order_0009301013_test_corr_001` (required) - An order `id`
    + `Correlation-ID`: `test_corr_001` (required) - The `Correlation-ID` header can be used instead of the *order id* in the uri.  
    
+ Request (application/json)

    + Headers

               Authorization: Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=
    

+ Response 201 (application/json)

        {
        "amount": 9.99,
        "currency": "EUR",
        "card": {
            "amount": 9.99,
            "currency": "EUR",
            "serial": 1850692086,
            "product_id": "00002"
        },
        "distributor_id": "0009301013",
        "order_id": "order_0009301013_test_corr_001",
        "product_id": "00002",
        "shop_id": "shopdid123",
        "terminal_id": "terminalid123",
        "order_status": "CANCELLED",
        "delivery_type": "ACCOUNT"
        }

# Group Paysafecash POS cashout API Response Objects
Below, all possible response objects for the Paysafecash POS cashout API are listed with the corresponding description.

|Parameter|Description|Requests|
|---|---|---|
|`amount`           |The order amount.  |`prepare order` `confirm order` `retrieve order`|
|`currency`         |The order currency.|`prepare order` `confirm order` `retrieve order`|
|`card[amount]`     |The face value of the card assigned to the order.|`confirm order` `retrieve order`|
|`card[currency]`   |The currency (ISO 4217) of the order.|`confirm order` `retrieve order`|
|`card[serial]`     |The serial number of the card assigned to the order.|`confirm order` `retrieve order`|
|`card[product_id]` |The product id of the card assigned to the order.|`confirm order` `retrieve order`|
|`distributor_id`   |The business partner ID assigned by paysafecard.|`prepare order` `confirm order` `retrieve order` `cancel order`|
|`order_id`         |Identifies the order. It is generated by the API or taken from the `Correlation-ID` header.|`retrieve order` `cancel order`|
|`shop_id`          |Identifies the shop from where the request was made.|`retrieve order` |
|`terminal_id`      |Identifies the terminal from where the request was made.|`retrieve order` |
|`order_status`     |The status of the order (`PREPARED`, `DELIVERED`, `REJECTED`, `WITHDRAWN`, `CANCELLED` or `EXPIRED`).|`retrieve order` |
|`delivery_type`    |To which channel was the order be delivered. For Paysafecash the value is always "ACCOUNT".|`retrieve order` |

# Group Paysafecash POS cashout Error Codes
Below, all possible error codes for the Paysafecash POS cashout API are listed with the corresponding description.

Coming soon.

# Group How to handle a lost response
In case the business partner does not get a response back to a `prepare order` or `confirm order` request, a lost response mechanism
shall be put in place to avoid order mismatches between the business partners system and paysafecard.

The below diagram show thes recommended implementation for the the lost response scenario.
![lost_response_flow](https://www.paysafecash.com/fileadmin/5_API/last_response.png "How to handle a lost response")

**Note:** It is crucial that the *Correlation-ID* is used, so the `cancel order` can be made using the correct *order id*.

# Group Customer Limits
Fully verified paysafecard customers with an account status FDD (Full due diligence) will not be affected by existing [*Pin-on-Demand terminal limits*](https://www.paysafecard.com/fileadmin/api/pin-on-demand.html#/reference/fraud-prevention-and-limits).
A new terminal limit is introduced for these customers.

This limit configuration is set to 2500€ for 12 hours (or equal value in other currencies).
If the limit is reached, the PoD system will return the error code:
```
{
    "code": "fdd_terminal_limit_reached",
    "message": "FDD terminal limit reached",
    "number": 3202
}
```

# Group Reconciliation / Sales Reporting 
paysafecard direct and Paysafecash orders are visible in the daily Pin-on-Demand reconciliation file
and can be distinguished by the 9th (Customer identification type) and 10th (delivery type) parameter.

|Value                              |Description    
|---                                |---                                                                 
|`Customer identification type`     |For the issuing of classic vouchers the value “NONE” is used, referring to the fact that the customer was not identified (anonymous). <br></br><br></br> In the case of paysafecard direct and Paysafecash, the value “ACCOUNT” is used, indicating that the end customer is identified (registered).
|`Delivery type`                    |For the issuing of classic vouchers the value “RETURN” is used, referring to the fact that the 16 digit PIN was delivered to the end customer. <br></br><br></br> In the case of paysafecard direct and Paysafecash, the value “ACCOUNT” is used, indicating that the PIN was delivered directly into the customer’s account.


```
| Distributor order id 
| |     Utc offset 
| |     |   Order date and time 
| |     |   |                   Distributor id 
| |     |   |                   |          Retailer id 
| |     |   |                   |          |   Shop id
| |     |   |                   |          |   |   Terminal id 
| |     |   |                   |          |   |   |   Customer identification type 
| |     |   |                   |          |   |   |   |       Delivery type 
| |     |   |                   |          |   |   |   |       |       Country code
| |     |   |                   |          |   |   |   |       |       |  Face value  
| |     |   |                   |          |   |   |   |       |       |  |     Product id 
| |     |   |                   |          |   |   |   |       |       |  |     |   Serial 
| |     |   |                   |          |   |   |   |       |       |  |     |   |                Order status 
| |     |   |                   |          |   |   |   |       |       |  |     |   |                |         Error code 
| |     |   |                   |          |   |   |   |       |       |  |     |   |                |         |          
D;93837;-60;2011-10-12 22:25:23;0000006938;304;506;309;ACCOUNT;ACCOUNT;DE;10.00;304;6954286854268596;DELIVERED;0
```

# Data Structures

## TypedObject (object)

## prepare order (TypedObject)
+ amount: 0.00 (number, required) - The request amount. 
The amount is ignored for the `prepare order` request, as this value is taken directly from the barcode.
+ currency: EUR (required) - ISO 4217 (3 letter ISO currency code).
+ country: AT (required) - The code (ISO 3166-1) that identifies the country of the request.
The country code is provided with the data package.
+ product_id: 00028 (required) - The id of the product that is requested.
Available product id’s can be found in the distribution contract with paysafecard and in the data package. 
+ delivery_type: ACCOUNT (string, required) - To which channel should the order be delivered. 
For paysafecard direct and Paysafecash, the value "ACCOUNT" must always be used.
+ utc_offset: +00:00 (string, required) - The difference between the distributor time zone and UTC.
+ shop_id: shopidtest (string, required ) - Identifies the shop from where the request is made. 
Provided by the business partner.
+ terminal_id: terminalidtest (string, required) - Identifies the terminal from where the request is made. One shop can have multiple terminals.
**Important:** It is required that each terminal has a unique id. Provided by the business partner.
+ retailer_id: retaileridtest (string, optional) - Can be used to distinguish retail channels. One distributor can have multiple retailers. 
Can also be used to identify sub-distributors. Provided by the business partner.
+ customer (object) 
    + `id_type`: ACCOUNT (string, required) - The customer identification type.
    For paysafecard direct and Paysafecash, the value "ACCOUNT" must always used.
    + `id`: 91200058124751281268 (number, required) - The barcode number.
+ capture: false (boolean, required) - Capture flag.
For the `prepare order`, the value "false" must always used.

## prepare cashout order (TypedObject)
+ amount: 0.00 (number, required) - The request amount. 
The amount is ignored for the `prepare order` request, as this value is taken directly from the barcode.
+ currency: EUR (required) - ISO 4217 (3 letter ISO currency code).
+ country: AT (required) - The code (ISO 3166-1) that identifies the country of the request.
+ shop_id: shopidtest (string, required ) - Identifies the shop from where the request is made. 
Provided by the business partner.
+ terminal_id: terminalidtest (string, required) - Identifies the terminal from where the request is made. One shop can have multiple terminals.
**Important:** It is required that each terminal has a unique id. Provided by the business partner.
+ retailer_id: retaileridtest (string, optional) - Can be used to distinguish retail channels. One distributor can have multiple retailers. 
Can also be used to identify sub-distributors. Provided by the business partner.
+ utc_offset: +00:00 (string, required) - The difference between the distributor time zone and UTC.
+ barcode: 91200058124751281268 (number, required) - The barcode number.