### Frontend Checkout Samples Setup

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Instructions to set up and run the frontend demo project for xMoney Checkout samples. This includes cloning the repository, installing dependencies, configuring the public key and optionally the user ID in constants, and starting the application.

```bash
git clone git@github.com:xMoney-Payments/checkout-samples.git
cd checkout-sample
npm install

# Update src/constants/general.constants.ts with your public key and customerId

npm start
```

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

### Backend Checkout Samples API Setup

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Instructions to set up and run the backend demo project for xMoney Checkout samples. This involves cloning the GitHub repository, installing Node.js dependencies, configuring the secret key in the application service, and starting the development server.

```bash
git clone git@github.com:xMoney-Payments/checkout-samples-api.git
cd checkout-samples-api
npm install

# Update app.service.ts with your secret key

npm run start:dev
```

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

### Install xMoney API SDK

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Installs the xMoney API SDK using npm. This package provides server-side utilities for interacting with the xMoney payment API.

```shell
npm install @xmoney/api-sdk
```

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

### Install xMoney Client SDK via CDN

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Include the xMoney Client SDK in your website by adding this script tag to your HTML. This makes the SDK functionalities available globally.

```html
<script
  src="https://secure-stage.xmoney.com/sdk/0.0.9/xmoney.js"
></script>
```

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

### Example Error Responses

Source: https://docs.xmoney.com/api/errors

Provides concrete examples of error responses for specific scenarios like 'Conflict' and 'Not Found'.

```APIDOC
## Example Error Responses

### 409 Conflict Example

This example shows an error response when a requested resource causes a conflict, such as attempting to create a customer that already exists.

```json
{
  "code": 409,
  "message": "Conflict",
  "errors": [
    {
      "code": 1627,
      "message": "Customer already exists",
      "type": "Exception"
    }
  ]
}
```

### 404 Not Found Example

This example illustrates an error response when a requested resource, like a specific card, cannot be found.

```json
{
  "code": 404,
  "message": "Not Found",
  "errors": [
    {
      "code": 902,
      "message": "Card not found",
      "type": "Exception"
    }
  ]
}
```
```

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

### Create Recurring Payment Plan with cURL

Source: https://docs.xmoney.com/guides/payments/recurring-payments

This example demonstrates how to create a recurring payment plan using a cURL command. It includes essential parameters like customer ID, order type, amount, currency, interval type, and an optional trial amount. The response indicates the success of the order creation.

```bash
curl -X POST \
  https://api.xmoney.com/order \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'customerId=12345&orderType=recurring&amount=29.99&currency=USD&ip=192.168.1.1&intervalType=month&intervalValue=1&description=Monthly%20Subscription&trialAmount=1.00'
```

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

### Example Request with Digital Wallet Parameters - JSON

Source: https://docs.xmoney.com/guides/payments/payment-methods/google-pay

An example of a transaction request that includes the additional parameters needed for digital wallet integration, specifically forcing the Google Pay method.

```json
{
  "siteId": 1,
  "customer": {
    ...
  },
  "order": {
    ...
    "forceMethodType": "digitalWallet",
    "forceMethodBrand": "googlePay", //"applePay"
    ...
  },
  "cardTransactionMode": "authAndCapture",
  "transactionOption" : {
    ...
  }
}
```

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

### Get Order Details using cURL

Source: https://docs.xmoney.com/crypto_api/introduction

Example of how to retrieve order details from the xMoney API using a cURL command. It demonstrates the HTTP method, URL structure for fetching a specific order by ID, and the required Authorization header.

```bash
curl -X GET \
 https://merchants.api.crypto.xmoney.com/api/stores/orders/{orderId} \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

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

### Request JWT Token via cURL, JavaScript, Python, PHP

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Demonstrates how to request a JWT token from the xMoney API using various common programming languages and tools. Includes examples for cURL, JavaScript (Axios), Python (requests), and PHP (cURL). These examples show how to set the correct HTTP method, URL, and headers for the request.

```bash
curl -X GET "https://api-stage.xmoney.com/auth/jwt-token" \
  -H "Authorization: Bearer your_secret_key_here" \
  -H "Content-Type: application/json"
