> ## 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.
# Order cards
> Order one or more cards for a customer. The process is asynchronous and returns an order reference.
The identifiers required in this request can be obtained from the Master Data APIs. The Card Order process will take up to 24-36 hrs to complete the order.
**Performance expectations:**
**p50:** 300 ms, **p99:** 900 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
## OpenAPI
````yaml /openapi.yaml post /cards/order
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/order:
post:
tags:
- Card
summary: Order cards
description: >
Order one or more cards for a customer. The process is asynchronous and
returns an order reference.
The identifiers required in this request can be obtained from the Master
Data APIs. The Card Order process will take up to 24-36 hrs to complete
the order.
operationId: orderCard
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customerAccountNumber:
type: string
cards:
type: array
items:
$ref: '#/components/schemas/CardOrderObject'
required:
- customerAccountNumber
- cards
responses:
'202':
description: Order accepted (async)
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Status'
- type: object
properties:
orderReference:
type: string
required:
- orderReference
example:
orderReference: ORD-20260117-001
'400':
$ref: '#/components/responses/BadRequestList'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
CardOrderObject:
example:
additionalEmbossing: new purchase
cardAddress:
companyName: ABC Ltd
addressLines: Unit 10, Industrial Estate Oxford Road
city: Oxford
country: United Kingdom
countryCode: GBR
region: Oxfordshire
zipCode: OX1 3PA
cardCategoryId: 1
cardContact:
emailAddress: jane.smith@example.com
firstName: Jane
lastName: Smith
middleName: B
mobilePhone: '+447700900124'
telephone: '+441234567891'
cardGroupId: 12
cardPIN: '2345'
cardTypeId: 1234
driverName: James Smith
fuelProductRestrictionId: 1
isDriverEmbossed: true
isVRNEmbossed: true
products:
- productId: 101
- productId: 102
purchaseCategoryId: 12
vehicleRegNumber: AB12 CDE
properties:
additionalEmbossing:
description: Any additional embossing text that needs to go on card.
type: string
cardAddress:
$ref: '#/components/schemas/CardAddress'
description: >-
card delivery address, if not provided customer address will be
used. If card address is provided then all the fields inside the
address object needs to be provided.
cardCategoryId:
description: >-
This defines whether card would be Driver, Vehicle of Both type of
the card. The value can be used from the array of Ids from
cardCategory[].id from master/all endpoint.
type: integer
cardContact:
$ref: '#/components/schemas/Contact'
description: >-
card delivery contact, if not provided customer contact will be
used.
cardGroupId:
description: >-
Card Group which needs to be assigned to card. The value can be used
from the array of Ids from cardGroup[].id from master/all endpoint.
Value needs to be selected based on selected cardTypeId.
type: integer
cardPIN:
description: >-
4 digit user selected PIN, if not provided then system generated PIN
is assigned.
maxLength: 4
minLength: 4
pattern: ^[0-9]{4}$
type: string
cardTypeId:
description: >-
Type of a card which needs to be ordered. The value can be used from
the array of Ids from cardType[].id from master/all endpoint.
type: integer
driverName:
description: Driver Name associated to the card.
type: string
fuelProductRestrictionId:
description: >-
Type of a fuel restriction which needs to be assigned to the card,
if not provided default will be assigned. The value can be used from
the array of Ids from fuelProductRestriction[].id from master/all
endpoint.
type: integer
isDriverEmbossed:
description: >-
Flag to determine whether Driver Name needs to be embossed on card
or not.
type: boolean
isVRNEmbossed:
description: >-
Flag to determine whether Vehicle Registration Number needs to be
embossed on card or not.
type: boolean
products:
items:
properties:
productId:
description: >-
non fuel product which needs to be assigned to card. The value
can be used from the array of Ids from product[].id from
master/all endpoint. Maximum 10 products can be added at a
time for the card.
type: integer
type: object
type: array
purchaseCategoryId:
description: >-
Type of a purchase category which needs to be assigned to the card,
if not provided default will be assigned. The value can be used from
the array of Ids from purchaseCategory[].id from master/all
endpoint.
type: integer
vehicleRegNumber:
description: >-
Vehicle Registration number associated to the card. No special
character accepted.
type: string
required:
- cardTypeId
- cardCategoryId
- vehicleRegNumber
type: object
Status:
additionalProperties: false
example: {}
type: object
CardAddress:
properties:
companyName:
type: string
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
required:
- addressLines
- city
- country
- countryCode
- region
- zipCode
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:
BadRequestList:
content:
application/json:
example:
- errorCode: ER-001
errorDescription: Invalid request parameters
- errorCode: ER-002
errorDescription: Missing required field
schema:
items:
$ref: '#/components/schemas/Error'
type: array
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
````