Skip to main content

Store locator API

The PaysafeCard Store Locator API provides a list and details of payment points around a geographic location.

The payment points can be filtered by various criteria and the results are shown in JSON format. They can be then vizualized on a map in your app or webshop.

Endpoint

Store locator:

Production environment: https://api.paysafecard.com/v2/shops/

Test environment: https://apitest.paysafecard.com/v2/shops/

Limits

For security reasons we will have rate limits in place:

300 seconds
2000 requests/IP
400 requests/IP per minute
600 second block if limit is reached

Interface Guidelines

The PaysafeCard Store Locator API must be implemented accordingly to the interface guidelines provided by the PaysafeCard integration team with the test data package and the instructions in this document.

Store locator request parameters

Parameter	Type	Example	Description
`lat`	Big decimal	48.3705878	Latitudinal search position (required).
`long`	Big decimal	10.8987651	Longitudinal search position (required).
`radius`	Big decimal	100	Radius in meters around lat/long to search for stores (required).
`limit`	String	2	Number of results to return (defaults to 20, optional). Max. number of results allowed is 1000.
`moneyFlowDirection`	String	IN	Filter to be applied to the stores. Available values: IN is to be used for PaysafeCash and OUT for PaysafeCash cashout. To filter for PaysafeCard stores, this parameter must be left out from the request.

Store locator response parameters

Parameter	Type	Example	Description
`id`	number	3713	The payment point ID.
`distributorId`	number	78	The payment point distributor id.
`shopId`	number	00005545	The payment point's shop ID.
`name`	string	Agip Tankstelle	The payment point name.
`address`	string	Allgäuer Str. 66	The payment point address.
`city`	string	Reutte	The payment city.
`recommended`	boolean	false	The payment point recommended status.
`zipCode`	string	6600	The payment point postal code.
`countryCode`	string	AUT	The payment point country.
`longitude`	number	10.72036517	The payment point longitudinal coordinates.
`latitude`	number	47.49912168	The payment point latitudinal coordinates.
`phone`	number	+43123123123	The payment point's phone number.
`logoUrl`	string	https://www.paysafecard.com/include/posicon/agip.gif	The payment point logo's url.
`logoThumbnailUrl`	string	null	The payment point's thumbnail logo URL.
`pointOfSaleType`	object	`{id: 744, name: "ch_bp", logoFilePath: "bp.gif", idAsString: "7444"}`	The payment point's logo information.
`pointOfSaleProducts`	array	`[{ shortName: "mdl", longName: "mdirectload", productCode: "003"}]`	The payment point's products.
`pointOfSaleRatings`	array	[]	The payment point customer feedback.
`distanceFromOrigin`	number	97810.0	The payment point distance from the origin coordinates, in meters.
`moneyFlowDirections`	array	["IN"]	The payment point's money flow directions.
`openingHours`	string	null	The payment point's opening hours.
`excludeFromTransaction`	boolean	false	The payment point's transaction exclusion based on max transaction amount.

