Joys payment API (0.0.1)

Download OpenAPI specification:Download

Введение

API Joys создан на основе REST. API имеет определенные и предсказуемые URL-адреса и использует коды ответов HTTP для обработки ошибок. Мы используем встроенные функции HTTP, такие как HTTP-аутентификация и методы HTTP, которые понимаются через готовые HTTP-клиенты. Мы поддерживаем совместное использование ресурсов, позволяя вам безопасно взаимодействовать с нашим API с клиентского веб-приложения (вы никогда не должны раскрывать свой секретный ключ API в клиентском коде любого общедоступного веб-сайта или каким-либо иным способом). Формат JSON возвращается всеми ответами API, включая ошибки. В целях ознакомления с API, учетные записи имеют тестовый и прод режим и соответствующие ключи API. Для переключения между режимами используйте соответствующий ключ для выполнения запроса. Запросы, сделанные с учетными данными режима тестирования, никогда не попадают в прод окружение, какие-либо банковские сети и не влекут за собой каких-либо затрат.

Аутентификация

Для аутентификации аккаунта и запросов от его имени включите ваш секретный ключ (X-Joys-Authorization) в запросы API. X-Joys-Application-Key - секретный ключ приложения X-Joys-Authorization - секретный ключ терминала, выполняющего обращение к API Обращения к API поддерживаются через HTTPS, запросы через HTTP, а также запросы без ключа приложения и ключа терминала будут возвращены с ошибкой

Коды ответа и Ошибки

Коды состояний HTTP REST API используется для указания успеха или неуспеха вызова API. В общем случае коды состояний 2XX - успешные, коды 4XX - неуспешные., коды состояния типа 5XX говорят о наличии ошибки сервера. Стандартный список состояний: 200 - OK Все работает ожидаемым образом. 400 - Bad Request Неприемлемый запрос, чаще по причине того, что были пропущены какие-либо параметры в запросе. Повторять подобный запрос не следует. 401 - Unauthorized Невалидный ключ API. 402 - Request Failed Параметры были валидными, но запрос в целом отвергнут 404 - Not Found Запрошенный ресурс не существует 409 - Conflict Запрос конфликтует с другим запросом или, например, с текущим состоянием сервера 429 - Too Many Requests Слишком много запросов. Рекомендация, уменьшить количество запросов к API. 500, 502, 503, 504 - Server Errors Что-то пошло не так на сервере Joys.

Коды ошибок, в общем случае, 2XX - успешные, коды 4XX - неуспешные., коды состояния типа 5XX говорят о наличии ошибки сервера.

Некоторые ошибки 4XX могут быть обработаны программно, они включают код ошибки и краткое пояснение к ней.

Атрибуты

|Field|Description| |type|The type of error returned. One of api_connection_error, api_error, authentication_error, wallet_error, idempotency_error, invalid_request_error, or rate_limit_error| |code|For some errors that could be handled programmatically, a short string indicating the error code reported.| |message|A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.|

Idempotent Requests

API поддерживает идемпотентность для безопасного повторения запросов, исключая при этом случайное повторение одной и той же операции. Это полезно,например, когда выполнение запроса API нарушено, и вы не получаете ответа. Например, если запрос на создание счета завершился с ошибкой сетевого подключения, то вы можете повторить запрос с тем же ключом идемпотентности, чтобы гарантировать, что будет создана только один счет. Idempotency Key - это уникальное значение, генерируемое клиентом, которое сервер использует для распознавания последующих повторений одного и того же запроса. То, как вы создаете уникальные ключи, зависит от вас, но мы предлагаем использовать UUID V4 или другую случайную строку с достаточной энтропией, чтобы избежать коллизий. Срок действия ключей истекает через 24 часа, поэтому возникает новый запрос, если ключ используется повторно за пределами 24 часового временного интервала. Чтобы выполнить Idemponent request, укажите дополнительно X-Joys-Idempotent-Key в заголовке запроса. X-Joys-Idempotent-Key: <key>

