SeverPay.io

https://docs.severpay.io
Admin
SeverPay.io is a payment system providing an API for processing payments, managing payment...
Tokens:4,357
Snippets:13
Trust Score:3.8
Update:11 months ago
Show doc for...
Tokens:
Raw
### Get Payment Info (JSON Example)

Source: https://docs.severpay.io/payin/get

This snippet demonstrates the JSON structure for a successful response when retrieving payment information. It includes details like payment ID, order ID, amount, currency, and status. An error response structure is also shown.

```json
{
  "status": true,
  "msg": "",
  "data": {
    "id": 123, 
    "order_id": "123", 
    "amount": 10.00, 
    "currency": "USD",
    "status": "new"
  }
}
```

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

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

### Provide webhook response JSON for Success and Error

Source: https://docs.severpay.io/webhook/basic-info

Example JSON bodies that the webhook endpoint should return. A successful processing returns {"status": true}. On return {"status": false} with an optional "msg" describing the error. Responses must be sent with content‑type application/json.

```json
{
  "status": true
}

{
  "status": false,
  "msg": "Error description"
}
```

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

### Merchant API Authentication and Request Signing

Source: https://docs.severpay.io/payin/basic-info

This section details the process of authenticating with the SeverPay Merchant API and generating the necessary request signature. It includes information on the base URL, headers, request body parameters, and provides code examples in PHP, Python, and JavaScript for signature generation.

```APIDOC
## Merchant API Authentication and Request Signing

### Description
This endpoint requires specific authentication headers and a signed request body. The signature is generated using the HMAC-SHA256 algorithm based on the sorted JSON representation of the request body and a secret token.

### Method
POST

### Endpoint
`/api/merchant`

### Parameters
#### Headers
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **mid** (integer) - Required - ID магазина (Merchant ID)
- **salt** (string) - Required - Случайно сгенерированная строка (Randomly generated string)
- **sign** (string) - Required - Подпись запроса (Request signature)

### Request Body Generation Steps
1. Prepare an array with the data to be sent in the request body.
2. Sort the array by keys.
3. Compute the `sign` using the HMAC-SHA256 algorithm with the JSON representation of the sorted array and the secret `token`.
4. Add the computed signature to the array.

### Request Example (Illustrative - actual values will vary)
```json
{
  "mid": 1,
  "salt": "AnyRandomString",
  "sign": "generated_signature_here"
}
```

### Response
#### Success Response (200)
(Specific success response details not provided in the input text, but would typically include confirmation of successful operation or returned data.)

#### Error Response
(Specific error response details not provided in the input text, but would typically include error codes and messages.)

### Code Examples (Signature Generation)
#### PHP
```php
$mid = 1;
$token = "041131a0906b08a5bebc1d4fdcc6d9";
$body = [
    'mid' => $mid,
    'salt' => "AnyRandomString",
];
ksort($body);
$body['sign'] = hash_hmac("sha256", json_encode($body), $token);
// Now $body contains the signed payload ready to be sent.
```

#### Python
```python
import json
import hmac
import hashlib

mid = 1
token = "041131a0906b08a5bebc1d4fdcc6d9"

body = {
    'mid': mid,
    'salt': "AnyRandomString"
}

sorted_body = dict(sorted(body.items()))

body['sign'] = hmac.new(
    token.encode('utf-8'),
    json.dumps(sorted_body, ensure_ascii=False, separators=(',', ':')).encode('utf-8'),
    hashlib.sha256
).hexdigest()
# Now 'body' contains the signed payload ready to be sent.
```

#### JavaScript
```javascript
const crypto = require('crypto');

const mid = 1;
const token = "041131a0906b08a5bebc1d4fdcc6d9";

let body = {
    mid: mid,
    salt: "AnyRandomString"
};

const sortedBody = {};
Object.keys(body).sort().forEach(key => {
    sortedBody[key] = body[key];
});

const sign = crypto.createHmac('sha256', token)
    .update(JSON.stringify(sortedBody))
    .digest('hex');

body.sign = sign;
// Now 'body' contains the signed payload ready to be sent.
```
```

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

### POST /payin/create

Source: https://docs.severpay.io/payin/create