Store Locator API 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_QUERY_PARAMETER`	—	400	One of the query parameters failed validation. The `errorMessage` and `errorDetail` fields contain more information.

Store Locator API SDK Samples

curl

curl -X GET "https://api.paysafecard.com/v2/shops?lat=48.3705878&long=10.8987651&radius=100&limit=2&moneyFlowDirection=IN"

Java

import org.openapitools.client.*;
import org.openapitools.client.auth.*;
import org.openapitools.client.model.*;
import org.openapitools.client.api.StoresApi;

import java.io.File;
import java.util.*;

public class StoresApiExample {

    public static void main(String[] args) {
        
        StoresApi apiInstance = new StoresApi();
        BigDecimal lat = 8.14; // BigDecimal | Latitude
        BigDecimal long = 8.14; // BigDecimal | Longitude
        BigDecimal radius = 8.14; // BigDecimal | Radius in kilometers around lat/long to search for stores
        String limit = limit_example; // String | Number of results to return
        String offset = offset_example; // String | Start position in the search results, used for pagination
        String sortOrder = sortOrder_example; // String | 
        String moneyFlowDirection = moneyFlowDirection_example; // String | IN or OUT - leave parameter out for PaysafeCard
        Object body = Object; // Object | 
        try {
            array[inline_response_200] result = apiInstance.getStores(lat, long, radius, limit, offset, sortOrder, moneyFlowDirection, body);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling StoresApi#getStores");
            e.printStackTrace();
        }
    }
}

Please note the request parameters in the above are not up to date.

Android

import org.openapitools.client.api.StoresApi;

public class StoresApiExample {

    public static void main(String[] args) {
        StoresApi apiInstance = new StoresApi();
        BigDecimal lat = 8.14; // BigDecimal | Latitude
        BigDecimal long = 8.14; // BigDecimal | Longitude
        BigDecimal radius = 8.14; // BigDecimal | Radius in kilometers around lat/long to search for stores
        String limit = limit_example; // String | Number of results to return
        String offset = offset_example; // String | Start position in the search results, used for pagination
        String sortOrder = sortOrder_example; // String | 
        String moneyFlowDirection = moneyFlowDirection_example; // String | IN or OUT - leave parameter out for PaysafeCard
        Object body = Object; // Object | 
        try {
            array[inline_response_200] result = apiInstance.getStores(lat, long, radius, limit, offset, sortOrder, moneyFlowDirection, body);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling StoresApi#getStores");
            e.printStackTrace();
        }
    }
}

Please note the request parameters in the above are not up to date.

Obj-c

BigDecimal *lat = 8.14; // Latitude (default to null)
BigDecimal *long = 8.14; // Longitude (default to null)
BigDecimal *radius = 8.14; // Radius in kilometers around lat/long to search for stores (optional) (default to null)
String *limit = limit_example; // Number of results to return (optional) (default to null)
String *offset = offset_example; // Start position in the search results, used for pagination (optional) (default to null)
String *sortOrder = sortOrder_example; //  (optional) (default to null)
String *moneyFlowDirection = moneyFlowDirection_example; // String | IN or OUT - leave parameter out for PaysafeCard
Object *body = Object; //  (optional)

StoresApi *apiInstance = [[StoresApi alloc] init];

// Retrieve Stores
[apiInstance getStoresWith:lat
    long:long
    radius:radius
    limit:limit
    offset:offset
    sortOrder:sortOrder
    moneyFlowDirection:moneyFlowDirection
    body:body
              completionHandler: ^(array[inline_response_200] output, NSError* error) {
                            if (output) {
                                NSLog(@"%@", output);
                            }
                            if (error) {
                                NSLog(@"Error: %@", error);
                            }
                        }];

Please note the request parameters in the above are not up to date.

Javascript

var StoreLocator = require('store_locator');

var api = new StoreLocator.StoresApi()
var lat = 8.14; // {BigDecimal} Latitude
var long = 8.14; // {BigDecimal} Longitude
var opts = {
  'radius': 8.14, // {BigDecimal} Radius in kilometers around lat/long to search for stores
  'limit': limit_example, // {String} Number of results to return
  'offset': offset_example, // {String} Start position in the search results, used for pagination
  'sortOrder': sortOrder_example, // {String} 
  'moneyFlowDirection': moneyFlowDirection_example, // {String} - IN or OUT - leave parameter out for PaysafeCard
  'body': Object // {Object} 
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
api.getStores(lat, long, opts, callback);

Please note the request parameters in the above are not up to date.

C#

using System;
using System.Diagnostics;
using Org.OpenAPITools.Api;
using Org.OpenAPITools.Client;
using Org.OpenAPITools.Model;

namespace Example
{
    public class getStoresExample
    {
        public void main()
        {
            
            var apiInstance = new StoresApi();
            var lat = 8.14;  // BigDecimal | Latitude (default to null)
            var long = 8.14;  // BigDecimal | Longitude (default to null)
            var radius = 8.14;  // BigDecimal | Radius in kilometers around lat/long to search for stores (optional)  (default to null)
            var limit = limit_example;  // String | Number of results to return (optional)  (default to null)
            var offset = offset_example;  // String | Start position in the search results, used for pagination (optional)  (default to null)
            var sortOrder = sortOrder_example;  // String |  (optional)  (default to null)
            var moneyFlowDirection = moneyFlowDirection_example;  // String | IN or OUT - leave parameter out for PaysafeCard
            var body = Object;  // Object |  (optional) 

            try
            {
                // Retrieve Stores
                array[inline_response_200] result = apiInstance.getStores(lat, long, radius, limit, offset, sortOrder, moneyFlowDirection, body);
                Debug.WriteLine(result);
            }
            catch (Exception e)
            {
                Debug.Print("Exception when calling StoresApi.getStores: " + e.Message );
            }
        }
    }
}

Please note the request parameters in the above are not up to date.

PHP

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new OpenAPITools\Client\Api\StoresApi();
$lat = 8.14; // BigDecimal | Latitude
$long = 8.14; // BigDecimal | Longitude
$radius = 8.14; // BigDecimal | Radius in kilometers around lat/long to search for stores
$limit = limit_example; // String | Number of results to return
$offset = offset_example; // String | Start position in the search results, used for pagination
$sortOrder = sortOrder_example; // String | 
$moneyFlowDirection = moneyFlowDirection_example; // String | IN or OUT - leave parameter out for PaysafeCard
$body = Object; // Object | 

try {
    $result = $api_instance->getStores($lat, $long, $radius, $limit, $offset, $sortOrder, $moneyFlowDirection, $body);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling StoresApi->getStores: ', $e->getMessage(), PHP_EOL;
}
?>

Please note the request parameters in the above are not up to date.

Perl

use Data::Dumper;
use WWW::OPenAPIClient::Configuration;
use WWW::OPenAPIClient::StoresApi;

my $api_instance = WWW::OPenAPIClient::StoresApi->new();
my $lat = 8.14; # BigDecimal | Latitude
my $long = 8.14; # BigDecimal | Longitude
my $radius = 8.14; # BigDecimal | Radius in kilometers around lat/long to search for stores
my $limit = limit_example; # String | Number of results to return
my $offset = offset_example; # String | Start position in the search results, used for pagination
my $sortOrder = sortOrder_example; # String | 
my moneyFlowDirection = moneyFlowDirection_example; # String | IN or OUT - leave parameter out for PaysafeCard
my $body = WWW::OPenAPIClient::Object::Object->new(); # Object | 

eval { 
    my $result = $api_instance->getStores(lat => $lat, long => $long, radius => $radius => limit => $limit, offset => $offset, sortOrder => $sortOrder, moneyFlowDirection => $moneyFlowDirection, body => $body);
    print Dumper($result);
};
if ($@) {
    warn "Exception when calling StoresApi->getStores: $@\n";
}

Please note the request parameters in the above are not up to date.

Pyhton

from __future__ import print_statement
import time
import openapi_client
from openapi_client.rest import ApiException
from pprint import pprint

# create an instance of the API class
api_instance = openapi_client.StoresApi()
lat = 8.14 # BigDecimal | Latitude (default to null)
long = 8.14 # BigDecimal | Longitude (default to null)
radius = 8.14 # BigDecimal | Radius in kilometers around lat/long to search for stores (optional) (default to null)
limit = limit_example # String | Number of results to return (optional) (default to null)
offset = offset_example # String | Start position in the search results, used for pagination (optional) (default to null)
sortOrder = sortOrder_example # String |  (optional) (default to null)
moneyFlowDirection = moneyFlowDirection_example # String  | String - IN or OUT - leave parameter out for PaysafeCard
body = Object # Object |  (optional)

try: 
    # Retrieve Stores
    api_response = api_instance.get_stores(lat, long, radius=radius, limit=limit, offset=offset, sortOrder=sortOrder, moneyFlowDirection=moneyFlowDirection, body=body)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling StoresApi->getStores: %s\n" % e)

Please note the request parameters in the above are not up to date.

Rust

extern crate StoresApi;

pub fn main() {
    let lat = 8.14; // BigDecimal
    let long = 8.14; // BigDecimal
    let radius = 8.14; // BigDecimal
    let limit = limit_example; // String
    let offset = offset_example; // String
    let sortOrder = sortOrder_example; // String
    let moneyFlowDirection = moneyFlowDirection_example; // String
    let body = Object; // Object

    let mut context = StoresApi::Context::default();
    let result = client.getStores(lat, long, radius, limit, offset, sortOrder, moneyFlowDirection, body, &context).wait();
    println!("{:?}", result);

}

Please note the request parameters in the above are not up to date.

Endpoint
Limits
Interface Guidelines
Store locator request parameters
Store locator response parameters
Store Locator API Error Codes
Store Locator API SDK Samples