Joys idempotency работает, сохраняя полученный код состояния и тело первого запроса, сделанного для любого заданного Idempotent-Key, независимо от того, удачным ли был запрос или нет. Последующие запросы с одним и тем же ключом возвращают один и тот же результат. Слой Идемпотентности сравнивает входящие параметры с параметрами исходного запроса и ошибки, чтобы предотвратить случайное злоупотребление. Если входящие параметры не прошли проверку, или запрос противоречил другому запросу, который выполнялся одновременно, ни один идемпотентный результат не сохраняется. Запросы GET и DELETE являются идемпотентными по определению, что означает, что одна и та же работа с бэкэнд происходит независимо от того, сколько раз выдается один и тот же запрос. Вы не должны посылать Idempotent-Key с этими методами, потому что он не требуется.

Ограничение скорости

Для запросов API, использующих OAuth, вы можете составлять до 100 запросов в минуту. Возвращенные HTTP-заголовки любого запроса API показывают текущий статус ограничения скорости:

HTTP/1.1 200 OK
Date: Tue, 05 Jun 2018 07:43:18 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Joys-Rate-Limit-Limit: 100
X-Joys-Rate-Limit-Remaining: 99
X-Joys-Rate-Limit-Reset: 100
Header Name Description
X-Rate-Limit-Limit Максимальное количество запросов в час
X-Rate-Limit-Remaining Количество запросов, оставшихся в текущем окне ограничения скорости
X-Rate-Limit-Reset Время, в которое текущее окно ограничения скорости сбрасывается UTC секунды

If you exceed the rate limit, an error response returns:

HTTP/1.1 403 Forbidden
Date: Tue, 05 Jun 2018 07:43:18 GMT
Status: 403 Forbidden
X-Joys-RateLimit-Limit: 100
X-Joys-RateLimit-Remaining: 0
X-Joys-RateLimit-Reset: 60
{
    "name": "Too Many Requests",
    "message": "Rate limit exceeded.",
    "code": 0,
}

Metadata

Обновляемые объекты такие как, счет, возврат, товарная позиция, покупатель имеют параметр метаданных. Этот параметр можно использовать для привязки некоторых произвольных данных к этим объектам. (см описание API выставления счета, например) Метаданные полезны для хранения дополнительной структурированной информации об объекте. Например, вы можете сохранить полное имя пользователя и соответствующий ему уникальный идентификатор из вашей системы в объекте Joys.

Некоторые из перечисленных выше объектов также поддерживают параметр описания. Вы можете использовать параметр описания, чтобы аннотировать плату - например, удобочитаемое описание, например, 2 футболки для test@example.com. В отличие от метаданных, описание представляет собой одну строку, и ваши пользователи могут видеть ее (например, в квитанции электронной почты). Не храните конфиденциальную информацию (личную информацию, данные карты и т. д.) в виде метаданных или в параметрах описания.

Pagination

Все ресурсы API верхнего уровня поддерживают массовые выборки через API "list" методы. Например, вы можете получить список счетов или список возвратов. Эти методы API списков имеют общую структуру, принимая параметры страницы. Joys использует разбиение на страницы на основе запроса "page" параметр запроса. Это номер страницы в списке объектов, расположенных в хронологическом порядке. Размер страницы 20 и не изменится в текущей версии API.

В ответ на ваши запросы вы получаете следующую структуру:

{
    "count": 1023
    "next": "https://api.example.org/cahrges/?page=5",
    "previous": "https://api.example.org/charges/?page=3",
    "results": []
}

Где:

  "count" - Total number of objects
  "next" - Link to next page. It will be 'null' if next page does not exist
  "previous" - Link to previous page. It will be 'null' if prev. page does not exist
  "results" - list of objects

Если вы запросили страницу, которой не существует, то вы получите следующий ответ:

404 Not Found
{
    "detail": "Invalid page"
}

Authentication

ApplicationToken

Security scheme type: API Key
header parameter name: X-Joys-Application-Token

TerminalKey

Security scheme type: API Key
header parameter name: X-Joys-Authorization

Service

Service status oriented endpoints

Service health check

Responses

200
get /service/health
Joys API
https://api.joys.digital/merchant/v0/service/health
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/service/health

