### Run SDK Examples

Source: https://github.com/sumup/sumup-ts/blob/main/README.md

Command to execute example scripts for the SumUp Node.js SDK. This requires having an API key and merchant code configured for the examples.

```bash
npx tsx examples/checkout/index.ts
```

--------------------------------

### Install SumUp Node.js SDK

Source: https://github.com/sumup/sumup-ts/blob/main/README.md

Instructions for installing the SumUp Node.js SDK using npm or yarn, and from jsr for Deno environments. Ensure Node.js 18 or higher is installed.

```bash
npm install @sumup/sdk
# or
yarn add @sumup/sdk
```

```bash
deno add jsr:@sumup/sdk
# or
npx jsr add @sumup/sdk
```

--------------------------------

### Initialize and Use SumUp SDK (CommonJS)

Source: https://github.com/sumup/sumup-ts/blob/main/README.md

Demonstrates how to initialize the SumUp SDK with an API key and make a request to get merchant information using CommonJS modules and Promises. Handles success and error cases.

```javascript
const sumup = require('@sumup/sdk')({
  apiKey: 'sup_sk_MvxmLOl0...'
});

sumup.merchant.get()
  .then(merchant => console.info(merchant))
  .catch(error => console.error(error));
```

--------------------------------

### List and Retrieve Checkouts (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Provides examples for listing existing checkouts, optionally filtering by a reference, and retrieving a specific checkout's details using its ID. Displays the number of found checkouts and their status.

```typescript
// List checkouts by reference
const checkouts = await client.checkouts.list({
  checkout_reference: "ORDER-12345"
});

console.log(`Found ${checkouts.length} checkout(s)`);

// Retrieve specific checkout
const checkout = await client.checkouts.get("d6e3c6b5-6a3c-4a6a-8d19-c6b5e6a3c6b5");

console.log(`Status: ${checkout.status}`);
console.log(`Amount: ${checkout.amount} ${checkout.currency}`);
console.log(`Transactions: ${checkout.transactions?.length || 0}`);
```

--------------------------------

### Get Available Payment Methods

Source: https://context7.com/sumup/sumup-ts/llms.txt

Check which payment methods are available for a specific merchant and transaction details before creating a checkout.

```APIDOC
## Get Available Payment Methods

### Description
Check which payment methods are available for a specific merchant and transaction details before creating a checkout.

### Method
`client.checkouts.listAvailablePaymentMethods(merchantCode, params)`

### Parameters
#### Path Parameters
- **merchantCode** (string) - Required - The code of the merchant.

#### Query Parameters
None

#### Request Body (`params`)
- **amount** (number) - Required - The transaction amount.
- **currency** (string) - Required - The transaction currency code.

### Request Example
```typescript
const paymentMethods = await client.checkouts.listAvailablePaymentMethods(
  "MXYZ1234", // merchant code
  {
    amount: 100,
    currency: "EUR"
  }
);

paymentMethods.available_payment_methods?.forEach(method => {
  console.log(`Payment method available: ${method.id}`);
});
```

### Response
#### Success Response (Object)
- **available_payment_methods** (Array of Objects) - A list of available payment methods.
  - **id** (string) - The ID of the payment method.
  - **name** (string) - The name of the payment method.

#### Response Example
```json
{
  "available_payment_methods": [
    {
      "id": "card",
      "name": "Card"
    },
    {
      "id": "paypal",
      "name": "PayPal"
    }
  ]
}
```
```

--------------------------------

### Get Merchant Account Information (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Retrieves various details about the merchant account, including settings, 'doing business as' information, bank accounts, and app settings. It also shows how to fetch personal and merchant profiles separately.

```typescript
const account = await client.merchant.get({
  "include[]": [
    "settings",
    "doing_business_as",
    "bank_accounts",
    "app_settings",
    "country_details"
  ]
});

console.log(`Merchant Code: ${account.merchant_profile?.merchant_code}`);
console.log(`Company: ${account.merchant_profile?.company_name}`);
console.log(`Country: ${account.merchant_profile?.country}`);
console.log(`Payout Type: ${account.merchant_profile?.settings?.payout_type}`);

const personalProfile = await client.merchant.getPersonalProfile();
console.log(`Name: ${personalProfile.first_name} ${personalProfile.last_name}`);

const merchantProfile = await client.merchant.getMerchantProfile();
console.log(`VAT ID: ${merchantProfile.vat_id}`);

const dbaProfile = await client.merchant.getDoingBusinessAs();
console.log(`Business Name: ${dbaProfile.business_name}`);
```

