Joys payment API (2019.07-1)

Download OpenAPI specification:Download

Введение

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

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

Для аутентификации запросов включите в запрос заголовки: X-Joys-Application-Token: apptoken value_of_your_app_secret_key - секретный ключ приложения X-Joys-Authorization: token value_of_your_terminal_secret_key - секретный ключ терминала, выполняющего обращение к 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" - Общее количество объектов
  "next" - Ссылка на следующую страницу. Может принимать значение null если следующая страница несуществует
  "previous" - Ссылка на предыдущую страницу. Может принимать значение null если предыдущая страница не существует.
  "results" - Список объектов на странице

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

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

Authentication

ApplicationToken

Security scheme type: API Key
Header parameter name: X-Joys-Applicatio-Token

TerminalKey

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

Service

Проверка состояния сервиса

Проверка состояния сервиса

Responses

200
get /service/health/

Joys API Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/service/health/

Response samples

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

Authentication

Управление токенами аутентификации POS

Запрос токена аутентификации POS

header Parameters
X-Joys-Application-Token
required
string

Application token

Request Body schema: application/json
terminal
required
uuid <uuid>

Идентификатор терминала точки продаж

Responses

201

Created

post /authentication/request/

Joys API Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/authentication/request/

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "terminal": "1fab9d30-6f27-4762-9c3e-832f6bbfeb5f"
}

Response samples

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

Получние информации о токене аутентификации POS.

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 Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/authentication/status/

Response samples

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

Отзыв токена аутентификации POS.

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 Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/authentication/revoke/

Refunds

Отмена оплаченных счетов.

Refunds list resource

query Parameters
not_before
integer

Date filter

not_after
integer

Date filter

session
string

Session 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 refunds

get /refunds/

Joys API Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/refunds/

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "count": 1,
  • "next": null,
  • "previous": null,
  • "results":
    [
    ]
}

Create refund

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

Request Body schema: application/json
external_id
string

Refund identifier in merchant system

amount
required
integer

Amount in minimal money/crypto units

charge
required
string <uuid>

Identifier of parent charge

currency
required
string (Currency) ^[A-Z]{3,3}$

Currency ISO code

description
string

An arbitrary string which you can attach to a Charge object. It is displayed when in the web interface alongside the charge. Note that if you use Joys to send automatic email receipts to your customers, your receipt emails will include the description of the charge(s) that they are describing. This will be unset if you POST an empty value.

reason
required
string
Enum:"duplicate" "fraudulent" "requested_by_customer"
metadata
object (Metadata)
session
string

POS Session number

Responses

200

Authorization details

post /refunds/

Joys API Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/refunds/

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "amount": 11100,
  • "currency": "RUB",
  • "charge": "charge/70e3e29e-d4e6-4d3a-b45c-2c01f06865d2",
  • "metadata":
    [
    ],
  • "reason": "requested_by_customer"
}

Response samples

Content type
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.",
  • "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 Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/refunds/{id}/

Response samples

Content type
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.",
  • "reason": "duplicate",
  • "receipt_number": "r-Zaegac1E/2018",
  • "status": "new",
  • "metadata":
    {
    },
  • "session": "string"
}

Void 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

Voided refund object

post /refunds/{id}/void/

Joys API Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/refunds/{id}/void/

Response samples

Content type
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.",
  • "reason": "duplicate",
  • "receipt_number": "r-Zaegac1E/2018",
  • "status": "new",
  • "metadata":
    {
    },
  • "session": "string"
}

Invoices

Выставление и оплата счетов

Create invoice

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

Request Body schema: application/json
amount
integer

Invoice sum in minimal money unit

tax
integer

The amount of tax included in the total, calculated from tax_percent and the subtotal. If no tax_percent is defined, this value will be null.

tax_percent
integer

This percentage of the subtotal has been added to the total amount of the invoice, including invoice line items and discounts. This field is inherited from the subscription’s tax_percent field, but can be changed before the invoice is paid. This field defaults to null.

subtotal
integer

Total of all subscriptions, invoice items, and prorations on the invoice before any discount is applied.

total
integer

Total after discount.

currency
required
string (Currency) ^[A-Z]{3,3}$

Currency ISO code

items
required
Array of objects (Item)
external_user_id
string

User id in external system

external_id
string

Unique identifier in external system

receipt_email
string <email>

The email address to which this charge’s receipt will be sent. The receipt will not be sent until the charge is paid, and no receipts will be sent for test mode charges. If this charge is for a customer, the email address specified here will override the customer’s email address

metadata
Array of objects (Metadata)

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

hosted_invoice_url
string

The URL for the hosted invoice page, which allows customers to view and pay an invoice. If the invoice has not been finalized yet, this will be null.

webhook_url
string
expired_at
integer

Responses

201

Invoice create response

