Payplus

https://payplus.kz/docs/en/
Admin
Payplus provides an API for payment processing, including deposit and payout methods, status...
Tokens:33,361
Snippets:144
Trust Score:2.9
Update:8 months ago
Show doc for...
Tokens:
Raw
### Response Currency Rates (Error)

Source: https://payplus.kz/docs/en/index

Example of an error response for a currency rates request.

```json
{
    "status" : "Error",
    "description" : "Error description"
}
```

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

### Response Currency Rates (Success)

Source: https://payplus.kz/docs/en/index

Example of a successful response for a currency rates request, showing exchange rates for specified currencies.

```json
{
    "status":"success",
    "description":"Rates from KZT",
    "rates":{
          "USD":0.0247,
          "EUR":0.0228
    }
}
```

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

### SEPA Payout Response JSON Examples (Success, Pending, Error)

Source: https://payplus.kz/docs/en/index

These JSON objects demonstrate the possible responses from the SEPA payout API. They include examples for a successful transaction, a pending transaction requiring further status checks, and an error response indicating issues with the request data. Each response contains status, code, payout ID, description, and a digital signature.

```json
{
    "status" : "Success",
    "code" : "0",
    "payout_id" : 000002,
    "description" : "Payment successful. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
 }
```

```json
{
    "status": "Pending",
    "code": "40",
    "payout_id": 000002,
    "description": "Payment in order",
    "sign": "XXXXXXXXXXXXXXXXXX"
}
```

```json
{
    "status": "Error",
    "code": "99",
    "payout_id": "",
    "description": "Sign error",
    "sign": "XXXXXXXXXXXXXXXXXX"
 }
```

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

### Request Currency Rates (JSON Example)

Source: https://payplus.kz/docs/en/index_methods-api

This JSON snippet shows the structure for requesting currency exchange rates. It requires the merchant ID and the base currency from which rates are to be fetched. The response includes a status, description, and a 'rates' object containing currency pairs and their values.

```json
{
    "status":"success",
    "description":"Description of the response",
    "rates": {
          "CURR1":VAL1,
          "CURR2":VAL2,
    …}
}
```

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

### Payouts to Bank Card

Source: https://payplus.kz/docs/en/index_methods-api

Information regarding the setup of payouts to bank cards.

```APIDOC
## Payouts to the bank card

### Description
This section provides guidance on setting up payouts to bank cards. For correct setup, navigate to the 'Personal Account' and then 'Edit merchant'.

### Setup
Detailed instructions for these settings can be found in the 'Sign up' section, specifically in paragraphs 8-11.
```

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

### Response Payments List (Success)

Source: https://payplus.kz/docs/en/index

Example of a successful response for a payments list request, detailing transaction information.

```json
{
    "id" : 11114,
    "uid" : "ABA4OD7X73L4Q",
    "order_id" : "0083",
    "subtotal" : 0.9,
    "fee_percentage" : 0,
    "fee_fixed" : 0.1,
    "total" : 1,
    "currency" : "KZT",
    "type" : "Deposit",
    "status" : "Success",
    "created_at" : "2021-02-10 09:34:57",
    "updated_ad" : "2021-02-10 09:37:40"
}
```

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

### SPEI Payout Request Example (JSON)

Source: https://payplus.kz/docs/en/index

This JSON object demonstrates the structure of a request to the /merchant/api/payout_send endpoint for initiating a payout via SPEI. It includes essential fields like merchant, method, payout_id, account, full_name, amount, currency, and the digital signature.