--------------------------------

### Get Available Payment Methods (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Retrieves a list of payment methods available for a given merchant code, amount, and currency. This helps in determining valid payment options before creating a checkout. Iterates and logs available methods.

```typescript
const paymentMethods = await client.checkouts.listAvailablePaymentMethods(
  "MXYZ1234", // merchant code
  {
    amount: 100,
    currency: "EUR"
  }
);

paymentMethods.available_payment_methods?.forEach(method => {
  console.log(`Payment method available: ${method.id}`);
});
```

--------------------------------

### List Payouts (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Retrieves a list of payout history for a specific merchant within a given date range. Supports filtering, pagination, and ordering. Includes an example of using a deprecated endpoint for the current merchant.

```typescript
const payouts = await client.payouts.list(
  "MXYZ1234", // merchant code
  {
    start_date: "2025-01-01",
    end_date: "2025-01-31",
    format: "json",
    limit: 50,
    order: "desc"
  }
);

payouts.forEach(payout => {
  console.log(`ID: ${payout.id}`);
  console.log(`Amount: ${payout.amount} ${payout.currency}`);
  console.log(`Date: ${payout.date}`);
  console.log(`Status: ${payout.status}`);
  console.log(`Fee: ${payout.fee}`);
  console.log(`Type: ${payout.type}`);
  console.log("---");
});

const myPayouts = await client.payouts.listDeprecated({
  start_date: "2025-01-01",
  end_date: "2025-01-31",
  format: "json"
});
```

--------------------------------

### Initialize and Use SumUp SDK (ES Modules)

Source: https://github.com/sumup/sumup-ts/blob/main/README.md

Shows how to initialize the SumUp SDK with an API key and fetch merchant data using ES modules and async/await syntax. Requires Node.js 18+.

```typescript
import SumUp from "@sumup/sdk";

const client = new SumUp({
  apiKey: 'sup_sk_MvxmLOl0...',
});

const merchant = await client.merchant.get();
console.info(merchant);
```

--------------------------------

### Client Initialization

Source: https://context7.com/sumup/sumup-ts/llms.txt

Initialize the SumUp client with your API key to authenticate all requests. You can optionally specify the API host and additional fetch parameters.

```APIDOC
## Client Initialization

### Description
Initialize the SumUp client with your API key to authenticate all requests. You can optionally specify the API host and additional fetch parameters.

### Method
`new SumUp(options)`

### Parameters
#### Options
- **apiKey** (string) - Required - Your SumUp API key.
- **host** (string) - Optional - The API host. Defaults to the production host.
- **baseParams** (object) - Optional - Additional fetch parameters to be used for all requests.

### Request Example
```typescript
import SumUp from "@sumup/sdk";

const client = new SumUp({
  apiKey: 'sup_sk_MvxmLOl0...',
  host: 'https://api.sumup.com', // optional, defaults to production
  baseParams: {} // optional, additional fetch parameters
});

// Access merchant information
const merchant = await client.merchant.get();
console.log(merchant);
```

### Response
#### Success Response (Object)
Returns an initialized SumUp client instance.

#### Response Example
```json
{ /* SumUp client instance */ }
```
```

--------------------------------

### Initialize SumUp Client (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Demonstrates how to initialize the SumUp client with an API key. The client is used to authenticate all subsequent API requests. Optional parameters for host and baseParams can also be provided.

```typescript
import SumUp from "@sumup/sdk";

const client = new SumUp({
  apiKey: 'sup_sk_MvxmLOl0...',
  host: 'https://api.sumup.com', // optional, defaults to production
  baseParams: {} // optional, additional fetch parameters
});

// Access merchant information
const merchant = await client.merchant.get();
console.log(merchant);
```

--------------------------------

### Create and Process Checkout (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Shows how to create a payment checkout session and then process it with card details to charge a customer. Includes error handling for payment failures. Requires SUMUP_API_KEY environment variable.