post /invoices/

Joys API Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/invoices/

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "amount": 12800000,
  • "currency": "RUB",
  • "external_id": "r-Zaegac1E/2018",
  • "external_user_id": "c52addce-c4fe-4e05-b7ea-e0da02e57ab",
  • "hosted_invoice_url": null,
  • "receipt_email": "test@example.com",
  • "subtotal": 12800000,
  • "tax": 0,
  • "tax_percent": 0,
  • "total": 12800000,
  • "webhook_url": null,
  • "expired_at": null,
  • "items":
    [
    ],
  • "metadata":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "invoice/bdce4578-d07f-412c-a892-5bf74a119d3a",
  • "created_at": 1539746210,
  • "updated_at": 1539746210,
  • "paid_at": 1539746210,
  • "is_paid": true,
  • "expired_at": 1539746210,
  • "is_expired": false,
  • "canceled_at": 1539746210,
  • "is_canceled": false,
  • "amount": 13421,
  • "amount_paid": 13421,
  • "amount_remaining": 0,
  • "tax": 1180,
  • "tax_percent": 18,
  • "subtotal": 0,
  • "total": 0,
  • "application_fee": 1000,
  • "status": "new",
  • "currency": "RUB",
  • "charges":
    [
    ],
  • "items":
    [
    ],
  • "external_user_id": "c52addce-c4fe-4e05-b7ea-e0da02e57ab7",
  • "external_id": "r-Zaegac1E/2018",
  • "receipt_email": "user@example.com",
  • "metadata":
    [
    ],
  • "hosted_invoice_url": null,
  • "webhook_url": null,
  • "webhook_delivered_at": null,
  • "failure":
    {
    }
}

Retrive invoice data

path Parameters
id
required
string

Invoice uuid

header Parameters
X-Joys-Application-Token
required
string

Application token

X-Joys-Authorization
required
string

POS token

Responses

200

Get Invoice response

get /invoices/{id}/

Joys API Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/invoices/{id}/

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "invoice/bdce4578-d07f-412c-a892-5bf74a119d3a",
  • "created_at": 1539746210,
  • "updated_at": 1539746210,
  • "paid_at": 1539746210,
  • "is_paid": true,
  • "expired_at": 1539746210,
  • "is_expired": false,
  • "canceled_at": 1539746210,
  • "is_canceled": false,
  • "amount": 13421,
  • "amount_paid": 13421,
  • "amount_remaining": 0,
  • "tax": 1180,
  • "tax_percent": 18,
  • "subtotal": 0,
  • "total": 0,
  • "application_fee": 1000,
  • "status": "new",
  • "currency": "RUB",
  • "charges":
    [
    ],
  • "items":
    [
    ],
  • "external_user_id": "c52addce-c4fe-4e05-b7ea-e0da02e57ab7",
  • "external_id": "r-Zaegac1E/2018",
  • "receipt_email": "user@example.com",
  • "metadata":
    [
    ],
  • "hosted_invoice_url": null,
  • "webhook_url": null,
  • "webhook_delivered_at": null,
  • "failure":
    {
    }
}

Оплата счета

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

Request Body schema: application/json
source
required
string <string>

Строка идентифицирующая кошелек юзера. Интеграционные решения не должны строить ни каких предположений о формате строки. Данная строка берется из QR-кода и передается в данном параметре как есть.

session
string

Pos session numner.

description
string

Human readable discription visible to client.

Responses

200

Authorization details

post /invoices/{id}/capture/

Joys API Sandbox

https://digital-joys-api-testing.dinect.com/payment/v1/invoices/{id}/capture/

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "source": "wallet/b9a72871-597b-4c1a-a484-bea5c250db4f"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "invoice/bdce4578-d07f-412c-a892-5bf74a119d3a",
  • "created_at": 1539746210,
  • "updated_at": 1539746210,
  • "paid_at": 1539746210,
  • "is_paid": true,
  • "expired_at": 1539746210,
  • "is_expired": false,
  • "canceled_at": 1539746210,
  • "is_canceled": false,
  • "amount": 13421,
  • "amount_paid": 13421,
  • "amount_remaining": 0,
  • "tax": 1180,
  • "tax_percent": 18,
  • "subtotal": 0,
  • "total": 0,
  • "application_fee": 1000,
  • "status": "new",
  • "currency": "RUB",
  • "charges":
    [
    ],
  • "items":
    [
    ],
  • "external_user_id": "c52addce-c4fe-4e05-b7ea-e0da02e57ab7",
  • "external_id": "r-Zaegac1E/2018",
  • "receipt_email": "user@example.com",
  • "metadata":
    [
    ],
  • "hosted_invoice_url": null,
  • "webhook_url": null,
  • "webhook_delivered_at": null,
  • "failure":
    {