paysafecash-apiary.apib

FORMAT: 1A
HOST: https://apitest.paysafecard.com/v1

# Integrating the Paysafecash REST API
[Paysafecash](https://www.paysafecash.com/en-gb/) is an alternative cash-based payment method that makes it possible to pay securely and easily with cash on the Internet.
Using Paysafecash, products or services can be ordered online and then paid for with cash offline at the nearest payment point by scanning a QR/barcode. 

More information can be found at https://www.paysafecash.com/business.

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

# Integration Process Overview

The following provides the necessary steps that need to be completed in order to integrate Paysafecash in a webshop.

+ **Test Data**: paysafecard provides the test data package. This contains an API key (technical authentication), information of the merchant account, the link to this documentation, a link to the logo and to the sample codes.
+ **Integration in Test Environment**: The webshop needs to integrate Paysafecash into their test system. For this, the sample codes might be used. Detailed information on the payment flow and the API calls are contained below in this documentation.
+ **Integration Test**: As soon as the integration is completed on the test environment, the webshop needs to provide a URL and 2 test users to paysafecard, so the technical support team can test the integration (technical payment flow and brand assurance)
+ **Productive Data**: If the test is finished successfully, paysafecard provides the productive data (API key)
+ **Switch Integration to Production**: The webshop needs to switch the Paysafecash integration to the production system (change API endpoints and the API key)
+ **IP whitelisting**: The webshop needs to provide their IPs, so paysafecard can whitelist them on their system
+ **Final Check**: When this setup is done, the webshop needs to provide a URL and 2 test users to paysafecard. The technical support team will then process a real money End-to-End test
+ **Go-Live**: As soon as this last test is completed successfully, the integration is finished and can be used for customers

# Technical introduction
This section provides a technical introduction of Paysafecash. Paysafecash is based on the paysafecard REST API.

## About the API
The paysafecard REST API follows <a href="http://en.wikipedia.org/wiki/Representational_state_transfer" target="_blank">*RESTful*</a> design principles making it easy to understand and integrate the API.
Representational State Transfer (REST) is a software architecture style, consisting of guidelines for creating scalable web services.
RESTful systems typically communicate over the Hypertext Transfer Protocol with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) used by web browsers to retrieve web pages and send data to remote servers.
It facilitates solid and universally accepted foundations like [*http basic authentication*](http://en.wikipedia.org/wiki/Basic_access_authentication), [*http verbs*](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods), [*JSON*](http://en.wikipedia.org/wiki/JSON) and [*CORS*](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing).

## Versioning
Every time there is backwards-incompatible change to the API, a new major version will be released. This major version is part of the URL path.
The current major version is *v1*. Unless informed by our technical support department that we are dropping support for a particular API version, you do not need to switch API versions.

## Prerequisites
You can only connect to the Paysafecash system if the following prerequisites are fulfilled:
- API key for request authentification provided by paysafecard.
- Authorisation of the payment 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.

## API key authentication
Every request to the paysafecard API is authenticated using an API key.
- The value of the **API key needs to be base64 encoded** when transmitted in the HTTP header!
- Set the key as the username. [*HTTP basic authentication*](http://en.wikipedia.org/wiki/Basic_access_authentication)
- Your API key may only be used from your backend systems.
- *Please note: Your API key must be kept secured - never expose the API key to anybody!*

Below is an example of how the API key is supposed to be set.

```
Authorization: Basic cHNjX0R4dThqSnI1LVdPYXhLWnpjOXdyMUtNLXd1Y3dZMXg=
```

## Test Environment and Endpoints

- paysafecard provides the ‘Paysafecash test system’, a test environment for integration of new business partners. 
    Every new business partner needs to integrate the payment platform first on the test system.
    Once the integration on your system is finished a UAT(UserAcceptanceTest) needs to be done in order to ensure a seemless integration flow.


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


| Hostname  | IP address  |
|---|---|
| https://apitest.paysafecard.com/v1/   | 13.248.157.194 <br> 76.223.29.211  |

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

| Hostname  | IP address  |
|---|---|
| https://api.paysafecard.com/v1/  | 75.2.1.208<br>99.83.185.216 |


## Interface Guidelines
Paysafecash must be implemented accordingly to the interface guidelines MSC (downloadable from https://www.paysafecash.com/business/downloads) and the instructions in this technical integration document.

## Barcode Application Details
Paysafecash customers are, by default, redirected to the hosted barcode application from paysafecard, where they login to get a barcode. With this barcode, they can complete the transaction at a point of sales. 

Please make sure that the hosted payment page size is correctly set in your webshop.
<br></br>
<br></br>
**Integration on desktop devices:** The Paysafecash barcode application should be displayed as a redirect in the same window, on a new browser tab or a new browser window.
Always allow vertical scrolling or dynamic sizing.

**Integration on mobile devices:** The Paysafecash barcode application is optimized automatically for mobile devices.

# Group Payment Process
This section describes in detail the technical process for Paysafecash payments.  

1. The customer selects the payment method Paysafecash.

1. Initiate Payment: Send POST request`initiate Payment`.
    * 2.1. If the response gives back http20x, redirect the customer to the payment panel (status of the transaction is "INITIATED").
    * 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 barcode application`auth_url`: The customer reaches the barcode application and logs in with its account (status of the transaction is "REDIRECTED").

1. Login(by customer): The customer logs in to retrieve the barcode
    * 4.1. If the customer cancels the transaction on the payment panel, please show the following error message: "Transaction aborted by user" on your failureURL (status of the transaction is "CANCELED_CUSTOMER")
    * 4.2. If the customer clicks on "Back to Webshop":
        * 4.2.1. If the transaction is in status "REDIRECTED", please show following message to the customer: Thank you, please go to the Point of Sales and pay the transaction
        * 4.2.2. If the transaction is in status "SUCCESS", please show following message to the customer: Thank you for your transaction
        * 4.2.2. If the transaction is in status "EXPIRED", please show following message to the customer: Unfortunately, your payment failed. Please try again

1. Customer goes to Point of Sales and pays the transaction with cash

1. Payment notification delivery: Since the transaction is paid, the amount assigned to the transaction(transaction status "AUTHORIZED"), we send a notification to your`notification_url`.

1. `notification_url` handling: You perform the GET request`Retrieve payment details`to check the state of the transaction.
    * 7.1. If the GET request `retrieve payment details` gets back the according status "AUTHORIZED", perform the POST request `capture Payment`. 
        * 7.2. If the response of`capture payment`is http20X and the status is "SUCCESS", make a user account top up.

1. As soon capture payment was successful, the transaction is completed (status of the transaction changes to "SUCCESS"). Mark it in your system as finished and ship the purchase

# Group Payment Information

The following section provides additional information about the payment process:

## Payment status

|Value          |Description    |
|---            |---                                                                 |
|`INITIATED`      |The initial state of a payment after it has been successfully created.    |
|`REDIRECTED`       |The customer has reached the barcode panel and logged in with its account.|
|`AUTHORIZED`|The customer has paid the transaction amount at a point of sales.|
|`SUCCESS`|The payment has been completed successfully.|
|`CANCELED_CUSTOMER`|The customer has cancelled the payment.|
|`EXPIRED`|The customer has not logged in to the barcode application in 30 minutes after the transaction has been created, the customer has not paid the transaction in the predefined time frame (default 72 hours) or you, the business partner, have not captured the authorized amount during the disposition time window.|

## HTTP status codes
| Code | Short Description     | Description |
| ---  | ---                   | ---         |
| 200  | OK                    | Everything is OK.|
| 201  | Created               | New object was successfully created.|
| 400  | Bad Request           | Missing parameter.|
| 401  | Unauthorized          | Invalid or expired API key.|
| 404  | Not Found             | Not found. This is also returned when you try to retrieve a payment that does not exist.|
| 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.|

*Below is an example of an error response:*

```
   400 Bad Request

   {
      "code": "invalid_request_parameter"
      "message": ""must contain 1-10 digits, followed by a decimal separator '.' followed by 2 digits",
      "number": 10028,
      "param": "amount"
   }
   
```

<br><br/>

## Customer ID
Also known as "Merchant Client ID", the customer ID is an important parameter for the integration of Paysafecash.

The Customer ID identifies the Customer on our business partners side. 

The most optimal customer ID is a completely random value. A value that uniquely identifies the customer and is disconnected from any personal information. 

This customer ID value should be the same for all transactions of the customer.

Here are Guidelines for possible Customer IDs: 
<br><br/>

**Valid Values:**
|Value |Type 
|--- |---
`2c3be0b50c7a5f1964a63d78f38a6ffc41c027e9` |SHA1 - test@123.com
`742f2b1a55cd5d606ea44b4fcb54646a` | MD5 - test@123.com
`3a5b0d0777dead9df93d502df85c8180e53804eb`|SHA1 - UsernameValue1
`3192481752123`| Random Customer Identifier
`CustomerID1`| Customer Identifier free of personal information

**Invalid Values:**
+ `test@123.com`
+ `Username_1`
+ `FirstName123`
+ `LastName123`
+ `Timestamp`
+ `IP Address`


Please note that sending any form of the invalid values will not be accepted. 

If you intend to process payments on multiple brands, please inquire about the possibilities of separating multiple entities for your account.

<br><br/>

## Disposition time window
Once a payment is in the state `AUTHORIZED`, you have to capture the customer's payment within a certain time period (disposition time).
The disposition time window is configurable per MID.
If this time window is exceeded, the payment will automatically expire and the amount will be available again on the customer’s account.
*Please note: All payments which have not been authorized by the customer or which have not been captured by you during the disposition time window, will be set to `EXPIRED`. These jobs are only active in the paysafecard production environment.*

<br><br/>

## Payment notification
The payment notification is used to notify the business partner about the status of the transaction. The payment notification is sent as soon money is assigned to the transaction, so when the transaction can be captured.
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).
- The transaction is completed successfully.
- The payment notification will be sent from either of the below IP addresses:

| IP addresses  |
|---|
|  3.127.106.50 <br>3.126.164.128 <br>3.127.123.143 <br>176.34.172.250 <br>54.228.173.185 |

<br><br/>

## Status before expiration
`status_before_expiration` can be used to hold the status of the payment before it transitions to `EXPIRED`.
This is useful to distinguish cases where a successfully authorized payment has not been captured from cases where a customer did not authorize the payment at all.
The possible values are "INITIATED", "REDIRECTED" and "AUTHORIZED".

# Group Payment API Calls

## Initiating a payment [/payments]

Upon successful execution of this request, the `status` of the payment transitions to `INITIATED`.

Using the optional HEADER-Parameter `Correlation-ID` you can set a part of the parameter `id` on your own.

+ Attributes (PaymentRequest)


### Initiating a payment [POST]


The next step is to redirect the customer to the `auth_url`, which is returned as part of the response.

As soon as the customer has authorized the payment, its state will transition to `AUTHORIZED` and the customer will be redirected to the `success_url` you specified when creating the payment.

In addition to redirecting the customer back to your site, we will call the `notification_url` you specified. See more details in the section "Payment notification".

Now you are ready to perform the final step, capturing the payment.

+ Request (application/json)

    + Headers

               Authorization: Basic cHNjX1U5TDMtbzBpM3p4NU92M09uY0tzSjNzOWZndzVTTk0=

    + Attributes (PaymentRequest)
    

+ Response 201 (application/json)

            {
            "object": "PAYMENT",
            "id": "pay_1000000007_Hukab77YIXzKUYMdgPDBQ986ihNUQChu_EUR",
            "created": 1430137532383,
            "updated": 1430137532383,
            "amount": 0.01,
            "currency": "EUR",
            "status": "INITIATED",
            "redirect": {
                "success_url": "http://ok.com/pay_1000000007_Hukab77YIXzKUYMdgPDBQ986ihNUQChu_EUR",
                "failure_url": "http://nok.com/pay_1000000007_Hukab77YIXzKUYMdgPDBQ986ihNUQChu_EUR",
                "auth_url": "https://dv.customer.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=1000000007&mtid=pay_1000000007_Hukab77YIXzKUYMdgPDBQ986ihNUQChu_EUR&amount=0.01&currency=EUR"
            },
            "customer": {
                "id": "ICuCsrKUmg3pCpTyFNNrPR6K5k36P8Sv"
                },
            "notification_url": "http://ok.com/pay_1000000007_Hukab77YIXzKUYMdgPDBQ986ihNUQChu_EUR"
            }

## Capturing a payment [/payments/{id}/capture]


```
POST /payments/{id}/capture
```

| Parameter                     | Type    | Required | Example            | Description                          |
| ---                           | ---     | ---      | ---                | ---                                  |
| `id`                  | string  | required | pay_9000001500_t7krk6idmLIzz6uUUv3AhU6dIay7ah75_EUR | id from Step 1 |


### Capturing a payment [POST]

+ Parameters
    + id: pay_9000001500_t7krk6idmLIzz6uUUv3AhU6dIay7ah75_EUR (required) - Id from the initiate payment call.

+ Request (application/json)

    + Headers

               Authorization: Basic cHNjX0R4dThqSnI1LVdPYXhLWnpjOXdyMUtNLXd1Y3dZMXg=

+ Response 200 (application/json)

            {
            "object":"PAYMENT",
            "id":"pay_1000000007_k3JfFMcpLPXGMk1mOdkbmRARdr5kKQeI_EUR",
            "created":1430205127021,
            "updated":1430206011382,
            "amount":0.01,
            "currency":"EUR",
            "status":"SUCCESS",
            "type":"PAYSAFECARD",
            "customer":{
                "id":"a4ssjAMiHia58AJ7wi4cHBgsFOTmTvCv"},
            "notification_url":"http://ok.com",
            "card_details":[{
                "serial":"1453591278",
                "currency":"EUR",
                "amount":0.01,
                "type":"00002",
                "country":"AT"}]
            }

### Retrieving payment details [/payments/{id}]

```
GET /payments/{id}
```
| Parameter                     | Type    | Required | Example            | Description                          |
| ---                           | ---     | ---      | ---                | ---                                  |
| `id`                  | string  | required | pay_9000001500_t7krk6idmLIzz6uUUv3AhU6dIay7ah75_EUR | id from Step 1 |

Upon successful `success_url` redirection, the business partner must call `retrieve payment details` to verfiy the status of the payment
and display the correct message to the customer, as shown in the [Payment Process](#payment_process) section.

<br></br>

Here, the transaction `id` is used to retrieve the details of that specific Paysafecash payment.


+ Parameters
    + id (required, string, `pay_9000001500_t7krk6idmLIzz6uUUv3AhU6dIay7ah75_EUR`) ... id from Step 1.

### Retrieving payment details [GET]

**Note**: Retrieving the details of a payment can be done at any time and it can be used to update the status of a specific payment displayed to the customer.

+ Request (application/json)

    + Headers

               Authorization: Basic cHNjX0R4dThqSnI1LVdPYXhLWnpjOXdyMUtNLXd1Y3dZMXg=
               

+ Response 200 (application/json)

 + Attributes (PaymentResponse)

# Group Payment API response objects

|Parameter|Description|Cases|
|---|---|---|
|`object`|Identifies the object. For a payment, the value returned is PAYMENT.|Always|
|`id`|Unique identifier for a payment.|Always|
|`created`|Unix timestamp specifying when this object was created.|Always|
|`updated`|Unix timestamp specifying when this object was last updated.|Always|
|`amount`|The payment amount.|Always|
|`currency`|Currency of this payment.|Always|
|`status`|Please scroll up to the section "Payment status" for a list of all possible payment states.|Always|
|`status_before_expiration`|Holds the status of the payment before it transitioned to `EXPIRED`. This is useful to distinguish cases where a successfully authorized payment has not been captured from cases where a customer did not authorize the payment at all.|Optional. Only returned when the payment is in status `EXPIRED`.|
|`type`|Always set to PAYSAFECARD.|Always|
|`redirect[success_url]`|URL to redirect if customer clicks on "Back to Shop". Should redirect to Homepage/Shopping basket. Shopping basket should be emptied as soon the customer is redirected to the barcode application.|Always|
|`redirect[failure_url]`|URL to redirect after customer/you as merchant cancels the transaction.|Always|
|`notification_url`|Notification URL we will contact after authorization has been successfully completed.|Always|
|`customer[id]`| ID provided by you, which identifies the customer.|Always|
|`customer[ip]`|IPv4 address of the customer.|After customer has been re-directed to paysafecards payment panel.|
|`card_details[serial]`|The serial number of the card that has been used to authorize the payment.|After cards have been assigned.|
|`card_details[currency]`|The currency of the card.|After cards have been assigned.|
|`card_details[amount]`|The amount that has been deducted from the card for this payment.|After cards have been assigned.|
|`card_details[type]`|The type of card.|After cards have been assigned.|
|`card_details[country]`|The country where this card was issued.|After cards have been assigned.|

# Group Payment Error Codes

|Code                           |Number (optional)  |HTTP Status    |Description          |
|---                                                                        |---                |---            |---                  |
|`general_technical_error`                                                  |10007              |500            |General technical error.|
|`invalid_api_key`                                                          |10008              |401            |Authentication failed due to missing or invalid API key. Your key needs to be set to the HTTP auth username.|
|`invalid_request_parameter`                                                |10028              |400            |One of the request parameters failed validation. The `message` and `param` fields contain more detailed information.|
|`duplicate_transaction_id`                                                 |2001               |400            |Transaction already exists.|
|`payment_invalid_state`                                                    |2017               |400            |The payment is in an invalid state, e.g. you tried to capture a payment that is in state `INITIATED` instead of `AUTHORIZED`.|
|`Merchant with Id XXXXXXXXXX is not active.`                               |3001               |400            |Merchant is not active.|
|`Merchant with Id XXXXXXXXXX is not allowed to perform this debit any more`|3007               |400            |Debit attempt after expiry of dispo time window.|
|`submerchant_not_found`                                                    |3014               |400            |The `submerchant_id` specified by you has not been configured.|
|`disposition_expiration_time_minutes_invalid`                              |3037               |400            |The time set in the parameter "expiration_time_minutes" is not in the allowed span (between 5 and 20160 minutes).|
|`general_error`                                                            |3017               |400            |It is mandatory to send an MCID.|
|`general_error`                                                            |3019               |400            |MCID contains invalid values.|


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 immediately via integration@paysafecard.com if the account is not live.
For live accounts, techsupport@paysafecard.com should be contacted.

#Group Variable Transaction Timeout

Upon the creation of the barcode, the customer is given a time frame to go to the Point of Sales and pay for the transaction. The customer will see on the payment panel how much time is left to pay with the barcode. 

This time frame is limited between the transaction creation and (if no payment happens) the expiration of the transaction. 

The default value for this is 3 days.

There is the possibility to set this timeout per transaction. The timeout can be specified in the initiation of the transaction. 

If no specific setting is in place, the default setting will be used.

#Group Customer Data Takeover
There is the possibility that the business partner sends the customer data (full name, DoB, full list of parameters at "Iniating a payment") to paysafecard, so the registration form is prefilled. 

This has the purpose to make the registration of the customer easier. If the business partner wants to use that feature, it has to be pointed out clearly to the customer that the data is shared with paysafecard.

The customer data exchange happens at the transaction creation.
+ Customer has to be informed of the data exchange
+ Makes it easier for the customer to register at paysafecard
+ Business partner sends the data in the transaction creation

**Important**: paysafecard does not store this data. It is solely used to make the registration easier. The data is only accessible as long as the transaction is in an open status and is dropped afterwards.

+ If a middle name is to be sent during the data exchange, the business partner must combine the customer middle name with the `first_name` parameter.

+ It is crucial that the international calling code of the phone number and the country is matching. Otherwise, the number is dropped and not prefilled to the registration form.

# Group Refund Process

The refund feature provides business partners to fully or partially refund a previously paid transaction back into the
customer‘s my paysafecard account.

A refund will always be issued in the currency of the original payment transaction.

Refunding a payment is possible up to 45 days after the initial payment.

- Prerequisites
    - The business partner needs to have the merchant refund REST functions implemented on the website or back-end system.
    - The business partner needs to be fully integrated and refund needs to be enabled at paysafecard’s side.
    - The customer needs to be registered with my paysafecard in order to receive a refund.
    - A refund transaction always refers to a previous underlying payment, because of this reason it is required that a
        payment has been processed before the refund can be processed.
    - There needs to be enough Credit in the Credit Limit

- Settlement

    All successfull refunds will be deducted from the payments (netting) on the montly invoice that paysafecard
sends its business partners.

- Credit Limit

    You cannot refund a higher amount than the amount you had in payments in one billing cycle. To prevent failed refunds at the beginning of a billing cycle, it is possible to assign an additional Credit Limit to your account. The duration of the billing cycle is defined in the contract.

# Group Refund API Call

## Capturing a Refund [/payments/{paymentid}/refunds]

## Capturing a Refund [/payments/{id}/refunds]

```
POST /payments/{id}/refunds
```

| Parameter                     | Type [validation]    | Required | Example            | Description                          |
| ---                           | ---     | ---      | ---                | ---                                  |
| `type`                        | string<br/>[PAYSAFECARD]  | required | paysafecard        | Must be set to PAYSAFECARD.|
| `capture`               | boolean<br/>[true,false] | required | true |needs to be set to 'true'|
| `amount`                      | float or integer<br/>[max length: 11 digits before, optionally 2 digits after decimal point]   | required | 10.00            | The precision needs to be two digits after the colon.|
| `currency`                    | string<br/> [max. length: 3, all uppercase]  | required | EUR             | ISO 4217 (3 letter ISO currency code) |
| `customer[id]`           | string<br/> [may. length: 50 characters] | required | client123  | Needs to be the same customerID as the one used at the original transaction |
| `customer[email]`           | string<br/> [valid email address] | optional<br/>one of email, phone_number, account_id | valid@email.com                            | Needs to be the email that the customer used to register for the Paysafecash account. |


### Capturing a Refund [POST]

+ Parameters

    + id: `pay_9000001500_Bo2Phc1X2Gtg6Nu7WtqHZrjA2At3qdkj_EUR` (required) - Id of a captured payment

+ Request (application/json)

    + Headers

               Authorization: Basic cHNjX0R4dThqSnI1LVdPYXhLWnpjOXdyMUtNLXd1Y3dZMXg=

    + Attributes (RefundValidationRequest)

+ Response 201 (application/json)

    + Attributes (RefundResponse)

# Group Refund Error Codes

|Code                                                   |Number (optional)  |HTTP Status      |Description          |
|---                                                    |---                |---              |---                  |
|`PRODUCT_NOT_AVAILABLE`                                |3100               |404              |Product not available.|
|`DUPLICATE_ORDER_REQUEST`                              |3103               |400              |Duplicate order request.|
|`FACEVALUE_FORMAT_ERROR`                               |3106               |400              |Invalid facevalue format.|
|`MISSING_PARAMETER`                                    |3150               |400              |Missing paramenter.|
|`INVALID_CURRENCY`                                     |3151               |400              |Invalid currency.|
|`MERCHANT_NOT_ALLOWED_FOR_PAYOUT`                      |3161               |400              |Merchant not allowed to perform this Action.|
|`CUSTOMER_NOT_FOUND`                                   |3162               |404              |No customer account found by provided credentials.|
|`INVALID_PARAMETER`                                    |3163               |400              |Invalid paramater.|
|`duplicate_payout_request`                             |3164               |400              |Transaction already exists.|
|`INVALID_AMOUNT`                                       |3165               |400              |Invalid amount.|
|`CUSTOMER_LIMIT_EXCEEDED`                              |3167               |400              |Customer limit exceeded.|
|`KYC_INVALID_FOR_PAYOUT_CUSTOMER`                      |3168               |400              |Feature not activated in this country for this kyc Level.|
|`payout_id_collision`                                  |3169               |400              |Payout id collides with existing disposition id|
|`topup_limit_exceeded`                                 |3170               |400              |Top-up limit exceeded.|
|`payout_amount_below_minimum`                          |3171               |400              |Payout amount is below minimum payout amount of the merchant.|
|`MERCHANT_REFUND_EXCEEDS_ORIGINAL_TRANSACTION`         |3179               |400              |Merchant refund exceeds original transaction.|
|`MERCHANT_REFUND_ORIGINAL_TRANSACTION_INVALID_STATE`   |3180               |400              |Original Transaction of Merchant Refund is in invalid state.|
|`MERCHANT_REFUND_CLIENT_ID_NOT_MATCHING`               |3181               |400              |Merchant Client Id not matching with original Payment.|
|`NO_UNLOAD_MERCHANT_CONFIGURED`                        |3182               |400              |merchant client Id missing.|
|`MERCHANT_REFUND_MISSING_TRANSACTION`                  |3184               |404              |No original Transaction found.|
|`merchant_refund_customer_credentials_missing`         |3185               |404              |my paysafecard account not found on original transaction and no additional credentials provided.|
|`customer_inactive`                                    |3193               |400              |Customer not active.|
|`customer_yearly_payout_limit_reached`                 |3194               |400              |Customer yearly payout limit exceeded.|
|`customer_details_mismatchd`                           |3195               |400              |Customer details from request don't match with database.|
|`max_amount_of_payout_merchants_reached`               |3198               |400              |There is already the maximum number of pay-out merchant clients assigned to this account.|
|`payout_blocked`                                       |3199               |400              |Payout blocked due to security reasons.|

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 immediately via integration@paysafecard.com if the account is not live.
For live accounts, techsupport@paysafecard.com should be contacted.


# Data Structures

## TypedObject (object)
+ type: PAYSAFECARD (required, fixed) - Type of the product, must be set to PAYSAFECARD.

## PaymentRequest (TypedObject)
+ amount: 0.01 (number, required) - Payment amount, precision must be 2 digits after the colon.
`10.00`
+ currency: EUR (required) - ISO 4217 (3 letter ISO currency code).
+ redirect (Redirect, 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.
+ `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.  
+ submerchant_id: 1 - ReportingCriterion (optional) - Also called ‘reporting criteria’, offers the possibility to classify sub-merchants. Agreement with paysafecard needed - not agreed values lead to a failed payment.
+ 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.
+ `expiration_time_minutes`: 4320 (optional) - Time frame the customer is given to go to the Point of Sales and pay for the transaction. For further details, please see "Variable Transaction Timeout".
+ `customer_takeover_data` (object) 
    + `first_name`: `Max`
    + `last_name`: `Mustermann`
    + `date_of_birth`: `1990-12-31`
    + `address1`: `Musterstrasse 2`
    + `postcode`: 1234
    + `city`: `Vienna`
    + `country_iso2`: `AT`
    + `phone_number`: `+43676123456789`
    + `email`: `example@test.at`

## PaymentResponse (TypedObject)
+ id: pay_1000000007_k3JfFMcpLPXGMk1mOdkbmRARdr5kKQeI_EUR - The unique id of this payment
+ created: 1430317131908 (number)
+ updated: 1430317131908 (number)
+ amount: 0.01 (number)
+ currency: EUR (required) - ISO 4217 (3 letter ISO currency code).
+ status: SUCCESS
+ redirect (Redirect)
+ `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 (CustomerResponseFull)
+ card_details (array[CardDetails])

## CardDetails (object)
+ serial: 1453591278
+ currency: EUR
+ amount: 0.01
+ type: 00002
+ country: AT 

## CustomerResponseFull (object)
+ id
+ account_id
+ first_name: xApuEWppcYCptzoRnykkNuKznx
+ last_name: DbHILeEKPCRTCFuGbHKByYtbCm
+ email: psc.mypins+TEST_MOXSMYkqkkwWDH@gmail.com - the customer identifier
+ age
+ kyc_level
+ currency

## Redirect (object)
+ `success_url`: https://ok.com/{payment_id}
+ `failure_url`: https://nok.com/{payment_id}

## CustomerTakeoverData (object)
+ `first_name`: `Max`,
+ `last_name`: `Mustermann`,
+ `date_of_birth`: `1990-12-31`,
+ `address1`: `Musterstrasse 2`,
+ `postcode`: `1234`,
+ `city`: `Vienna`,
+ `country_iso2`: `AT`,
+ `phone_number`: `+43676123456789`,
+ `email`: `example@test.at`

## RefundRequest (TypedObject)
+ amount: 00.01 (required)
+ currency: EUR (required)
+ customer (object, required)
    + id: merchantclientid5HzDvoZSodKDJ7X7VQKrtestAutomation (required) 
    + email: psc.mypins+9000001500_xZteDVTw@gmail.com (required)

## RefundValidationRequest (RefundRequest)
+ capture: true (boolean, required)

## RefundCaptureRequest (RefundRequest)
+ capture: true (boolean, required)

## RefundResponse (object)
+ object: refund - Type of object, always refund
+ id: ref_1000000007_2838fhsd6dashsdkfsd_EUR
+ created: 1430137532383 (number)
+ updated: 1430137532383 (number)
+ currency: EUR
+ amount: 10.00
+ customer (object)
    + id: merchantclientid5HzDvoZSodKDJ7X7VQKrtestAutomation
    + email: valid@email.com
+ status : SUCCESS