Developers

Search for documents

Dev

Shoppers

Operations related to shopper references and stored methods

All endpoints require a JWT Bearer token in the Authorization header and an API key in the X-API-KEY header.

Base URL: https://payments.valpay.com.

GET `/v1/shoppers/references/{storeId}`

Get unique shopper references for a store

Parameters

Name	In	Type	Required	Description
`storeId`	path	`string`	Yes	Valpay Store ID to retrieve shopper references for
`cardNameOrSummaryFilter`	query	`string`	No	Optional filter to search shopper references by card holder name (case-insensitive partial match) or card number ending with exactly 4 characters (exact match)

Responses

Status	Description
`200`	Shopper references retrieved successfully
`400`	Bad request - validation failed
`401`	Unauthorized - invalid or missing authentication
`500`	Internal server error

Response schema (2xx)

Field	Type	Required
`success`	`boolean`	Yes
`data`	`array<object>`	Yes
`message`	`string`	Yes

Examples

GET `/v1/shoppers/references/{storeId}`

Shopper references for a store, filtered by card holder name:

curl "https://payments.valpay.com/v1/shoppers/references/665f1e2a9c8b4a0012d3e4b1?cardNameOrSummaryFilter=doe" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://payments.valpay.com/v1/shoppers/references/665f1e2a9c8b4a0012d3e4b1?cardNameOrSummaryFilter=doe" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://payments.valpay.com/v1/shoppers/references/665f1e2a9c8b4a0012d3e4b1?cardNameOrSummaryFilter=doe" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

Response 200 (illustrative):

{
  "success": true,
  "data": [
    {
      "shopperReference": "SHOPPER_EXAMPLE_001",
      "cardHolderName": "Jane Doe",
      "cardSummary": "1111"
    }
  ],
  "message": "Shopper references retrieved successfully"
}

{
  "success": true,
  "data": [
    {
      "shopperReference": "SHOPPER_EXAMPLE_001",
      "cardHolderName": "Jane Doe",
      "cardSummary": "1111"
    }
  ],
  "message": "Shopper references retrieved successfully"
}

{
  "success": true,
  "data": [
    {
      "shopperReference": "SHOPPER_EXAMPLE_001",
      "cardHolderName": "Jane Doe",
      "cardSummary": "1111"
    }
  ],
  "message": "Shopper references retrieved successfully"
}