<!-- canonical: https://docs.costplus.io/docs/payment-methods/cards -->

> Accept credit and debit card payments
## Overview

Accept credit and debit card payments through the Cost+ API using the `credit-card` payment method.

```json
{
  "transactions": [
    {
      "payment_method": "credit-card"
    }
  ]
}
```

## Supported Card Brands

| Brand | Type |
|-------|------|
| Amex | Credit |
| Mastercard | Credit / Debit |
| Maestro | Debit |
| Visa | Credit / Debit |
| V Pay | Debit |

## Configuration Options

### Dynamic Descriptor

Use the `dynamic_descriptor` field to set a custom statement text that appears on your customer's bank or card statement.

```json
{
  "transactions": [
    {
      "payment_method": "credit-card",
      "payment_method_details": {
        "dynamic_descriptor": "My Store Order 123"
      }
    }
  ]
}
```

### Use Customer Name as Cardholder Name

Set `use_customer_name_as_cardholder_name` to `true` to automatically use the customer's name from the order as the cardholder name.

```json
{
  "transactions": [
    {
      "payment_method": "credit-card",
      "payment_method_details": {
        "use_customer_name_as_cardholder_name": true
      }
    }
  ]
}
```

## Custom Card Entry Form

If you want to build your own card entry form instead of using the hosted payment page, follow these four steps.

### Step 1: Create an Order with a Setup Token

Create an order and include `setup_token: true` in the transaction's `payment_method_details`. This tells Cost+ to generate a setup token you can use to securely tokenize card details.

```bash
curl -X POST https://api.costplus.online/v1/orders \
  -u your-api-key: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 5000,
    "merchant_order_id": "order-001",
    "transactions": [
      {
        "payment_method": "credit-card",
        "payment_method_details": {
          "setup_token": true
        }
      }
    ],
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook"
  }'
```

The response will include a `setup_token` value in the transaction's `payment_method_details`:

```json
{
  "id": "order-uuid",
  "transactions": [
    {
      "id": "txn-uuid",
      "payment_method": "credit-card",
      "payment_method_details": {
        "setup_token": "st_abc123..."
      }
    }
  ]
}
```

### Step 2: Tokenize Card Details

Send the card PAN, expiry date, and the setup token to the token endpoint. This securely vaults the card and returns a `vault_token`.

```bash
curl -X POST https://api.costplus.online/v1/tokens/ \
  -H "Content-Type: application/json" \
  -d '{
    "pan": "4111111111111111",
    "expiry_date": "1228",
    "setup_token": "st_abc123..."
  }'
```

Response:

```json
{
  "vault_token": "vt_xyz789..."
}
```

### Step 3: Authenticate the Transaction

Submit the `vault_token` and `cvc` to the authenticate endpoint. If 3D Secure is required, you will receive a `redirect_url` to redirect the customer to their bank's authentication page.

```bash
curl -X POST https://api.costplus.online/v1/orders/{order_id}/transactions/{transaction_id}/authenticate/ \
  -u your-api-key: \
  -H "Content-Type: application/json" \
  -d '{
    "vault_token": "vt_xyz789...",
    "cvc": "123"
  }'
```

Response:

```json
{
  "redirect_url": "https://3ds.bank.example.com/auth?id=..."
}
```

Redirect the customer to `redirect_url` to complete 3D Secure authentication. After the customer completes (or cancels) authentication, they will be redirected back to your `return_url`.

### Step 4: Poll Order Status

After the customer returns from 3D Secure, poll the order to check the final status.

```bash
curl -X GET https://api.costplus.online/v1/orders/{order_id} \
  -u your-api-key:
```

The order `status` will transition to one of:

| Status | Meaning |
|--------|---------|
| `completed` | Payment was successful |
| `cancelled` | Customer cancelled or authentication failed |
| `error` | An error occurred during processing |
| `expired` | The order expired before completion |

> [!TIP]
> For manual authorization and capture flows with card payments, see the [Auth / Capture / Void](/docs/guides/auth-capture-void) guide.