```typescript
import SumUp from "@sumup/sdk";

const client = new SumUp({
  apiKey: process.env.SUMUP_API_KEY,
});

// Step 1: Create a checkout
const checkout = await client.checkouts.create({
  amount: 19.99,
  checkout_reference: "ORDER-12345",
  currency: "EUR",
  merchant_code: "MXYZ1234",
  description: "Premium subscription",
  return_url: "https://example.com/payment/callback",
  customer_id: "cust_123456" // optional, for saved customers
});

console.log(`Checkout created: ${checkout.id}`);

// Step 2: Process the checkout with card details
try {
  const result = await client.checkouts.process(checkout.id, {
    payment_type: "card",
    card: {
      name: "John Doe",
      number: "4200000000000042",
      expiry_month: "12",
      expiry_year: "2025",
      cvv: "123",
      last_4_digits: "0042",
      type: "VISA"
    }
  });

  if (result.status === "PAID") {
    console.log(`Payment successful! Transaction ID: ${result.transaction_id}`);
  }
} catch (error) {
  console.error(`Payment failed: ${error.message}`);
}
```

--------------------------------

### Create and Process Checkout

Source: https://context7.com/sumup/sumup-ts/llms.txt

Create a payment checkout session with specified details and then process it using card information to charge a customer.

```APIDOC
## Create and Process Checkout

### Description
Create a payment checkout session with specified details and then process it using card information to charge a customer.

### Method
1. `client.checkouts.create(checkoutDetails)`
2. `client.checkouts.process(checkoutId, paymentDetails)`

### Parameters
#### `client.checkouts.create(checkoutDetails)`
##### Path Parameters
None

##### Query Parameters
None

##### Request Body (`checkoutDetails`)
- **amount** (number) - Required - The amount to charge.
- **checkout_reference** (string) - Required - A unique reference for the checkout.
- **currency** (string) - Required - The currency code (e.g., 'EUR').
- **merchant_code** (string) - Required - The merchant code.
- **description** (string) - Optional - A description for the checkout.
- **return_url** (string) - Optional - The URL to redirect the user after payment.
- **customer_id** (string) - Optional - The ID of a saved customer.

#### `client.checkouts.process(checkoutId, paymentDetails)`
##### Path Parameters
- **checkoutId** (string) - Required - The ID of the checkout to process.

##### Query Parameters
None

##### Request Body (`paymentDetails`)
- **payment_type** (string) - Required - The type of payment (e.g., 'card').
- **card** (object) - Required if `payment_type` is 'card'.
  - **name** (string) - Required - The cardholder's name.
  - **number** (string) - Required - The full card number.
  - **expiry_month** (string) - Required - The expiry month (e.g., '12').
  - **expiry_year** (string) - Required - The expiry year (e.g., '2025').
  - **cvv** (string) - Required - The card verification value.
  - **last_4_digits** (string) - Required - The last 4 digits of the card number.
  - **type** (string) - Required - The card type (e.g., 'VISA').

### Request Example
```typescript
// Step 1: Create a checkout
const checkout = await client.checkouts.create({
  amount: 19.99,
  checkout_reference: "ORDER-12345",
  currency: "EUR",
  merchant_code: "MXYZ1234",
  description: "Premium subscription",
  return_url: "https://example.com/payment/callback",
  customer_id: "cust_123456" // optional, for saved customers
});

console.log(`Checkout created: ${checkout.id}`);

// Step 2: Process the checkout with card details
try {
  const result = await client.checkouts.process(checkout.id, {
    payment_type: "card",
    card: {
      name: "John Doe",
      number: "4200000000000042",
      expiry_month: "12",
      expiry_year: "2025",
      cvv: "123",
      last_4_digits: "0042",
      type: "VISA"
    }
  });

  if (result.status === "PAID") {
    console.log(`Payment successful! Transaction ID: ${result.transaction_id}`);
  }
} catch (error) {
  console.error(`Payment failed: ${error.message}`);
}
```

### Response
#### Success Response (Object)
- **id** (string) - The unique ID of the checkout.
- **status** (string) - The status of the checkout (e.g., 'PENDING', 'PAID', 'EXPIRED').
- **transaction_id** (string, optional) - The ID of the transaction if the checkout was paid.

#### Response Example
```json
{
  "id": "d6e3c6b5-6a3c-4a6a-8d19-c6b5e6a3c6b5",
  "status": "PAID",
  "transaction_id": "txn_abc123def456"
}
```
```

--------------------------------

### Point-of-Sale (POS) Integration Pattern

Source: https://context7.com/sumup/sumup-ts/llms.txt

Integration pattern for mobile point-of-sale systems using the SumUp SDK with physical card readers for in-person payments.

