Obucks API

Integration process

This documentation gives business partners a clear understanding of the technical integration work that needs to be carried out to successfully implement the Pin-on-Demand REST API for Obucks. The Pin-on-Demand REST API allows full control of the sales process in real-time for both parties and therefore means some integration work and thorough testing of the real-time API.

A note to Openbucks legacy resellers:

Openbucks was acquired by Paysafe Group in August 2020. We are pleased to announce that the Openbucks payment panel is now officially merged with paysafecard, a product offered by the Paysafe Group. In addition to this change, we have moved the distribution of Obucks cards to the paysafecard rails and Pin-on-Demand REST API integration. Note: There is no change to the branding of the Obucks card. However, there is a change to the API and the Obucks card number format by only using a 16-digit card number also known as “PIN” as described in this documentation.

About the API

This section provides a technical introduction to the Pin-on-Demand REST API.

The Pin-on-Demand REST API follows RESTful 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 also facilitates solid and universally accepted foundations like http basic authentication, http verbs, JSON and CORS.

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.

Establishing a connection

A connection to the paysafecard system is successful if the following prerequisites are fulfilled:

• X.509 certificate for request authenticity (provided by paysafecard).
• API key for request authentication (provided by paysafecard).
• 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.

DNS settings

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

• Connect only via respective FQDN
• 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

X.509 certificate authenticity

paysafecard will provide the business partner with a .conf file that must be used to create a signed certificate requests (CSR). Instructions for the creation of the CSR will be provided with the test data delivery.

After successful CSR creation, paysafecard will then provide the business partner with the X.509 certificate based on this CSR, which will work on both test and productive environments.

Important: Please keep the private key in a safe place and do not provide it to paysafecard nor disclose it to third parties. paysafecard will never ask for the private key.

SSL encryption

The certificate ensures encryption of all communications.

• Only TLS 1.2 (SSL 3.3) is supported
• Weak ciphers are disabled

API key authentication

Every request must be 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
• 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 environments and endpoints

Every new business partner needs to first integrate the paysafecard API on the test environment for Obucks cards. Once the integration is finished, a UAT(User Acceptance Test) needs to be done to ensure a seamless 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": "invalid_request_parameter",
"message": "Correlation-ID is invalid: 'test123!'",
"number": 10028,
"param": "Correlation-ID"}

Required data

Obucks card delivery data requirements

Please use the example below for reference of data to display for end consumer card delivery.

Each Obucks card must contain the following data (example above)

IMPORTANT: The product page and e-delivery display must also contain:

Confidentiality

paysafecard assumes that the business partner will handle the PIN for Obucks cards confidentially (it is only intended for the end customer).

Important: The business partner shall not store the unencrypted PIN in any server, system, application, database, log file or error log where it may be subject to fraud.

If the business partner needs to store the PIN on its local systems for the card delivery, the PIN should be stored encrypted or in such a way that it is not easily accessible.

PIN-on-demand flow

PIN-on-demand process

1. The customer requests an Obucks card PIN for an available face value at the distributor website
2.  An execute order request is made to the paysafecard system for the Obucks card
3. paysafecard performs validation checks (credit limit, terminal limits) and a valid response is returned (the status of the order is DELIVERED)
4. The Obucks card is delivered by the business partner system containing the PIN, serial number, product, face value, currency, date, terminal Id and the Terms and Conditions and delivered to the customer
5. (Optional) A cancellation can be made via the cancel order request (the status of the order is CANCELLED)
6. paysafecard performs validation checks (order status, date) and a valid response is returned
7. A cancellation receipt is delivered by the business partner system and delivered to the customer

This section describes in detail all the requests available in the Pin-on-Demand REST API. Real API request examples can be viewed in the Mock Server by clicking in the requests names below.

Execute an order

The execute order request is intended for the purchase of one (single) Obucks card PIN. Note: Using the optional HEADER-Parameter Correlation-ID, the business partner can set 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

Execute order example below
POST /orders/

POST https://distributor.test.paysafecard.com/v1/orders/

Parameters

Request

Headers

Content-Type: application/json
Authorization: Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=

{ "amount": 10,
"currency": "USD",
"country": "AT",
"product_id": "00028",
"delivery_type": "RETURN",
"utc_offset": "+00:00",
"shop_id": "shopidtest",
"terminal_id": "terminalidtest",
"retailer_id": "retaileridtest",
"customer": {
"id_type": "NONE"
},
"capture": true
}

Response

201

Headers

Content-Type: application/json

BODY
{ "amount": 10,
"currency": "USD",
"card": {
"amount": 10,
"currency": "USD",
"serial": 1850422961,
"pin": "0381859494354749",
"product_id": "CLASSIC"
},
"distributor_id": "0009402006",
"order_id": "order_0009402006_test_corr_001",
"product_id": "CLASSIC"
}

Cancel an order

The cancel order request is used to undo a previous order. The Obucks card PIN associated with that order will be invalidated as well.