Creates a new payment (payin) and returns a payment link that can be presented to the client. The endpoint accepts order and client details and optionally a return URL and link lifetime.

```APIDOC
## POST /payin/create\n\n### Description\nCreates a new payment (payin) and returns a payment link that can be presented to the client.\n\n### Method\nPOST\n\n### Endpoint\n/payin/create\n\n### Parameters\n#### Path Parametersn*(none)*\n\n#### Query Parameters\n*(none)*\n\n#### Request Body\n- **order_id** (string) - Required - ID of the order/payment.\n- **amount** (number) - Required - Payment amount (e.g., 10.00).\n- **currency** (string) - Required - Currency code (e.g., USD).\n- **client_email** (string) - Required - of the client.\n- **client_id** (string) - Required - Client identifier in your system.\n- **url_return** ( - Optional - Return URL after payment.\n- **lifetime** (integer) - Optional - Link validity in minutes (30-4320, default 1440).\n\n### Request Example\n{\n  "order_id": "order123",\n  "amount": 10.00,\n  "currency": "USD",\n  "client_email": "client@example.com",\n  "client_id": "client123",\n  "url_return": "https://example.com/return",\n  "lifetime": 1440\n}\n\n### Response\n#### Success Response (200)\n- **status** (boolean) - Indicates success.\n- **msg** (string) - Message, empty on success.\n- **data** (object) - Contains payment details.\n  - **** (string) - Payment ID in SeverPay system.\n  - **url** (string) - URL for the payment page.\n  - **expire_at** (string) - Unix timestamp when the link expires.\n\n#### Response Example\n{\n  "status": true,\n  "msg": "",\n  "data": {\n    "id": "123",\n    "url": "https://severpay.io/pay/link123",\n    "expire_at": "1735675200"\n  }\n}\n\n#### Error Response\n- **status** (boolean) - Indicates failure (false).\n- **msg** (string) - Description of the error.\n\n#### Error Example\n{\n  "status": false,\n  "msg": "Error description"\n}
```

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

### Configure Payin Settings (API)

Source: https://docs.severpay.io/payin/settings

This API endpoint allows merchants to configure their payment-in settings. It accepts a POST request to `/payin/settings`. The success response includes merchant details, fee structure, and transaction limits, while the error response provides a description of the failure.

```json
{
  "status": true,
  "msg": "",
  "data": {
    "mid": 1,
    "name": "Merchant name",
    "fee": 1.50,
    "min_amount": 10.00,
    "max_amount": 1000.00,
    "currency": "USD"
  }
}
```

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

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

### Create Payment Request Body - SeverPay API

Source: https://docs.severpay.io/payin/create

Defines the parameters required to create a payment. Includes order ID, amount, currency, client email/ID, and optional return URL and link lifetime. The amount is a number, and lifetime is an integer with specific range limitations.

```json
{
  "order_id": "string",
  "amount": 10.00,
  "currency": "USD",
  "client_email": "string",
  "client_id": "string",
  "url_return": "string",
  "lifetime": 1440
}
```

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

### Create Payment - SeverPay API Response

Source: https://docs.severpay.io/payin/create

Illustrates the expected JSON response structure for payment creation. A successful response includes a payment ID, a payment URL, and an expiration timestamp. An error response provides a status flag and an error message.

```json
{
  "status": true,
  "msg": "",
  "data": {
    "id": "123",
    "url": "https://severpay.io/pay/link123",
    "expire_at": "1735675200"
  }
}
```

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

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

### POST /payin/settings

Source: https://docs.severpay.io/payin/settings

Configure terminal settings, including merchant information, fees, and transaction limits.