```APIDOC
## Point-of-Sale (POS) Integration

### Description
This pattern is designed for mobile or physical retail environments. It allows your application to interact with SumUp's physical card readers to accept in-person payments.

### Workflow
1. **Connect Reader**: Use the SDK to discover and connect to available SumUp card readers.
2. **Initiate Transaction**: Create a transaction request through the SDK, specifying the amount and currency.
3. **Process Payment**: The SDK communicates with the card reader to process the payment.
4. **Update Application**: Receive transaction status updates and confirmation within your application.

### Key Considerations
- **Reader Management**: Implement logic for reader discovery, connection, and handling connection errors.
- **Transaction History**: Maintain transaction records within your application for reconciliation and reporting.
```

--------------------------------

### Manage Customers (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Illustrates how to create, retrieve, and update customer records. This is useful for managing customer data, especially for recurring payments or tokenization. Uses customer IDs for operations.

```typescript
// Create a new customer
const customer = await client.customers.create({
  customer_id: "cust_unique_123",
  personal_details: {
    first_name: "Jane",
    last_name: "Smith",
    email: "jane.smith@example.com",
    phone: "+49123456789",
    address: {
      line_1: "123 Main Street",
      city: "Berlin",
      postal_code: "10115",
      country: "DE"
    }
  }
});

console.log(`Customer created: ${customer.customer_id}`);

// Retrieve customer
const existingCustomer = await client.customers.get("cust_unique_123");

// Update customer details
const updated = await client.customers.update("cust_unique_123", {
  personal_details: {
    email: "jane.newemail@example.com",
    phone: "+49987654321"
  }
});
```

--------------------------------

### Subscription and Recurring Payments Integration Pattern

Source: https://context7.com/sumup/sumup-ts/llms.txt

Pattern for handling subscription and recurring payments using customer tokenization via the Customers API.

```APIDOC
## Subscription and Recurring Payments

### Description
This pattern enables you to manage recurring billing and subscriptions by securely storing customer payment information (tokenization).

### Workflow
1. **Create Customer**: Use the Customers API to create a customer record.
2. **Setup Recurring Payment**: Initiate the first checkout with `purpose: "SETUP_RECURRING_PAYMENT"`. This saves the customer's payment instrument securely as a token.
3. **Process Subsequent Charges**: Use the obtained customer token to process future payments without needing the customer's card details again.

### Key Considerations
- **Token Security**: Ensure secure storage and handling of customer tokens.
- **Payment Failures**: Implement logic to handle failed recurring payments and customer communication.
```

--------------------------------

### Manage Customers

Source: https://context7.com/sumup/sumup-ts/llms.txt

Create, retrieve, and update customer records for purposes like recurring payments and tokenization.

```APIDOC
## Manage Customers

### Description
Create, retrieve, and update customer records for purposes like recurring payments and tokenization.

### Method
1. `client.customers.create(customerDetails)`
2. `client.customers.get(customerId)`
3. `client.customers.update(customerId, updateDetails)`

### Parameters
#### `client.customers.create(customerDetails)`
##### Path Parameters
None

##### Query Parameters
None

##### Request Body (`customerDetails`)
- **customer_id** (string) - Required - A unique identifier for the customer.
- **personal_details** (object) - Optional - Details about the customer.
  - **first_name** (string) - Optional.
  - **last_name** (string) - Optional.
  - **email** (string) - Optional.
  - **phone** (string) - Optional.
  - **address** (object) - Optional.
    - **line_1** (string) - Optional.
    - **city** (string) - Optional.
    - **postal_code** (string) - Optional.
    - **country** (string) - Optional.

#### `client.customers.get(customerId)`
##### Path Parameters
- **customerId** (string) - Required - The ID of the customer to retrieve.

##### Query Parameters
None

##### Request Body
None

#### `client.customers.update(customerId, updateDetails)`
##### Path Parameters
- **customerId** (string) - Required - The ID of the customer to update.

##### Query Parameters
None

##### Request Body (`updateDetails`)
- **personal_details** (object) - Optional - Updated personal details for the customer.
  - **email** (string) - Optional.
  - **phone** (string) - Optional.
  - **address** (object) - Optional.
    - **line_1** (string) - Optional.
    - **city** (string) - Optional.
    - **postal_code** (string) - Optional.
    - **country** (string) - Optional.

### Request Example
```typescript
// Create a new customer
const customer = await client.customers.create({
  customer_id: "cust_unique_123",
  personal_details: {
    first_name: "Jane",
    last_name: "Smith",
    email: "jane.smith@example.com",
    phone: "+49123456789",
    address: {
      line_1: "123 Main Street",
      city: "Berlin",
      postal_code: "10115",
      country: "DE"
    }
  }
});