Response samples

application/json
Copy
Expand all Collapse all
{
  • "status": "OPERATING"
}

Authentication

Client authentication endpoints

Request POS authentication token

query Parameters
shop
required
string

Shop idenitifier

pos
required
string

POS identifier

header Parameters
X-Joys-Application-Token
required
string

Application token

Responses

201

Created

post /authentication/request
Joys API
https://api.joys.digital/merchant/v0/authentication/request
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/authentication/request

Response samples

application/json
Copy
Expand all Collapse all
{
  • "token": "token/c5ef71cf-f32a-41f1-bb86-18d69848d880",
  • "status": "new",
  • "not_before": 1539746210,
  • "not_after": 1539746214
}

Retrive token status

header Parameters
X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

200

Token response

get /authentication/status
Joys API
https://api.joys.digital/merchant/v0/authentication/status
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/authentication/status

Response samples

application/json
Copy
Expand all Collapse all
{
  • "token": "token/c5ef71cf-f32a-41f1-bb86-18d69848d880",
  • "status": "new",
  • "not_before": 1539746210,
  • "not_after": 1539746214
}

Revoke token

header Parameters
X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

204

Token revoke response

post /authentication/revoke
Joys API
https://api.joys.digital/merchant/v0/authentication/revoke
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/authentication/revoke

Payments

To charge a wallet, you create a Charge object. You can retrieve and void individual charges as well as list all charges. Charges are identified by a unique, random ID.

List charges

query Parameters
not_before
integer

Date filter

not_after
integer

Date filter

session
string

Session filter

customer
string

Customer filter

page
integer

page number (see pagination part)

header Parameters
X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

200

Get charges

get /charges
Joys API
https://api.joys.digital/merchant/v0/charges
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/charges

Response samples

application/json
Copy
Expand all Collapse all
{
  • "has_more": false,
  • "object": "list",
  • "data":
    [
    ]
}

Create charge

query Parameters
charge
required
object (Charge)

Charge object

header Parameters
X-Joys-Idempotent-Key
required
string

Idempotency key

X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

201

Charge response

post /charges
Joys API
https://api.joys.digital/merchant/v0/charges
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/charges

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "charge/d1de825d-7d53-4cc5-acc3-60e25b861ec0",
  • "amount": 1000,
  • "fee": 50,
  • "currency": "RUB",
  • "rate":
    {
    },
  • "source": "wallet/a323ef30-4ed6-4f7e-a18b-766816beecc3",
  • "customer":
    {
    },
  • "status": "new",
  • "txid": "tx/bf943208-e985-49f3-9295-adf202f36344",
  • "captured": true,
  • "paid": true,
  • "refunded": true,
  • "expired": true,
  • "voided": true,
  • "refunds":
    [
    ],
  • "failure":
    {
    },
  • "created_at": "214 7483640",
  • "expired_at": 3147483640,
  • "captured_at": 2147483651,
  • "paid_at": 2147483662,
  • "refunded_at": 2147483673,
  • "voided_at": 2147483673,
  • "description": "Human readable discription visible to client.",
  • "invoice": null,
  • "receipt_email": "user@example.com",
  • "receipt_number": "r-Zaegac1E/2018",
  • "items":
    [
    ],
  • "metadata":
    [
    ],
  • "pos_signature": "f546e927c291a52c9414705f5b476f1346c3e6e5ea99b4e15c080a05edb508c02210622b1c8025a0e728e9a6f4d7edb9668868f85b81bab6e1a61e3b815de372",
  • "user_signature": "f546e927c291a52c9414705f5b476f1346c3e6e5ea99b4e15c080a05edb508c02210622b1c8025a0e728e9a6f4d7edb9668868f85b81bab6e1a61e3b815de372",
  • "transaction":
    {
    },
  • "session": "string"
}

Get charge object

path Parameters
id
required
string

Charge identifier

header Parameters
X-Joys-Idempotent-Key
required
string

Idempotency key

X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

200

Get authorization details