```APIDOC
## POST /payin/settings

### Description
Configure terminal settings, including merchant information, fees, and transaction limits.

### Method
POST

### Endpoint
/payin/settings

### Request Body
* **mid** (integer) - Required - Merchant ID.
* **name** (string) - Required - Merchant name.
* **fee** (float) - Required - Commission fee in percentage.
* **min_amount** (float) - Required - Minimum payment amount.
* **max_amount** (float) - Required - Maximum payment amount.
* **currency** (string) - Required - Currency code (e.g., USD).

### Request Example
```json
{
  "mid": 1,
  "name": "Merchant name",
  "fee": 1.50,
  "min_amount": 10.00,
  "max_amount": 1000.00,
  "currency": "USD"
}
```

### Response
#### Success Response (200)
* **status** (boolean) - Indicates if the operation was successful.
* **msg** (string) - Contains an error message if the status is false.
* **data** (object) - Contains the updated terminal settings.
  * **mid** (integer) - Merchant ID.
  * **name** (string) - Merchant name.
  * **fee** (float) - Commission fee in percentage.
  * **min_amount** (float) - Minimum payment amount.
  * **max_amount** (float) - Maximum payment amount.
  * **currency** (string) - Currency code.

#### Response Example
```json
{
  "status": true,
  "msg": "",
  "data": {
    "mid": 1,
    "name": "Merchant name",
    "fee": 1.50,
    "min_amount": 10.00,
    "max_amount": 1000.00,
    "currency": "USD"
  }
}
```

#### Error Response (4xx/5xx)
* **status** (boolean) - Indicates if the operation was successful (will be false).
* **msg** (string) - Description of the error.

#### Error Response Example
```json
{
  "status": false,
  "msg": "Error description"
}
```
```

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

### Payment Object Structure

Source: https://docs.severpay.io/webhook/payin

Details the structure and attributes of a payment object in the SeverPay system, including ID, order ID, amount, currency, and status.

```APIDOC
## Payment Object Structure

### Description
Details the structure and attributes of a payment object in the SeverPay system.

### Fields
| Name       | Type    | Description                |
| ---------- | ------- | -------------------------- |
| `id`       | integer | ID платежа в нашей системе |
| `order_id` | string  | ID платежа в вашей системе |
| `amount`   | number  | Сумма                      |
| `currency` | string  | Валюта                     |
| `status`   | string  | Статус платежа             |

### Status Reference
For detailed status descriptions, refer to the [status-list](https://docs.severpay.io/payin/status-list).
```

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

### POST /WEBHOOK_URL

Source: https://docs.severpay.io/webhook/basic-info

This endpoint receives notifications from Severpay. It expects a JSON payload containing the notification type, data, a random string, and a signature for verification.