There is a timeout setting which can be individually configured and defines the maximum timeframe between the execute order and cancel order requests. This timeout is set by default to 5 minutes in the test environment and 20 days in the productive environment . A cancel order request is successful if:

• The PIN has not been used (i.e, the order status is "DELIVERED")
• The timeout setting has not elapsed

Note: An order canceled using the cancel order request will not appear on the invoice to the business partner, but will appear in the reconciliation file. If the PIN is already invoiced, a credit note will be issued.

Cancel order example below
DELETE /orders/id

DELETE https:// distributor.test.paysafecard.com/v1/orders/id/

Parameters

Request

Content-Type:application/json
Authorization:Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=

DELETE https:// distributor.test.paysafecard.com/v1/orders/ order_000942006_test_corr_001

Response

200

Header

Content-Type:application/json

Body

{ "distributor_id": "0009402006",
"order_id": "order_0009402006_test_corr_001"}

Retrieving an order

The retrieve order request is used to retrieve the status and information of a previous order. This request can be done at any time by the business partner.

Order status

Retrieve order example below
GET /orders/id

GET https://distributor.test.paysafecard.com/v1/orders/id

Parameters

Request

Headers

Content-Type:application/json
Authorization:Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=

GET https://distributor.test.paysafecard.com/v1/orders/order_0009402006_XxVNh31ux78Y1eJRgGe6Y6qcbVNtnMbr

Response

200

Headers

Content-Type:application/json

Body

{ "amount": 10,
"currency": "EUR",
"card": {
"amount": 10,
"currency": "EUR",
"serial": 1850423010,
"product_id": "00028"
},
"distributor_id": "0009402006",
"order_id": "order_0009402006_gfGMpuuhPHhipuIMff6qOQM0MHmv90yb",
"product_id": "00028",
"shop_id": "shopdid_test",
"terminal_id": "test_terminal_123",
"order_status": "DELIVERED",
"delivery_type": "RETURN"
}

Cancelling a card

Cancel card example below
DELETE /cards/sn/

GET https://distributor.test.paysafecard.com/v1/cards/sn

Parameters

Request

Headers

Content-Type:application/json
Authorization:Basic cHNjXzdoT2lCTFc4bURSNFl3TWdDV3RPZHU4SWZXNjdBanU=

GET https://distributor.test.paysafecard.com/v1/cards/1850428953

Response

200

Headers

Content-Type:application/json

Body

{ "terminal_id": "danade_term_1" }

Response objects

Below, all possible response objects for the Pin-on-Demand API are listed with the corresponding description:

Error codes

Below, all possible error codes for the Pin-on-Demand REST API are listed with the corresponding description:

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 Obucks cards for more information via integration@paysafecard.com if the account is not live.

For live accounts, please contact: techsupport@paysafecard.com.

Order id format

The order id can take two different formats, depending if the Correlation-ID was used or not.

When no Correlation-ID is provided:

• order_did_random-string
• Ex: order_0009402006_PQ4zB0QrXZWrcvpZLIp5nW4s7ctz2fvf

When a Correlation-ID is provided:

• order_did_correlation-id
• Ex: order_0009402006_test_corr_001

Handling lost response

The order id can take two different formats, depending if the Correlation-ID was used or not. When no Correlation-ID is provided:

• order_did_random-string
• Ex: order_0009402006_PQ4zB0QrXZWrcvpZLIp5nW4s7ctz2fvf

When a Correlation-ID is provided:

• order_did_correlation-id
• Ex: order_0009402006_test_corr_001

In case the business partner does not get a response back to an execute order request, a lost response mechanism shall be put in place to avoid order mismatches between the business partners system and paysafecard for Obucks cards.

The below diagram show these recommended implementation for the lost response scenario:

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

Fraud prevention and limits

paysafecard assumes that the business partner itself has implemented several mechanisms in order to detect and prevent fraud.

As an additional service, paysafecard provides a set of tools to support this:

• Several terminal limits are set and if a certain terminal exceeds the allowed limit, the sales will be blocked.
• Terminal limits can be set globally or on terminal level.
• Limit notification: when a specific terminal has reached its limit, both paysafecard and the business partner will be informed
• paysafecard employees will receive a notification
• The business partner will receive the error “terminal_limit_1_exceeded” during the executing of the order.

When limits are reached the following procedure needs to be followed:

• The business partner must investigate the issue
• If no fraud is detected
• Wait for the limit to reset or reset it manually using use the Distributor Service Center
• Inform paysafecard and request a limit increase for Obucks cards distribution
• If fraud is detected, inform paysafecard to temporarily disable the terminal (on paysafecard side)

Global and terminal limits

The Pin-on-Demand system allows configuration up to 5 terminal limits on global and on terminal level.

NOTE: for online distribution, these terminal limits will apply for each customer individually.

By default only one global maximum limit of 2400 EUR (in each currency) per 12 hours is applied. If this limit is reached the terminal will be temporarily blocked.

Clarification using the 12 hour limit as example:

