Joys payment API (0.0.1)

Download OpenAPI specification:Download

Introduction

The Joys API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

Authentication

Authenticate your account by including your secret key (X-Joys-Authorization) in API requests. You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via headers X-Joys-Application-Key and X-Joys-Authorization.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

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

Errors

Joys uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Joys servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a wallet is declined) include an error code that briefly explains the error reported.

Attributes

|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

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a charge fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single charge is created.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Keys expire after 24 hours, so a new request is generated if a key is reused outside of that time frame.

To perform an idempotent request, provide an additional X-Joys-Idempotent-Key: <key> header to the request.

Joys idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result. The idempotency layer compares incoming parameters to those of the original request and error unless they're the same to prevent accidental misuse. The exception to these rules is that results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution.

GET and DELETE requests are idempotent by definition, meaning that the same backend work occurs no matter how many times the same request is issued. You shouldn't send an idempotency key with these verbs because it has no effect.

Rate Limiting

The returned HTTP headers of any API request show your current rate limit status:

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 The maximum number of requests you're permitted to make per hour.
X-Rate-Limit-Remaining The number of requests remaining in the current rate limit window.
X-Rate-Limit-Reset The time at which the current rate limit window resets in UTC epoch second

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

Updateable Joys objects — including Charge, Refund, Item, Customer have a metadata parameter. You can use this parameter to attach key-value data to these Joys objects.

Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on a Joys Customer object. Metadata is not used by Joys — for example, not used to authorize or decline a charge—and won't be seen by your users unless you choose to show it to them.

Some of the objects listed above also support a description parameter. You can use the description parameter to annotate a charge—with, for example, a human-readable description like 2 shirts for test@example.com. Unlike metadata, description is a single string, and your users may see it (e.g., in email receipts Stripe sends on your behalf).

Do not store any sensitive information (personally identifiable information, card details, etc.) as metadata or in the description parameter.

Note: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can get list charges and list refunds (TODO). These list API methods share a common structure, taking page parameter. Joys utilizes page-based pagination via the 'page' request query parameter. It's page number in list of objects arranged in chronological order. Page size is 20 and wont change in current version of api.

You get following structure in response on your requests:

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

Where is:

  "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

if you specify page number that does not exist, you will receive next response:

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

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