### Example Success Callback URL

Source: https://yookassa.ru/developers/solutions-for-platforms/partners-api/oauth/obtain-token

This URL is an example of how the user will be redirected back to your application after granting rights, containing the authorization code.

```URL
http://www.example.com/app?code=rvunUlge6gUMx6TT0UT6ys4y398qqG73KQb1PjXETuX6eiQYJXXi-IrNHe49a9mt&state=324234
```

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

### OAuth Token Example

Source: https://yookassa.ru/developers/using-api/interaction-format

Example of how to authenticate a request using an OAuth token for partner integrations.

```APIDOC
## GET payments/{payment_id} with OAuth

### Description
Retrieves details of a specific payment using its ID, authenticated with an OAuth token.

### Method
GET

### Endpoint
`https://api.yookassa.ru/v3/payments/{payment_id}`

### Parameters
#### Path Parameters
- **payment_id** (string) - Required - The unique identifier of the payment.

### Request Example
```bash
curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -H "Authorization: Bearer <OAuth token>"
```
```

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

### Example Success URL for Authorization

Source: https://yookassa.ru/developers/solutions-for-platforms/partners-api/oauth/obtain-token

This is an example of the URL a user will be redirected to after successfully initiating the authorization process.

```URL
https://yookassa.ru/oauth/v2/authorize?client_id=tr2fhrsh0e7naugqmoq6tesc5h0sbpsv&response_type=code&state=324234
```

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

### Example Error Callback URL

Source: https://yookassa.ru/developers/solutions-for-platforms/partners-api/oauth/obtain-token

This URL is an example of how the user will be redirected back to your application if they refuse to grant rights, indicating an 'access_denied' error.

```URL
http://www.example.com/token?error=access_denied&state=324234
```

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

### Tokenize with Valid Data Example

Source: https://yookassa.ru/developers/payment-acceptance/integration-scenarios/checkout-js/library-implementation

An example demonstrating the successful tokenization of bank card data. The response contains a paymentToken upon successful validation.

```javascript
checkout.tokenize({
    number: document.querySelector('.number').value,
    cvc: document.querySelector('.cvc').value,
    month: document.querySelector('.expiry_month').value,
    year: document.querySelector('.expiry_year').value
}).then(response => {
    if (response.status === 'success') {
        const { paymentToken } = response.data.response;

        // eyJlbmNyeXB0ZWRNZXNzYWdlIjoiWlc...
        return paymentToken;
    }
});

```

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

### HTTP Basic Auth Request Example

Source: https://yookassa.ru/developers/using-api/interaction-format?lang=en

Example of an API request using HTTP Basic Authentication. Replace <Shop ID> and <Secret Key> with your actual credentials.

```cURL
curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -u <Shop ID>:<Secret Key>
```

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

### OAuth Authentication Example

Source: https://yookassa.ru/developers/using-api/interaction-format?lang=en

Example of authenticating a request using an OAuth token with a cURL command. This method is for partners using the YooMoney API.

```APIDOC
## GET payments/{payment_id} with OAuth

### Description
Retrieves details of a specific payment using its ID, authenticated with an OAuth token.

### Method
GET

### Endpoint
`https://api.yookassa.ru/v3/payments/{payment_id}`

### Parameters
#### Path Parameters
- **payment_id** (string) - Required - The unique identifier of the payment.

#### Request Headers
- **Authorization** (string) - Required - `Bearer <OAuth token>`

