> ## Documentation Index
> Fetch the complete documentation index at: https://api.corpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search cards
> Search for cards by customer, order reference, and pagination. Sorting can be applied on card status. Default sorting includes Active cards on top.
**Performance expectations:**
**p50:** 220 ms, **p99:** 1900 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
## OpenAPI
````yaml /openapi.yaml post /cards/search
openapi: 3.1.0
info:
title: Corpay APIs
version: 1.0.0
description: >
Corpay APIs for customer profile management, card management, transaction
history, and master data retrieval.
servers:
- url: https://apigwuat.corpay.com
description: Test environment
- url: https://apigw.corpay.com
description: Production environment
security:
- oauth2ClientCredentials: []
tags:
- name: Customer
description: Customer profile and account lifecycle APIs
- name: Card
description: Card retrieval, ordering and lifecycle APIs
- name: Geosearch
description: >-
Search and retrieve detailed information about charging locations and
stations
- name: Remote Charging
description: >-
Control charging sessions remotely including starting and stopping
sessions, and monitoring session status
- name: EV Session
description: >-
Access and manage charging session data including history, status, and
detailed session information
- name: Transaction
description: Transaction history APIs
- name: Master
description: Master/reference data APIs
- name: Webhooks
description: Event callback payloads sent by Corpay
paths:
/cards/search:
post:
tags:
- Card
summary: Search cards
description: >
Search for cards by customer, order reference, and pagination. Sorting
can be applied on card status. Default sorting includes Active cards on
top.
operationId: searchCards
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
minimum: 1
description: Max number of records to return.
cursor:
type: string
description: Pagination cursor from a previous response.
sortExpression:
type: string
description: Sort expression, e.g., "createdAt desc".
customerAccountNumber:
type: string
description: Customer account identifier.
orderReference:
type: string
description: Order reference to filter by.
additionalProperties: false
responses:
'200':
description: Card results
content:
application/json:
schema:
$ref: '#/components/schemas/CardListResponse'
example:
$ref: '#/components/schemas/CardListResponse/example'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
CardListResponse:
example:
cards:
- additionalEmbossing: FLEET-01
cardDeliveryAddress:
addressLines: Unit 10, Industrial Estate Oxford Road
city: Oxford
country: United Kingdom
countryCode: GBR
region: Oxfordshire
zipCode: OX1 3PA
cardDeliveryContact:
emailAddress: jane.smith@example.com
firstName: Jane
lastName: Smith
middleName: B
mobilePhone: '+447700900124'
telephone: '+441234567891'
cardIdentifier: 1234
cardType: BE EV
driverName: James Smith
fuelProductRestriction:
productRestrictionId: 1
productRestrictionName: Fuel Only
keyIdentifier: 2323s
primaryVisualCardNumber: '3080002323232'
products:
- productId: 101
productName: Car Wash
- productId: 102
productName: Lubricants
purchaseCategoryName: Fuel
secondaryCardNumber: NL-TBE-2323-2323
status: Active
vehicleRegNumber: AB12 CDE
customerAccountNumber: '23444444'
hasNextPage: true
nextCursor: '500'
totalCount: 125
properties:
cards:
items:
properties:
additionalEmbossing:
type: string
cardDeliveryAddress:
$ref: '#/components/schemas/Address'
cardDeliveryContact:
$ref: '#/components/schemas/Contact'
cardIdentifier:
type: integer
cardType:
type: string
driverName:
type: string
fuelProductRestriction:
properties:
productRestrictionId:
type: integer
productRestrictionName:
type: string
type: object
keyIdentifier:
type: string
primaryVisualCardNumber:
type: string
products:
items:
properties:
productId:
type: integer
productName:
type: string
type: object
type: array
purchaseCategoryName:
type: string
secondaryCardNumber:
type: string
status:
type: string
vehicleRegNumber:
type: string
type: object
type: array
customerAccountNumber:
type: string
hasNextPage:
type: boolean
lastPage:
type: boolean
nextCursor:
type: string
totalCount:
type: integer
type: object
Address:
properties:
addressLines:
type: string
city:
type: string
country:
description: >-
Country Name, which needs to match from master/all API within
country[].name
type: string
countryCode:
description: >-
Country Code, which needs to match from master/all API within
country[].code
type: string
region:
description: >-
Region Name, which needs to match from master/all API within
region[].name
type: string
zipCode:
type: string
type: object
Contact:
properties:
emailAddress:
format: email
type: string
firstName:
type: string
lastName:
type: string
middleName:
type: string
mobilePhone:
type: string
telephone:
type: string
type: object
Error:
example:
errorCode: ER-001
errorDescription: Invalid request parameters
properties:
errorCode:
type: string
errorDescription:
type: string
required:
- errorCode
- errorDescription
type: object
responses:
BadRequest:
content:
application/json:
example:
errorCode: ER-001
errorDescription: Invalid request parameters
schema:
$ref: '#/components/schemas/Error'
description: Bad request - validation error
Unauthorized:
description: Unauthorized - missing or invalid authentication token
Forbidden:
description: Forbidden - insufficient permissions
NotFound:
description: Not found - resource does not exist
InternalServerError:
content:
application/json:
example:
errorCode: ER-012
errorDescription: >-
The server encountered an unexpected condition and could not
complete the request. Please contact Corpay Support.
schema:
$ref: '#/components/schemas/Error'
description: Internal server error
securitySchemes:
oauth2ClientCredentials:
description: >
Use OAuth2 client credentials to obtain a bearer token.
Token endpoint:
`POST /keycloak/realms/longship/protocol/openid-connect/token`
Use the same base URL as the selected API server:
- Test environment: `https://apigwuat.corpay.com`
- Production environment: `https://apigw.corpay.com`
Example:
```bash
curl --location
'/keycloak/realms/longship/protocol/openid-connect/token' \
--header 'accept: application/json' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=.......' \
--data-urlencode 'client_secret=......'
```
flows:
clientCredentials:
scopes: {}
tokenUrl: /keycloak/realms/longship/protocol/openid-connect/token
type: oauth2
````