console.log(`Customer created: ${customer.customer_id}`);

// Retrieve customer
const existingCustomer = await client.customers.get("cust_unique_123");

// Update customer details
const updated = await client.customers.update("cust_unique_123", {
  personal_details: {
    email: "jane.newemail@example.com",
    phone: "+49987654321"
  }
});
```

### Response
#### Success Response (Object)
- **customer_id** (string) - The unique ID of the customer.
- **personal_details** (object) - The personal details of the customer.

#### Response Example
```json
{
  "customer_id": "cust_unique_123",
  "personal_details": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.newemail@example.com",
    "phone": "+49987654321",
    "address": {
      "line_1": "123 Main Street",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "DE"
    }
  }
}
```
```

--------------------------------

### Create Reader Checkout (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Initiates a payment on a physical card reader device, specifying the amount, currency, and optional affiliate and tip details. It returns a transaction ID that can be used later to retrieve the transaction status.

```typescript
const merchantCode = "MXYZ1234";
const readerId = "reader_abc123";

const checkoutResponse = await client.readers.createCheckout(
  merchantCode,
  readerId,
  {
    total_amount: {
      currency: "EUR",
      minor_unit: 100, // smallest currency unit (cents for EUR)
      value: 1250 // 12.50 EUR
    },
    affiliate: {
      key: "partner_ref",
      value: "STORE_123"
    },
    tip: {
      minor_unit: 100,
      value: 150 // 1.50 EUR tip
    }
  }
);

const transactionId = checkoutResponse.data.client_transaction_id;
console.log(`Transaction initiated: ${transactionId}`);

const transaction = await client.transactions.get(transactionId);
console.log(`Transaction status: ${transaction.status}`);
```

--------------------------------

### E-commerce Integration Pattern

Source: https://context7.com/sumup/sumup-ts/llms.txt

Typical pattern for e-commerce applications involving creating a checkout, handling payment collection on the frontend, and processing from the backend. Supports automatic 3D Secure authentication.

```APIDOC
## E-commerce Integration

### Description
This pattern is suitable for online stores. It involves creating a checkout on your backend, directing the user to SumUp's hosted payment forms for secure payment collection, and handling the post-payment callback.

### Workflow
1. **Create Checkout**: Use the SDK to create a checkout with a `redirect_url` pointing back to your application.
2. **Redirect User**: Redirect the user to the SumUp payment page URL provided in the checkout response.
3. **Handle Callback**: Upon successful payment or failure, SumUp redirects the user back to your specified `redirect_url`. Your application should handle this callback to confirm the transaction status.
4. **3D Secure**: The SDK automatically handles 3D Secure authentication if required, redirecting users through the necessary steps.

### Key Considerations
- **PCI Compliance**: Using SumUp's hosted payment forms is recommended for PCI compliance.
- **Webhooks**: Implement webhooks for real-time transaction status updates.
```

--------------------------------

### Custom Fetch Parameters

Source: https://context7.com/sumup/sumup-ts/llms.txt

Shows how to pass custom headers or fetch options to individual requests, such as setting a custom header or a request timeout.

```APIDOC
## GET /checkouts/{checkoutId}

### Description
Retrieves a specific checkout by its ID, allowing for custom request headers and fetch options like timeouts.

### Method
GET

### Endpoint
`/checkouts/{checkoutId}`

### Parameters

#### Path Parameters
- **checkoutId** (string) - Required - The ID of the checkout to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const checkout = await client.checkouts.get(
  checkoutId,
  {
    headers: {
      'X-Custom-Header': 'value',
      'Accept-Language': 'en-US'
    },
    signal: AbortSignal.timeout(5000) // 5 second timeout
  }
);
```

### Response
#### Success Response (200)
- **checkout** (object) - The checkout details.

#### Response Example
```json
{
  "id": "checkout-id",
  "amount": 1000,
  "currency": "EUR"
}
```
```

--------------------------------

### Manage Payment Instruments (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Lists saved payment instruments for a customer and shows how to deactivate a specific instrument for tokenized payments. Requires a SumUp client instance.

```typescript
const instruments = await client.customers.listPaymentInstruments("cust_unique_123");

