> ## Documentation Index
> Fetch the complete documentation index at: https://developer.plugsurfing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plug&Charge

Enable Plug\&Charge (roaming) for your users via Drive API. Create Plug\&Charge keys, understand EMAID generation, and learn how roaming works for Plug\&Charge.

## Overview

Plug\&Charge (ISO 15118) allows EV drivers to authenticate charging sessions by just plugging in the cable — no RFID card, app interaction, or QR code needed.
Plug\&Charge is contract-based charging and works with digital certificates. These certificates are generated on behalf of end-users by e-Mobility Providers and installed in vehicles.
The secure distribution, validation and revocation of these certificates is maintained via trusted key infrastructures (PKIs).

## Full solution vs. roaming-only solution

The Plugsurfing platform fully supports Plug\&Charge (ISO-15118-2) in the role of a Mobility Operator (MO):

1. We can ***manage*** contract certificates on behalf of end-users, signed by Hubject's Plug\&Charge infrastructure.
2. We enable full Plug\&Charge ***roaming*** via OICP and OCPI 2.x, including token exchange, location search and live charging authorization.

Drive API currently provides the ***roaming*** part of Plug\&Charge: the partner creates and manages contract certificates on their side, and uses Drive API to register the vehicle's PCID so
that Plugsurfing can authorize charging sessions at Plug\&Charge-capable stations across the roaming network.

If your use case requires full contract certificate lifecycle management (provisioning, renewal, revocation) via Drive API, [Contact us](/contact-and-support) for details.

## Prerequisites

<Info>
  ###

  Before using Plug\&Charge, ensure the following:

  * **Plug\&Charge is enabled** for your organization — [contact us](/contact-and-support) to activate it
  * Your platform **manages contract certificates** (provisioning, renewal, revocation). Reach out to us if you are interested in the full solution via Drive API.
  * You have the vehicle's **PCID** (Provisioning Certificate Identifier), and optionally an **EMAID** (EMA-ID / contract identifier)
</Info>

## Creating a Plug\&Charge key

Register a vehicle (and contract) for Plug\&Charge roaming by creating a charging key of this type:

```
POST /v1/users/{userId}/charging-keys/plug-and-charge
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `pcid` | string | Yes | Provisioning Certificate Identifier of the vehicle. Must be 17–18 alphanumeric characters. |
| `contractId` | string | No | Optional EMA-ID (following emi3 specification) to use as the contract identifier. Must follow the agreed prefix for your organization. If omitted, a globally unique EMAID will be generated. |

Whether the `contractId` is provided depends on the intended flow:

* **Case A**: The partner already generated a Plug\&Charge contract certificate with a specific EMAID on their end. This EMAID must be provided as `contractId` in the request to create the corresponding Plug\&Charge charging key. This will enable roaming via Plugsurfing's platform. Plugsurfing accepts any valid EMAID in all representations as specified by the emi3 group. If the optional trailing check-digit is present, Plugsurfing validates it. Further, the EMAID must follow the agreed prefix for your organization (the default is `DE-8PS`). Plugsurfing does not (and cannot) validate the certificate itself.
* **Case B**: The partner does not specify the `contractId` in the request: Plugsurfing will generate a unique one. This `contractId` (in EMAID format) is returned and must be used to generate the contract certificate for the vehicle. Plugsurfing always generates and returns EMAIDs in the *long* readable form with separators and trailing check-digit, e.g. `DE-8PS-C0AD21B13-Q`. This identifier is equivalent to the representation without separators and without check-digit, e.g. `DE8PSC0AD21B13`.

The partner is asked to keep the state of the contract certificate and the Plug\&Charge key in sync. Whenever the contract certificate is revoked or expires, the Plug\&Charge key should be deleted or disabled accordingly.
If a contract certificate is renewed, it is recommended to re-use the same EMAID.

### Example request

```json theme={null}
{
  "pcid": "WDBRF61J21F123456",
  "contractId": "DE-8PS-C0AD21B13-Q"
}
```

### Example response

```json theme={null}
{
  "contractId": "DE-8PS-C0AD21B13-Q",
  "pcid": "WDBRF61J21F123456",
  "keyId": "DE-8PS-C0AD21B13-Q"
}
```

See the [API Reference](/reference/createPncChargingKey) for full details.

## EMAID behavior

By default, a new globally unique EMAID is generated for each Plug\&Charge key. The EMAID of existing virtual or RFID keys is **not** reused.

If EMAID reuse is required for your use case, [contact us](/contact-and-support).

## Error handling

| Code | Cause |
| - | - |
| 400 | PCID or contractId syntactically invalid, contractId prefix not allowed, or Plug\&Charge feature not enabled |
| 404 | User (intended owner of the charging key) not found by the specified id. |
| 409 | Conflict: A (Plug\&Charge) charging key with this contractId/EMAID already exists. And multiple keys with the same EMAID are not allowed per configuration. |
| 500 | Internal error |

## Roaming / Token exchange

Plug\&Charge keys are roamed via OICP and OCPI 2.x (following OCPI 3.0 recommendations for tokens and locations).

When a Plug\&Charge vehicle connects at a compatible charging station:

1. The CPO sends an authorization request containing the vehicle's contract identifier (EMAID).
2. Plugsurfing matches the EMAID to the registered Plug\&Charge key and approves the session.

### Token exchange format

| Field | Value |
| - | - |
| `UID` | EMAID |
| `authID` / `contractID` | EMAID |
| `token_type` | `OTHER` |
| `whitelist` | `NEVER` |

## Finding Plug\&Charge-compatible chargers

Use the Drive API geosearch endpoint to filter for Plug\&Charge-capable locations by including `PLUG_AND_CHARGE_CAPABLE` in the capabilities filter.

See [Geosearch — Capabilities](/docs/drive-api/geosearch#capabilities) for details.

## Managing Plug\&Charge keys

Existing charging key endpoints work for Plug\&Charge keys:

* **Disable or enable**: `PATCH /v1/users/{userId}/charging-keys/{contractId}` with `{"enabled": false}` or `{"enabled": true}`
* **List keys**: Plug\&Charge keys appear in `GET /v1/users/{userId}/charging-keys` with `type: "plug_and_charge"`

<br />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.