```APIDOC
## POST /WEBHOOK_URL

### Description
This endpoint receives notifications from Severpay. It expects a JSON payload containing the notification type, data, a random string, and a signature for verification. Severpay will retry sending notifications until a successful response is received.

### Method
POST

### Endpoint
/WEBHOOK_URL

### Parameters
#### Request Body
- **type** (string) - Required - The type of notification.
- **data** (object) - Required - An object containing the notification data.
- **salt** (string) - Required - A random string.
- **sign** (string) - Required - The signature of the notification for verification.

### Request Example
```json
{
  "type": "payment_success",
  "data": {
    "transaction_id": "12345",
    "amount": 100.00
  },
  "salt": "random_string",
  "sign": "calculated_signature"
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the notification was processed successfully.

#### Response Example
```json
{
  "status": true
}
```

#### Error Response (Non-200)
- **status** (boolean) - Indicates failure.
- **msg** (string) - A description of the error.

#### Error Response Example
```json
{
  "status": false,
  "msg": "Error description"
}
```

### Signature Verification
To verify the signature of incoming requests:
1. Receive the request body and decode it as JSON.
2. Remove the `sign` key from the payload.
3. Calculate the signature using the HMAC-SHA256 algorithm on the JSON representation of the remaining payload, using your secret `token` as the key.
4. Compare the calculated signature with the `sign` value received in the request.

#### Example Notification Handler (PHP)
```php
<?php
$token = 'YOUR_SECRET_TOKEN';

$inputJSON = file_get_contents('php://input');
$input = json_decode($inputJSON, TRUE);

$input_sign = $input['sign'];
unset($input['sign']);

$sign = hash_hmac("sha256", json_encode($input), $token);

if( !hash_equals($input_sign, $sign) ) {
    // Return an error response
    http_response_code(400);
    echo json_encode(['status' => false, 'msg' => 'Invalid signature']);
    exit;
}

// Process the valid notification
// ... your code here ...

// Return a success response
echo json_encode(['status' => true]);
?>
```

### IP Addresses for Notifications
Severpay sends notifications from the following IP addresses:
- `45.76.81.14`
- `2001:19f0:6c01:878:5400:5ff:fe38:50d1`
- `207.148.69.64`
- `2401:c080:1400:109b:5400:5ff:fe95:20d3`
```

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

### POST /payin/get - Retrieve Payment Information

Source: https://docs.severpay.io/payin/get

Retrieves detailed information about a specific payment by its ID. It supports both success and error responses, providing payment status and details or an error message.

```APIDOC
## POST /payin/get

### Description
Retrieves detailed information about a specific payment using its ID.

### Method
POST

### Endpoint
/payin/get

### Parameters
#### Request Body
- **id** (string) - Required - ID of the payment in our system

### Request Example
```json
{
  "id": "string"
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the request was successful.
- **msg** (string) - An empty string if the request was successful.
- **data** (object) - Contains payment details if successful:
  - **id** (integer) - Payment ID in our system.
  - **order_id** (string) - Payment ID in your system.
  - **amount** (float) - The payment amount.
  - **currency** (string) - The currency of the payment.
  - **status** (string) - The current status of the payment.

#### Error Response (Non-200 status codes may also occur)
- **status** (boolean) - Indicates if the request was successful (will be false).
- **msg** (string) - A description of the error.

#### Response Example (Success)
```json
{
  "status": true,
  "msg": "",
  "data": {
    "id": 123,
    "order_id": "123",
    "amount": 10.00,
    "currency": "USD",
    "status": "new"
  }
}
```

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

**Note:** For a list of possible payment statuses, refer to [status-list](https://docs.severpay.io/payin/status-list).
```

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

### Validate webhook signature using HMAC‑SHA256 in PHP

Source: https://docs.severpay.io/webhook/basic-info

PHP handler that reads the raw POST body, decodes the JSON payload, removes the "sign" field, recalculates the HMAC‑SHA256 signature with the shared token, and compares it to the provided signature. Returns an error response if verification fails, otherwise proceeds with custom logic and returns success.

```php
$token = '041131a0906b08a5bebc1d4fdcc6d9';

$inputJSON = file_get_contents('php://input');
$input = json_decode($inputJSON, true);

$input_sign = $input['sign'];
unset($input['sign']);
$sign = hash_hmac('sha256', json_encode($input), $tokenn
if (!hash_equals($input_sign, $sign)) {
    // Return error response
    header('Content-Type: application/json');
    echo json_encode(['status' => false, 'msg' => 'Invalid signature']);
    exit;
}

// Your custom processing logic here

// Return success response
header('Content-Type: application/json');
echo json_encode(['status' => true]);
```

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

### Generate request signature using HMAC‑SHA256

Source: https://docs.severpay.io/payin/basic-info

Creates a signed payload for SeverPay API requests by sorting the body parameters, encoding them as JSON, and applying HMAC‑SHA256 with the merchant token. Supports PHP, Python, and JavaScript implementations. The resulting "sign" field is added to the request body before sending.

```PHP
$mid = 1;
$token = "041131a0906b08a5bebc1d4fdcc6d9";
$body = [
    'mid' => $mid,
    'salt' => "AnyRandomString",
];
ksort($body);
$body['sign'] = hash_hmac("sha256", json_encode($body), $token);

```

```Python
import json
import hmac
import hashlib

mid = 1
token = "041131a0906b08a5bebc1d4fdcc6d9"

body = {
    'mid': mid,
    'salt': "AnyRandomString"
}

sorted_body = dict(sorted(body.items()))

body['sign'] = hmac.new(
    token.encode('utf-8'),
    json.dumps(sorted_body, ensure_ascii=False, separators=(',', ':')).encode('utf-8'),
    hashlib.sha256
).hexdigest()

```

```JavaScript
const crypto = require('crypto');

const mid = 1;
const token = "041131a0906b08a5bebc1d4fdcc6d9";

let body = {
    mid: mid,
    salt: "AnyRandomString"
};

const sortedBody = {};
Object.keys(body).sort().forEach(key => {
    sortedBody[key] = body[key];
});

const sign = crypto.createHmac('sha256', token)
    .update(JSON.stringify(sortedBody))
    .digest('hex');

body.sign = sign;

```
Tokens:
Raw