instruments.forEach(instrument => {
  console.log(`Token: ${instrument.token}`);
  console.log(`Card: ${instrument.card?.type} ending in ${instrument.card?.last_4_digits}`);
  console.log(`Active: ${instrument.active}`);
  console.log(`Created: ${instrument.created_at}`);
});

await client.customers.deactivatePaymentInstrument(
  "cust_unique_123",
  "tok_abc123def456"
);

console.log("Payment instrument deactivated");
```

--------------------------------

### Manage Card Readers (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Lists all paired card readers for a merchant, displaying their IDs, names, statuses, and device details. It also shows how to retrieve information for a specific reader by its ID.

```typescript
const { items: readers } = await client.readers.list("MXYZ1234");

readers.forEach(reader => {
  console.log(`Reader ID: ${reader.id}`);
  console.log(`Name: ${reader.name}`);
  console.log(`Status: ${reader.status}`);
  console.log(`Model: ${reader.device.model}`);
  console.log(`Serial: ${reader.device.identifier}`);
  console.log(`Created: ${reader.created_at}`);
});

const reader = await client.readers.get("MXYZ1234", "reader_abc123");
console.log(`Reader status: ${reader.status}`);
```

--------------------------------

### List and Retrieve Checkouts

Source: https://context7.com/sumup/sumup-ts/llms.txt

Query existing checkouts using a reference or retrieve a specific checkout by its unique ID.

```APIDOC
## List and Retrieve Checkouts

### Description
Query existing checkouts using a reference or retrieve a specific checkout by its unique ID.

### Method
1. `client.checkouts.list(params)`
2. `client.checkouts.get(checkoutId)`

### Parameters
#### `client.checkouts.list(params)`
##### Path Parameters
None

##### Query Parameters
- **checkout_reference** (string) - Optional - Filter checkouts by their reference.

##### Request Body
None

#### `client.checkouts.get(checkoutId)`
##### Path Parameters
- **checkoutId** (string) - Required - The ID of the checkout to retrieve.

##### Query Parameters
None

##### Request Body
None

### Request Example
```typescript
// List checkouts by reference
const checkouts = await client.checkouts.list({
  checkout_reference: "ORDER-12345"
});

console.log(`Found ${checkouts.length} checkout(s)`);

// Retrieve specific checkout
const checkout = await client.checkouts.get("d6e3c6b5-6a3c-4a6a-8d19-c6b5e6a3c6b5");

console.log(`Status: ${checkout.status}`);
console.log(`Amount: ${checkout.amount} ${checkout.currency}`);
console.log(`Transactions: ${checkout.transactions?.length || 0}`);
```

### Response
#### Success Response (Array of Objects for `list`, Object for `get`)
- **id** (string) - The unique ID of the checkout.
- **checkout_reference** (string) - The reference of the checkout.
- **amount** (number) - The amount charged.
- **currency** (string) - The currency code.
- **status** (string) - The status of the checkout.
- **transactions** (Array of Objects, optional) - Details of associated transactions.

#### Response Example (for `get`)
```json
{
  "id": "d6e3c6b5-6a3c-4a6a-8d19-c6b5e6a3c6b5",
  "checkout_reference": "ORDER-12345",
  "amount": 19.99,
  "currency": "EUR",
  "status": "PAID",
  "transactions": [
    {
      "id": "txn_abc123def456",
      "status": "COMPLETED"
    }
  ]
}
```
```

--------------------------------

### Error Handling with Response Details

Source: https://context7.com/sumup/sumup-ts/llms.txt

Demonstrates how to access full response details, including headers and status codes, when handling API errors with the SumUp SDK.

```APIDOC
## GET /merchant

### Description
Retrieves merchant data along with response metadata such as status and headers.

### Method
GET

### Endpoint
`/merchant`