The 12 hour limit is not limited to 1 day but can start at 16:00 and end at 04:00 on the following day. When a terminal requests a paysafecard it receives a timestamp and the 12h limit is counted from this first time stamp. If a terminal does not sell for 2 days and reconnects on day 3 it will again receive a new timestamp (e.g. 11:00). This also applies to all limits available.

Currently there are 5 Limits available:

Global and terminal specific limits can be negotiated with paysafecard for Obucks cards. Please note:

• The limits should be configured so that in no case regular sales will be blocked. The limits are there for fraud prevention only.
• The limits will automatically release themselves as explained above. Alternatively, the limits can be reset in the Distributor Service Center.
• Please note that the terminal IDs sent to paysafecard must be unique. If different terminals

Terminal limit CSV

The business partner has the possibility to share a list of terminals with paysafecard upfront. In this file the limits for specific “high load” or “high risk” terminals can be communicated to paysafecard. Requests for limit changes must be sent to distribution@paysafecard.com.

The filename of the .csv file must have the following format:

[distributorid].csv
Example: 0009382795.csv

H record - Identifies the header record
| distributor_id
| |
H;0009382795`

D record - Identifies the detail record
| terminal_id
| | terminal_limit 1 (24 hour) in currency of distributor
| | | terminal limit 2 (5 mins) in currency of distributor
| | | | terminal limit 3 (2 hour) in currency of distributor
| | | | | terminal limit 4 (6 hour) in currency of distributor
| | | | | | terminal limit 5 (12 hours) in currency of distributor
| | | | | | |
D;39483;1700;300;1000;500;800

Last record - Identifies the footer record (End of File)
| number of lines in file (including this record)
| | EOF;5

Full example
H;0009382795
D;39483;1700;300;1000;;
D;39486;2000;500;;;
D;39487;3000;;1000;500;1500
EOF;5

Note: If one of the limits in the file is left empty, the general limits will apply.

Shop limits

Shop Limits have been implemented to allow business partners that have several terminals in one shop, to have a limit not only on the terminal but also on the whole shop. This can be useful for supermarkets where each cash register has it’s own terminal ID.

The shop limit is based on the highest terminal limit in one shop and is configured as a percentage. For example if the 12 hour terminal limit in a shop with 4 terminals is 500€ for each terminal and the shop limit is 50%, the shop (the 4 terminals together) can sell up to 750€, while each terminal can sell 500€.

The shop limits can be agreed with paysafecard and can be set individually for each specific limit (limits 1 to 5 as shown above for the global and terminal limits).

Temporary card locking

The temporary card locking guarantees that cancelling the order or the card (by either cancel order or cancel card) will succeed for the period that the lock is enabled. (when a PIN is already used, the cancellation will fail.

If the feature is enabled (by default it is always disabled), all PINs sold over Pin-on-Demand will be temporarily locked, meaning they cannot be used by the customer who purchased the card until the temporary card lock time elapses.

The recommended setting is 5 minutes, as most fraudulent card sale activities are detected within a rather short period of time, this feature should considerably lower the risk of POS fraud.

Note: Enabling this feature can only be done at paysafecard side.

If the temporary card locking is enabled, the business partner must add an extra text printed on the card delivery explaining that it takes some time before the customer can use the PIN.

Reconciliation sales reporting

By default on a daily basis the, the business partner will receive a detailed sales report (in csv), containing all orders of last day. Orders successfully executed as well as cancelled orders will be included in the reconciliation file.

The reconciliation files will be available on a SFTP at 3:00 CET/CEST for the previous day and should be picked up by the business partner. The SFTP will be a paysafecard SFTP and the distributor will have to pick up the files from the paysafecard SFTP.

The distributor should process these reports on a daily basis in order to prevent any inconsistencies between both systems. Should there be orders delivered to the distributor but not sold, the distributor should make a cancel order request, otherwise they will be invoiced based on the reconciliation file.

Important: paysafecard will invoice all orders that have been successfully executed for Obucks cards.

Filename: YYYY-MM-DD_DID.CSV
Example: 2014-05-05_0009300000.CSV

Reconciliation flow

Reconciliation file records

H1 record - Identifies the header 1 record | distributor_id
| |
H1;93827495

H2 record - Identifies the header 2 record
| reporting period (start)
| |
| | reporting period (end)
| | |
H2;2011-11-01;2011-11-03

H3 record - Identifies the header 3 record
| invoice id (if recon is sent with invoice)
| | invoice currency
| | | total invoice amount
| | | |
H3;90045466/06.11.2011;EUR;500.00

D record - Indicates the detail record
| 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;NONE;RETURN;DE;10.00;304;6954286854268596;DELIVERED;0

F record - Identifies the footer record (End of File)
| number of lines (including this record)
| |
EOF;56

Full example
H1;93827495
H2;2011-11-01;2011-11-3
H3;90045466/06.11.2011;EUR;500.00
D;93837;-60;2011-10-12
22:25:23;0000006938;304;506;309;NONE;RETURN;DE;10.00;304;6954286854268596;DELIVERED;0
EOF;56