get /charges/{id}
Joys API
https://api.joys.digital/merchant/v0/charges/{id}
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/charges/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "charge/d1de825d-7d53-4cc5-acc3-60e25b861ec0",
  • "amount": 1000,
  • "fee": 50,
  • "currency": "RUB",
  • "rate":
    {
    },
  • "source": "wallet/a323ef30-4ed6-4f7e-a18b-766816beecc3",
  • "customer":
    {
    },
  • "status": "new",
  • "txid": "tx/bf943208-e985-49f3-9295-adf202f36344",
  • "captured": true,
  • "paid": true,
  • "refunded": true,
  • "expired": true,
  • "voided": true,
  • "refunds":
    [
    ],
  • "failure":
    {
    },
  • "created_at": "214 7483640",
  • "expired_at": 3147483640,
  • "captured_at": 2147483651,
  • "paid_at": 2147483662,
  • "refunded_at": 2147483673,
  • "voided_at": 2147483673,
  • "description": "Human readable discription visible to client.",
  • "invoice": null,
  • "receipt_email": "user@example.com",
  • "receipt_number": "r-Zaegac1E/2018",
  • "items":
    [
    ],
  • "metadata":
    [
    ],
  • "pos_signature": "f546e927c291a52c9414705f5b476f1346c3e6e5ea99b4e15c080a05edb508c02210622b1c8025a0e728e9a6f4d7edb9668868f85b81bab6e1a61e3b815de372",
  • "user_signature": "f546e927c291a52c9414705f5b476f1346c3e6e5ea99b4e15c080a05edb508c02210622b1c8025a0e728e9a6f4d7edb9668868f85b81bab6e1a61e3b815de372",
  • "transaction":
    {
    },
  • "session": "string"
}

Capture the authorization of charge

path Parameters
id
required
string

Authorization uuid

header Parameters
X-Joys-Idempotent-Key
required
string

Idempotency key

X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

200

Authorization details

post /charges/{id}/capture
Joys API
https://api.joys.digital/merchant/v0/charges/{id}/capture
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/charges/{id}/capture

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "charge/d1de825d-7d53-4cc5-acc3-60e25b861ec0",
  • "amount": 1000,
  • "fee": 50,
  • "currency": "RUB",
  • "rate":
    {
    },
  • "source": "wallet/a323ef30-4ed6-4f7e-a18b-766816beecc3",
  • "customer":
    {
    },
  • "status": "new",
  • "txid": "tx/bf943208-e985-49f3-9295-adf202f36344",
  • "captured": true,
  • "paid": true,
  • "refunded": true,
  • "expired": true,
  • "voided": true,
  • "refunds":
    [
    ],
  • "failure":
    {
    },
  • "created_at": "214 7483640",
  • "expired_at": 3147483640,
  • "captured_at": 2147483651,
  • "paid_at": 2147483662,
  • "refunded_at": 2147483673,
  • "voided_at": 2147483673,
  • "description": "Human readable discription visible to client.",
  • "invoice": null,
  • "receipt_email": "user@example.com",
  • "receipt_number": "r-Zaegac1E/2018",
  • "items":
    [
    ],
  • "metadata":
    [
    ],
  • "pos_signature": "f546e927c291a52c9414705f5b476f1346c3e6e5ea99b4e15c080a05edb508c02210622b1c8025a0e728e9a6f4d7edb9668868f85b81bab6e1a61e3b815de372",
  • "user_signature": "f546e927c291a52c9414705f5b476f1346c3e6e5ea99b4e15c080a05edb508c02210622b1c8025a0e728e9a6f4d7edb9668868f85b81bab6e1a61e3b815de372",
  • "transaction":
    {
    },
  • "session": "string"
}

Void charge

path Parameters
id
required
string

Charge uuid

header Parameters
X-Joys-Idempotent-Key
required
string

Idempotency key

X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

200

Charge details

