Shell B2B Mobility Card Management API - Quick Start Guide
API Version: 3.1.5 | Authentication: OAuth 2.0 | Status: Production
Overview
The Shell Card Management API is a REST-based API that enables developers to manage Shell fuel cards programmatically. The API supports card searching, ordering, status updates, cancellation, and various other card management operations.
Note: This guide covers only OAuth 2.0 authenticated endpoints (base path: /card-management/v1). Legacy Basic Auth endpoints (/fleetmanagement/v1/card) are not included as they are being phased out.
Key Features
- Search and filter fuel cards with flexible criteria
- Order new cards and track order status
- Block, unblock, and cancel cards
- Update card delivery addresses
- Manage card auto-renewal settings
- Move cards between card groups and accounts
- Request PIN reminders
Important Notice - OAuth 2.0
IMPORTANT: OAuth 2.0 is now the standard authentication method
- New integrations: Use OAuth 2.0 from the start
- Existing integrations: Plan your migration to OAuth 2.0
- Legacy methods: Basic Auth and API Key are being phased out
Contact Shell Technical Support to obtain your OAuth 2.0 credentials (client_id and client_secret).
Authentication
OAuth 2.0 (Standard Authentication Method)
The Shell Card Management API uses OAuth 2.0 Client Credentials flow for secure authentication.
WARNING: All customers should plan to adopt OAuth 2.0 authentication. This is the recommended and future-proof authentication method for the Shell Card Management API. Legacy authentication methods are being phased out.
OAuth 2.0 Flow
Step 1: Obtain Access Token
Request an access token from the OAuth token endpoint:
POST /oauth/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret
Step 2: Use Access Token in API Requests
Authorization: Bearer <access-token> Content-Type: application/json
Token Management
Token management best practices:
- Access tokens have a limited lifetime (typically 15 mins)
- Implement token caching to avoid unnecessary token requests
- Refresh tokens before expiry to ensure uninterrupted service
- Never share your client_secret or embed it in client-side code
OAuth 2.0 Adoption Strategy
Why Migrate to OAuth 2.0?
Security Benefits:
- Industry-standard authentication protocol
- Time-limited access tokens reduce security risks
- No credentials transmitted with each request
- Better support for token rotation and revocation
Operational Benefits:
- Improved scalability and performance
- Better monitoring and audit capabilities
- Simplified credential management
- Future-proof integration
Migration Path
If you're currently using legacy authentication methods, follow this migration path:
- Request OAuth 2.0 credentials from Shell Technical Support
- Implement OAuth token management in your application
- Test thoroughly in the Test/Sandbox environment
- Run parallel authentication (OAuth + legacy) during transition
- Monitor and validate OAuth integration
- Switch to OAuth-only once validated
- Decommission legacy authentication after successful migration
Environments
The API is available in two environments:
| Environment | Base URL | Purpose |
|---|---|---|
| Production | https://api.shell.com | Live production environment |
| Test (Sandbox) | https://api-test.shell.com/test | Testing and development environment |
Tip: Always test your integration in the Test environment before moving to production.
Quick Start
1. Get Your OAuth Credentials
- Contact Shell Technical Support
- Request OAuth 2.0 credentials (client_id and client_secret)
- Review terms of service
2. Obtain Access Token
First, get your OAuth access token:
cURL Example:
curl -X POST https://api-test.shell.com/v2/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret"
Response:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 899
}3. Make Your First API Request
Example: Search for Active Cards
cURL Example:
curl -X POST https://api-test.shell.com/test/card-management/v1/search \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"Filters": {
"PayerNumber": "CZ00000927",
"AccountNumber": "CZ00000927",
"ColCoCode": 32,
"CardStatus": [
"Active"
]
},
"Page": 1,
"PageSize": 1
}'Example Response:
{
"Page": 1,
"TotalRecords": 7994,
"TotalPages": 7994,
"PageSize": 1,
"Data": [
{
"AccountId": 1227,
"AccountName": "Dominica1_C_1",
"AccountNumber": "CZ00000927",
"AccountShortName": "Dominica1_1",
"BundleId": null,
"CardBlockSchedules": null,
"CardGroupId": null,
"CardGroupName": null,
"CardId": 491623,
"CardTypeCode": "7027329",
"CardTypeId": 11120,
"CardTypeName": "CZ SFA NAT SIN - CHIP",
"ColCoCountryCode": "CZ",
"CreationDate": "20220810 23:53:25",
"DriverName": "SHELL973169581",
"EffectiveDate": "20220810",
"ExpiryDate": "20260831",
"FleetIdInput": true,
"IsCRT": false,
"IsFleet": true,
"IsInternational": false,
"IsNational": true,
"IsPartnerSitesIncluded": false,
"IsShellSitesOnly": true,
"IssueDate": "20220812",
"IsSuperseded": false,
"IsVirtualCard": false,
"LastModifiedDate": "20230614 00:05:16",
"LastUsedDate": null,
"LocalCurrencyCode": "CZK",
"LocalCurrencySymbol": "Kč",
"OdometerInput": true,
"PAN": "7027329200001461736",
"MaskedPAN": "7027329******461736",
"PANID": 17268839,
"PurchaseCategoryCode": "2",
"PurchaseCategoryId": 102,
"PurchaseCategoryName": "2 - All Fuels Products, Car related items and TMF",
"Reason": "Scheduled for unblock",
"ReissueSetting": "True",
"StatusDescription": "Active",
"StatusId": 1,
"TokenTypeID": 503742,
"TokenTypeName": "CZ SFA NAT SIN – CHIP",
"VRN": "VRN347886994",
"ClientReferenceId": null,
"IsEMVContact": true,
"IsEMVContactless": false,
"IsRFID": false,
"RFIDUID": null,
"EMAID": null,
"EVPrintedNumber": null,
"CardMediaCode": "100999",
"MediumTypeID": 1,
"MediumType": "Fuel Card"
}
],
"RequestId": "5a474d3e-70f4-4f7d-9416-5d5475b33e4f",
"Status": "SUCCESS"
}API Endpoints Reference
Card Search & Retrieval
| Endpoint | Method | Description |
|---|---|---|
| /card-management/v1/search | POST | Search for cards with flexible filters (OAuth 2.0) |
| /card-management/v1/details | POST | Get details of a single fuel card (OAuth 2.0) |
Common Use Cases:
- Search by card status (ACTIVE, BLOCKED, EXPIRED, etc.)
- Filter by driver name or vehicle registration
- Search by PAN (last 4 digits)
- Find cards expiring in X days
Card Summary
| Endpoint | Method | Description |
|---|---|---|
| /card-management/v1/summary | POST | Get high-level summary of fuel cards (OAuth 2.0) |
Returns:
- Total count of cards by status
- Summary statistics by card type
- Active vs inactive breakdown
Card Ordering
| Endpoint | Method | Description |
|---|---|---|
| /card-management/v1/ordercard | POST | Order one or more fuel cards (OAuth 2.0) |
| /card-management/v1/ordercardenquiry | POST | Check card order status (OAuth 2.0) |
Required Information for Card Ordering:
- ColCoCode (Collecting Company Code)
- PayerNumber or PayerId
- AccountNumber
- Card type and configuration
- Delivery address details
Card Status Management
| Endpoint | Method | Description |
|---|---|---|
| /card-management/v1/updatestatus | POST | Block, unblock, or cancel cards (OAuth 2.0) |
| /card-management/v1/schedulecardblock | POST | Schedule card block/unblock requests (OAuth 2.0) |
Status Actions:
- BLOCK - Temporarily block a card
- UNBLOCK - Reactivate a blocked card
- DAMAGED - Report card as damaged and request replacement
- TEMP_BLOCK_CUSTOMER - Customer-initiated temporary block
- TEMP_BLOCK_SHELL - Shell-initiated temporary block
CAUTION: Card cancellation is permanent and cannot be reversed.
Additional Endpoints
| Category | Endpoint | Method | Description |
|---|---|---|---|
| Cancellation | /card-management/v1/cancel | POST | Cancel one or multiple cards |
| Card Movement | /card-management/v1/move | POST | Move cards to another card group or account |
| PIN Management | /card-management/v1/pinreminder | POST | Request PIN reminder for a card |
| Delivery Address | /card-management/v1/deliveryaddressupdate | POST | Update card delivery address |
| Auto Renewal | /card-management/v1/autorenew | POST | Update reissue indicator |
Usage Examples
Example 1: Search for Cards Expiring Soon
POST /card-management/v1/search
{
"Filters": {
"PayerNumber": "CZ00000927",
"AccountNumber": "CZ00000927",
"ColCoCode": 32,
"CardStatus": [
"Active"
],
"ExpiringInDays" : 70
},
"Page": 1,
"PageSize": 1
}Example 2: Block a Card Temporarily
POST /card-management/v1/updatestatus
{
"Cards": [
{
"CardId": 125,
"ColCoCode": 86,
"PayerNumber": "PH50000843",
},
"ReasonId": 1236,
"ReasonText": "Unblock",
"TargetStatus": "Unblock"
]
}Example 3: Cancel Cards
POST /card-management/v1/cancel
{
"Cards": [
{
"CardId": 125,
"CardExpiryDate": "20231231",
"ColCoCode": 86,
"PayerNumber": "PH50000843",
}
],
"ReasonText": "Lost",
"RequestId": "1"
}Error Handling
Common Error Codes
| HTTP Status | Error Code | Description | Solution |
|---|---|---|---|
| 200 | N/A | Status: SUCCESS | N/A |
| 400 | E0001 | Validation Error | Check request parameters |
| 401 | E0003 | Unauthorized | Verify OAuth token is valid |
| 403 | E0003 | Forbidden | Check user permissions |
| 404 | E0005 | Resource Not Found | Verify endpoint URL and resource exists |
| 500 | E0002 | Unknown Error / Internal Server Error | Contact support |
Best Practices
1. Adopt OAuth 2.0 Authentication
IMPORTANT: All customers should migrate to OAuth 2.0 authentication. Implement proper token management:
- Cache access tokens and reuse until expiry
- Refresh tokens before they expire (recommended 60 seconds before)
- Store client credentials securely (use environment variables or secrets manager)
- Never log or expose access tokens in client-side code
2. Use Request IDs
Always include a unique RequestId (GUID format) for end-to-end traceability
3. Implement Pagination
For large datasets, use pagination to avoid timeouts
4. Test in Sandbox Environment
Always test integration in the Test/Sandbox environment before moving to production
SDK & Code Examples
Shell provides official SDKs and comprehensive code examples to accelerate your integration with the Card Management API.
Available SDK Languages
- Python - Full-featured SDK with OAuth 2.0 support
- TypeScript - Type-safe SDK with full type definitions
- Java - Enterprise-grade SDK
- C#/.NET - Complete .NET integration
- PHP - Easy-to-use PHP library
- Ruby - Ruby gem for seamless integration
View Official SDKs & Documentation
Support & Resources
Technical Support
- Support: Shell Technical Support
Documentation
Getting Help
When contacting support, provide:
- Your client_id (never share your client_secret or access tokens)
- RequestId from the API response
- Timestamp of the request
- Environment (Production/Test)
Last Updated: July 1, 2026
Document Version: 1.0
API Version: 3.1.5
