---
title: "POST /get_retailer_locations"
method: POST
path: "/get_retailer_locations"
tags: ["Retailers"]
---

# POST /get_retailer_locations

`POST /get_retailer_locations`

## Request

- Base URL: `https://api.paynearme-sandbox.com/json-api`
- URL: `https://api.paynearme-sandbox.com/json-api/get_retailer_locations`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://login.paynearme.com/oauth/token`
  - API key in query parameter `signature`

Find retailer locations using either an address or coordinates

## Request body

- union: Finds retailer locations near the specified address or corrdinates where consumers can make cash payments.
  - object
    - `site_identifier` string, required: Identifies your client site.
    - `timestamp` string, required: The Unix Epoch time of the call
    - `version` string, required: The version of the API. This version must match the version associated with your API key pair.
    - `signature` string: The HMAC signature that is calculated by running your API Secret Key and the alphabetized, concatenated parameters of the request payload through the SHA256 message digest algorithm. **NOTE:** This field is required when authenticating with the HMAC signature method; it is not required when authenticating with OAuth 2.0.
    - `retailer_identifier` '7-Eleven' | 'R4443678411' | '28' | '1346' | 'CVS' | '52e507ae8599be79d0010786000a3989' | '9108444872f74feaa0b20824efb182d4' | 'GDN-WALGREENS' | 'R5879324308': The name of the retailer where the consumer should make the cash payments. Use the following identifiers for the specified retailers:<ul><li>7-Eleven - <code>7-Eleven</code></li><li>Ace Cash Express - <code>R4443678411</code></li><li>Albertsons - <code>00028</code></li><li>Casey's - <code>01346</code></li><li>CVS - <code>CVS</code></li><li>Dollar General - <code>52e507ae8599be79d0010786000a3989</code></li><li>Family Dollar - <code>9108444872f74feaa0b20824efb182d4</code></li><li>Walgreens - <code>GDN-WALGREENS</code></li><li>Walmart - <code>R5879324308</code></li></ul>
    - `street` string, required: The street address of the consumer's location
    - `city` string, required: The city of the consumer's location
    - `state` string, required: The state of the consumer's location
    - `postal_code` string, required: The ZIP code of the consumer's location.
  - object
    - `site_identifier` string, required: Identifies your client site.
    - `timestamp` string, required: The Unix Epoch time of the call
    - `version` string, required: The version of the API. This version must match the version associated with your API key pair.
    - `signature` string: The HMAC signature that is calculated by running your API Secret Key and the alphabetized, concatenated parameters of the request payload through the SHA256 message digest algorithm. **NOTE:** This field is required when authenticating with the HMAC signature method; it is not required when authenticating with OAuth 2.0.
    - `retailer_identifier` '7-Eleven' | 'R4443678411' | '28' | '1346' | 'CVS' | '52e507ae8599be79d0010786000a3989' | '9108444872f74feaa0b20824efb182d4' | 'GDN-WALGREENS' | 'R5879324308': The name of the retailer where the consumer should make the cash payments. Use the following identifiers for the specified retailers:<ul><li>7-Eleven - <code>7-Eleven</code></li><li>Ace Cash Express - <code>R4443678411</code></li><li>Albertsons - <code>00028</code></li><li>Casey's - <code>01346</code></li><li>CVS - <code>CVS</code></li><li>Dollar General - <code>52e507ae8599be79d0010786000a3989</code></li><li>Family Dollar - <code>9108444872f74feaa0b20824efb182d4</code></li><li>Walgreens - <code>GDN-WALGREENS</code></li><li>Walmart - <code>R5879324308</code></li></ul>
    - `latitude` string, required: The latitude coordinate of the consumer's location.
    - `longitude` string, required: The longitude coordinate of the consumer's location.

## Response `200`

List of Retailers Created

- union
  - object
    - `status` 'ok', required
    - `locations` Location[]
      - `retailer` '7-Eleven' | 'Ace Cash Express' | 'Albertson's' | 'Casey's' | 'CVS' | 'Dollar General' | 'Family Dollar' | 'Fidelity Express' | 'Kroger' | 'Pin4' | 'QuotePro' | 'Walgreens' | 'Walmart': The name of the retailer
      - `street` string: The street address of this retailer location.
      - `city` string: The state of this retailer location
      - `latitude` string: The latitude coordinate of this retailer location.
      - `longitude` string: The longitude coordinate of this retailer location.
      - `distance` string: The distance (in miles) of this retailer location from the customer address.
      - `phone` string: The phone number of this retailer location.
      - `pnm_retailer_identifier` '7-Eleven' | 'R4443678411 (Ace Cash Express)' | '00028 (Albertson's)' | '03135 (Blackhawk Network)' | '01346 (Casey's)' | 'CVS' | '52e507ae8599be79d0010786000a3989 (Dollar General)' | '0de49278bc2c7cffa6f4e7481e51e62e (Family Dollar)' | 'FidelityExpress' | 'GDN-KROGER' | 'PIN4' | 'QUOTEPRO' | 'GDN-WALGREENS' | 'R2396117362 (Walmart)': A unique, PayNearMe-provided ID for the retailer
  - ErrorEnvelope: Returned with HTTP 200 for every failure except a rejected OAuth 2.0 access token, which returns HTTP 401 with the same shape. Every response carries a status; on failure it is "error" and the errors array describes what went wrong.
    - `status` 'error', required
    - `errors` ErrorDetail[], required: One entry per failure.
      - `description` string, required: Human-readable description of the failure.
      - `message` string: Parameter-validation detail (APPS-17178).
      - `receipt` string: Receipt text, where the failure relates to a payment.
      - `format` string: Expected format, for parameter-validation failures.
      - `example` string: Example of a well-formed value.
      - `details` object: Processor response details (APPS-18223).

## Other responses

- `401`: OAuth 2.0 requests only. The `Authorization` header has no Bearer token, the access token is invalid, expired, or issued for a different site, or the `site_identifier` does not match any site. The response does not say which. If the request is rejected before it reaches PayNearMe, the body may not be JSON, so detect this error by the HTTP status. HMAC-signed requests never receive this status.

## Changes

- **2026-11-03** `907541f733a3`: 1 breaking, 6 info
  - removed the success response with the status `201`
  - api operation id `get_retailer_locations` was added
  - the request property `site_identifier` with a default value became required
  - the request property `timestamp` with a default value became required
  - …3 more

[Operation history](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0/changes/get_retailer_locations/post.md)

---

[API](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0.md) - [All operations](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0/llms.txt) - [OpenAPI document](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0/revisions/907541f733a3?raw)