### Parameters

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
try {
  // Get data with response metadata
  const { data, response } = await client.merchant.get().withResponse();

  console.log("Status:", response.status);
  console.log("Headers:", response.headers);
  console.log("Merchant:", data.merchant_profile?.merchant_code);

} catch (error) {
  if (error instanceof SumUp.APIError) {
    console.error(`API Error ${error.status}:`, error.error);
    console.error("Response:", error.response);
  } else {
    console.error("Unexpected error:", error);
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The merchant data.
- **response** (object) - The response metadata, including status and headers.

#### Response Example
```json
{
  "data": {
    "merchant_profile": {
      "merchant_code": "YOUR_MERCHANT_CODE"
    }
  },
  "response": {
    "status": 200,
    "headers": {
      "content-type": "application/json"
    }
  }
}
```
```

--------------------------------

### Pass Custom Fetch Parameters to Requests (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Shows how to include custom HTTP headers and fetch options, such as setting an 'Accept-Language' header or configuring a request timeout using AbortSignal, for individual SumUp API requests.

```typescript
const checkout = await client.checkouts.get(
  checkoutId,
  {
    headers: {
      'X-Custom-Header': 'value',
      'Accept-Language': 'en-US'
    },
    signal: AbortSignal.timeout(5000) // 5 second timeout
  }
);
```

--------------------------------

### API Error Handling

Source: https://context7.com/sumup/sumup-ts/llms.txt

Details on the SumUp SDK's typed exception system for handling API errors, providing HTTP status codes and detailed error messages.

```APIDOC
## API Error Handling

### Description
The SumUp SDK provides typed exceptions to simplify error management. These exceptions expose valuable information for implementing robust error handling strategies.

### Exception Details
- **SumUp.APIError**: A specific error type for API-related issues.
  - **status**: The HTTP status code of the error response.
  - **error**: A detailed error message or object from the API.
  - **response**: The raw response object associated with the error.

### Recommended Practices
- **Retry Logic**: Implement intelligent retry mechanisms for transient errors (e.g., 5xx status codes).
- **User Feedback**: Provide clear and user-friendly error messages based on the API error details.
```

--------------------------------

### Handle API Errors with Full Response Details (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Demonstrates how to catch and handle SumUp API errors, extracting detailed information such as status codes, headers, and specific error messages from the response. This allows for more granular error management and user feedback.

```typescript
try {
  // Get data with response metadata
  const { data, response } = await client.merchant.get().withResponse();

  console.log("Status:", response.status);
  console.log("Headers:", response.headers);
  console.log("Merchant:", data.merchant_profile?.merchant_code);

} catch (error) {
  if (error instanceof SumUp.APIError) {
    console.error(`API Error ${error.status}:`, error.error);
    console.error("Response:", error.response);
  } else {
    console.error("Unexpected error:", error);
  }
}
```

--------------------------------

### Process Checkout with Saved Card (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Processes a checkout using a previously saved tokenized card for returning customers. This requires the checkout ID and the payment token. The status of the payment is checked upon completion.

```typescript
const checkout = await client.checkouts.create({
  amount: 29.99,
  checkout_reference: "RECURRING-789",
  currency: "GBP",
  merchant_code: "MXYZ1234",
  customer_id: "cust_unique_123"
});

const result = await client.checkouts.process(checkout.id, {
  payment_type: "card",
  token: "tok_abc123def456",
  customer_id: "cust_unique_123"
});

if (result.status === "PAID") {
  console.log("Recurring payment successful!");
}
```

--------------------------------

### Deactivate Checkout (TypeScript)

Source: https://context7.com/sumup/sumup-ts/llms.txt

Demonstrates how to deactivate a pending checkout using its ID. This operation is only possible for checkouts that have not yet been processed. Logs success or failure messages.

```typescript
try {
  const deactivated = await client.checkouts.deactivate(checkoutId);

  if (deactivated.status === "EXPIRED") {
    console.log("Checkout successfully deactivated");
  }
} catch (error) {
  console.error("Cannot deactivate processed checkout:", error);
}
```

--------------------------------

### Deactivate Checkout

Source: https://context7.com/sumup/sumup-ts/llms.txt

Cancel a pending checkout that has not yet been processed.

```APIDOC
## Deactivate Checkout

### Description
Cancel a pending checkout that has not yet been processed.

### Method
`client.checkouts.deactivate(checkoutId)`

### Parameters
#### Path Parameters
- **checkoutId** (string) - Required - The ID of the checkout to deactivate.

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
try {
  const deactivated = await client.checkouts.deactivate(checkoutId);

  if (deactivated.status === "EXPIRED") {
    console.log("Checkout successfully deactivated");
  }
} catch (error) {
  console.error("Cannot deactivate processed checkout:", error);
}
```

### Response
#### Success Response (Object)
- **id** (string) - The ID of the checkout.
- **status** (string) - The updated status of the checkout, expected to be 'EXPIRED'.

#### Response Example
```json
{
  "id": "d6e3c6b5-6a3c-4a6a-8d19-c6b5e6a3c6b5",
  "status": "EXPIRED"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.