Payout

Go

Go-модуль для интеграции с Payment Easy Payout API.

Go

Go-модуль для интеграции с Payment Easy Payout API.

Установка

go get github.com/unitewt/sdk-payout/go

Быстрый старт

package main

import (
    "fmt"
    "os"
    "time"

    payout "github.com/unitewt/sdk-payout/go"
)

func main() {
    privateKey, _ := os.ReadFile("private-key.pem")

    config, err := payout.NewConfig(
        "https://your-server.example.com",
        "your_username",
        privateKey,
    )
    if err != nil {
        panic(err)
    }

    client := payout.NewClient(config)

    // Запрос баланса
    balance, err := client.Balance()
    if err != nil {
        panic(err)
    }
    fmt.Printf("Баланс: %d копеек\n", balance.Balance)

    // Выплата на карту
    resp, err := client.Payment(&payout.PaymentRequest{
        ID:      "unique-tx-id",
        Sum:     100000, // 1000 рублей в копейках
        Service: payout.ServiceBankCard,
        Account: "4277255555555555",
        Date:    time.Now(),
        Phone:   "79999999999",
    })
    if err != nil {
        panic(err)
    }

    if resp.IsFinal() {
        fmt.Printf("Финальный статус: успех=%v\n", resp.IsSuccessful())
    }

    // Проверка статуса
    status, err := client.GetStatus("unique-tx-id")
    if err != nil {
        panic(err)
    }
    fmt.Printf("Статус: code=%d, state=%d, final=%d\n", status.Code, status.State, status.Final)
}

Конфигурация

config, err := payout.NewConfig(baseURL, username, privateKeyPEM,
    payout.WithTimeout(600),                        // таймаут в секундах (по умолчанию 300)
    payout.WithServerPublicKey(serverPublicKeyPEM),  // верификация подписи ответов
)

Параметр	Тип	Обязательный	По умолчанию	Описание
`baseURL`	`string`	да	—	URL сервера
`username`	`string`	да	—	Имя пользователя в системе
`privateKeyPEM`	`[]byte`	да	—	RSA приватный ключ (PKCS1 или PKCS8 PEM)
`WithTimeout`	`ConfigOption`	нет	300 сек	HTTP таймаут
`WithServerPublicKey`	`ConfigOption`	нет	nil	Публичный ключ сервера для верификации ответов

API

`Client`

Метод	Описание	Возвращает
`Balance()`	Запрос баланса	`(*BalanceResponse, error)`
`Payment(req)`	Выполнение выплаты	`(*PaymentResponse, error)`
`GetStatus(txID)`	Проверка статуса платежа	`(*PaymentResponse, error)`

`PaymentRequest`

Поле	Тип	Описание
`ID`	`string`	Уникальный ID транзакции (до 64 байт)
`Sum`	`int64`	Сумма в копейках
`Service`	`ServiceCode`	Тип сервиса (24, 25, 26, 28)
`Account`	`string`	Номер карты / телефона / кошелька
`Date`	`time.Time`	Дата транзакции
`Phone`	`string`	Телефон плательщика
`PayeeBankCode`	`string`	Код банка получателя (только для СБП)

`PaymentResponse`

Поле/Метод	Тип	Описание
`ID`	`string`	Ваш ID транзакции
`Code`	`int`	Код результата
`State`	`int`	Состояние платежа
`Final`	`int`	1 = финальный статус
`Trans`	`string`	ID транзакции на стороне шлюза
`Fee`	`*int64`	Комиссия в копейках (может быть nil)
`ErrorDescription`	`string`	Описание ошибки
`IsSuccessful()`	`bool`	code=0, state=60, final=1
`IsFailed()`	`bool`	code=20, state=80, final=1
`IsNotFound()`	`bool`	code=15, state=-2, final=1
`IsProcessing()`	`bool`	code=1, state=40, final=0
`IsFinal()`	`bool`	final=1

`BalanceResponse`

Поле	Тип	Описание
`Balance`	`int64`	Баланс в копейках
`Overdraft`	`int64`	Овердрафт в копейках

Сервисы

payout.ServiceBankCard    // 24 — банковские карты
payout.ServiceQIWIWallet  // 25 — кошельки QIWI
payout.ServiceSBP         // 26 — СБП
payout.ServiceMobilePhone // 28 — мобильные телефоны

Коды банков (СБП)

Для платежей через СБП используйте константы из bank_codes.go:

payout.BankCodeSberbankOfRussia  // "100000000111"
payout.BankCodeTinkoffBank       // "100000000004"
payout.BankCodeAlfaBank          // "100000000008"
// ... 238 банков

Выплата через СБП

resp, err := client.Payment(&payout.PaymentRequest{
    ID:            "sbp-tx-id",
    Sum:           50000,
    Service:       payout.ServiceSBP,
    Account:       "79876543210",
    Date:          time.Now(),
    Phone:         "79999999999",
    PayeeBankCode: payout.BankCodeSberbankOfRussia,
})

Обработка ошибок

SDK определяет два типа ошибок:

*payout.APIError — ошибки API (HTTP-ошибки, ошибки в ответах)
*payout.SignatureError — ошибки подписи/верификации

resp, err := client.Payment(req)
if err != nil {
    var apiErr *payout.APIError
    var sigErr *payout.SignatureError
    switch {
    case errors.As(err, &apiErr):
        fmt.Printf("API ошибка: %s (code=%d)\n", apiErr.Message, apiErr.Code)
    case errors.As(err, &sigErr):
        fmt.Printf("Ошибка подписи: %s\n", sigErr.Message)
    default:
        fmt.Printf("Ошибка: %v\n", err)
    }
}

Примеры

examples/generate_keys/ — генерация RSA-ключей
examples/integration_test/ — полный интеграционный тест (баланс, выплата на карту, выплата по СБП)

Для запуска интеграционного теста задайте переменные окружения:

export PAYOUT_BASE_URL="https://your-server.example.com"
export PAYOUT_USERNAME="your_username"
export PAYOUT_PRIVATE_KEY_PATH="./private-key.pem"

go run examples/integration_test/main.go

HTTP API

Прямой HTTP-контракт Payout API (Payment Easy).

Node.js

Node.js SDK для интеграции с Payment Easy Payout API.