Skip to main content
Discover card products and create one-card charging key orders for fleet organizations through EMP mode. Fleet card orders let you create physical charging card orders for fleet organizations through EMP mode. Use this flow when Plugsurfing handles card order fulfilment and the card should belong to a fleet organization instead of an individual Drive API user. Each request creates one card order. For multiple cards, submit one request per card.

Before you start

Before creating an order:
  • Create the fleet with POST /emp/v1/fleets.
  • Keep the customer-provided fleetId; you will use the same value when placing card orders.
  • Discover available products with GET /emp/v1/products.
  • If the selected product includes printing.schema, use that schema to understand the supported printing payload.

Flow

1. Create or identify the fleet

The order request uses the fleetId you provided when creating the fleet.
The fleet must already exist before you create an order. The order endpoint does not create fleets.

2. Discover available products

Use product discovery to see which cards can be ordered.
Products may include a printing.schema object. This schema describes the printing payload expected for that product.
If a product has no printing field, create the order without a printing payload.

3. Create the order

Create one order for one card.
Do not include quantity. One request always represents one card order. printing is optional at the Drive API level because requirements depend on the selected product. The fulfilment system validates the submitted payload against the product configuration.

4. Track the order

The card is a physical product that has to be manufactured, so it is not available right after the order is created. Track the order until the card has been produced. The create response contains the id of the order. To track an order, provide its ID to the single-order endpoint.
Poll this endpoint to follow the order. Physical cards require manufacturing and assignment. Availability can take several days, particularly when an order spans a weekend or public holiday. Use the order status to decide when to stop polling:
  • While the status is not final, keep polling.
  • Stop polling when the status is ORDER_ASSIGNED, ORDER_CANCELLED, ORDER_REFUNDED, ORDER_PAYMENT_FAILED or ORDER_REFUND_FAILED.
  • ORDER_ASSIGNED means fulfilment is complete and no further charging keys will be added.
  • ORDER_CANCELLED and ORDER_REFUNDED mean fulfilment ended and no further charging keys will be added.
  • ORDER_PAYMENT_FAILED and ORDER_REFUND_FAILED are final from your perspective, because the Drive API offers no action to recover them. Contact your Plugsurfing support contact to resolve the order.
If you do not have the order ID at hand, you can find it with GET /emp/v1/orders, which lists the orders of your organizations. Prefer the single-order endpoint for tracking.

5. Retrieve the manufactured card

The response has the same fields as an item of the order list, plus an optional chargingKeys array. Each entry in chargingKeys is the charging key of a card that has been manufactured for the order.
  • chargingKeys is omitted until the first card has been manufactured.
  • While the status is ORDER_PROCESSING, chargingKeys may contain only the cards manufactured so far, including for an order with quantity greater than 1. Do not treat the order as complete until it reaches a final status.
  • The list endpoint GET /emp/v1/orders never includes chargingKeys.
Other order fields and some charging key fields (such as validTo and contractId) are omitted above for brevity. Orders that do not exist or are not accessible to the caller return 404.

6. Enable the card

Manufactured cards are created disabled. Enable each card with its keyIdentifier before it can be used for charging.
See Enable charging key.

Error handling

Common client-facing errors:
  • 400 Bad Request: required fields are missing, the body is malformed JSON, or the printing payload does not match product requirements.
  • 404 Not Found: the fleetId does not exist, the fleet is not available to the calling EMP, or the decoded productId does not exist.
  • 500 Internal Server Error: an unexpected server-side error occurred.