### Request Example
```bash
curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -H "Authorization: Bearer <OAuth token>"
```
```

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

### Example Redirect URL After Successful Authorization

Source: https://yookassa.ru/developers/solutions-for-platforms/partners-api/quick-start

This is an example of the URL the user will be redirected to after successfully granting your application access. It contains the authorization code and the state parameter you provided.

```url
http://www.example.com/app?code=rvunUlge6gUMx6TT0UT6ys4y398qqG73KQb1PjXETuX6eiQYJXXi-IrNHe49a9mt&state=test-user
```

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

### Created Payment Object Example

Source: https://yookassa.ru/developers/payment-acceptance/integration-scenarios/manual-integration/bank-card?lang=en

Example of a payment object created after submitting bank card details, which includes a confirmation URL for 3-D Secure authentication.

```json
{
    "id": "22c5d173-000f-5000-9000-1bdf241d4651",
    "status": "pending",
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "confirmation": {
        "type": "redirect",
        "enforce": false,
        "return_url": "https://www.example.com/return_url",
        "confirmation_url": "https://payment.yookassa.ru:443/wallet-redirect/confirm/22c5d173-000f-5000-9000-1bdf241d4651"
    },
    "created_at": "2021-04-13T10:00:00.000Z",
    "description": "Order No. 72",
    "payment_method": {
        "type": "bank_card"
    },
    "recipient": {
        "account_id": "100500",
        "gateway_id": "100700"
    },
    "test": true
}
```

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

### SberLoan Payment Success Example (Installment Plan)

Source: https://yookassa.ru/developers/payment-acceptance/integration-scenarios/manual-integration/other/sber-loan?lang=en

This JSON object illustrates a successful payment using SberBank's installment plan. It includes payment details and specifies the 'sber_loan' payment method with 'loan_option' set to 'installments_12' and includes the 'discount_amount'.

```json
{
  "id": "22c5d0f0-000f-5000-8000-13ece77bc6c1",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "4500.00",
    "currency": "RUB"
  },
  "income_amount": {
    "value": "4342.50",
    "currency": "RUB"
  },
  "captured_at": "2021-06-22T21:44:55.506Z",
  "created_at": "2021-06-22T21:43:44.794Z",
  "description": "Order No. 37",
  "metadata": {
    "order_id": "37"
  },
  "payment_method": {
    "type": "sber_loan",
    "id": "22c5d0f0-000f-5000-8000-13ece77bc6c1",
    "saved": false,
    "loan_option": "installments_12",
    "discount_amount": {
      "value": "500.00",
      "currency": "RUB"
    }
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": true
}
```

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

### Idempotency Key Example

Source: https://yookassa.ru/developers/using-api/interaction-format

Example of making a POST request with an idempotency key to ensure transaction safety.

```APIDOC
## POST refunds

### Description
Creates a refund for a payment. Using an idempotency key ensures that the request is processed only once, even if repeated.

### Method
POST

### Endpoint
`https://api.yookassa.ru/v3/refunds`

### Parameters
#### Request Body
- **amount** (object) - Required - The amount of the refund.
  - **value** (string) - Required - The refund amount value.
  - **currency** (string) - Required - The currency of the refund amount (e.g., "RUB").
- **payment_id** (string) - Required - The ID of the payment to refund.

### Request Example
```bash
curl https://api.yookassa.ru/v3/refunds \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d 
    {
      "amount": {
        "value": "2.00",
        "currency": "RUB"
      },
      "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
    }
```
```

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

### Example Store Information Response

Source: https://yookassa.ru/developers/solutions-for-platforms/partners-api/quick-start

This JSON response provides details about your store's configuration, such as its account ID, test mode status, and enabled payment methods.

```json
{
  "account_id": "123",
  "test": true,
  "fiscalization_enabled": false,
  "payment_methods": [
    "bank_card",
    "yoo_money"
  ]
}
```

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

### Example Payout Object (Bank Card)

Source: https://yookassa.ru/developers/solutions-for-platforms/safe-deal/integration/payouts

This is an example of a payout object with a 'succeeded' status for a payout to a bank card.

```json
{
  "id": "po-28559c4f-0003-5000-9000-0baf38b7a7fd",
  "amount": {
    "value": "800.00",
    "currency": "RUB"
  },
  "status": "succeeded",
  "payout_destination": {
    "type": "bank_card",
    "card": {
      "first6": "555555",
      "last4": "4477",
      "card_type": "Mir",
      "issuer_country": "RU",
      "issuer_name": "Sberbank Of Russia"
    }
  },
  "description": "Payout for order No. 37",
  "created_at": "2021-06-21T14:28:45.132Z",
  "succeeded_at": "2021-06-21T14:29:17.141Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
  },
  "metadata": {
    "order_id": "37"
  },
  "test": false
}
```

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

### Initialize and Render YooKassa Widget

Source: https://yookassa.ru/developers/payment-acceptance/integration-scenarios/widget/integration?lang=en

Demonstrates how to initialize the YooKassa checkout widget with a confirmation token and render it into a specified HTML element. Includes optional callbacks for errors and a promise for when the form is fully loaded.

```html
<!--Library implementation-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

