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
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
security:
- oauth2ClientCredentials: []
paths:
/customers:
get:
operationId: listCustomers
tags:
- Customer
summary: List customers
description: |
List subaccounts under the top-level account with pagination.
x-mint:
content: |
**Performance expectations:**
**p50:** 450 ms, **p99:** 1200 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: limit
in: query
schema:
type: integer
default: 50
- name: cursor
in: query
schema:
type: string
- name: customerAccountNumber
in: query
description: Limits the results to direct subaccounts of the specified customer account. If omitted, returns all descendants of the top-level account; the top-level account itself is never included.
schema:
type: string
- name: searchText
in: query
description: Filters customers using a case-insensitive partial match against customerAccountNumber, customerName, or customerBusinessReference. When combined with customerAccountNumber, both filters are applied.
schema:
type: string
responses:
"200":
description: Customers page
content:
application/json:
schema:
$ref: "#/components/schemas/CustomerListResponse"
"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"
/customers/{customerAccountNumber}:
get:
operationId: getCustomer
tags:
- Customer
summary: Get a customer
description: |
Retrieve the full customer profile by Corpay customer account number. Customer's MAIN address and contact is returned in response.
x-mint:
content: |
**Performance expectations:**
**p50:** 170 ms, **p99:** 600 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: customerAccountNumber
in: path
required: true
schema:
type: string
responses:
"200":
description: Customer
content:
application/json:
schema:
$ref: "#/components/schemas/Customer"
"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"
/customers/subcustomer:
post:
operationId: createSubcustomer
tags:
- Customer
summary: Create sub customer
description: |
Create a sub-customer either under customer by supplying the 'Customer Account Number' in the request, or under the top-level customer if not provided in request. The system returns the 'Customer Account Number' of the newly created customer.
Sub-customers can be created only up to two levels below the top-level customer. Supplied Address and Contact data are created as MAIN address and contact for customer.
Top-level customer creation is corpay's responsibility. The top-level customer cannot be created via APIs. All customers under top-level customer are identified as sub customer.
x-mint:
content: |
**Performance expectations:**
**p50:** 250 ms, **p99:** 800 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customerName
- customerContact
- customerAddress
properties:
customerAccountNumber:
type: string
customerName:
type: string
maxLength: 310
customerBusinessReference:
type: string
maxLength: 20
description: Reference to Consumer System Internal Identifier
customerContact:
$ref: "#/components/schemas/Contact"
customerAddress:
$ref: "#/components/schemas/Address"
description: If customer address is provided then all the fields inside the address object needs to be provided.
responses:
"200":
description: Subcustomer's customer account number
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/Status"
- type: object
properties:
customerAccountNumber:
type: string
example:
customerAccountNumber: 50000002122
"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"
/customers/{customerAccountNumber}/updateDetail:
post:
operationId: updateCustomerDetail
tags:
- Customer
summary: Update customer details
description: |
Update mutable attributes of a customer (name, contact, and address). Address and contact updates are updated against MAIN Address and contact of customer.
x-mint:
content: |
**Performance expectations:**
**p50:** 1100 ms, **p99:** 1900 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: customerAccountNumber
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customerName:
type: string
maxLength: 310
customerBusinessReference:
type: string
maxLength: 20
description: Reference to Consumer System Internal Identifier
customerContact:
$ref: "#/components/schemas/Contact"
customerAddress:
$ref: "#/components/schemas/Address"
description: If customer address is provided then all the fields inside the address object needs to be provided.
responses:
"200":
description: Operation status
content:
application/json:
schema:
$ref: "#/components/schemas/Status"
"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"
/customers/{customerAccountNumber}/cardTypes:
get:
operationId: getCustomerCardTypes
tags:
- Customer
summary: Get card types for a customer
description: |
Return the card types available/assigned to a specific customer.
x-mint:
content: |
**Performance expectations:**
**p50:** 160 ms, **p99:** 500 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: customerAccountNumber
in: path
required: true
schema:
type: string
responses:
"200":
description: List of card types
content:
application/json:
schema:
type: array
items:
type: object
properties:
cardTypeId:
type: integer
cardTypeName:
type: string
cardTypeDescription:
type: string
defaultPurchaseCategoryId:
type: integer
purchaseCategoryName:
type: string
isEV:
type: boolean
example:
- cardTypeId: 1
cardTypeName: BE EV
cardTypeDescription: BE EV Card
defaultPurchaseCategoryId: 1
purchaseCategoryName: EV Only
isEV: true
"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"
/customers/{customerAccountNumber}/block:
post:
operationId: blockCustomer
tags:
- Customer
summary: Block a customer
description: |
Temporary Block a customer account (e.g., due to non-payment).
x-mint:
content: |
**Performance expectations:**
**p50:** 1200 ms, **p99:** 1800 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: customerAccountNumber
in: path
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
notes:
type: string
maxLength: 200
responses:
"200":
description: Operation status
content:
application/json:
schema:
$ref: "#/components/schemas/Status"
"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"
/customers/{customerAccountNumber}/unblock:
post:
operationId: unblockCustomer
tags:
- Customer
summary: Unblock (reactivate) a customer
description: |
Reactivate a previously blocked customer account.
x-mint:
content: |
**Performance expectations:**
**p50:** 900 ms, **p99:** 1800 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: customerAccountNumber
in: path
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
notes:
type: string
maxLength: 200
responses:
"200":
description: Operation status
content:
application/json:
schema:
$ref: "#/components/schemas/Status"
"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"
/customers/{customerAccountNumber}/close:
post:
operationId: closeCustomer
tags:
- Customer
summary: Close a customer permanently
description: |
Close a customer account permanently.
x-mint:
content: |
**Performance expectations:**
**p50:** 1200 ms, **p99:** 1800 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: customerAccountNumber
in: path
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
notes:
type: string
maxLength: 200
responses:
"200":
description: Operation status
content:
application/json:
schema:
$ref: "#/components/schemas/Status"
"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"
/cards/order:
post:
operationId: orderCard
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.
x-mint:
content: |
**Performance expectations:**
**p50:** 300 ms, **p99:** 900 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
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"
/cards/{cardIdentifier}:
get:
operationId: getCard
tags:
- Card
summary: Get a card
description: |
Retrieve a single card by its Corpay card identifier.
x-mint:
content: |
**Performance expectations:**
**p50:** 170 ms, **p99:** 600 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: cardIdentifier
in: path
required: true
schema:
type: integer
responses:
"200":
description: Card
content:
application/json:
schema:
$ref: "#/components/schemas/Card"
"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"
/cards/search:
post:
operationId: searchCards
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.
x-mint:
content: |
**Performance expectations:**
**p50:** 220 ms, **p99:** 1900 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
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"
"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"
/cards/{cardIdentifier}/block:
post:
operationId: blockCard
tags:
- Card
summary: Block a card
description: |
Temporarily block the card.
x-mint:
content: |
**Performance expectations:**
**p50:** 500 ms, **p99:** 2000 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: cardIdentifier
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- statusReasonId
properties:
statusReasonId:
type: integer
notes:
type: string
maxLength: 200
example:
statusReasonId: 2
notes: Lost report
responses:
"200":
description: Operation status
content:
application/json:
schema:
$ref: "#/components/schemas/Status"
"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"
/cards/{cardIdentifier}/unblock:
post:
operationId: unblockCard
tags:
- Card
summary: Unblock a card
description: |
Unblock a previously blocked card.
x-mint:
content: |
**Performance expectations:**
**p50:** 900 ms, **p99:** 2100 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: cardIdentifier
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- statusReasonId
properties:
statusReasonId:
type: integer
notes:
type: string
maxLength: 200
example:
statusReasonId: 2
notes: Unblock after validation
responses:
"200":
description: Operation status
content:
application/json:
schema:
$ref: "#/components/schemas/Status"
"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"
/cards/{cardIdentifier}/replace:
post:
operationId: replaceCard
tags:
- Card
summary: Replace a card
description: |
Block and replace a card, optionally modifying card parameters. If card parameters are not provided, the replaced card contains exact same properties as original card.
x-mint:
content: |
**Performance expectations:**
**p50:** 1200 ms, **p99:** 2200 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: cardIdentifier
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
cardTypeId:
type: integer
purchaseCategoryId:
type: integer
additionalEmbossing:
type: string
maxLength: 200
driverName:
type: string
maxLength: 80
vehicleRegNumber:
type: string
maxLength: 8
cardGroupId:
type: integer
example:
cardTypeId: 1
purchaseCategoryId: 2
additionalEmbossing: FLEET-01
driverName: James Smith
vehicleRegNumber: AB12 CDE
cardGroupId: 12
responses:
"200":
description: Operation status
content:
application/json:
schema:
$ref: "#/components/schemas/Status"
"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"
/cards/{cardIdentifier}/cancel:
post:
operationId: cancelCard
tags:
- Card
summary: Cancel a card
description: |
Cancel the card permanently.
x-mint:
content: |
**Performance expectations:**
**p50:** 900 ms, **p99:** 2500 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: cardIdentifier
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- statusReasonId
properties:
statusReasonId:
type: integer
notes:
type: string
maxLength: 200
example:
statusReasonId: 2
notes: Card cancelled by admin
responses:
"200":
description: Operation status
content:
application/json:
schema:
$ref: "#/components/schemas/Status"
"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"
/cards/{cardIdentifier}/replacedCard:
get:
operationId: getReplacedCard
tags:
- Card
summary: Get replaced card details
description: |
Given an old card identifier, return the new card identifier and card details after replace card request has been done.
This API can be used in case of failure obtaining data from webhook for replaced card.
x-mint:
content: |
**Performance expectations:**
**p50:** 220 ms, **p99:** 700 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: cardIdentifier
description: Card Identifier of the Original Card
in: path
required: true
schema:
type: integer
responses:
"200":
description: Old and new card details
content:
application/json:
schema:
$ref: "#/components/schemas/ReplacedCardResponse"
"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"
/cards/{cardIdentifier}/reprintPIN:
post:
operationId: reprintPIN
tags:
- Card
summary: Request PIN reprint
description: |
Request a PIN letter reprint to the supplied card delivery address.
x-mint:
content: |
**Performance expectations:**
**p50:** 1000 ms, **p99:** 1500 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: cardIdentifier
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cardAddress
properties:
cardAddress:
$ref: "#/components/schemas/Address"
description: If card address is provided then all the fields inside the address object needs to be provided.
example:
cardAddress:
addressLines: Unit 10, Industrial Estate Oxford Road
zipCode: OX1 3PA
city: Oxford
region: Oxfordshire
country: United Kingdom
countryCode: GB
responses:
"200":
description: Operation status
content:
application/json:
schema:
$ref: "#/components/schemas/Status"
"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"
/cards/lodging:
post:
operationId: lodgeCard
tags:
- Card
summary: Lodge a card into app
description: |
Lodge a physical card into the app and obtain the EV card number, keyIdentifier, and cardNumber. Lodging of card will be done based on provided visual card number.
x-mint:
content: |
**Performance expectations:**
**p50:** 170 ms, **p99:** 600 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cardNumber
properties:
cardNumber:
type: string
example:
cardNumber: 4715XXXXXXXX0064
responses:
"200":
description: EV identifiers and card number
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/Status"
- type: object
properties:
evCardNumber:
type: string
keyIdentifier:
type: string
cardNumber:
type: string
example:
evCardNumber: NL-TBE-2323-2323
keyIdentifier: 2323d
cardNumber: 4715XXXXXXXX0064
"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"
/locations/geosearch/rectangle:
post:
summary: Search locations within a rectangle
description: Search for charging locations within a specified rectangle defined by two diagonal points. The rectangle coordinates are passed via the `topLatitude`, `bottomLatitude`, `leftLongitude`, and `rightLongitude` query parameters; the request body contains only filters and options. Returns up to 300 locations.
operationId: searchLocationsByRectangle
tags:
- Geosearch
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/DriveRectangleRequest"
example:
filters:
connectorStandards:
- Combo
capabilities:
- CHARGING_PROFILE_CAPABLE
options:
includeAvailableOnly: false
parameters:
- name: topLatitude
in: query
required: true
description: Latitude of the top edge of the rectangle in decimal degrees (e.g. N58°30' is represented as 58.5). Must be greater than bottomLatitude.
example: 52.354551
schema:
type: number
format: double
minimum: -90
maximum: 90
- name: bottomLatitude
in: query
required: true
description: Latitude of the bottom edge of the rectangle in decimal degrees (e.g. S58°30' is represented as -58.5)
example: 52.354551
schema:
type: number
format: double
minimum: -90
maximum: 90
- name: leftLongitude
in: query
required: true
description: Longitude of the left edge of the rectangle in decimal degrees (e.g. E014°45' is represented as 14.75). Must be less than rightLongitude.
example: 4.7391593
schema:
type: number
format: double
minimum: -180
maximum: 180
- name: rightLongitude
in: query
required: true
description: Longitude of the right edge of the rectangle in decimal degrees (e.g. E014°45' is represented as 14.75)
example: 4.7391593
schema:
type: number
format: double
minimum: -180
maximum: 180
- name: limit
in: query
description: Number of locations returned in the response (doesn't apply when aggregation is enabled)
schema:
type: number
maximum: 300
default: 300
- name: aggregate
in: query
description: If true, the results will be aggregated. For large radius it makes the response much faster.
required: false
schema:
type: boolean
default: false
- name: aggregationPrecision
in: query
description: Value between 2 and 9. The bigger value is, the smaller is the cell size of the grid for aggregation. If not passed, a default value, based on radius, is assumed.
required: false
schema:
type: integer
minimum: 2
maximum: 9
- name: language
schema:
type: string
minLength: 2
maxLength: 2
in: query
required: false
example: en
description: "Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv."
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/DriveBaseResponseListLocation"
example:
locations:
- id: 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=
name: Ebee Smart Technologies
coordinates:
latitude: "52.475911"
longitude: "13.350794"
evses:
- uid: 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE
evse_id: +49*839*030*000074
physical_reference: "4"
status: AVAILABLE
connectors:
- {}
capabilities:
- RESERVABLE
- PLUG_AND_CHARGE_CAPABLE
- PLUG_AND_CHARGE_CAPABLE
last_updated: 2025-01-15T10:30:00Z
operator:
id: "881941"
name: Ebee Smart Technologies
hotline: "+498944255071"
external_id: DE*ABC
operator_display_name: Sub-operator X
opening_times:
twentyfourseven: false
regular_hours:
- weekday: 1
period_begin: 00:10
period_end: 29:59
exceptional_openings:
- period_begin: 2025-01-15T10:30:00Z
period_end: 2025-01-15T10:30:00Z
exceptional_closings:
- period_begin: 2025-01-15T10:30:00Z
period_end: 2025-01-15T10:30:00Z
directions:
- language: DE
text: example
country: DEU
state: Bayern
city: Berlin
postal_code: 10829
address: EUREF CAMPUS 4-5
openNow: false
is_green_energy: false
last_updated: 2024-03-15T14:30:00Z
aggregates:
- coordinates:
latitude: "52.475911"
longitude: "13.350794"
count: 1
"400":
description: The provided query parameters, route parameters or body is invalid.
content:
application/json:
schema:
$ref: "#/components/schemas/DriveInvalidRequestErrorResponse"
example:
message: Invalid request payload
details:
- field X is required
"500":
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/DriveErrorResponse"
example:
message: Resource not found
/locations/geosearch/{locationId}:
get:
tags:
- Geosearch
summary: Get a location
description: Returns detailed location data for a single charging location, with optional pricing context. Only one of keyIdentifier or fleetId can be provided in a single request. If none are provided, default prices are returned.
operationId: getLocationById
parameters:
- name: locationId
in: path
description: URL-encoded location id.
required: true
schema:
type: string
- name: keyIdentifier
in: query
description: The keyIdentifier of a charging key, will be used to look up specific prices for this charging key.
required: false
schema:
type: string
- name: fleetId
in: query
description: The id of a fleet organization, will be used to look up specific prices for this fleet.
required: false
schema:
type: string
- name: language
in: query
description: "Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv."
required: false
schema:
type: string
minLength: 2
maxLength: 2
example: en
responses:
"200":
description: Location
content:
application/json:
schema:
$ref: "#/components/schemas/DriveLocation"
example:
id: 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=
name: Ebee Smart Technologies
coordinates:
latitude: "52.475911"
longitude: "13.350794"
evses:
- uid: 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE
evse_id: +49*839*030*000074
physical_reference: "4"
status: AVAILABLE
connectors:
- id: 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJEM0D69tJVN05/1hZ1zxqZSJ9kBdNsmfryS0+gvjLNZvdF1pDHJuCTydsJX6vPZh7U=
standard: Type2
power: 22000
power_type: AC_3_PHASE
price:
id: 4370769f30bd7927
description: € 0.56/kWh, € 0.10/min (> 2 h)
currency: EUR
priceIncludesVat: "true"
vatRate: "22"
elements:
- {}
max_amperage: 32
max_voltage: 400
capabilities:
- RESERVABLE
- PLUG_AND_CHARGE_CAPABLE
- PLUG_AND_CHARGE_CAPABLE
last_updated: 2025-01-15T10:30:00Z
operator:
id: "881941"
name: Ebee Smart Technologies
hotline: "+498944255071"
external_id: DE*ABC
operator_display_name: Sub-operator X
opening_times:
twentyfourseven: false
regular_hours:
- weekday: 1
period_begin: 00:10
period_end: 29:59
exceptional_openings:
- period_begin: 2025-01-15T10:30:00Z
period_end: 2025-01-15T10:30:00Z
exceptional_closings:
- period_begin: 2025-01-15T10:30:00Z
period_end: 2025-01-15T10:30:00Z
directions:
- language: DE
text: example
country: DEU
state: Bayern
city: Berlin
postal_code: 10829
address: EUREF CAMPUS 4-5
openNow: false
is_green_energy: false
last_updated: 2024-03-15T14:30:00Z
"404":
description: Location not found
content:
application/json:
schema:
$ref: "#/components/schemas/DriveErrorResponse"
example:
message: Resource not found
"500":
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/DriveErrorResponse"
example:
message: Resource not found
/sessions/start:
post:
tags:
- Remote Charging
summary: Start a remote charging session
operationId: startRemoteSession
description: Starts a remote charging session with the given charging key on the given connector.
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/DriveSessionStartRequest"
example:
connectorId: aHeS4zN1UjzJf/HVDH66SbaItXqHvfLxexulktxTqJavgcbozuV9KJGqNYjmaQPwTb4Ck9wTZcWeEdfeco1srw==
keyIdentifier: BnZd3qp87z
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/DriveSessionStartResponse"
example:
sessionId: AAdmD55q8Vz
"400":
description: The provided query parameters, route parameters or body is invalid.
content:
application/json:
schema:
$ref: "#/components/schemas/DriveInvalidRequestErrorResponse"
example:
message: Invalid request payload
details:
- field X is required
"403":
description: Forbidden. The charging key is not allowed to charge, or the connector won't allow remote charging.
content:
application/json:
schema:
$ref: "#/components/schemas/DriveErrorResponse"
example:
message: Resource not found
"404":
description: Charging key or connector is not found
content:
application/json:
schema:
$ref: "#/components/schemas/DriveErrorResponse"
example:
message: Resource not found
"500":
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/DriveErrorResponse"
example:
message: Resource not found
/sessions/{sessionId}/stop:
post:
tags:
- Remote Charging
summary: Stop a remote charging session
operationId: stopRemoteSession
description: Stops the given remote charging session. Only sessions started remotely can be remotely stopped.
parameters:
- name: sessionId
in: path
description: session id
example: AAdmD55q8Vz
required: true
schema:
type: string
responses:
"200":
description: OK
"404":
description: Session not found
content:
application/json:
schema:
$ref: "#/components/schemas/DriveErrorResponse"
example:
message: Resource not found
"500":
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/DriveErrorResponse"
example:
message: Resource not found
/sessions/{sessionId}:
get:
tags:
- EV Session
summary: Get a charging session
operationId: getSessionById
description: Returns charging session details
parameters:
- name: sessionId
in: path
description: Session id
required: true
schema:
type: string
responses:
"200":
description: Session
content:
application/json:
schema:
$ref: "#/components/schemas/DriveSession"
example:
balanceStatus: PROCESSING
sessionStatus: CREATED
charger:
chargingStationName: Drive_API_Test1_Station1
city: Solna
connectorLabel: "1"
evseId: SE*CND*EC1*1
streetName: Rättarvägen
balanceAmountMinor: "-2160"
chargingKeyType: virtual
connectorId: O9UXK+YI5Q6i0FoI4qHwcA==
duration: PT28.913S
energy:
unit: WH
value: 57
paymentMethod: CREDIT_CARD
price:
currencyCode: EUR
minorExclVat: 2785
minorInclVat: 1
vat: "17.5"
receiptAvailable: true
sessionId: AAdmD55q8Vz
site: Drive_API_Test1
startTime: 2021-01-30T10:00:00.111111111Z
transactions:
- paymentMethod: CREDIT_CARD
paymentOutcome: CHARGE
amount:
currencyCode: EUR
minorExclVat: 2785
minorInclVat: 1
vat: "17.5"
time: 2021-01-30T10:00:00.111111111Z
"404":
description: Session not found
content:
application/json:
schema:
$ref: "#/components/schemas/DriveErrorResponse"
example:
message: Resource not found
"500":
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/DriveErrorResponse"
example:
message: Resource not found
/customers/{customerAccountNumber}/transactions:
post:
operationId: getCustomerTransactions
tags:
- Transaction
summary: Get transactions for a customer
description: |
Retrieve transactions across all cards under a customer with filters and pagination.
ProductIds and CardIdentifiers are Identifiers of Product and Card from Corpay System.
Note: after a user stopped the session, a transaction might take up to 10 minutes to be available via the transactions endpoints.
x-mint:
content: |
**Performance expectations:**
**p50:** 300 ms, **p99:** 1600 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: customerAccountNumber
in: path
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
transactionDateFrom:
type: string
format: date
transactionDateTo:
type: string
format: date
billingStatus:
type: string
enum:
- Billed
- Unbilled
- All
cardIdentifiers:
type: array
items:
type: integer
productIds:
type: array
items:
type: integer
cursor:
type: string
limit:
type: integer
sortExpression:
type: string
filter:
type: object
description: Filters transactions using the supplied card, driver, network, and vehicle criteria.
properties:
cardNumber:
type: string
description: Card number associated with the transaction.
driverName:
type: string
description: Driver name associated with the transaction.
network:
type: string
description: Network name associated with the transaction.
cardAddtionalData:
type: string
description: Additional customer-specific data supplied when the card was ordered but not embossed on the card.
vehicleRegistrationNumber:
type: string
description: Vehicle registration number associated with the transaction.
partialMatch:
type: boolean
description: When true, each supplied string filter uses a case-insensitive partial match. When false, each supplied string filter uses a case-insensitive exact match.
responses:
"200":
description: Transactions
content:
application/json:
schema:
$ref: "#/components/schemas/TransactionsResponse"
"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"
/cards/{cardIdentifier}/transactions:
post:
operationId: getCardTransactions
tags:
- Transaction
summary: Get transactions for a card
description: |
Retrieve transactions for a single card with filters and pagination.
ProductIds identifies the Products from the Corpay System.
Note: after a user stopped the session, a transaction might take up to 10 minutes to be available via the transactions endpoints.
x-mint:
content: |
**Performance expectations:**
**p50:** 250 ms, **p99:** 1500 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
parameters:
- name: cardIdentifier
in: path
required: true
schema:
type: integer
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
transactionDateFrom:
type: string
format: date
transactionDateTo:
type: string
format: date
billingStatus:
type: string
enum:
- Billed
- Unbilled
- All
productIds:
type: array
items:
type: integer
cursor:
type: string
limit:
type: integer
sortExpression:
type: string
filter:
type: object
description: Filters transactions using the supplied card, driver, network, and vehicle criteria.
properties:
cardNumber:
type: string
description: Card number associated with the transaction.
driverName:
type: string
description: Driver name associated with the transaction.
network:
type: string
description: Network name associated with the transaction.
cardAddtionalData:
type: string
description: Additional customer-specific data supplied when the card was ordered but not embossed on the card.
vehicleRegistrationNumber:
type: string
description: Vehicle registration number associated with the transaction.
partialMatch:
type: boolean
description: When true, each supplied string filter uses a case-insensitive partial match. When false, each supplied string filter uses a case-insensitive exact match.
responses:
"200":
description: Transactions
content:
application/json:
schema:
$ref: "#/components/schemas/TransactionsResponse"
"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"
/master/all:
get:
operationId: getMasterData
tags:
- Master
summary: Get master data
description: |
Return master/reference data required for card operations based on top level customer
(card types, categories, products, statuses, reasons, groups, regions, countries).
x-mint:
content: |
**Performance expectations:**
**p50:** 950 ms, **p99:** 1300 ms.
Measured on successful requests (2xx), server-side only.
[How to interpret these metrics](/performance)
responses:
"200":
description: Master data
content:
application/json:
schema:
$ref: "#/components/schemas/MasterData"
"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"
/cards/statusUpdate:
post:
operationId: registerCardStatusUpdate
tags:
- Webhooks
summary: Register for card status updates
description: |
To get card status updates from Corpay system, register for webhook using Card Identifier.
for each card the registration needs to be done separately. if hmac_enabled is set true then hmac_secret is needed.
max_retries value by default it set to 1.
Upon updates on card status, the data that is shared on registered target URL would contain following properties:
example:
cardIdentifier: 1234
previousStatus: Active
newStatus: Blocked
changedAt: '2026-01-17T10:30:00Z'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cardIdentifier
- target_url
properties:
cardIdentifier:
type: integer
target_url:
type: string
description: url for the system where webhook should respond to in case of event.
hmac_enabled:
type: boolean
hmac_secret:
type: string
max_retries:
type: integer
responses:
"201":
description: created
content:
application/json:
schema:
type: object
properties:
status:
type: string
integration_key:
type: string
webhook_id:
type: string
example:
status: created
integration_key: corpay.gfn.cards.statusUpdate.cardIdentifier.123426
webhook_id: 744317f9-ca90-4388-bb00-f2a10f1db627
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"409":
description: Conflict
content:
application/json:
schema:
type: object
properties:
error:
type: string
integration_key:
type: string
example:
error: Integration key already registered
integration_key: corpay.gfn.cards.statusUpdate.cardIdentifier.123426
"500":
$ref: "#/components/responses/InternalServerError"
delete:
operationId: deRegisterCardStatusUpdate
tags:
- Webhooks
summary: De-Register for card status updates.
description: |
To stop receiving card status updates from Corpay system, de-register for webhook using Card Identifier.
for each card the de-registration needs to be done separately. if hmac_enabled was set true during register then hmac_secret and hmac_enabled flag is needed.
max_retries value by default it set to 1.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cardIdentifier
- target_url
properties:
cardIdentifier:
type: integer
target_url:
type: string
description: url for the system where webhook should stop responding to in case of event.
hmac_enabled:
type: boolean
hmac_secret:
type: string
max_retries:
type: integer
responses:
"204":
description: acknowledgement
"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"
/cards/created:
post:
operationId: registerCardCreated
tags:
- Webhooks
summary: Register for getting details of newly created cards.
description: |
To get newly ordered cards data from Corpay system, register for webhook using Customer Account Number and Order reference (Which was part of response of card order API).
Please note, the registration needs to be done immediately after card order.
If registration process has failed and consumer has missed the response, then same data can be obtained using /cards/search API.
for each card order the registration needs to be done separately. if hmac_enabled is set true then hmac_secret is needed.
max_retries value by default it set to 1.
Upon successful card order, the newly created cards will be published to target url as array of card object.
The cards created will not be activated immediately, the card will be activated once the physical card has been created and sent to card delivery address, which takes upto 2 days.
The webhook would respond with created card data once the cards are activated in Corpay System, Which would take upto 24 - 36 hrs.
To get the real time status of the card, register for card status updates using Card Identifier received from this webhook.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customerAccountNumber
- orderReference
- target_url
properties:
customerAccountNumber:
type: string
orderReference:
type: string
target_url:
type: string
description: url for the system where webhook should respond to in case of event.
hmac_enabled:
type: boolean
hmac_secret:
type: string
max_retries:
type: integer
responses:
"201":
description: created
content:
application/json:
schema:
type: object
properties:
status:
type: string
integration_key:
type: string
webhook_id:
type: string
example:
status: created
integration_key: corpay.gfn.cards.created.customerAccountNumber.7000001565.orderReference.593153cc-7cb0-48e4-8f7c-e9bea6ce8bb9
webhook_id: 744317f9-ca90-4388-bb00-f2a10f1db627
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"409":
description: Conflict
content:
application/json:
schema:
type: object
properties:
error:
type: string
integration_key:
type: string
example:
error: Integration key already registered
integration_key: corpay.gfn.cards.created.customerAccountNumber.7000001565.orderReference.593153cc-7cb0-48e4-8f7c-e9bea6ce8bb9
"500":
$ref: "#/components/responses/InternalServerError"
delete:
operationId: deRegisterCardCreated
tags:
- Webhooks
summary: De-Register for getting details of newly created cards.
description: |+
Once the newly created cards are received against order reference, use the API to de register webhook for the Order Reference.
for each card order the registration needs to be done separately. if hmac_enabled was enabled during registration then hmac_secret and hmac_enabled flag is needed.
max_retries value by default it set to 1.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customerAccountNumber
- orderReference
- target_url
properties:
customerAccountNumber:
type: string
orderReference:
type: string
target_url:
type: string
description: url for the system where webhook should stop publishing to in case of event.
hmac_enabled:
type: boolean
hmac_secret:
type: string
max_retries:
type: integer
responses:
"204":
description: acknowledgement
"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"
/cards/replaced:
post:
operationId: registerCardReplaced
tags:
- Webhooks
summary: Register for receiving replaced card information.
description: |+
To get replaced card data from Corpay system, register for webhook using Card Identifier of original card.
for each card the registration needs to be done separately. if hmac_enabled is set true then hmac_secret is needed.
max_retries value by default it set to 1.
If registration process has failed and consumer has missed the response, then same data can be obtained using /cards/{cardIdentifier}/replacedCard API.
Upon successful replacement of the card, the replaced card object would be published to target url.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cardIdentifier
- target_url
properties:
cardIdentifier:
type: integer
target_url:
type: string
description: url for the system where webhook should respond to in case of event.
hmac_enabled:
type: boolean
hmac_secret:
type: string
max_retries:
type: integer
responses:
"201":
description: created
content:
application/json:
schema:
type: object
properties:
status:
type: string
integration_key:
type: string
webhook_id:
type: string
example:
status: created
integration_key: corpay.public.api.card.replaced.cardIdenitifier.2823795
webhook_id: 744317f9-ca90-4388-bb00-f2a10f1db627
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"409":
description: Conflict
content:
application/json:
schema:
type: object
properties:
error:
type: string
integration_key:
type: string
example:
error: Integration key already registered
integration_key: corpay.public.api.card.replaced.cardIdenitifier.2823795
"500":
$ref: "#/components/responses/InternalServerError"
delete:
operationId: deRegisterCardReplaced
tags:
- Webhooks
summary: De-Register for receiving replaced card information.
description: |+
To stop receiving replaced card data from Corpay system, register for webhook using Card Identifier of original card.
for each card the registration needs to be done separately. if hmac_enabled was enabled during registration then hmac_secret and hmac_enabled flag is needed.
max_retries value by default it set to 1.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cardIdentifier
- target_url
properties:
cardIdentifier:
type: integer
target_url:
type: string
description: url for the system where webhook should stop publishing to in case of event.
hmac_enabled:
type: boolean
hmac_secret:
type: string
max_retries:
type: integer
responses:
"204":
description: acknowledgement
"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"
webhooks:
cardCreated:
post:
description: |
Sent to the consumer's registered target URL whenever a card’s are created.
requestBody:
content:
application/json:
example:
cards:
- additionalEmbossing: FLEET-01
cardDeliveryAddress:
companyName: ACME Ltd.
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"
schema:
$ref: "#/components/schemas/CardCreatedEvent"
required: true
responses:
"200":
description: Event received successfully
"400":
description: Invalid payload
"401":
description: Unauthorized
"500":
description: Consumer processing error
security: []
summary: Card creation notification
tags:
- Webhooks
cardReplaced:
post:
description: |
Sent to the consumer's registered target URL whenever a card is replaced.
requestBody:
content:
application/json:
example:
additionalEmbossing: FLEET-01
cardDeliveryAddress:
addressLines: Unit 10, Industrial Estate Oxford Road
city: Oxford
country: United Kingdom
countryCode: GB
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
customerAccountNumber: "23444444"
driverName: James Smith
fuelProductRestriction:
productRestrictionId: 1
productRestrictionName: Fuel Only
keyIdentifier: 2323s
newCardIdentifier: 1244
primaryVisualCardNumber: "3080002323232"
products:
- productId: 101
productName: Car Wash
- productId: 102
productName: Lubricants
purchaseCategoryName: Fuel
secondaryCardNumber: NL-TBE-2323-2323
status: Active
vehicleRegNumber: AB12 CDE
schema:
$ref: "#/components/schemas/CardReplacedEvent"
required: true
responses:
"200":
description: Event received successfully
"400":
description: Invalid payload
"401":
description: Unauthorized
"500":
description: Consumer processing error
security: []
summary: Card Replaced notification
tags:
- Webhooks
cardStatusUpdated:
post:
description: |
Sent to the consumer's registered target URL whenever a card’s status changes.
requestBody:
content:
application/json:
example:
cardIdentifier: 1234
changedAt: 2026-01-17T10:30:00Z
newStatus: Blocked
previousStatus: Active
schema:
$ref: "#/components/schemas/CardStatusUpdateEvent"
required: true
responses:
"200":
description: Event received successfully
"400":
description: Invalid payload
"401":
description: Unauthorized
"500":
description: Consumer processing error
security: []
summary: Card status update notification
tags:
- Webhooks
components:
responses:
BadRequest:
content:
application/json:
example:
errorCode: ER-001
errorDescription: Invalid request parameters
schema:
$ref: "#/components/schemas/Error"
description: Bad request - validation error
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
Conflict:
description: Conflict - operation conflicts with current state
Forbidden:
description: Forbidden - insufficient permissions
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
NotFound:
description: Not found - resource does not exist
Unauthorized:
description: Unauthorized - missing or invalid authentication token
schemas:
Address:
properties:
addressLines:
type: string
city:
type: string
country:
description: Country name as returned in country[].name by GET /master/all.
type: string
countryCode:
description: Country code as returned in country[].countryCode by GET /master/all.
type: string
region:
description: Region name as returned in region[].name by GET /master/all.
type: string
zipCode:
type: string
type: object
CardAddress:
properties:
companyName:
type: string
description: Company name associated with the card delivery address.
addressLines:
type: string
city:
type: string
country:
description: Country name as returned in country[].name by GET /master/all.
type: string
countryCode:
description: Country code as returned in country[].countryCode by GET /master/all.
type: string
region:
description: Region name as returned in region[].name by GET /master/all.
type: string
zipCode:
type: string
required:
- addressLines
- city
- country
- countryCode
- region
- zipCode
type: object
Card:
example:
additionalEmbossing: FLEET-01
cardDeliveryAddress:
companyName: ACME Ltd
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
customerAccountNumber: "23444444"
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
properties:
additionalEmbossing:
type: string
cardDeliveryAddress:
$ref: "#/components/schemas/CardAddress"
cardDeliveryContact:
$ref: "#/components/schemas/Contact"
cardIdentifier:
type: integer
cardType:
type: string
customerAccountNumber:
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
CardCreatedEvent:
properties:
cards:
items:
$ref: "#/components/schemas/Card"
type: array
customerAccountNumber:
type: string
type: object
CardListResponse:
example:
cards:
- additionalEmbossing: FLEET-01
cardDeliveryAddress:
companyName: ACME ltd
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
lastPage: false
nextCursor: "100"
totalCount: 125
properties:
cards:
items:
properties:
additionalEmbossing:
type: string
cardDeliveryAddress:
$ref: "#/components/schemas/CardAddress"
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
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: Delivery address for the card. If omitted, the customer's address is used. If provided, all required CardAddress fields must be supplied.
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
CardReplacedEvent:
$ref: "#/components/schemas/ReplacedCardResponse"
CardStatusUpdateEvent:
properties:
cardIdentifier:
example: 1234
type: integer
changedAt:
example: 2026-01-17T10:30:00Z
format: date-time
type: string
newStatus:
example: Blocked
type: string
previousStatus:
example: Active
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
Customer:
example:
customerAccountNumber: "50000012345"
customerAddress:
addressLines: 123 Main Street Suite 5
city: London
country: United Kingdom
countryCode: GBR
region: Greater London
zipCode: AB12 3CD
customerBusinessReference: "10234398"
customerContact:
emailAddress: john.doe@example.com
firstName: John
lastName: Doe
middleName: A
mobilePhone: "+447700900123"
telephone: "+441234567890"
customerName: Acme Corp
status: Active
statusIdentifier: 1
countOfSubAccount: 2
parentCustomerAccountNumber: "980000000"
parentCustomerIdentifier: 3211
properties:
customerAccountNumber:
type: string
customerAddress:
$ref: "#/components/schemas/Address"
customerBusinessReference:
description: Reference to Consumer System Internal Identifier
type: string
customerContact:
$ref: "#/components/schemas/Contact"
customerName:
type: string
status:
type: string
statusIdentifier:
type: integer
description: Identifier of the customer's current status.
countOfSubAccount:
type: integer
description: Number of direct subaccounts of this customer.
parentCustomerAccountNumber:
type: string
description: Account number of the customer's parent account.
parentCustomerIdentifier:
type: integer
description: Internal identifier of the customer's parent account.
required:
- customerAccountNumber
- customerName
- status
type: object
CustomerListResponse:
example:
customers:
- customerAccountNumber: "1234567890"
customerAddress:
addressLines: 123 Main Street Apt 4B
city: London
country: United Kingdom
countryCode: GBR
region: Greater London
zipCode: AB12 3CD
customerBusinessReference: "123444"
customerContact:
emailAddress: john.doe@example.com
firstName: John
lastName: Doe
middleName: A
mobilePhone: "+447700900123"
telephone: "+441234567890"
customerName: John Doe
status: Active
statusIdentifier: 1
countOfSubAccount: 2
parentCustomerAccountNumnber: "980000000"
parentCustomerIdentifier: 3211
hasNextPage: true
lastPage: true
nextCursor: "12131"
totalCount: 100
properties:
customers:
items:
$ref: "#/components/schemas/Customer"
type: array
hasNextPage:
type: boolean
lastPage:
type: boolean
nextCursor:
type: string
totalCount:
type: integer
type: object
DriveAggregate:
properties:
coordinates:
$ref: "#/components/schemas/DriveCoordinates"
description: Aggregate center coordinates returned as strings.
count:
description: Number of locations around this point.
minimum: 2
type: integer
required:
- coordinates
- count
type: object
DriveBaseResponseListLocation:
description: Response payload containing matching locations and aggregate metadata for a geosearch query.
properties:
aggregates:
description: Present only if 'aggregate' request param = true. Contains only aggregates of 2 or more locations. Single locations are returned in 'locations' array.
items:
$ref: "#/components/schemas/DriveAggregate"
type: array
locations:
description: Locations matching the geosearch criteria.
items:
$ref: "#/components/schemas/DriveLocation"
type: array
required:
- locations
type: object
DriveBusinessDetails:
properties:
external_id:
example: DE*ABC
type: string
hotline:
example: "+498944255071"
type: string
id:
example: "881941"
type: string
name:
example: Ebee Smart Technologies
maxLength: 100
minLength: 0
type: string
required:
- id
- name
type: object
DriveCapabilities:
enum:
- REMOTE_START_STOP_CAPABLE
- PLUG_AND_CHARGE_CAPABLE
type: string
DriveConnector:
properties:
id:
description: Unique identifier for this connector. Use this ID when starting charging sessions.
example: 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJEM0D69tJVN05/1hZ1zxqZSJ9kBdNsmfryS0+gvjLNZvdF1pDHJuCTydsJX6vPZh7U=
minLength: 0
type: string
max_amperage:
description: Maximum current in Amperes that this connector can provide
example: 32
type: number
max_voltage:
description: Maximum voltage in Volts that this connector can provide
example: 400
type: number
power:
description: Maximum power output in Watts. For AC chargers, this is typically between 3.7kW and 43kW. For DC chargers, typically between 50kW and 350kW.
example: 22000
type: integer
power_type:
enum:
- AC_1_PHASE
- AC_3_PHASE
- DC
- AC
example: AC_3_PHASE
type: string
price:
description: Pricing information for this connector. Only available when retrieving a specific location.
properties:
currency:
description: Three-letter currency code ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format)
example: EUR
type: string
description:
description: Human-readable description of the pricing structure
example: € 0.56/kWh, € 0.10/min (> 2 h)
type: string
elements:
description: Possible prices for that connector, depending on restrictions
items:
$ref: "#/components/schemas/DrivePriceElement"
type: array
id:
example: 4370769f30bd7927
type: string
priceIncludesVat:
description: Indicates whether the price includes VAT or not (same meaning as for the CDR object)
example: "true"
type: boolean
vatRate:
description: The VAT rate that is applied to the price (in case priceIncludesVat=true) or the VAT rate that should be applied to the price (in case priceIncludesVat=false)
example: "22"
type: string
type: object
standard:
$ref: "#/components/schemas/DriveConnectorStandard"
description: Physical connector type/standard (e.g., Type2, Combo, CHADEMO). Use `Combo` for CCS connectors.
required:
- id
- standard
- power_type
type: object
DriveConnectorStandard:
description: Connector standard accepted by the API. Use `Combo` for CCS connectors. `CHADEMO` is the preferred token; `Chademo` is a legacy alias.
enum:
- 3PinSquare
- Cee2Poles
- CeeBlue
- CeePlus
- CeeRed
- Combo
- Marechal
- Nema5
- Scame
- CHADEMO
- Chademo
- Type1
- Type2
- Type3
- TypeE
- Schuko
- UNKNOWN
- T23
- T13
- T15
- Tesla
- DOMESTIC_A
- DOMESTIC_B
- DOMESTIC_C
- DOMESTIC_D
- DOMESTIC_E
- DOMESTIC_F
- DOMESTIC_G
- DOMESTIC_H
- DOMESTIC_I
- DOMESTIC_J
- DOMESTIC_K
- DOMESTIC_L
- IEC_60309_2_single_16
- IEC_60309_2_three_16
- IEC_60309_2_three_32
- IEC_60309_2_three_64
- IEC_62196_T1
- IEC_62196_T1_COMBO
- IEC_62196_T2
- IEC_62196_T2_COMBO
- IEC_62196_T3A
- IEC_62196_T3C
- TESLA_R
- TESLA_S
example: Type2
type: string
DriveConnectorStatus:
enum:
- AVAILABLE
- CHARGING
- BLOCKED
- INOPERATIVE
- OCCUPIED
- OFFLINE
- OUTOFORDER
- PLANNED
- REMOVED
- RESERVED
- UNKNOWN
- UNAVAILABLE
example: AVAILABLE
type: string
DriveCoordinates:
description: Latitude and longitude values serialized as strings with fixed decimal precision. This schema is used in response payloads and in route-search points.
properties:
latitude:
description: Latitude serialized as a string, for example `52.475911`.
example: "52.475911"
pattern: -?[0-9]{1,2}\.[0-9]{6}
type: string
longitude:
description: Longitude serialized as a string, for example `13.350794`.
example: "13.350794"
pattern: -?[0-9]{1,3}\.[0-9]{6}
type: string
type: object
DriveDisplayText:
properties:
language:
example: DE
maxLength: 2
minLength: 2
type: string
text:
example: example
maxLength: 512
type: string
required:
- language
- text
type: object
DriveErrorResponse:
properties:
message:
type: string
title: ErrorResponse
type: object
DriveEvse:
description: Electric Vehicle Supply Equipment (EVSE) represents a charging station unit that may have multiple connectors. Only one connector can be active at a time.
properties:
capabilities:
description: "Values: `PLUG_AND_CHARGE_CAPABLE`, `REMOTE_START_STOP_CAPABLE`. New values in this array might be added without notice, so unknown values should be handled gracefully."
example:
- RESERVABLE
- PLUG_AND_CHARGE_CAPABLE
- PLUG_AND_CHARGE_CAPABLE
items:
type: string
type: array
connectors:
items:
$ref: "#/components/schemas/DriveConnector"
type: array
evse_id:
example: +49*839*030*000074
minLength: 1
type: string
last_updated:
format: date-time
type: string
physical_reference:
description: The 'physical reference' is used by some CPOs to represent the label printed on the charging station itself. For example, in a charging location, the physical references could be '1', '2', '3', '4', for the four different charging stations
example: "4"
type: string
status:
$ref: "#/components/schemas/DriveConnectorStatus"
uid:
example: 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE
minLength: 0
type: string
required:
- uid
- status
- connectors
- capabilities
- last_updated
type: object
DriveExceptionalPeriod:
properties:
period_begin:
format: date-time
type: string
period_end:
format: date-time
type: string
required:
- period_begin
- period_end
DriveGeoFilters:
description: Filtering criteria applied to geosearch requests.
properties:
capabilities:
description: Required EVSE capabilities.
items:
$ref: "#/components/schemas/DriveCapabilities"
type: array
connectorStandards:
description: Accepted connector standards.
items:
$ref: "#/components/schemas/DriveConnectorStandard"
type: array
countries:
description: Array of 3-letter country codes
items:
example:
- NOR
- SWE
- DEU
type: string
type: array
evseIds:
description: Return only stations with evses id match a pattern
example:
- +49*839
- "*075*000075"
items:
type: string
type: array
excludedOperatorIds:
description: Exclude stations from these operators. (This parameter will be ignored when operatorIds are provided.)
items:
type: integer
type: array
locationStatuses:
description: Only return locations whose status is included in this list. A common default is `[AVAILABLE, CHARGING, OCCUPIED, RESERVED, UNKNOWN, OUTOFORDER]`, which excludes statuses such as `BLOCKED`, `INOPERATIVE`, `OFFLINE`, and `REMOVED`.
example:
- AVAILABLE
- CHARGING
- OCCUPIED
- RESERVED
- UNKNOWN
- OUTOFORDER
items:
$ref: "#/components/schemas/DriveConnectorStatus"
type: array
open247:
description: Return only stations open 24/7.
type: boolean
openNow:
description: Returns only stations now opened (based on data provided by CPOs). This parameter is not supported with aggregations.
type: boolean
operatorIds:
description: Get stations only from these operators. (When provided, excludedOperatorIds will be ignored.)
items:
type: integer
type: array
power:
description: Minimum power in W
example: 30000
type: integer
powerType:
description: AC filter will contain both AC 1-phase and 3-phase.
enum:
- AC
- DC
type: string
type: object
DriveGeoOptions:
description: Additional geosearch options for shaping returned results.
properties:
filterEvsesAndConnectors:
description: Filter out connectors and evses which don't match filters params. Significantly decreases payload if non-matching objects are not needed.
type: boolean
type: object
DriveInvalidRequestErrorResponse:
properties:
fields:
items:
properties:
message:
example: UserId is not correct
type: string
name:
type: string
rejectedValue:
type: string
required:
- name
- message
- rejectedValue
title: InvalidField
type: object
type: array
message:
type: string
required:
- message
- fields
title: InvalidRequestErrorResponse
type: object
DriveLocation:
properties:
address:
description: Street address of the charging location
example: EUREF CAMPUS 4-5
type: string
city:
description: City where the charging location is situated
example: Berlin
type: string
coordinates:
$ref: "#/components/schemas/DriveCoordinates"
description: Geographic coordinates of the charging location. These values are returned as strings.
country:
description: Three-letter country code (ISO 3166-1 alpha-3) where the charging location is situated
example: DEU
maxLength: 3
minLength: 3
type: string
directions:
description: Navigation instructions to help locate the charging points, available in multiple languages
items:
$ref: "#/components/schemas/DriveDisplayText"
type: array
evses:
description: List of Electric Vehicle Supply Equipment (EVSE) at this location. Each EVSE may have multiple connectors.
items:
$ref: "#/components/schemas/DriveEvse"
type: array
id:
example: 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=
minLength: 0
type: string
is_green_energy:
description: Indicates if the location uses renewable energy sources for charging, based on CPO-provided data
example: false
type: boolean
last_updated:
description: ISO 8601 timestamp of when this location's data was last updated. Use this to track changes and implement efficient polling.
example: 2024-03-15T14:30:00Z
type: string
name:
description: Human-readable name of the charging location
example: Ebee Smart Technologies
maxLength: 255
minLength: 0
type: string
openNow:
description: Indicates if the location is currently open based on opening_hours and local timezone. Use this for quick filtering of available locations.
example: false
type: boolean
opening_times:
$ref: "#/components/schemas/DriveOpeningTimes"
description: Operating hours of the charging location
operator:
$ref: "#/components/schemas/DriveBusinessDetails"
description: Information about the Charging Point Operator (CPO) managing this location
operator_display_name:
description: An enhanced display name of the operator. This may be the operator name as found in the operator object, or the sub-operator of the location. When showing the location to end users, this is the operator name that should be shown.
example: Sub-operator X
type: string
postal_code:
description: Postal code of the charging location
example: 10829
type: string
state:
description: State, region, or province where the charging location is situated. Format varies by country.
example: Bayern
type: string
required:
- id
- name
- coordinates
- address
- evses
- country
- city
- last_updated
type: object
DriveOpeningTimes:
properties:
exceptional_closings:
items:
$ref: "#/components/schemas/DriveExceptionalPeriod"
type: array
exceptional_openings:
items:
$ref: "#/components/schemas/DriveExceptionalPeriod"
type: array
regular_hours:
items:
$ref: "#/components/schemas/DriveRegularHours"
type: array
twentyfourseven:
example: false
type: boolean
required:
- twentyfourseven
type: object
DrivePriceComponent:
description: Defines a single component of a charging price. A price can have multiple components (e.g., energy cost + time cost).
properties:
price:
description: Cost in the currency stated above. VAT is included. Decimal number. For example, if currency is EUR and price is 1.10, the cost is €1.10. More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation
example: 0
type: number
step_size:
description: "The smallest unit of usage that will be billed. Unit: seconds for `TIME` and `PARKING_TIME`, watt-hours (Wh) for `ENERGY`. More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation"
example: 1
type: number
type:
description: More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation
enum:
- TIME
- ENERGY
- FLAT
- CAPPED
example: FLAT
type: string
type: object
DrivePriceElement:
description: Defines a complete pricing structure that may apply under certain conditions. Multiple price elements may exist for different times or usage patterns.
properties:
price_components:
description: List of individual price components that make up this pricing structure
items:
$ref: "#/components/schemas/DrivePriceComponent"
type: array
restrictions:
description: Conditions under which this price element applies. Multiple restrictions can be combined.
properties:
day_of_week:
description: Days of the week when this price applies
enum:
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
- SATURDAY
- SUNDAY
example:
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
type: string
end_time:
description: Time of day when this price stops applying (local time at the charging location)
example: 22:30
type: string
max_congestion_threshold:
description: Maximum congestion threshold of the location, congestion fee will apply to valid x%
example: 90
type: number
max_duration:
description: Maximum charging duration in seconds for this price to apply
example: 10000
type: number
max_kwh:
description: Maximum energy consumption in kWh for this price to apply
example: 5
type: number
min_congestion_threshold:
description: Minimum congestion threshold of the location, congestion fee will apply from valid x%
example: 70
type: number
min_duration:
description: Minimum charging duration in seconds before this price applies (e.g., 7200 means this price applies after 2 hours)
example: 7200
type: number
min_kwh:
description: Minimum energy consumption in kWh before this price applies
example: 2
type: number
min_vehicle_soc:
description: Minimum vehicle state of charge in percentage, valid for vehicle state of charge from x%
example: 80
type: number
start_time:
description: Time of day when this price starts applying (local time at the charging location)
example: 08:30
type: string
type: object
required:
- price_components
type: object
DriveRectangleRequest:
description: Geosearch request constrained to a rectangular area.
example:
filters:
locationStatuses:
- AVAILABLE
- CHARGING
- OCCUPIED
- RESERVED
- UNKNOWN
- OUTOFORDER
powerType: AC
properties:
filters:
$ref: "#/components/schemas/DriveGeoFilters"
description: Filtering criteria for location selection.
options:
$ref: "#/components/schemas/DriveGeoOptions"
description: Additional options controlling search behavior.
type: object
DriveRegularHours:
description: Only to be used if twentyfourseven = false
properties:
period_begin:
example: 00:10
format: ([0-1][0-9]|2[0-3]):[0-5][0-9]
type: string
period_end:
example: 29:59
format: ([0-1][0-9]|2[0-3]):[0-5][0-9]
type: string
weekday:
description: Number of day in the week, from Monday (1) till Sunday (7)
example: 1
type: integer
required:
- weekday
- period_begin
- period_end
DriveSession:
description: Detailed charging session information.
properties:
balanceAmountMinor:
description: Type "Long". This field is not relevant for External Clearing (only used when using Plugsurfing's Payment Service Provider). Represents the remaining amount to be paid, expressed as a negative number. A value of 0 indicates the balance is fully paid. -2160 means there is an outstanding amount of 21.60 in the currency of the session.
example: "-2160"
type: number
balanceStatus:
$ref: "#/components/schemas/DriveSessionBalanceStatus"
description: Balance state after applying session costs.
charger:
$ref: "#/components/schemas/DriveSessionCharger"
description: Charger location and connector metadata.
chargingKeyType:
description: Only available after a session has successfully started. Possible values are "tag", "card", "virtual" or "plug_and_charge".
example: virtual
type: string
connectorId:
description: Only available after a session has successfully started.
example: O9UXK+YI5Q6i0FoI4qHwcA==
type: string
duration:
description: The value is in ISO 8601 duration format
example: PT28.913S
format: duration
type: string
energy:
$ref: "#/components/schemas/DriveSessionEnergy"
description: Energy consumed during the session.
paymentMethod:
deprecated: true
description: "Returns the `paymentMethod` of the transaction with the earliest timestamp. This field is `DEPRECATED` and will be removed in future versions. Use `session.transactions[].paymentMethod` instead. Migration note: `WRITE_OFF` was renamed to `NONE`, where `session.transactions[].paymentOutcome=WRITE_OFF` is the replacement"
enum:
- CREDIT_CARD
- EXTERNAL
- PREPAID
- WRITE_OFF
type: string
price:
$ref: "#/components/schemas/DriveSessionAmount"
description: Total session price.
receiptAvailable:
description: Indicates whether a receipt can be downloaded.
type: boolean
sessionId:
description: Unique identifier of the charging session.
example: AAdmD55q8Vz
type: string
sessionStatus:
$ref: "#/components/schemas/DriveSessionStatus"
description: Current lifecycle status of the session.
site:
description: Human-readable charging site name.
example: Drive_API_Test1
type: string
startTime:
$ref: "#/components/schemas/DriveTime"
description: UTC timestamp when the session started.
transactions:
description: Transactions linked to this charging session.
items:
$ref: "#/components/schemas/DriveTransaction"
type: array
required:
- sessionStatus
- connectorId
- sessionId
- transactions
type: object
DriveSessionAmount:
description: Monetary amount with currency and VAT breakdown.
properties:
currencyCode:
description: 3-letter currency code
example: EUR
type: string
minorExclVat:
description: "Minor units amount. Example: 2785 = 27.85€."
example: 2785
type: integer
minorInclVat:
description: Minor units amount
type: integer
vat:
description: VAT percentage
example: "17.5"
type: string
required:
- currencyCode
- minorExclVat
- minorInclVat
- vat
type: object
DriveSessionBalanceStatus:
description: "Note: this field is not relevant when using External Clearing."
enum:
- PROCESSING
- PAID
- DEBT
- REFUND
type: string
DriveSessionCharger:
description: Location and connector information for the charger used in a session.
properties:
chargingStationName:
description: Display name of the charging station.
example: Drive_API_Test1_Station1
type: string
city:
description: City where the charger is located.
example: Solna
type: string
connectorLabel:
description: Connector label reported by the charge point operator.
example: "1"
type: string
evseId:
description: EVSE identifier for the charging point.
example: SE*CND*EC1*1
type: string
streetName:
description: Street address of the charger.
example: Rättarvägen
type: string
type: object
DriveSessionEnergy:
description: Energy measurement data for a charging session.
properties:
unit:
description: Energy unit, typically kWh.
example: WH
type: string
value:
description: Measured energy value for the session.
example: 57
type: string
required:
- unit
- value
type: object
DriveSessionStartRequest:
description: Session start request identifying connector and charging key.
properties:
connectorId:
description: Connector identifier to start charging on.
example: aHeS4zN1UjzJf/HVDH66SbaItXqHvfLxexulktxTqJavgcbozuV9KJGqNYjmaQPwTb4Ck9wTZcWeEdfeco1srw==
type: string
keyIdentifier:
description: Charging key identifier used for authorization.
example: BnZd3qp87z
type: string
required:
- connectorId
- keyIdentifier
type: object
DriveSessionStartResponse:
description: Session start response containing a session identifier.
properties:
sessionId:
description: This session id should be stored and used in other endpoints.
example: AAdmD55q8Vz
type: string
type: object
DriveSessionStatus:
description: IMPORTANT - when handling this enum other unknown values should be handled.
enum:
- CREATED
- WAITING_TO_START
- STARTED
- WAITING_TO_STOP
- STOPPED
- COMPLETE
- FAILED
- UNKNOWN
- STOP_FAILED
type: string
DriveTime:
description: Timestamp in ISO 8601 UTC format with up to nanosecond precision.
example: 2021-01-30T10:00:00.111111111Z
format: date-time
type: string
DriveTransaction:
description: Represents a transaction with payment details and time.
properties:
amount:
$ref: "#/components/schemas/DriveSessionAmount"
paymentMethod:
description: The payment method used for the transaction. Can be `NONE` for outcome `WRITE_OFF`
enum:
- CREDIT_CARD
- EXTERNAL
- PREPAID
- NONE
type: string
paymentOutcome:
description: The outcome of the payment process.
enum:
- CHARGE
- WRITE_OFF
- REFUND
type: string
time:
$ref: "#/components/schemas/DriveTime"
required:
- paymentMethod
- paymentOutcome
- amount
- time
type: object
Error:
example:
errorCode: ER-001
errorDescription: Invalid request parameters
properties:
errorCode:
type: string
errorDescription:
type: string
required:
- errorCode
- errorDescription
type: object
MasterData:
example:
cardCategory:
- id: 201
name: Driver Card
cardGroup:
- cardTypeId: 1
id: 3001
name: Fleet Group A
cardType:
- defaultPurchaseCategoryId: 101
description: Card used for EV charging
id: 1
isEV: false
name: EV Card
country:
- countryCode: NLD
id: 1
name: Netherlands
fuelProductRestrictions:
- id: 1
name: diesel
product:
- id: 1001
name: Diesel Fuel
purchaseCategory:
- id: 101
name: Fuel
productRestrictionId: 1
reason:
- cardTypeId: 1
description: Card Lost
id: 1
region:
- id: 1
name: Alemere
status:
- id: 1
name: Active
properties:
cardCategory:
items:
properties:
id:
type: integer
name:
type: string
type: object
type: array
cardGroup:
items:
properties:
cardTypeId:
type: integer
id:
type: integer
name:
type: string
type: object
type: array
cardType:
items:
properties:
defaultPurchaseCategoryId:
type: integer
description:
type: string
id:
type: integer
isEV:
type: boolean
name:
type: string
type: object
type: array
country:
items:
properties:
countryCode:
type: string
id:
type: integer
name:
type: string
type: object
type: array
fuelProductRestriction:
items:
properties:
id:
type: integer
name:
type: string
type: object
type: array
product:
items:
properties:
code:
type: string
id:
type: integer
name:
type: string
type: object
type: array
purchaseCategory:
items:
properties:
cardTypeId:
type: integer
id:
type: integer
name:
type: string
productRestrictionId:
type: integer
type: object
type: array
reason:
items:
properties:
cardTypeId:
type: integer
description:
type: string
id:
type: integer
type: object
type: array
region:
items:
properties:
id:
type: integer
name:
type: string
type: object
type: array
status:
items:
properties:
id:
type: integer
name:
type: string
type: object
type: array
type: object
ReplacedCardResponse:
example:
additionalEmbossing: FLEET-01
cardDeliveryAddress:
companyName: ACME Ltd
addressLines: Unit 10, Industrial Estate Oxford Road
city: Oxford
country: United Kingdom
countryCode: GB
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
customerAccountNumber: "23444444"
driverName: James Smith
fuelProductRestriction:
productRestrictionId: 1
productRestrictionName: Fuel Only
keyIdentifier: 2323s
newCardIdentifier: 1244
primaryVisualCardNumber: "3080002323232"
products:
- productId: 101
productName: Car Wash
- productId: 102
productName: Lubricants
purchaseCategoryName: Fuel
secondaryCardNumber: NL-TBE-2323-2323
status: Active
vehicleRegNumber: AB12 CDE
properties:
additionalEmbossing:
type: string
cardDeliveryAddress:
$ref: "#/components/schemas/CardAddress"
cardDeliveryContact:
$ref: "#/components/schemas/Contact"
cardIdentifier:
type: integer
cardType:
type: string
customerAccountNumber:
type: string
driverName:
type: string
fuelProductRestriction:
properties:
productRestrictionId:
type: integer
productRestrictionName:
type: string
type: object
keyIdentifier:
type: string
newCardIdentifier:
type: integer
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
Status:
additionalProperties: false
example: {}
type: object
Transaction:
properties:
cardGroupId:
type: integer
cardGroupName:
type: string
cardIdentifier:
type: integer
cardNumber:
type: string
currency:
type: string
customerAccountNumber:
type: string
duration:
type: time
evEndTime:
type: datetime
evStartTime:
type: datetime
homeChargeVatExempt:
type: boolean
keyIdentifier:
type: string
merchant:
properties:
address:
properties:
addressLines:
type: string
city:
type: string
country:
type: string
countryCode:
type: string
region:
type: string
zipcode:
type: string
type: object
incomingMerchantDescription:
type: string
incomingMerchantNumber:
type: string
merchantId:
type: integer
merchantName:
type: string
type: object
merchantGroup:
properties:
merchantGroupId:
type: integer
merchantGroupName:
type: string
type: object
network:
properties:
networkId:
type: integer
networkName:
type: string
type: object
odometer:
type: integer
powerType:
type: string
private:
type: boolean
productGroup:
properties:
productGroupId:
type: integer
productGroupName:
type: string
type: object
additionalInfo:
type: object
description: Additional information associated with the card used for this transaction.
properties:
driverName:
type: string
description: Name of the driver associated with the card.
cardAdditionalData:
type: string
description: Additional customer-specific data supplied when the card was ordered but not embossed on the card.
totalAmountExclVAT:
type: decimal
totalAmountInclVAT:
type: decimal
transactionDate:
type: date
transactionId:
type: string
voucherNumber:
type: string
transactionSegments:
items:
properties:
product:
properties:
productCode:
type: string
productId:
type: integer
productName:
type: string
type: object
productEndTime:
type: datetime
productQuantity:
type: decimal
productStartTime:
type: datetime
transactionLineItemId:
type: integer
unitAmountExclVAT:
type: decimal
unitOfMeasurement:
type: string
description: Unit used to express productQuantity.
type: object
type: array
transactionStatus:
type: string
vatRate:
type: decimal
vehicleRegistrationNumber:
type: string
type: object
TransactionsResponse:
example:
hasNextPage: true
nextCursor: "454334"
totalCount: 120
lastPage: false
totalTransactionAmount: 130000
transactions:
- cardGroupId: 43534
cardGroupName: Fleet Group A
cardIdentifier: 453
cardNumber: 411111******1111
currency: EUR
customerAccountNumber: "435435"
duration: 45
evEndTime: 2025-01-15T11:00:00Z
evStartTime: 2025-01-15T10:15:00Z
homeChargeVatExempt: false
keyIdentifier: "23221321"
merchant:
address:
addressLines: 123 Energy Park
city: Amsterdam
country: Netherlands
countryCode: NLD
region: North Holland
zipCode: "12345"
incomingMerchantDescription: FastCharge NL Central
incomingMerchantNumber: IM-7890
merchantId: 223
merchantName: FastCharge Station
merchantGroup:
merchantGroupId: 324
merchantGroupName: FastCharge Group
network:
networkId: 2342
networkName: IONITY
odometer: 45230
powerType: DC
private: false
productGroup:
productGroupId: 234
productGroupName: EV Charging
totalAmountExclVAT: 125.63
totalAmountInclVAT: 150.75
transactionDate: 2025-01-15
transactionId: 2332-2322-3322-1212
voucherNumber: zmdkwl33
additionalInfo:
driverName: "John Doe"
cardAddtionalData: "new card"
transactionSegments:
- product:
productCode: EV-DC-FAST
productId: 501
productName: DC Fast Charging
productEndTime: 2025-01-15T10:40:00Z
productQuantity: 20.5
productStartTime: 2025-01-15T10:15:00Z
transactionLineItemId: 1
unitAmountExclVAT: 62.82
- product:
productCode: EV-AC
productId: 502
productName: AC Charging
productEndTime: 2025-01-15T11:00:00Z
productQuantity: 18.3
productStartTime: 2025-01-15T10:40:00Z
transactionLineItemId: 2
unitAmountExclVAT: 62.81
unitAmountInclVAT: 75.37
unitOfMeasurement: "kwH"
transactionStatus: Unbilled
vatRate: 20%
vehicleRegistrationNumber: AB12CDE
properties:
hasNextPage:
type: boolean
lastPage:
type: boolean
nextCursor:
type: string
totalCount:
type: integer
totalTransactionAmount:
type: decimal
description: Total amount including VAT for all transactions matching the request, before pagination. The amount is expressed in the customer's currency after transaction enrichment and currency conversion.
transactions:
items:
$ref: "#/components/schemas/Transaction"
type: array
type: object
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