> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkouts

> Create, retrieve, capture, refund, update, and delete Neuro-Pay hosted checkouts

## Endpoints

| Method | Path                 | Purpose                                     |
| ------ | -------------------- | ------------------------------------------- |
| `POST` | `/checkout/create`   | Create a hosted checkout                    |
| `POST` | `/checkout/retrieve` | Retrieve a checkout                         |
| `POST` | `/checkout/capture`  | Capture an authorized checkout              |
| `POST` | `/checkout/refund`   | Refund a paid checkout                      |
| `POST` | `/checkout/update`   | Update checkout metadata                    |
| `POST` | `/checkout/delete`   | Delete a checkout still in `created` status |

## Create checkout

`POST /checkout/create`

### cURL example

```bash theme={null}
curl -X POST https://api.neuro-admin.com/checkout/create \
  -H "Authorization: Bearer $NEURO_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "SEK",
    "message": "Order #1001",
    "capture": true,
    "allowSaveCard": true,
    "returnUrl": "https://merchant.example/success",
    "returnUrlCancel": "https://merchant.example/cancel",
    "customer_id": "9a7991cb1e8e9f30911970e913ad4841",
    "metaData": {
      "orderId": "1001"
    },
    "paymentMethods": [
      {
        "method": "card",
        "brands": ["amex", "visa"]
      }
    ]
  }'
```

### Request body

```json theme={null}
{
  "amount": 2000,
  "currency": "SEK",
  "message": "Order #1001",
  "capture": true,
  "allowSaveCard": true,
  "returnUrl": "https://merchant.example/success",
  "returnUrlCancel": "https://merchant.example/cancel",
  "customer_id": "9a7991cb1e8e9f30911970e913ad4841",
  "metaData": {
    "orderId": "1001"
  },
  "paymentMethods": [
    {
      "method": "card",
      "brands": ["amex", "visa"]
    }
  ]
}
```

### Key fields

> **Note:** The `paymentMethods` field is only applicable when the payment integrator is Nuvei; it is ignored for other integrators. Admitted methods: `card`, `swish`, `trustly`, `paypal`. Admitted brands: `amex`, `visa`, `mastercard`, `maestro`, `discover`, `diners`, `jcb`, `unionpay`, `bancontact`, `carte_bancaire`.

| Field               | Type    | Required | Description                                     |
| ------------------- | ------- | -------- | ----------------------------------------------- |
| `amount`            | integer | yes      | Amount in minor units                           |
| `currency`          | string  | yes      | Currency code such as `SEK`                     |
| `message`           | string  | yes      | Buyer-facing description                        |
| `capture`           | boolean | no       | Whether to capture immediately                  |
| `allowSaveCard`     | boolean | no       | Allow storing the payment method for a customer |
| `returnUrl`         | string  | no       | Success redirect URL                            |
| `returnUrlCancel`   | string  | no       | Cancel redirect URL                             |
| `customer_id`       | string  | no       | Existing checkout customer ID                   |
| `card_id`           | string  | no       | Saved card identifier                           |
| `identifier`        | string  | no       | Your own reference value                        |
| `template`          | string  | no       | Optional checkout template identifier           |
| `metaData`          | object  | no       | Optional metadata stored with the checkout      |
| `paymentMethods`    | array   | no       | Optional payment-method filter                  |
| `sendInLanguage`    | string  | no       | Preferred checkout language                     |
| `afterPaid`         | mixed   | no       | Optional post-payment data                      |
| `skip_confirmation` | boolean | no       | Optional checkout behavior flag                 |

### Response shape

```json theme={null}
{
  "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9",
  "identifier": "order-1001",
  "authCode": "test123",
  "status": "created",
  "statusChanged": "2026-05-06 08:00:00",
  "mode": "test",
  "amount": 2000,
  "currency": "SEK",
  "message": "Order #1001",
  "returnUrl": "https://merchant.example/success",
  "returnUrlCancel": "https://merchant.example/cancel",
  "metaData": {
    "orderId": "1001"
  },
  "capture": true,
  "allowSaveCard": true,
  "redirectUrl": "https://neuro-admin.com/checkout/checkout?id=123&cid=ba3e9a3d911ca9e4413eb9e6dcaafec9",
  "balance": 0
}
```

After creating a checkout, redirect the buyer to `redirectUrl`.

## Retrieve checkout

`POST /checkout/retrieve`

### cURL example

```bash theme={null}
curl -X POST https://api.neuro-admin.com/checkout/retrieve \
  -H "Authorization: Bearer $NEURO_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9"
  }'
```

```json theme={null}
{
  "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9"
}
```

Returns the same checkout summary shape used by checkout creation.

## Capture checkout

`POST /checkout/capture`

### cURL example

```bash theme={null}
curl -X POST https://api.neuro-admin.com/checkout/capture \
  -H "Authorization: Bearer $NEURO_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9"
  }'
```

```json theme={null}
{
  "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9"
}
```

Use this when a checkout was created with `capture: false` and payment was
authorized but not yet captured.

## Refund checkout

`POST /checkout/refund`

### cURL example

```bash theme={null}
curl -X POST https://api.neuro-admin.com/checkout/refund \
  -H "Authorization: Bearer $NEURO_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9",
    "amount": 500,
    "reason": "requested_by_customer"
  }'
```

```json theme={null}
{
  "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9",
  "amount": 500,
  "reason": "requested_by_customer"
}
```

### Refund notes

* `reason` must be one of `duplicate`, `fraudulent`, or
  `requested_by_customer`
* `amount` is sent in minor units. If not provided, the full remaining amount will be refunded.
* the refund amount cannot exceed the refundable balance

### Key fields

| Field           | Type    | Required | Description                                    |
| --------------- | ------- | -------- | ---------------------------------------------- |
| `checkout_id`   | string  | yes      | Unique identifier of the checkout              |
| `amount`        | integer | no       | Amount in minor units                          |
| `reason`        | string  | no       | Reason for the refund                          |
| `refundDetails` | string  | no       | Optional free text attached to the transaction |

## Update checkout metadata

`POST /checkout/update`

### cURL example

```bash theme={null}
curl -X POST https://api.neuro-admin.com/checkout/update \
  -H "Authorization: Bearer $NEURO_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9",
    "metaData": {
      "erpOrderId": "SO-1001",
      "oldKey": ""
    }
  }'
```

```json theme={null}
{
  "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9",
  "metaData": {
    "erpOrderId": "SO-1001",
    "oldKey": ""
  }
}
```

`metaData` is merged into the stored checkout metadata. Empty values can be
used to remove existing keys.

## Delete checkout

`POST /checkout/delete`

### cURL example

```bash theme={null}
curl -X POST https://api.neuro-admin.com/checkout/delete \
  -H "Authorization: Bearer $NEURO_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9"
  }'
```

```json theme={null}
{
  "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9"
}
```

Only checkouts still in `created` status can be deleted.

Example response:

```json theme={null}
{
  "status": "success",
  "message": "Checkout status changed to deleted.",
  "checkout_id": "ba3e9a3d911ca9e4413eb9e6dcaafec9"
}
```