# Cards (Stripe)

Manage saved payment cards for customers using Stripe as the payment provider. Customers can store, list, and remove cards linked to their account.

Cards are created and stored on **Innovorder's platform Stripe account**. Tokenizing a card client-side requires the platform publishable key, which is provided as part of an integration project. Contact [support@innovorder.fr](mailto:support@innovorder.fr). For the end-to-end payment flow (metadata contract of `POST /orders`, 3-D Secure), see the [Stripe Payments guide](https://developers.innovorder.io/docs/guides/guide-stripe-payments.md).

### `POST /cards/v2` - Create a card (Stripe)

Register a payment card for the authenticated customer (Customer role required) in two calls. First, call WITHOUT cardToken: a Stripe SetupIntent is created on the Innovorder platform account and its client\_secret is returned - confirm it client-side (e.g. stripe.confirmCardSetup(client\_secret, { payment\_method: { card } })) to obtain a PaymentMethod id (pm\_…). Then call again WITH cardToken set to that pm\_… id: the card is attached to the customer and persisted. The Stripe Customer is created automatically on the first save.

#### Request Body

```json
{
  "name": "My Visa",
  "cardToken": "pm_1PxYz..."
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| name | string | Yes | "My Visa" | Display name of the card. |
| cardToken | string | No | "pm\_1PxYz..." | Stripe PaymentMethod id (pm\_…) obtained by confirming the SetupIntent. Omit it to receive the SetupIntent client\_secret instead (first call). |

#### Response

```json
{
  "status": 200,
  "code": "create_card_succeed",
  "message": "Credit card has been successfully created.",
  "data": {
    "cardId": 4521,
    "name": "My Visa",
    "brand": "visa",
    "last4": "4242"
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| status | integer | Not specified | 200 | HTTP status code returned by the API. |
| code | string | Not specified | "create\_card\_succeed" | Machine-readable application code for the result. |
| message | string | Not specified | "Credit card has been successfully created." | Human-readable result message. Do not use this value for program logic. |
| data | object | Not specified | {…} | Endpoint-specific response payload. |
| data.cardId | integer | Not specified | 4521 | Identifier of the associated card. |
| data.name | string | Not specified | "My Visa" | The name value. |
| data.brand | string | Not specified | "visa" | The brand value. |
| data.last4 | string | Not specified | "4242" | The last4 value. |
| cardId | integer | Yes | Not provided | Persisted card id. Use it to pay in POST /orders with payment metadata "{\\"cardId\\":4521}". |

#### First call - without `cardToken` (SetupIntent creation)

```json
// POST /cards/v2   { "name": "My Visa" }
{
  "status": 200,
  "code": "create_card_succeed",
  "message": "Credit card has been successfully created.",
  "data": {
    "client_secret": "seti_1PxYz..._secret_AbC..."
  }
}
```

### `GET /cards` - List all cards (Stripe)

Retrieve all saved payment cards for a given customer. Requires the customerId as a query parameter.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| customerId | integer | Yes | The customer whose cards to retrieve. |

#### Response

```json
{
  "status": 200,
  "code": "card_succeed",
  "data": [
    {
      "cardId": 4521,
      "name": "My Visa",
      "stripeCardId": "card_1PxYz...",
      "last4": "4242",
      "brand": "visa",
      "expMonth": 12,
      "expYear": 2027
    },
    {
      "cardId": 4522,
      "name": "My Mastercard",
      "stripeCardId": "card_1QaWs...",
      "last4": "5555",
      "brand": "mastercard",
      "expMonth": 6,
      "expYear": 2026
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "card\_succeed" | Machine-readable application code for the result. |
| data | array | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | {…} | Endpoint-specific response payload. |
| data\[\].cardId | integer | 4521 | Identifier of the associated card. |
| data\[\].name | string | "My Visa" | The name value. |
| data\[\].stripeCardId | string | "card\_1PxYz..." | Identifier of the associated stripe card. |
| data\[\].last4 | string | "4242" | The last4 value. |
| data\[\].brand | string | "visa" | The brand value. |
| data\[\].expMonth | integer | 12 | The exp month value. |
| data\[\].expYear | integer | 2027 | The exp year value. |

### `DELETE /cards/{cardId}` - Delete a card (Stripe)

Remove a saved payment card. The card is disabled in the system and the corresponding Stripe payment method is detached.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| cardId | integer | Yes | The ID of the card to delete. |

#### Response

```json
{
  "status": 200,
  "code": "delete_card_succeed",
  "message": "Card deleted successfully."
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "delete\_card\_succeed" | Machine-readable application code for the result. |
| message | string | "Card deleted successfully." | Human-readable result message. Do not use this value for program logic. |