```

```javascript
const axios = require('axios');

  const response = await axios.get('https://api-stage.xmoney.com/auth/jwt-token', {
    headers: {
      'Authorization': 'Bearer sk_test_your_secret_key_here',
      'Content-Type': 'application/json'
    }
  });

  console.log(response.data);
```

```python
import requests

  url = "https://api-stage.xmoney.com/auth/jwt-token"
  headers = {
      "Authorization": "Bearer sk_test_your_secret_key_here",
      "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers)
  data = response.json()
  print(data)
```

```php
<?php
    $url = "https://api-stage.xmoney.com/auth/jwt-token";
    $headers = [
        "Authorization: Bearer sk_test_your_secret_key_here",
        "Content-Type: application/json"
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response, true);
    print_r($data);
    ?>
```

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

### Example API Response Format

Source: https://docs.xmoney.com/api/introduction

This is an example of a typical JSON response from the xMoney API. It includes a status code, a message indicating the outcome, and a data object containing relevant information. Successful creation requests often return a 201 status code.

```json
{
    "code": 201,
    "message": "Created",
    "data": {
        "id": "unique-id"
    }
}
```

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

### API Request: Partial Refund using cURL

Source: https://docs.xmoney.com/guides/payments/refunds

Shows how to issue a partial refund for a transaction using cURL. This example includes the transaction ID, a reason, a message, and crucially, the specific 'amount' to be refunded. Replace YOUR_API_KEY with your valid API key.

```bash
curl -X DELETE \
  https://api.xmoney.com/transaction/12345 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'reason=customer-demand&message=Partial%20refund%20for%20damaged%20item&amount=25.50'
```

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

### Build xMoney Checkout Form Payload (JSON)

Source: https://docs.xmoney.com/guides/payments/one-off-payments

Example JSON payload for initiating a one-off purchase via xMoney's hosted checkout page. It includes customer and order details, payment type, amount, currency, and return URL. The `purchase` type indicates a one-off payment.

```json
{
  "siteId": 1,
  "customer": {
    "identifier": "your-unique-customer-id",
    "email": "john.doe@myshop.com"
  },
  "order": {
    "orderId": "your-unique-order-id",
    "description": "Order #122",
    "type": "purchase",
    "amount": 110,
    "currency": "EUR"
  },
  "cardTransactionMode": "authAndCapture",
  "backUrl": "https://myshop.com/payment-back-url"
}
```

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

### Example Webhook Payload (JSON)

Source: https://docs.xmoney.com/guides/crypto/webhooks

This JSON object represents an example payload for a webhook event, including event type, resource details, signature, and state. It demonstrates the structure of data sent by the xMoney platform.

```json
{
  "event_type": "ORDER.PAYMENT.RECEIVED",
  "resource": {
    "reference": "1400012634",
    "amount": "10.8200",
    "currency": "EUR"
  },
  "signature": "5ef8a5994e917c14479b31f690d4d2a023dfcc6059081504e3087977b21580ab",
  "state": "completed"
}
```

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

### GET /customer

Source: https://docs.xmoney.com/api/reference/customer

Fetches a list of all customers. This endpoint is useful for retrieving an overview of all registered customers.

```APIDOC
## GET /customer

### Description
Fetches a list of all customers.

### Method
GET

### Endpoint
/customer

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of customers to return.
- **offset** (integer) - Optional - The number of customers to skip before returning results.

### Request Example
```
GET /customer?limit=10&offset=0
```

### Response
#### Success Response (200)
- **customers** (array) - A list of customer objects.
  - **id** (string) - The unique identifier for the customer.
  - **name** (string) - The name of the customer.
  - **email** (string) - The email address of the customer.

#### Response Example
```json
{
  "customers": [
    {
      "id": "cust_12345",
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    {
      "id": "cust_67890",
      "name": "Jane Smith",
      "email": "jane.smith@example.com"
    }
  ]
}
```
```

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

### xMoney API Example Error: 404 Not Found (JSON)

Source: https://docs.xmoney.com/crypto_api/errors

Presents an example of a 404 Not Found error response from the xMoney Crypto API. This JSON structure includes the error code 404 and a descriptive 'detail' message, 'Resource not found'. It aids in diagnosing and handling requests for non-existent resources.

```json
{
  "code": 404,
  "errors": [
    {
      "detail": "Resource not found"
    }
  ]
}
```

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

### Create Pre-Authorized Order

Source: https://docs.xmoney.com/guides/payments/pre-authorization-capture

Initiates a payment by pre-authorizing funds on the customer's card. The `cardTransactionMode` should be set to 'auth'.

```APIDOC
## POST /orders

### Description
Creates a new order with a pre-authorization transaction mode to reserve funds on the customer's card.

### Method
POST

### Endpoint
/orders

### Parameters
#### Request Body
- **siteId** (string) - Required - The ID of the site.
- **customer** (object) - Required - Customer details.
- **order** (object) - Required - Order details.
  - **orderId** (string) - Required - Unique identifier for the order.
  - **type** (string) - Required - Type of the order (e.g., "purchase").
  - **amount** (number) - Required - The amount to pre-authorize.
  - **currency** (string) - Required - The currency of the amount (e.g., "EUR").
  - **description** (string) - Optional - A description of the order.
- **cardTransactionMode** (string) - Required - Must be set to "auth" for pre-authorization.

### Request Example
```json
{
  "siteId": "yourSiteId",
  "customer": {},
  "order": {
    "orderId": "order1",
    "type": "purchase",
    "amount": 10,
    "currency": "EUR",
    "description": "Sample Pre-Auth Order"
  },
  "cardTransactionMode": "auth"
}
```

### Response
#### Success Response (200)
- **transactionId** (string) - The ID of the created pre-authorization transaction.
- **orderId** (string) - The ID of the order.
- **status** (string) - The status of the transaction.

#### Response Example
```json
{
  "transactionId": "txn_12345",
  "orderId": "order1",
  "status": "pre-authorized"
}
```
```

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

### GET /auth/jwt-token

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Obtain a JWT token for authentication with the xMoney API. This token is required for subsequent API requests.

```APIDOC
## GET /auth/jwt-token

### Description
This endpoint is used to retrieve a JSON Web Token (JWT) which is necessary for authenticating requests to the xMoney API.

### Method
GET

### Endpoint
`https://api-stage.xmoney.com/auth/jwt-token`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication
- **Content-Type** (string) - Required - `application/json`

### Request Example
```bash
curl -X GET "https://api-stage.xmoney.com/auth/jwt-token" \
  -H "Authorization: Bearer your_secret_key_here" \
  -H "Content-Type: application/json"
```

### Response
#### Success Response (200)
- **token** (string) - The JWT token

#### Response Example
```json
{
  "token": "your_jwt_token_here"
}
```
```

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

### Initialize xMoney Checkout SDK

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Initializes the xMoney checkout SDK with specified container, public key, and options. It includes callbacks for error handling and readiness notification. Dependencies include the `XMoneyCheckout` class, typically available globally.

```javascript
const sdk = new window.XMoneyCheckout({
      container: "payment-widget",
      publicKey: PUBLIC_KEY,
      options: { appearance: customThemeStyles },
      onError: (err: any) => console.error("❌ Payment error", err),
      onReady: () => setIsReady(true),
    });

document.querySelector("#pay-button").addEventListener("click", async () => {
  await sdk.submitPayment({ payload, checksum })
})
```

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

### GET /order

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Retrieve order details, including status, by providing an external order ID. This is used for handling payment results without redirect.

```APIDOC
## GET /order

### Description
Retrieves the status and details of a specific order using its external identifier. This endpoint is crucial for implementing a polling mechanism to track payment completion without requiring a user redirect.

### Method
GET

### Endpoint
`https://api-stage.xmoney.com/order`

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number for pagination. Defaults to 0.
- **perPage** (integer) - Optional - The number of results per page. Defaults to 1.
- **externalOrderId** (string) - Required - The unique identifier of the order to retrieve.

### Request Example
```bash
curl -X GET "https://api-stage.xmoney.com/order?page=0&perPage=1&externalOrderId=your_order_id_here"
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the order (e.g., `complete-ok`, `complete-failed`).
- **orderId** (string) - The internal order ID.
- **externalOrderId** (string) - The external order ID provided.

#### Response Example
```json
{
  "status": "complete-ok",
  "orderId": "ord_abc123",
  "externalOrderId": "your_order_id_here"
}
```
```

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

### Authenticate API Request with Curl

Source: https://docs.xmoney.com/api/authentication

Example of how to include an API key in the Authorization header for a curl request to the xMoney API. This demonstrates the correct format for authenticating GET requests.

```bash
curl -X GET \
  https://api-stage.xmoney.com/order \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

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

### Backend Checkout Samples API Configuration

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Code snippet for initializing the xMoney API client within the backend application service. It demonstrates how to set the `secretKey` and enable verbose logging for debugging purposes.

```typescript
constructor() {
    this.xMoneyApiClient = new xMoneyApiClient({
      secretKey: 'sk_test_<your-secret-key>',
      verbose: true,
    });
  }
```

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

### Create Customer using cURL

Source: https://docs.xmoney.com/api/introduction

This example demonstrates how to create a new customer using the xMoney API via a cURL command. It specifies the endpoint, authentication header, content type, and customer data in URL-encoded format. The API expects POST requests with 'application/x-www-form-urlencoded' content type.

```bash
curl -X POST \
  https://api-stage.xmoney.com/customer \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d email=johndoe@example.com \
  -d identifier=my-unique-id
```

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

### Authenticate API Request using Curl

Source: https://docs.xmoney.com/crypto_api/authentication

Example of how to include your API key in a curl request to authenticate with the xMoney Crypto API. It demonstrates the GET request method and the required 'Authorization' header.

```bash
curl -X GET \
 https://merchants.api.crypto.xmoney.com/api/stores/orders/ \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

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

### Create an order

Source: https://docs.xmoney.com/crypto_api/reference

Creates a new order for payment processing. Returns a URL where the buyer can complete the payment.

```APIDOC
## POST /stores/orders

### Description
Creates a new order for payment processing and returns a URL where the buyer can complete the payment.

### Method
POST

### Endpoint
/stores/orders

### Parameters
#### Query Parameters
None

#### Request Body
(Not specified in provided text, refer to OpenAPI description for details)

### Request Example
(Not specified in provided text, refer to OpenAPI description for details)

### Response
#### Success Response (200)
- **url** (string) - The URL where the buyer can complete the payment.

#### Response Example
{
  "data": {
    "type": "order",
    "id": "ord_12345",
    "attributes": {
      "payment_url": "https://pay.xmoney.com/pay/abcde"
    }
  }
}
```

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

### Initialize xMoney Full Payment Form SDK

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Instantiate the xMoneyPaymentForm class to render the full checkout form. Configure appearance, locale, saved card options, and callbacks for readiness and errors. Requires container ID, public key, and other specific options.

```javascript
const sdk = new window.XMoneyPaymentForm({
    container: "payment-form-widget", // placeholder for the payment form
    options: {
      appearance: customThemeStyles,
      locale: "en-US", // "en-US" | "el-GR" | "ro-RO";
      displaySaveCardOption?: true; // displays the checkbox for saving the cards
      enableSavedCards?: true; // Display a list of saved cards
      enableBackgroundRefresh?: true; // Enables background refresh for the payment form
      displayCardHolderName?: false; // Displays a cardholder name in the form
      validationMode?: "onSubmit" | "onChange" | "onBlur" | "onTouched"; // Validation mode for the form. Default is "onSubmit".
    }
    savedCards: [], // list with saved cards prefetched for a customerId
    checksum: '', // checksum for the payment payload, received from the API
    payload: '', // order payload
    publicKey: PUBLIC_KEY, // your public key using the pk_<env>_<siteId> format
    userId: 0, // Needed to fetch user's cards
    sessionToken: '', // Session token used for background data refresh or saved card functionality.
    onReady: () => setIsReady(true), // callback when the paymentForm is ready
    onError: (err: any) => console.error("❌ Payment error", err), // error callback
    onPaymentComplete: (data: unknown) => void; // Callback executed when the payment is completed.
  });
```

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

### Change Payment Method with cURL

Source: https://docs.xmoney.com/guides/payments/recurring-payments

This example demonstrates updating the payment method for future recurring payments using a cURL request. It requires the order ID and allows specifying a new transaction method and associated card ID.

```bash
curl -X PUT \
  https://api.xmoney.com/order/67890 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'customerId=12345&orderType=recurring&transactionMethod=card&cardId=c_123456'
```

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

### Initialize xMoney API SDK

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Initializes the xMoney API SDK with a provided secret key. This client is used for server-side operations, such as creating payment intents and generating session tokens.

```typescript
import xMoneyApiClient from "@xmoney/api-sdk";

const client = new xMoneyApiClient({
  secretKey: "sk_test_secretkey",
});
```

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

### Update Recurring Payment Plan with cURL

Source: https://docs.xmoney.com/guides/payments/recurring-payments

This example shows how to update an existing recurring payment plan using a cURL command. It targets a specific order ID and allows modification of parameters such as the next due date, interval type, and interval value.

```bash
curl -X PUT \
  https://api.xmoney.com/order/67890 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'customerId=12345&orderType=recurring&nextDueDate=2023-12-01T00:00:00Z&intervalType=month&intervalValue=1'
```

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

### POST /order

Source: https://docs.xmoney.com/api/reference/order/create-an-order

Creates new orders, supporting both one-time purchases and recurring subscriptions.

```APIDOC
## POST /order

### Description
This endpoint creates new orders, supporting both one-time purchases and recurring subscriptions.

### Method
POST

### Endpoint
/order

### Parameters
#### Query Parameters
- **version** (string) - Optional - API version. Defaults to 1.0.

#### Request Body
(No specific request body fields provided in the input text)

### Request Example
(No example provided in the input text)

### Response
#### Success Response (200)
(No specific success response fields provided in the input text)

#### Response Example
(No example provided in the input text)
```

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

### Handle xMoney Payment Notification Payload (JSON)

Source: https://docs.xmoney.com/guides/payments/one-off-payments

Example JSON payload received from xMoney after a payment is completed. It contains transaction status, order and transaction IDs, customer details, amount, currency, custom data, and timestamp. Use `transactionStatus` to determine payment outcome.

```json
{
  "transactionStatus": "complete-ok",
  "orderId": 1234,
  "externalOrderId": "your-unique-order-id",
  "transactionId": 1234,
  "transactionMethod": "card",
  "customerId": 1,
  "identifier": "your-unique-customer-id",
  "amount": 110,
  "currency": "EUR",
  "customData": {
    "key_1": "value_1",
    "key_2": "value_2"
  },
  "timestamp": 1600874501,
  "cardId": 3
}
```

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

### POST /customer

Source: https://docs.xmoney.com/api/introduction

Creates a new customer with the provided email and a unique identifier. This endpoint is used to onboard new customers into the xMoney system.

```APIDOC
## POST /customer

### Description
Creates a new customer with the provided email and a unique identifier. This endpoint is used to onboard new customers into the xMoney system.

### Method
POST

### Endpoint
/customer

### Parameters
#### Query Parameters
- **email** (string) - Required - The email address of the customer.
- **identifier** (string) - Required - A unique identifier for the customer.

### Request Example
```bash
curl -X POST \
  https://api-stage.xmoney.com/customer \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d email=johndoe@example.com \
  -d identifier=my-unique-id
```

### Response
#### Success Response (201)
- **code** (integer) - The status code of the response.
- **message** (string) - A message indicating the result of the operation.
- **data** (object) - Contains additional data related to the response.
  - **id** (string) - The unique identifier assigned to the newly created customer.

#### Response Example
```json
{
    "code": 201,
    "message": "Created",
    "data": {
        "id": "unique-id"
    }
}
```
```

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

### Example xMoney Transaction Notification Payload

Source: https://docs.xmoney.com/guides/payments/accepting-payments

This JSON object represents a typical notification payload received from xMoney after a payment transaction. It includes details such as transaction status, order IDs, amount, currency, and custom data, which are essential for updating order fulfillment and providing customer feedback.

```json
{
  "transactionStatus": "complete-ok",
  "orderId": 1234,
  "externalOrderId": "external-order-id",
  "transactionId": 1234,
  "transactionMethod": "card",
  "customerId": 1,
  "identifier": "identifier",
  "amount": 5.55,
  "currency": "EUR",
  "customData": {
    "key_1": "value_1",
    "key_2": "value_2"
  },
  "timestamp": 1600874501,
  "cardId": 3
}
```

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

### Frontend Checkout Samples Configuration

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Code snippets for configuring the xMoney public key and user ID in the frontend application. The `PUBLIC_KEY` is essential for checkout initialization, and `USER_ID` is required for fetching saved cards.

```typescript
export const PUBLIC_KEY = "pk_test_<your_site_id>";

export const USER_ID = <customerId>;
```

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

### POST /websites/xmoney - Initiate One-off Payment

Source: https://docs.xmoney.com/guides/payments/one-off-payments

Initiates a one-off payment by constructing a checkout form with a base64 encoded JSON payload and a checksum. This form redirects the customer to the xMoney hosted checkout page.

```APIDOC
## POST /websites/xmoney

### Description
Initiates a one-off payment by constructing a checkout form. This form redirects the customer to the xMoney hosted checkout page to complete the transaction.

### Method
POST

### Endpoint
/websites/xmoney

### Parameters
#### Request Body
- **jsonRequest** (string) - Required - The base64 encoded JSON payload containing payment details.
- **checksum** (string) - Required - A checksum to ensure the integrity of the `jsonRequest`.

### Request Example
```html
<form action="https://secure-stage.xmoney.com" method="POST" accept-charset="UTF-8">
  <input type="hidden" name="jsonRequest" value="${base64JsonRequest}">
  <input type="hidden" name="checksum" value="${base64Checksum}">
    
  <button type="submit">Pay Now</button>
</form>
```

### Response
#### Success Response (302)
- Redirects the customer to the xMoney hosted checkout page.

#### Response Example
(Browser redirect to payment page)
```

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

### POST /stores/orders

Source: https://docs.xmoney.com/crypto_api/reference/order/create-an-order

Creates a new order for payment processing and returns a URL where the buyer can complete the payment.

```APIDOC
## POST /stores/orders

### Description
Creates a new order for payment processing and returns a URL where the buyer can complete the payment.

### Method
POST

### Endpoint
/stores/orders

### Parameters
#### Request Body
- **data** (object) - Required
  - **data.type** (string) - Required - Enum: "orders"
  - **data.attributes** (object) - Required
    - **data.attributes.order** (object) - Required - Represents the input data for creating an order.
      - **data.attributes.order.reference** (string) - Required - Your internal reference for the order. Example: "order-1977"
      - **data.attributes.order.amount** (object) - Required - The amount details for the order.
        - **data.attributes.order.amount.total** (string) - Required - The total amount, formatted as a decimal string (e.g., "1090.00"). Example: "1090.00"
        - **data.attributes.order.amount.currency** (string) - Required - The 3-letter currency code (ISO 4217). Enum: "AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "CZK", "DKK", "DOP", "EUR", "GBP", "HKD", "HUF", "IDR", "ILS", "INR", "JPY", "KRW", "MYR", "MXN", "NOK", "NZD", "PHP", "PKR", "PLN", "RON", "RUB", "SEK", "SGD", "THB", "TWD", "USD", "ZAR". Example: "USD"
        - **data.attributes.order.amount.details** (object) - Optional - Details about the amount breakdown.
          - **data.attributes.order.amount.details.subtotal** (string) - The subtotal amount. Example: "98.00"
          - **data.attributes.order.amount.details.shipping** (string) - The shipping amount. Example: "10.00"
          - **data.attributes.order.amount.details.tax** (string) - The tax amount. Example: "3.00"
          - **data.attributes.order.amount.details.discount** (string) - The discount amount. Example: "2.00"
      - **data.attributes.order.return_urls** (object) - Required - URLs for redirecting the user after payment.
        - **data.attributes.order.return_urls.return_url** (string) - Required - URL to redirect to upon successful payment. Example: "https://example.com/success"
        - **data.attributes.order.return_urls.cancel_url** (string) - Optional - URL to redirect to if the payment is canceled. Example: "https://example.com/cancel"
        - **data.attributes.order.return_urls.callback_url** (string) - Optional - URL to send webhooks to for payment status updates. Example: "https://example.com/webhook"
      - **data.attributes.order.line_items** (array) - Deprecated - List of items in the order.
        - **data.attributes.order.line_items.name** (string) - Required - The name of the item. Example: "T-Shirt White Large"
        - **data.attributes.order.line_items.price** (string) - Required - The price of the item. Example: "100.00"
        - **data.attributes.order.line_items.currency** (string) - Required - The currency of the item price. Example: "USD"
        - **data.attributes.order.line_items.quantity** (integer) - Required - The quantity of the item. Example: 5
        - **data.attributes.order.line_items.sku** (string) - Optional - The SKU (Stock Keeping Unit) of the item. Example: "tsh-6110"
    - **data.attributes.customer** (object) - Required - Represents customer information.
      - **data.attributes.customer.email** (string) - Required - The customer's email address. Example: "john@example.com"
      - **data.attributes.customer.country** (string) - Required - The billing country code (ISO 3166-1 alpha-2). Example: "US"
      - **data.attributes.customer.name** (string) - Optional - Full name of the customer (first_name + last_name). Only available in responses. Example: "John Doe"
      - **data.attributes.customer.first_name** (string) - Optional - The customer's first name. Example: "John"
      - **data.attributes.customer.last_name** (string) - Optional - The customer's last name. Example: "Doe"
      - **data.attributes.customer.billing_address** (string) - Optional - Full billing address (address1 + address2). Only available in responses. Example: "118 Main St"
      - **data.attributes.customer.address1** (string) - Optional - The first line of the billing address. Example: "118 Main St"
      - **data.attributes.customer.address2** (string) - Optional - The second line of the billing address. Example: "Apartment 1"
      - **data.attributes.customer.city** (string) - Optional - The billing city. Example: "Anytown"
      - **data.attributes.customer.state** (string) - Optional - The billing state or region. Example: "CA"
      - **data.attributes.customer.postcode** (string) - Optional - The billing postal code. Example: "12345"

### Request Example
```json
{
  "data": {
    "type": "orders",
    "attributes": {
      "order": {
        "reference": "order-1977",
        "amount": {
          "total": "1090.00",
          "currency": "USD",
          "details": {
            "subtotal": "98.00",
            "shipping": "10.00",
            "tax": "3.00",
            "discount": "2.00"
          }
        },
        "return_urls": {
          "return_url": "https://example.com/success",
          "cancel_url": "https://example.com/cancel",
          "callback_url": "https://example.com/webhook"
        },
        "line_items": [
          {
            "name": "T-Shirt White Large",
            "price": "100.00",
            "currency": "USD",
            "quantity": 5,
            "sku": "tsh-6110"
          }
        ]
      },
      "customer": {
        "email": "john@example.com",
        "country": "US",
        "first_name": "John",
        "last_name": "Doe",
        "address1": "118 Main St",
        "address2": "Apartment 1",
        "city": "Anytown",
        "state": "CA",
        "postcode": "12345"
      }
    }
  }
}
```

### Response
#### Success Response (201)
- **data** (object) - Required
  - **data.type** (string) - Enum: "orders_redirect"
  - **data.id** (string) - A universally unique identifier (UUID). Example: "c8d65cc2-0c82-429a-95ea-3f65011fc2cc"
  - **data.attributes** (object) - Required
    - **data.attributes.redirect_url** (string) - The URL where the buyer can complete the payment. Example: "https://bill.crypto.xmoney.com/uuid"

#### Response Example
```json
{
  "data": {
    "type": "orders_redirect",
    "id": "c8d65cc2-0c82-429a-95ea-3f65011fc2cc",
    "attributes": {
      "redirect_url": "https://bill.crypto.xmoney.com/uuid"
    }
  }
}
```
```

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

### GET /customer/{id}

Source: https://docs.xmoney.com/api/reference/customer

Retrieves a specific customer by their unique identifier. Use this to get detailed information about a single customer.

```APIDOC
## GET /customer/{id}

### Description
Retrieves a customer by its ID.

### Method
GET

### Endpoint
/customer/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer to retrieve.

### Request Example
```
GET /customer/cust_12345
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the customer.
- **name** (string) - The name of the customer.
- **email** (string) - The email address of the customer.
- **phone** (string) - The phone number of the customer.
- **createdAt** (string) - The timestamp when the customer was created.

#### Response Example
```json
{
  "id": "cust_12345",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "123-456-7890",
  "createdAt": "2023-10-27T10:00:00Z"
}
```
```

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

### Initialize Checkout with TypeScript

Source: https://docs.xmoney.com/guides/checkout/inline-checkout

Initializes the xMoney checkout process using the provided client SDK. This function takes order and customer data as input and returns a checkout object containing payload and checksum. It configures payment details, customer information, and redirect URLs.

```typescript
async function createPaymentIntent(orderData, customerData) {
  const checkout = client.initializeCheckout({
    publicKey: orderData.publicKey,
    customer: {
      identifier: customerData.id,
      firstName: customerData.firstName,
      lastName: customerData.lastName,
      country: customerData.country,
      city: customerData.city,
      email: customerData.email,
    },
    order: {
      orderId: orderData.id,
      description: orderData.description,
      type: "purchase",
      amount: orderData.amount,
      currency: orderData.currency,
    },
    cardTransactionMode: "authAndCapture",
    backUrl: "https://localhost:3002/transaction-result", // this is the client side URL, where the user will be redirected
  });
  return checkout; // { payload, checksum }
}
```

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

### Create Order API Call (cURL)

Source: https://docs.xmoney.com/index

This snippet demonstrates how to create an order using the xMoney API. It requires an API key for authorization and sends the amount and currency as parameters. This is a basic example for initiating a transaction.

```cURL
curl -X POST \
  https://api.xmoney.com/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d amount=100 \
  -d currency=EUR
```

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

### Create Pre-Authorized Order with xMoney

Source: https://docs.xmoney.com/guides/payments/pre-authorization-capture

This JSON snippet demonstrates how to initiate a pre-authorization request using xMoney. It requires `siteId`, customer details, order information (including amount and currency), and sets `cardTransactionMode` to 'auth'. The output is a pre-authorized amount on the customer's card, with transaction IDs available for subsequent capture.

```json
{
  "siteId": "yourSiteId",
  "customer": {
    // customer details
  },
  "order": {
    "orderId": "order1",
    "type": "purchase",
    "amount": 10,
    "currency": "EUR",
    "description": "Sample Pre-Auth Order"
  },
  "cardTransactionMode": "auth"
}
```