post /charges/{id}/void
Joys API
https://api.joys.digital/merchant/v0/charges/{id}/void
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/charges/{id}/void

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "charge/d1de825d-7d53-4cc5-acc3-60e25b861ec0",
  • "amount": 1000,
  • "fee": 50,
  • "currency": "RUB",
  • "rate":
    {
    },
  • "source": "wallet/a323ef30-4ed6-4f7e-a18b-766816beecc3",
  • "customer":
    {
    },
  • "status": "new",
  • "txid": "tx/bf943208-e985-49f3-9295-adf202f36344",
  • "captured": true,
  • "paid": true,
  • "refunded": true,
  • "expired": true,
  • "voided": true,
  • "refunds":
    [
    ],
  • "failure":
    {
    },
  • "created_at": "214 7483640",
  • "expired_at": 3147483640,
  • "captured_at": 2147483651,
  • "paid_at": 2147483662,
  • "refunded_at": 2147483673,
  • "voided_at": 2147483673,
  • "description": "Human readable discription visible to client.",
  • "invoice": null,
  • "receipt_email": "user@example.com",
  • "receipt_number": "r-Zaegac1E/2018",
  • "items":
    [
    ],
  • "metadata":
    [
    ],
  • "pos_signature": "f546e927c291a52c9414705f5b476f1346c3e6e5ea99b4e15c080a05edb508c02210622b1c8025a0e728e9a6f4d7edb9668868f85b81bab6e1a61e3b815de372",
  • "user_signature": "f546e927c291a52c9414705f5b476f1346c3e6e5ea99b4e15c080a05edb508c02210622b1c8025a0e728e9a6f4d7edb9668868f85b81bab6e1a61e3b815de372",
  • "transaction":
    {
    },
  • "session": "string"
}

Refunds

To refund charged funds, you create Refund object linked to charge.

Refunds list resource

query Parameters
not_before
integer

Date filter

not_after
integer

Date filter

session
string

Session filter

customer
string

Customer filter

page
integer

page number (see pagination part)

header Parameters
X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

200

Get charges

get /refunds
Joys API
https://api.joys.digital/merchant/v0/refunds
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/refunds

Response samples

application/json
Copy
Expand all Collapse all
{
  • "has_more": false,
  • "object": "list",
  • "data":
    [
    ]
}

Create refund

query Parameters
refund
object (Refund)

Refund object

header Parameters
X-Joys-Idempotent-Key
required
string

Idempotency key

X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

200

Authorization details

post /refunds
Joys API
https://api.joys.digital/merchant/v0/refunds
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/refunds

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "refund/3a5f022a-08b6-47ed-855e-e3d617e69279",
  • "external_id": "Refund claim",
  • "amount": 1000,
  • "fee": 50,
  • "charge": "charge/f941072b-3e63-4f03-a4a1-239bed824577",
  • "created_at": 2147483640,
  • "expired_at": 3147483640,
  • "refunded_at": 2147483662,
  • "voided_at": 2147483673,
  • "refunded": true,
  • "voided": false,
  • "currency": "RUB",
  • "description": "Human readable discription visible to client.",
  • "failure":
    {
    },
  • "reason": "duplicate",
  • "receipt_number": "r-Zaegac1E/2018",
  • "status": "new",
  • "metadata":
    {
    },
  • "session": "string"
}

Get refund object

path Parameters
id
required
string

Refund id

header Parameters
X-Joys-Idempotent-Key
required
string

Idempotency key

X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

200

Refund object

get /refunds/{id}
Joys API
https://api.joys.digital/merchant/v0/refunds/{id}
Joys API Sandbox
https://sandbox-api.joys.digital/merchant/v0/refunds/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "refund/3a5f022a-08b6-47ed-855e-e3d617e69279",
  • "external_id": "Refund claim",
  • "amount": 1000,
  • "fee": 50,
  • "charge": "charge/f941072b-3e63-4f03-a4a1-239bed824577",
  • "created_at": 2147483640,
  • "expired_at": 3147483640,
  • "refunded_at": 2147483662,
  • "voided_at": 2147483673,
  • "refunded": true,
  • "voided": false,
  • "currency": "RUB",
  • "description": "Human readable discription visible to client.",
  • "failure":
    {
    },
  • "reason": "duplicate",
  • "receipt_number": "r-Zaegac1E/2018",
  • "status": "new",
  • "metadata":
    {