```json
{
    "merchant" : "QYKVQCL07H44B",
    "method" : 36,
    "payout_id" : "000002",
    "account" : "1111111122222",
    "full_name" : "Lorena Garcia",
    "amount" : "102.81",
    "currency" : "MXN",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

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

### Payout Request Example (JSON)

Source: https://payplus.kz/docs/en/index

This JSON object demonstrates a typical payout request. It includes essential fields like merchant ID, payout method, transaction amount, currency, and a digital signature for authentication. Note that specific payout methods may require additional fields.

```json
{
    "merchant" : "QYKVQCL07H44B",
    "method" : 1,
    "payout_id" : "000002",
    "account" : "5300111122223333",
    "amount" : "102.81",
    "currency" : "KZT",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

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

### Deposit Request (iframe) - JSON Example

Source: https://payplus.kz/docs/en/index

This JSON object represents an initial payment request for the iframe deposit method. It includes essential merchant and transaction details required to initiate a payment.

```json
{
    "merchant" : "QYKVQCL07H44B",
    "order" : "0001",
    "amount" : "16",
    "currency" : "KZT",
    "item_name" : "Samsung TV",
    "first_name" : "IVAN",
    "last_name" : "IVANOV",
    "user_id" : "492235",
    "payment_url" : "https://test.com",
    "country" : "UA",
    "ip" : "212.10.20.75",
    "custom" : "",
    "email": "test@gmail.com",
    "phone": "+35988222763",
    "address": "Avenue Marius Renard 21",
    "city": "Anderlecht",
    "post_code": "1070",
    "region": "stuttgart",
    "lang" : "en"
}
```

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

### UPI Payout Request JSON Example

Source: https://payplus.kz/docs/en/index

This JSON object represents a sample request payload for initiating a UPI payout. It includes all necessary fields such as merchant ID, payout method, transaction details, and customer information.

```json
{
    "merchant" : "QYKVQCL07H44B",
    "method" : 26,
    "payout_id" : "000002",
    "account" : "1111111122222",
    "full_name" : "CARD HOLDER",
    "customs_email" : "test@test.com",
    "customs_phone" : "+91000000000",
    "customs_ifsc" : "ICIC0001818",
    "customs_ip" : "127.0.0.1",
    "amount" : "102.81",
    "currency" : "INR",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

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

### SEPA Payout Request JSON Example

Source: https://payplus.kz/docs/en/index

This JSON object represents a sample request to the /merchant/api/payout_send endpoint for initiating a SEPA payout. It includes all necessary fields such as merchant ID, payout method, payout ID, bank account details, amount, currency, and a digital signature.

```json
{
    "merchant" : "QYKVQCL07H44B",
    "method" : 15,
    "payout_id" : "000002",
    "account" : "iban adress",
    "full_name" : "IVANOV IVAN",
    "amount" : "102.81",
    "currency" : "EUR",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

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

### Request Currency Rates (GET/POST)

Source: https://payplus.kz/docs/en/index

Fetches currency exchange rates. Requires merchant ID and base currency. Supports GET and POST methods.

```json
{
    "merchant" : "MERCHANT_ID",
    "currency_from" : "BASE_CURRENCY"
}
```

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

### Currency Rates Request API

Source: https://payplus.kz/docs/en/index

Retrieves currency exchange rates. Supports both POST and GET methods.

```APIDOC
## GET /api/rates

### Description
Retrieves currency exchange rates. Supports both POST and GET methods.

### Method
GET or POST

### Endpoint
/api/rates

### Parameters
#### Query Parameters (for GET requests)
- **merchant** (string) - Required - Merchant ID.
- **currency_from** (string) - Required - Base currency.

#### Request Body (for POST requests)
- **merchant** (string) - Required - Merchant ID.
- **currency_from** (string) - Required - Base currency.

### Request Example
```json
{
    "merchant": "QYKVQCL07H44B",
    "currency_from": "KZT"
}
```

### Response
#### Success Response (200)
- **status** (string) - "success"
- **description** (string) - Description of the response.
- **rates** (object) - An object containing currency codes as keys and their rates as values.

#### Response Example (Success)
```json
{
    "status":"success",
    "description":"Rates from KZT",
    "rates":{
          "USD":0.0247,
          "EUR":0.0228
    }
}
```

#### Error Response
- **status** (string) - "Error"
- **description** (string) - Error description.

#### Response Example (Error)
```json
{
    "status" : "Error",
    "description" : "Error description"
}
```
```

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

### PIX Payout Request Example (JSON)

Source: https://payplus.kz/docs/en/index

This JSON object demonstrates the structure for a PIX payout request to a bank account. It includes essential fields like merchant ID, payout method, transaction details, and a digital signature for authentication. Ensure all fields are correctly populated according to the API specifications.

```json
{
    "merchant" : "QYKVQCL07H44B",
    "method" : 21,
    "payout_id" : "000002",
    "account" : "73859120463",
    "pix_key" : "73859120463",
    "customs_email" : "test@test.com",
    "full_name" : "Lorena Garcia",
    "amount" : "102.81",
    "currency" : "BRL",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

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

### Balance Request Response JSON Examples

Source: https://payplus.kz/docs/en/index

These JSON objects show possible responses from the /payment/balance endpoint. A successful response includes the status, currency, available balance, a description, and a digital signature. An error response may include status, merchant ID, and a description, with the signature omitted if the merchant is not found or not approved.

```json
{
    "status": "Success",
    "currency": "KZT",
    "balance": 212.07,
    "description": "Wallet balance",
    "sign": "XXXXXXXXXXXXXXXXXX"
}
```

```json
{
    "status": "Error",
    "merchant": "QYKVQCL07H44B",
    "description": "Merchant not found or not Approved"
}
```

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

### PIX Payout Response Examples (JSON)

Source: https://payplus.kz/docs/en/index

These JSON objects illustrate the possible responses from the PIX payout API. They cover successful transactions, pending statuses requiring further action, and error states. Each response includes a status, code, payout ID, description, and a digital signature for verification.

```json
{
    "status" : "Success",
    "code" : "0",
    "payout_id" : 000002,
    "description" : "Payment successful. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

```json
{
    "status": "Pending",
    "code": "40",
    "payout_id": 000002,
    "description": "Payment in order",
    "sign": "XXXXXXXXXXXXXXXXXX"
}
```

```json
{
    "status": "Error",
    "code": "99",
    "payout_id": "",
    "description": "Sign error",
    "sign": "XXXXXXXXXXXXXXXXXX"
}
```

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

### Payout Response Example - Success (JSON)

Source: https://payplus.kz/docs/en/index

This JSON response indicates a successful payout transaction. It includes the transaction status, a status code, the payout ID, a description, and a digital signature. The 'Success' status is final.

```json
{
    "status" : "Success",
    "code" : "0",
    "payout_id" : 000002,
    "description" : "Payment successful. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

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

### Payout Response Example - Error (JSON)

Source: https://payplus.kz/docs/en/index

This JSON response indicates an error during the payout transaction. It includes the status, code, payout ID, description, and signature. An 'Error' status with an empty payout ID suggests a data validation issue.

```json
{
    "status": "Error",
    "code": "99",
    "payout_id": "",
    "description": "Sign error",
    "sign": "XXXXXXXXXXXXXXXXXX"
}
```

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

### Query Payment Status (Payout) Response JSON Examples

Source: https://payplus.kz/docs/en/index

These JSON objects illustrate possible responses from the /merchant/api/payout_status endpoint, indicating the transaction status. Responses include the status (Success, Pending, Blocked, Error), payout ID, a status code, a description, and a digital signature. The 'sign' field may be empty in case of an 'Error' status due to data validation issues.

```json
{
    "status" : "Success",
    "payout_id" : 000002,
    "code" : "0",
    "description" : "Payment successful. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

```json
{
    "status" : "Error",
    "code" : "8",
    "payout_id" : "",
    "description" : "Transaction not found",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

```json
{
    "status" : "Blocked",
    "payout_id" : 000002,
    "code" : "80",
    "description" : "Payment error. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

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

### GET /payment/status - Payment Status Request

Source: https://payplus.kz/docs/en/index

Retrieves the status of a payment transaction using merchant and order details. Supports both GET and POST methods.

```APIDOC
## GET /payment/status

### Description
Retrieves the status of a payment transaction using merchant and order details. Supports both GET and POST methods.

### Method
GET or POST

### Endpoint
/payment/status

### Parameters
#### Query Parameters (for GET) or Request Body (for POST)
- **merchant** (string) - Required - Unique merchant ID.
- **order** (string) - Required - Transaction number in the merchant system.
- **co_inv_id** (string) - Optional - Unique transaction number (transferred after payment processing).
- **sign** (string) - Required - Digital signature with the merchant's key, generated using MD5 for fields: "merchant", "order", "co_inv_id".

### Request Example (GET or POST Body)
```json
{
    "merchant" : "QYKVQCL07H44B",
    "order" : "0001",
    "co_inv_id" : "1111111",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

### Response
#### Success Response (200)
- **status** (string) - Transaction status (e.g., "success", "pending", "fail", "refund").
- **order** (string) - Transaction number in the merchant system.
- **description** (string) - Status description.
- **card_number** (string) - Bank card mask (e.g., "NNNNNN******NNNN").
- **sign** (string) - Digital signature with the merchant's key.

#### Error Response (e.g., 400)
- **status** (string) - Transaction status (e.g., "Error").
- **order** (string) - Transaction number in the merchant system.
- **description** (string) - Status description (e.g., "Merchant payment not found").
- **sign** (string) - Digital signature with the merchant's key (may be empty if signature is invalid).

### Response Example (Success)
```json
{
    "status" : "success",
    "order" : "0001",
    "description" : "Merchant payment success",
    "card_number" : "530011******3333",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

### Response Example (Error)
```json
{
    "status" : "Error",
    "order" : "0001",
    "description" : "Merchant payment not found",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```
```

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

### Response Payments List (Blocked)

Source: https://payplus.kz/docs/en/index

Example of a blocked transaction response for a payments list request.

```json
{
    "id" : 11115,
    "uid" : "XTJTEZXMJAUMT",
    "order_id" : "0084",
    "subtotal" : 0.9,
    "fee_percentage" : 0,
    "fee_fixed" : 0.1,
    "total" : 1,
    "currency" : "KZT",
    "type" : "Deposit",
    "status" : "Blocked",
    "created_at" : "2021-02-10 10:22:32",
    "updated_ad" : "2021-02-10 10:24:17"
}
```

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

### Deposit PIX (host-2-host)

Source: https://payplus.kz/docs/en/index_methods-api

Documentation for initiating a PIX deposit using the host-to-host integration.

```APIDOC
## Deposit PIX (host-2-host)

### Description
This section details the process for initiating a PIX deposit via the host-to-host API integration. It outlines the request parameters and expected responses for successful and failed transactions.
```

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

### Response Payments List (Error)

Source: https://payplus.kz/docs/en/index

Example of an error response for a payments list request, indicating a rate limit issue.

```json
{
    "status": "Error",
    "description": "Please send one request per minute"
}
```

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

### Payments List Request API

Source: https://payplus.kz/docs/en/index

Retrieves a list of payments based on specified criteria. Supports both POST and GET methods. Rate limited to one request per minute.

```APIDOC
## GET /api/payment-list

### Description
Retrieves a list of payments based on specified criteria. Supports both POST and GET methods. Rate limited to one request per minute. The maximum number of transactions in the response is 10,000.

### Method
GET or POST

### Endpoint
/api/payment-list

### Parameters
#### Query Parameters (for GET requests)
- **merchant** (string) - Required - Unique merchant ID.
- **currency** (string) - Required - Requested currency (USD, EUR, KZT, BRL, INR, AZN).
- **order** (integer) - Optional - The number of the transaction in the merchant’s system, from which the selection begins. If 0, all transactions are returned.
- **start_date** (string) - Optional - Date and time of the beginning of the period in "YYYY-MM-DD HH:ii:ss" format.
- **finish_date** (string) - Optional - Date and time of the end of the period in "YYYY-MM-DD HH:ii:ss" format.
- **status** (string) - Optional - Status of payments to be selected (all, success, pending, blocked, refund).
- **type** (string) - Optional - Transaction type (withdrawal or deposit).
- **sign** (string) - Required - Digital signature with the merchant’s key. Available fields: "merchant", "currency", "order", "start_date", "finish_date", "status", "type". Hashed using MD5.

#### Request Body (for POST requests)
- **merchant** (string) - Required - Unique merchant ID.
- **currency** (string) - Required - Requested currency (USD, EUR, KZT, BRL, INR, AZN).
- **order** (integer) - Optional - The number of the transaction in the merchant’s system, from which the selection begins. If 0, all transactions are returned.
- **start_date** (string) - Optional - Date and time of the beginning of the period in "YYYY-MM-DD HH:ii:ss" format.
- **finish_date** (string) - Optional - Date and time of the end of the period in "YYYY-MM-DD HH:ii:ss" format.
- **status** (string) - Optional - Status of payments to be selected (all, success, pending, blocked, refund).
- **type** (string) - Optional - Transaction type (withdrawal or deposit).
- **sign** (string) - Required - Digital signature with the merchant’s key. Available fields: "merchant", "currency", "order", "start_date", "finish_date", "status", "type". Hashed using MD5.

### Request Example
```json
{
    "merchant" : "QYKVQCL07H44B",
    "currency" : "KZT",
    "order" : "0",
    "start_date" : "2021-02-09 00:00:00",
    "finish_date" : "2021-02-11 16:59:59",
    "status" : "all",
    "type" : "deposit",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

### Response
#### Success Response (200)
- **id** (integer) - Unique transaction number.
- **uid** (string) - Unique transaction ID.
- **order_id** (string) - Transaction number in the merchant system.
- **subtotal** (number) - Amount transferred.
- **fee_percentage** (number) - Deducted fee (if the type of fee is a per cent).
- **fee_fixed** (number) - Fee rate (if the fee type is fixed).
- **total** (number) - Total transaction amount.
- **currency** (string) - Transaction currency.
- **type** (string) - Transaction type (withdrawal or deposit).
- **status** (string) - Transaction status (Success, Pending, Blocked, Refund).
- **created_at** (string) - Transaction creation date and time.
- **updated_ad** (string) - Transaction processing date and time.

#### Response Example (Success)
```json
{
    "id" : 11114,
    "uid" : "ABA4OD7X73L4Q",
    "order_id" : "0083",
    "subtotal" : 0.9,
    "fee_percentage" : 0,
    "fee_fixed" : 0.1,
    "total" : 1,
    "currency" : "KZT",
    "type" : "Deposit",
    "status" : "Success",
    "created_at" : "2021-02-10 09:34:57",
    "updated_ad" : "2021-02-10 09:37:40"
}
```

#### Response Example (Blocked)
```json
{
    "id" : 11115,
    "uid" : "XTJTEZXMJAUMT",
    "order_id" : "0084",
    "subtotal" : 0.9,
    "fee_percentage" : 0,
    "fee_fixed" : 0.1,
    "total" : 1,
    "currency" : "KZT",
    "type" : "Deposit",
    "status" : "Blocked",
    "created_at" : "2021-02-10 10:22:32",
    "updated_ad" : "2021-02-10 10:24:17"
}
```

#### Error Response
- **status** (string) - "Error"
- **description** (string) - Error message.

#### Response Example (Error)
```json
{
    "status": "Error",
    "description": "Please send one request per minute"
}
```
```

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

### POST /api/exchange

Source: https://payplus.kz/docs/en/index

Initiates a currency exchange request with specified order details and amounts.

```APIDOC
## POST /api/exchange

### Description
Initiates a currency exchange request. This endpoint allows merchants to exchange one currency for another, providing details about the transaction, including the amount, source currency, and target currency.

### Method
POST

### Endpoint
/api/exchange

### Parameters
#### Request Body
- **merchant** (string) - Required - Merchant ID.
- **order** (string) - Required - Payment number in the merchant's system.
- **amount** (number) - Required - The amount to be exchanged.
- **currency_from** (string) - Required - The currency to exchange from.
- **currency_to** (string) - Required - The currency to exchange to.
- **currency_sign** (string) - Required - Request signature using SHA256 encryption.

### Request Example
```json
{
  "merchant": "merchant_id_123",
  "order": "order_456",
  "amount": 100.50,
  "currency_from": "USD",
  "currency_to": "EUR",
  "currency_sign": "sha256_signature_here"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the currency exchange request ('success' or 'error').
- **description** (string) - A message describing the outcome of the request.
- **transInfo** (object) - Contains detailed transaction information if the status is 'success'.
  - **order** (string) - The order ID from the merchant's system.
  - **uuid** (string) - A unique identifier for the transaction.
  - **amount** (number) - The original amount exchanged.
  - **fee** (number) - The fee associated with the transaction.
  - **currency_from** (string) - The source currency.
  - **converted_amount** (number) - The amount after conversion.
  - **currency_to** (string) - The target currency.
  - **rate** (number) - The exchange rate used.

#### Response Example (Success)
```json
{
    "status": "success",
    "description": "Currency exchange success",
    "transInfo":{
        "order":"order_456",
        "uuid":"uuid_789",
        "amount": 100.50,
        "fee":0,
        "currency_from":"USD",
        "converted_amount": 92.15,
        "currency_to":"EUR",
        "rate":0.917
    }
}
```

#### Error Response Example
```json
{
    "status": "Error",
    "description": "Invalid currency_from provided"
}
```

### Status Codes
- **0**: Success - Payout successful.
- **2**: Error - Input data error.
- **3**: Error - Payment method blocked.
- **4**: Error - Merchant blocked.
- **5**: Error - Payout currency error.
- **6**: Error - Merchant account blocked.
- **7**: Error - The amount exceeds the balance.
- **8**: Error - Transaction ID not found (Contact technical support for details).
- **10**: Error - Repeated withdrawal request, transaction status request required.
- **40**: Pending - Transaction in processing.
- **80**: Blocked - Refused to pay.
- **99**: Error - Signature error in request.
- **100**: Error - The error is not documented.
```

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

### Payment Status Request (Deposit)

Source: https://payplus.kz/docs/en/index

This endpoint allows merchants to retrieve the status of a payment transaction. It can be accessed via POST or GET requests and requires merchant, order, and signature details.

```APIDOC
## POST /payment/status

### Description
Retrieves the status of a payment transaction. This endpoint supports both POST and GET methods.

### Method
POST or GET

### Endpoint
`/payment/status`

### Parameters
#### Query Parameters
- **merchant** (string) - Required - Unique merchant identifier.
- **order** (string) - Required - Transaction number in the merchant system.
- **co_inv_id** (string) - Required - Unique transaction number transmitted after payment processing.
- **sign** (string) - Required - Digital signature generated using MD5 hashing of merchant, order, and co_inv_id.

### Request Example
```json
{
    "merchant" : "QYKVQCL07H44B",
    "order" : "0001",
    "co_inv_id" : "1111111",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

### Response
#### Success Response (200)
- **status** (string) - Transaction status (e.g., Success, Pending, Fail, Refund, Error).
- **order** (string) - Transaction number in the merchant system.
- **description** (string) - A brief description of the transaction status.
- **card_number** (string) - Masked card number used for the transaction.
- **error_resolution** (string) - Additional details for the payment status, including sub-statuses.
- **sign** (string) - Digital signature of the response.

#### Response Example (Success)
```json
{
    "status" : "success",
    "order" : "0001",
    "description" : "Merchant payment success",
    "error_resolution" : "success",
    "card_number" : "530011******3333",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```

#### Response Example (Error)
```json
{
    "status" : "Error",
    "order" : "0001",
    "description" : "Merchant payment not found",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}
```
```

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

### GET/POST Payout Callback

Source: https://payplus.kz/docs/en/index

This endpoint receives payout status updates via GET or POST request when a transaction status changes. The merchant's server must respond with 'OK'.

```APIDOC
## Payout Callback

### Description
This endpoint is called via GET or POST request to notify the merchant's server about changes in payout transaction status (e.g., from 'Pending' to 'Success' or 'Fail').

### Method
GET or POST

### Endpoint
[URL specified in merchant's settings]

### Parameters
#### Query Parameters (for GET) or Request Body (for POST)
- **co_inv_id** (string) - Required - Unique transaction number.
- **co_inv_crt** (string) - Required - Transaction creation date and time (YYYY-MM-DD HH:MM:SS).
- **co_inv_prc** (string) - Required - Transaction processing date and time (YYYY-MM-DD HH:MM:SS).
- **co_inv_st** (string) - Required - Payment processing status ("Success" or "Fail").
- **co_payout_id** (string) - Required - Payment number in the merchant's system (payout number).
- **co_merchant_uuid** (string) - Required - Unique merchant ID.
- **co_sign** (string) - Required - Digital signature generated with the merchant's key.

### Request Example (GET or POST)
```json
{
    "co_inv_id" : "1111111",
    "co_inv_crt" : "2021-02-16 19:12:04",
    "co_inv_prc" : "2021-02-16 19:12:11",
    "co_inv_st" : "Success",
    "co_payout_id" : "000002",
    "co_merchant_uuid" : "QYKVQCL07H44B",
    "co_sign" : "XXXXXXXXXXXXXXXXXX"
}
```

### Response
#### Success Response
The merchant's server must respond with 'OK' to acknowledge receipt of the callback.

#### Response Example
OK
```

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

### Deposit Success Response (iframe) - JSON Example

Source: https://payplus.kz/docs/en/index

This JSON object represents a successful payment response after a customer is redirected from the iframe payment form. It confirms the transaction details and its 'success' status.

```json
{
    "order_no" : "0001",
    "amount" : "16",
    "currency_code" : "KZT",
    "item_name" : "Samsung TV",
    "co_inv_id" : "1111111",
    "co_inv_st" : "success"
}
```

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

### Deposit Canceled Response (iframe) - JSON Example

Source: https://payplus.kz/docs/en/index

This JSON object represents a canceled payment response after a customer is redirected from the iframe payment form. It confirms the transaction details and its 'canceled' status.

```json
{
    "order_no" : "0001",
    "amount" : "16",
    "currency_code" : "KZT",
    "item_name" : "Samsung TV",
    "co_inv_id" : "1111111",
    "co_inv_st" : "canceled"
}
```

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

### Merchant Creation

Source: https://payplus.kz/docs/en/index_methods-api

This section details the process of creating a new merchant account through the PayPlus platform. It outlines the necessary fields and their descriptions.

```APIDOC
## Merchant Creation

### Description
This endpoint allows for the creation of a new merchant account within the PayPlus system. It requires various details about the merchant and their integration preferences.

### Method
POST

### Endpoint
/merchants

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **merchant_name** (string) - Required - The name of the merchant.
- **resource_link** (string) - Required - The URL of the merchant's resource.
- **secret_key** (string) - Optional - The secret key for the merchant. If not provided, it will be generated.
- **url_transition_in_form** (boolean) - Optional - 'YES' to enable URL transition to the payment form, 'NO' to use default settings.
- **process_url** (string) - Required if url_transition_in_form is 'NO' - The URL of the payment processor on the store's side.
- **success_url** (string) - Required if url_transition_in_form is 'YES' - The URL to redirect to after a successful transaction.
- **fail_url** (string) - Required if url_transition_in_form is 'YES' - The URL to redirect to after a failed transaction.
- **withdrawal_callback** (boolean) - Optional - 'YES' to receive callback responses for withdrawals.
- **withdrawal_url** (string) - Required if withdrawal_callback is 'YES' - The URL for the withdrawal callback processor.
- **return_recipient_card_mask** (boolean) - Optional - 'YES' to receive the recipient's card mask in the callback response.
- **api_access_ip_restriction** (array) - Optional - A list of IP addresses allowed to access "Payout Send" and "Payout Status" API methods.

### Request Example
```json
{
  "merchant_name": "Example Merchant",
  "resource_link": "https://example.com",
  "secret_key": "generated_secret_key",
  "url_transition_in_form": true,
  "success_url": "https://example.com/success",
  "fail_url": "https://example.com/fail"
}
```

### Response
#### Success Response (200)
- **merchant_id** (string) - The unique identifier for the created merchant.
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "merchant_id": "MERCHANT123",
  "message": "Merchant created successfully."
}
```
```

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

### Merchant Creation API

Source: https://payplus.kz/docs/en/index

This section details the process of creating a new merchant account through the PayPlus platform. It outlines the required fields for merchant registration, including details for payment acceptance and withdrawal configurations.

```APIDOC
## POST /merchants

### Description
Creates a new merchant account on the PayPlus platform.

### Method
POST

### Endpoint
/merchants

### Parameters
#### Request Body
- **merchant_name** (string) - Required - The name of the merchant.
- **resource_link** (string) - Required - The URL of the merchant's resource.
- **secret_key** (string) - Required - The secret key for the merchant. Can be generated automatically.
- **url_transition_in_form** (boolean) - Optional - If 'YES', confirms consent for URL transition to the payment form. Defaults to merchant's default settings if 'NO'.
- **process_url** (string) - Optional - The URL address of the payment processor on the store's side. Specifies the request type.
- **success_url** (string) - Optional - The redirection URL in case of a successful transaction. Specifies the request type.
- **fail_url** (string) - Optional - The redirection URL in case of a failed transaction. Specifies the request type.
- **receive_withdrawal_callback** (boolean) - Optional - If 'YES', confirms receipt of callback requests with withdrawal results.
- **withdrawal_url** (string) - Optional - The URL for the callback response processor for withdrawals. Specifies the request method (GET or POST).
- **return_recipient_card_mask** (boolean) - Optional - If 'YES', agrees to receive the recipient's card mask in the callback response.
- **restrict_payout_api_access** (boolean) - Optional - If true, restricts access to 'Payout Send' and 'Payout Status' API methods by IP address.

### Request Example
```json
{
  "merchant_name": "Example Merchant",
  "resource_link": "https://example.com",
  "secret_key": "generated_secret_key",
  "url_transition_in_form": true,
  "process_url": "https://example.com/process",
  "success_url": "https://example.com/success",
  "fail_url": "https://example.com/fail",
  "receive_withdrawal_callback": true,
  "withdrawal_url": "https://example.com/withdrawal_callback",
  "return_recipient_card_mask": true,
  "restrict_payout_api_access": true
}
```

### Response
#### Success Response (200)
- **merchant_id** (string) - The unique identifier for the created merchant.
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "merchant_id": "MERCHANT123",
  "message": "Merchant created successfully."
}
```
```

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

### POST /api/host2host

Source: https://payplus.kz/docs/en/index

Initiates a payment transaction through the PayPlus host-to-host API. This endpoint accepts detailed transaction information and returns a status indicating the next steps, potentially including a 3D Secure redirect.

```APIDOC
## POST /api/host2host

### Description
Initiates a payment transaction. This endpoint requires a comprehensive set of transaction details, including payment information, card details, customer information, and a digital signature for security. The response indicates the transaction status and may provide a URL for 3D Secure authentication.

### Method
POST

### Endpoint
/api/host2host

### Parameters
#### Request Body
- **type** (string) - Required - Transaction type (e.g., "payment").
- **merchant** (string) - Required - Unique merchant ID.
- **order** (string) - Required - Transaction number in the merchant system.
- **amount** (string) - Required - Transaction amount with a point as the separator (e.g., "10.99").
- **currency** (string) - Required - Transaction currency (USD, EUR, KZT, BRL, AZN).
- **card_num** (string) - Required - Bank card number.
- **card_exp_month** (string) - Required - Bank card expiration month (e.g., "01").
- **card_exp_year** (string) - Required - Bank card expiration year (e.g., "25").
- **card_cvv** (string) - Required - CVV of the bank card.
- **process_url** (string) - Required - URL for sending the transaction summary status.
- **item_name** (string) - Optional - Goods name.
- **first_name** (string) - Optional - Cardholder's first name (Latin characters only).
- **last_name** (string) - Optional - Cardholder's last name (Latin characters only).
- **user_id** (string) - Optional - Client identifier in the merchant's system.
- **payment_url** (string) - Optional - URL of the site in whose favor the payment is made.
- **country** (string) - Optional - Customer's country in ISO 3166-1 alpha-2 format.
- **email** (string) - Optional - Customer's e-mail.
- **phone** (string) - Optional - Customer's phone number.
- **address** (string) - Optional - Customer's address.
- **city** (string) - Optional - Customer's city.
- **post_code** (string) - Optional - Customer's post code.
- **region** (string) - Optional - Customer's region.
- **sign** (string) - Required - Digital signature generated from specific fields using SHA256.
- **browser** (object) - Optional - An object containing browser details:
  - **accept_header** (string) - Browser accept header.
  - **color_depth** (string) - Color depth of the browser.
  - **ip** (string) - Customer's IP address.
  - **language** (string) - Browser language.
  - **screen_height** (string) - Screen height.
  - **screen_width** (string) - Screen width.
  - **time_different** (string) - Time difference.
  - **window_width** (string) - Window width.
  - **window_height** (string) - Window height.

### Request Example
```json
{
    "type": "payment",
    "merchant": "QYKVQCL07H44B",
    "order": "0001",
    "amount": "10.99",
    "currency": "KZT",
    "card_num": "5300111122223333",
    "card_exp_month": "01",
    "card_exp_year": "25",
    "card_cvv": "111",
    "process_url": "https://test.com/api/callback_url",
    "item_name": "Samsung TV",
    "first_name": "IVAN",
    "last_name": "IVANOV",
    "user_id": "492235",
    "payment_url": "https://test.com",
    "country": "UA",
    "email": "test@gmail.com",
    "phone": "+35988222763",
    "address": "Avenue Marius Renard 21",
    "city": "Anderlecht",
    "post_code": "1070",
    "region": "stuttgart",
    "browser": {
        "accept_header": "...",
        "color_depth": "...",
        "ip": "...",
        "language": "...",
        "screen_height": "...",
        "screen_width": "...",
        "time_different": "...",
        "window_width": "...",
        "window_height": "..."
    },
    "sign": "GENERATED_SIGNATURE"
}
```

### Response
#### Success Response (200)
- **status** (string) - Transaction status (e.g., "3ds").
- **merchant** (string) - Unique merchant ID.
- **order** (string) - Transaction number in the merchant system.
- **uuid** (string) - Unique transaction ID.
- **co_inv_id** (integer) - Unique transaction number.
- **d3_acs_url** (string) - URL for the 3D Secure page.
- **d3_pareq** (string) - Data for passing to the 3D Secure page.
- **d3_md** (string) - Data for passing to the 3D Secure page.

#### Response Example (Success)
```json
{
    "status": "3ds",
    "merchant": "QYKVQCL07H44B",
    "order": "0001",
    "uuid": "H8OJ05IJEKG5Q",
    "co_inv_id": 1111111,
    "d3_acs_url": "https://3ds.bank.ua",
    "d3_pareq": "eJxVUt...tuwjAM/RX==",
    "d3_md": "1:809b...82316eb"
}
```

#### Response Example (Canceled)
```json
{
    "status": "canceled"
}
```
```

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

### Payout Response Example - Pending (JSON)

Source: https://payplus.kz/docs/en/index

This JSON response signifies that the payout transaction is pending. It includes the status, code, payout ID, description, and signature. A 'Pending' status requires an additional request to check the final status.

```json
{
    "status": "Pending",
    "code": "40",
    "payout_id": 000002,
    "description": "Payment in order",
    "sign": "XXXXXXXXXXXXXXXXXX"
}
```

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

### API Endpoints Overview

Source: https://payplus.kz/docs/en/index

A list of available API methods for payment processing, payouts, and status checks.

```APIDOC
## API Methods

List of API methods:

*   **/payment/form** - Payment request (iframe)
*   **/api/host2host** - Payment request (host-2-host)
*   **/payment/status** - Payment status request (Deposit)
*   **/merchant/api/payout_send** - Payout request
*   **/merchant/api/payout_status** - Payment status request (Payout)
*   **/payment/balance** - Balance request
*   **/api/payment-list** - Payments list request
```
Tokens:
Raw