<!--HTML element in which the payment form will be displayed-->
<div id="payment-form"></div>

<script>
//Widget initialization. All parameters are required.
const checkout = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process
    return_url: 'https://example.com', //URL to the payment completion page
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form')
//The method returns Promise. When Promise is executed, it means the payment form is fully loaded (optional use).
  .then(() => {
     //Code that must be executed after the payment form is displayed.
  });

//Deletion of payment form from the container
checkout.destroy();

//New widget initialization. All parameters are required.
const checkoutNew = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process
    return_url: 'https://example.com', //URL to the payment completion page
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkoutNew.render('payment-form')
//The method returns Promise. When Promise is executed, it means the payment form is fully loaded (optional use).
    .then(() => {
       //Code that must be executed after the payment form is displayed.
  });
</script>
```

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

### Example Response Body for a List of Payments

Source: https://yookassa.ru/developers/using-api/lists?lang=en

This is an example of the JSON response body when a list of payments is returned. It includes details about the payment items.

```JSON
{
  "type": "list",
  "items": [
    {
      "id": "22979b7b-000f-5000-9000-1a603a795739",
      "status": "canceled",
      "paid": false,
      "amount": {
        "value": "2.00",
        "currency": "RUB"
       },
      "created_at": "2018-05-23T15:24:43.812Z",
      "metadata": {},
      "payment_method": {
        "type": "bank_card",
        "id": "22979b7b-000f-5000-9000-1a603a795739",
        "saved": false
      },
      "recipient": {
        "account_id": "100500",
        "gateway_id": "100700"
      },
      "refundable": false,
      "test": false,
      "cancellation_details": {
        "party": "payment_network",
        "reason": "payment_method_restricted"
      }
    }
  ]
}

```

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

### Initialize YooMoney Checkout Widget (HTML/JavaScript)

Source: https://yookassa.ru/developers/payment-acceptance/integration-scenarios/widget/quick-start

Initialize the widget with the 'confirmation_token' obtained from payment creation. Specify a 'return_url' for redirection after payment and an 'error_callback' function. Render the payment form into a specified HTML container.

```javascript
//Example of a script with a specified token.
<script>
//Widget initialization. All parameters are required.
const checkout = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'ct-24301ae5-000f-5000-9000-13f5f1c2f8e0', //Token you received after creating the payment
    return_url: 'https://yookassa.ru/', //URL to the payment completion page
    error_callback: function(error) {
        console.log(error)
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
```

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

### Payment Object Example

Source: https://yookassa.ru/developers/solutions-for-platforms/split-payments/payments?lang=en

This is an example of a payment object after a successful capture. It includes details like status, amount, authorization information, and captured timestamp.

```JSON
{
  "id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "11000.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "603668680243",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "captured_at": "2019-08-16T12:23:12.849Z",
  "created_at": "2019-08-16T10:44:12.717Z",
  "description": "Order No. 1: \"Company 1\" LLC 5000 rub., \"Company 2\" LLC 12000 rub.",
  "metadata": {
  },
  "payment_method": {
    "type": "bank_card",
    "id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "06",
      "expiry_year": "2022",
      "card_type": "Mir",
      "card_product": {
        "code": "MCP",
        "name": "MIR Privilege"
      },
      "issuer_country": "RU",
      "issuer_name": "T-Bank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "10001"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "transfers": [
    {
       "account_id": "123",
       "amount": {
         "value": "2000.00",
         "currency": "RUB"
       },
       "platform_fee_amount": {
         "value": "20.00",
         "currency": "RUB"
       }
    }
   ]
 }
```

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

### Example Gateway Settings JSON Response

Source: https://yookassa.ru/developers/payouts/scenario-extensions/balance

This JSON object displays the gateway settings, including the current payout balance. The `payout_balance` field shows the available amount and currency for payouts. For test gateways, this balance may be negative.

```json
{
    "account_id": "100500",
    "test": false,
    "payout_methods": [
        "bank_card",
        "yoo_money"
    ],
    "name": "<Name of the gateway in the YooMoney Merchant Profile>",
    "payout_balance": {
        "value": "1000.47",
        "currency": "RUB"
    },
    "status": "enabled"
}
```

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

### OAuth Token Request Example

Source: https://yookassa.ru/developers/using-api/interaction-format?lang=en

Example of an API request using an OAuth token for authentication. This method is for partners using the YooMoney partnership program.

```cURL
curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -H "Authorization: Bearer <OAuth token>"
```

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

### Partial Capture with Receipt

Source: https://yookassa.ru/developers/payment-acceptance/receipts/54fz/other-services/payments?lang=en

This example shows how to perform a partial capture of a payment and simultaneously generate a receipt with updated details. This is useful when you need to adjust the payment amount or items after the initial authorization.

```APIDOC
## POST /payments/:id/capture

### Description
Captures a payment, optionally including receipt details for partial captures or updated information.

### Method
POST

### Endpoint
https://api.yookassa.ru/v3/payments/:id/capture

### Parameters
#### Headers
- **Authorization**: Basic authentication with Shop ID and Secret Key.
- **Idempotence-Key**: Unique key for idempotency.
- **Content-Type**: application/json

#### Request Body
- **amount** (object) - Required - The amount to capture.
  - **value** (string) - Required - The monetary value.
  - **currency** (string) - Required - The currency code (e.g., RUB).
- **receipt** (object) - Optional - Data for generating a receipt.
  - **customer** (object) - Required if receipt is provided.
    - **full_name** (string) - Required - Full name of the customer.
    - **phone** (string) - Optional - Customer's phone number.
  - **items** (array) - Required if receipt is provided.
    - **description** (string) - Required - Description of the item.
    - **quantity** (number) - Required - Quantity of the item.
    - **amount** (object) - Required.
      - **value** (string) - Required - The monetary value.
      - **currency** (string) - Required - The currency code.
    - **vat_code** (integer) - Required - VAT rate code.
    - **payment_mode** (string) - Required - Payment mode (e.g., "full_prepayment").
    - **payment_subject** (string) - Required - Subject of the payment (e.g., "commodity").
  - **internet** (string) - Optional - Indicates if it's an internet transaction ('true' or 'false').

### Request Example
```json
{
  "amount": {
    "value": "500.00",
    "currency": "RUB"
  },
  "receipt": {
    "customer": {
      "full_name": "Ivanov Ivan Ivanovich",
      "phone": "79000000000"
    },
    "items": [
      {
        "description": "Product name 1",
        "quantity": 2.000,
        "amount": {
          "value": "250.00",
          "currency": "RUB"
        },
        "vat_code": 2,
        "payment_mode": "full_prepayment",
        "payment_subject": "commodity"
      }
    ],
    "internet": "true"
  }
}
```
```

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

### Initialize and Render YooMoney Checkout Widget

Source: https://yookassa.ru/developers/payment-acceptance/integration-scenarios/widget/integration

This JavaScript code demonstrates how to initialize the YooMoney Checkout Widget with a confirmation token and render the payment form. It also shows how to use the `destroy` method to remove the widget and re-initialize it.

```html
<!--Library implementation-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

<!--HTML element in which the payment form will be displayed-->
<div id="payment-form"></div>

<script>
//Widget initialization. All parameters are required.
const checkout = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process
    return_url: 'https://example.com', //URL to the payment completion page
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form')
//The method returns Promise. When Promise is executed, it means the payment form is fully loaded (optional use).
  .then(() => {
     //Code that must be executed after the payment form is displayed.
  });

//Deletion of payment form in the container
checkout.destroy();

//New widget initialization. All parameters are required.
const checkoutNew = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process
    return_url: 'https://example.com', //URL to the payment completion page
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkoutNew.render('payment-form')
//The method returns Promise. When Promise is executed, it means the payment form is fully loaded (optional use).
    .then(() => {
       //Code that must be executed after the payment form is displayed.
  });
</script>
```

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

### Idempotency Key Example

Source: https://yookassa.ru/developers/using-api/interaction-format?lang=en

Example of making a POST request with an idempotency key to ensure safe transaction repetition. This is used for operations like creating refunds.

```APIDOC
## POST refunds

### Description
Creates a refund for a payment. The `Idempotence-Key` header ensures that the request is processed only once, even if repeated.

### Method
POST

### Endpoint
`https://api.yookassa.ru/v3/refunds`

### Parameters
#### Request Headers
- **Authorization** (string) - Required - `<Shop ID>:<Secret Key>` (for HTTP Basic Auth) or `Bearer <OAuth token>`
- **Idempotence-Key** (string) - Required - A unique value (e.g., V4 UUID) for this transaction to ensure idempotency. Maximum length is 64 characters.
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **amount** (object) - Required - The amount of the refund.
  - **value** (string) - Required - The refund amount value.
  - **currency** (string) - Required - The currency of the refund amount (e.g., "RUB").
- **payment_id** (string) - Required - The ID of the payment to refund.

### Request Example
```bash
curl https://api.yookassa.ru/v3/refunds \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d 
    {
      "amount": {
        "value": "2.00",
        "currency": "RUB"
      },
      "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
    }
```
```

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

### Example Payout Report (CSV)

Source: https://yookassa.ru/developers/payouts/after-the-payout/reports

This is an example of a daily payout report in CSV format. It shows the header row and several entries detailing successful payouts.

```csv
"Идентификатор выплаты";"Сумма выплаты";"Валюта выплаты";Комиссия;"Время операции";"Дополнительные реквизиты";Описание;"Метод выплат";"Проверка получателя";"VAT on commission"
po-28e7d82e-0003-5000-9000-0f1483ebc9ca;143.33;RUB;4.01;"30.09.2021 17:06:39";4100315000430537;Выплата №37;yoo_money;нет
po-28e7d741-0003-5000-a000-0aaf7f924c72;100.00;RUB;8.00;"30.09.2021 17:02:45";MJJYIpFhJG8BqZ_nMmUJaICY.SC.000.202109;Выплата курьеру 001;bank_card;нет;1.76
po-29aab543-002c-5000-8000-0f9aa8b2e8a0;1243.12;RUB;34.81;"25.02.2022 12:29:44";79810000000;"Order No. 1";sbp;нет
po-29aab44a-002c-5000-8000-0dc745a77375;1243.12;RUB;34.81;"25.02.2022 12:25:40";79110000000;"Выплата курьеру 007";sbp;да
```

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

### Example Gateway Settings Response

Source: https://yookassa.ru/developers/payouts/scenario-extensions/balance?lang=en

This JSON object shows the structure of the response when requesting gateway settings. The 'payout_balance' field indicates the available funds for payouts.

```json
{
    "account_id": "100500",
    "test": false,
    "payout_methods": [
        "bank_card",
        "yoo_money"
    ],
    "name": "<Name of the gateway in the YooMoney Merchant Profile>",
    "payout_balance": {
        "value": "1000.47",
        "currency": "RUB"
    },
    "status": "enabled"
}


```

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

### Canceled Refund Object Example

Source: https://yookassa.ru/developers/payment-acceptance/integration-scenarios/manual-integration/other/electronic-certificate/merchant-payment-form

This example shows the structure of a refund object when the refund process has been canceled, typically due to issues with electronic certificate refunds.

```APIDOC
## Refund Object Status: Canceled

### Description
Represents a refund that has been canceled. This often occurs when a refund to an electronic certificate fails, causing the entire refund transaction to be voided.

### Response Example
```json
{
  "id": "216749f7-0016-50be-b000-078d43a63ae4",
  "payment_id": "2d78da66-000f-5000-9000-1297ba86ffa5",
  "status": "canceled",
  "cancellation_details": {
    "party": "refund_network",
    "reason": "payment_tru_code_not_found"
  },
  "created_at": "2024-01-29T15:21:38.320Z",
  "amount": {
    "value": "1200.00",
    "currency": "RUB"
  },
  "description": "Refund for order No. 37",
  "metadata": {}
}
```
```