NAV
cURL

Introduction

The PaySuper API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

All API requests must be made over HTTPS.

Authentication

Authentication to the API occurs via Signature-based authentication. You must authenticate for all requests that contain a user data.

Add a Header X-API-SIGNATURE with the Project’s Secret key found on the Project webhooks page.

Errors

PaySuper uses conventional HTTP response codes to indicate 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 resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with PaySupers’s servers.

HTTP status codes summary:

200 OK - Everything worked as expected.

201 Created - Resource has been successfully created

202 Accepted - Request has been accepted, but requires asynchronous work to be fully performed

400 Bad Request - Request failed due to a combination of errors

401 Unauthorized - No valid API credentials provided.

402 Payment Required - Your request was in Live Mode while your account is not activated for Live requests yet.

403 Forbidden - You are not authorized to access the requested item.

404 Not Found - The requested item doesn’t exist.

406 Unacceptable - Your request format was not supported. Use JSON.

409 Conflict - The data you submitted is in conflict with existing data.

422 Unprocessable Entity - Often missing a required parameter.

429 Too Many Requests - You sent us too many API requests in a row. Please retry later.

500, 502, 503, 504 Server errors - Something went wrong on PaySupers’s end.

Versioning

PaySuper is developed incrementally. We use semantic versioning and approach to release new versions of the specification.

The content of each release is the result of the work of the project team located on GitHub. All changes and additions to each version of this specification are publicly discussed by the PaySuper working group.

While making requests in PaySuper using HTTPS, the version is passed as a special HTTP header, which makes it easier to choose the correct implementation of objects on the receiving and transmitting side. The version passed is specified as major and minor of the version using semantic versioning.

For the transmission version must use the header 'x-paysuper-api-version': '1.0'.

Compression

The amount of data transferred with notifications can be huge, and endpoints are required to support data compression to reduce the amount and speed of data transfer over the network.

Endpoints that send HTTP 1.1 messages are required to send gzip-compressed data by specifying the appropriate value in the HTTP Accept-Encoding header.

Receiving hosts are required to support gzip and respond to requests by passing an HTTP Content-Encoding header.

Pagination

Example request

$ curl https://api.pay.super.com/payouts?limit=3 \
   -u tkHCYYOUVrYyY5rBFZxNzgtt:

Example response

{
  "object": "list",
  "has_more": true,
  "has_before": false,
  "total_count": 240,
  "data": [
    {
      "id": "po_1ED765CmSJsu7cy1iQZUkPKz",
      "object": "payout",
      "type": "bank_account",  
      "status": "in_transit",
      "created_at": "2018-07-10T14:27:54.691Z",
      "arrival_date": "2018-07-10T14:27:54.691Z",
      "amount": "2.00",
      "currency": "USD",
      "payout_url": "https://pay.super.com/receipts/long-id-string-for-receipt",
      "automatic": true,
      "description": "PAYSUPER PAYOUT",
      "destination": "ba_1ED765CmSJsu7cy1ZufOeBtW",
      "failure_balance_transaction": null,
      "failure_code": null,
      "failure_message": null,
      "live": false,
      "metadata": {}
    },
    {...},
    {...}
  ]
}

All top-level PaySuper API resources have support for bulk fetches “list” API methods. For instance, you can list users, list orders. Like Stripe, PaySuper uses cursor-based pagination using the parameter starting_after. Pass starting_after parameter at the previous page last object id value to determine where to start in the list.

PARAMETER TYPE DESCRIPTION
limit integer A limit on the number of objects to be returned. Must be included between 1 and 100.
starting_after string A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
ending_before string A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

Response

PARAMETER TYPE DESCRIPTION
object string The string representing the object’s type. Value: list.
data array An array containing the actual response elements, paginated by any request parameters.
has_more boolean Whether or not there are more elements available after this page. If false, this page is the end of the list.
has_before boolean Whether or not there are more elements available before this page. If false, this page is the beginning of the list.
total_count boolean The total count of all recipients that match your filters, as if there was no pagination.

WEBHOOKS

The PaySuper system can send you notifications for a set of events during the flow, such as creating new accounts or transaction flow, making payouts, and so on.

These notifications are sent as webhooks to the corresponding URL configured on your Project Webhook page.

In most cases, webhooks are triggered by user actions on your website or by back-end related events like a successful payment, a refund payment and other.

The Webhook object examples:

For instance, this is the base object representing the webhook event payment.success:

{
  "id": "5d23426ab8b1eea163304202653796fa801081e739d506615ddac583019045f3",
  "type": "notification",
  "event": "payment.success",
  "live": false,
  "created_at": "2019-11-16T05:41:05Z",
  "expires_at": "",
  "delivery_try": 0,
  "object": {
    "id": "726d9e07-1dc8-4159-8d52-f95941066bc8",
    "transaction": "2978077",
    "object": "order",
    "status": "created",
    "description": "A summary for the purchase",
    "created_at": "2019-07-10T14:27:54.691Z",
    "canceled_at": "",
    "canceled": false,
    "cancellation": null,
    "refunded": false,
    "refunded_at": "",
    "receipt_email": "user.email@example.com",
    "receipt_phone": "",
    "receipt_number": "",
    "receipt_url": "https://dashboard.pay.super.com/receipt/purchase/efefc5d3-c2e2-4157-8789-4bfb7c1eec34/726d9e07-1dc8-4159-8d52-f95941066bc8",
    "agreement_version": "",
    "agreement_accepted": false,
    "notify_sale": false,
    "notify_sale_email": "",
    "issuer": {
      "url": "https://domain.com",
      "embedded": false,
      "reference": "",
      "reference_type": "",
      "utm_source": "",
      "utm_medium": "",
      "utm_campaign": "",
      "referrer_host": "domain.com"
    },
    "amount": 595,
    "currency": "RUB",
    "user": {
      "id": "5dcf8b24b5a6990001bac2b6",
      "object": "user",
      "external_id": "0000000000001",
      "name": "User Name",
      "email": "user.email@example.com",
      "email_verified": true,
      "phone": "9112223344",
      "phone_verified": true,
      "ip": "79.137.163.2",
      "locale": "ru-RU",
      "address": {
        "country": "RU",
        "city": "Moscow",
        "postal_code": "127221",
        "state": "MOW"
      },
      "metadata": {
        "user.param1": "user.val1",
        "user.param2": "user.val2",
        "user.param3": "user.val3"
      },
      "notify_new_region": false,
      "notify_new_region_email": ""
    },
    "billing_address": {
      "country": "DE"
    },
    "tax": {
      "type": "vat",
      "rate": 0.19,
      "amount": 95,
      "currency": "RUB"
    },
    "net_revenue" : {
        "amount": 10.12,
        "currency": "EUR"
    },
    "fee" : {
        "amount": 1.78,
        "currency": "EUR"
    },
    "method": {
      "title": "Bank card",
      "external_id": "BANKCARD",
      "payment_system_id": "5be2d0b4b0b30d0007383ce5",
      "saved": false,
      "card": {
        "first6": "400000",
        "last4": "0002",
        "masked": "400000...0002",
        "expiry_month": "11",
        "expiry_year": "2023",
        "brand": "VISA",
        "fingerprint": "$2a$04$9VRouYlBC.qMYQrLpmlXOeGbL2WFZDGGq/KdTeeHSfWkosgJgrWw2",
        "secure3d": true
      },
      "wallet": null,
      "crypto_currency": null,
      "refund_allowed": true
    },
    "items": null,
    "refund": null,
    "metadata": {
      "param1": "val1",
      "param2": "val2",
      "param3": "val3"
    },
    "original_amount": 500,
    "country": "DE",
    "type": "simple",
    "platform_id": "",
    "receipt_id": "efefc5d3-c2e2-4157-8789-4bfb7c1eec34",
    "virtual_currency_amount": 0,
    "is_buy_for_virtual_currency": false
  }
}

This example is the base object representing the webhook event user.validate:

{
  "id": "79bfd757-bb5a-4754-9d5c-5c7e131e7cf3",
  "type": "notification",
  "event": "user.validate",
  "live": false,
  "created_at": "2020-04-06T21:14:18Z",
  "expires_at": "",
  "delivery_try": 1,
  "object": {
    "id": "5e8b9baa8fba167a4a284572",
    "object": "user",
    "external_id": "bcbb8259-b65e-44bc-ba1d-2a150cc04338",
    "name": "User Name",
    "email": "user.email@example.com",
    "email_verified": true,
    "phone": "9112223344",
    "phone_verified": true,
    "ip": "79.137.163.2",
    "locale": "ru-RU",
    "address": {
        "country": "RU",
        "city": "Moscow",
        "postal_code": "127221",
        "state": "MOW"
    },
    "metadata": {
      "user.param1": "user.val1",
      "user.param2": "user.val2"
    },
    "notify_new_region": false,
    "notify_new_region_email": ""
  }
}

Setting up a webhook

1. Add the URL of the server that will receive the webhook requests in the Functional URL section on the Project Webhooks page.

2. Select the Webhooks mode:

Default is the asynchronous mode that provides webhook notifications only about a payment.

a. A customer initiates a payment request on your site via the PaySuper payment form.

b. If the payment is finished with a successful or failed result PaySuper sends a payment notification to your server.

Pre-approval is the mode that provides a synchronous notification for user validation and asynchronous notification about a payment.

a. A customer initiates a payment request on your site via the PaySuper payment form.

b. PaySuper sends the user validation request with the customer data to check the details of the user on the project side.

c. When the project server responds with success or failure, PaySuper continues or cancel the payment respectively for this customer.

d. If the payment is finished with a successful or failed result PaySuper sends a payment notification to your server.

3. Verify the webhook request.

4. Respond with HTTP code 200 without a message body to acknowledge the receipt a webhook notification.

Webhook event types

TYPE PAYLOAD DESCRIPTION
payment.success Order Sent when a customer successfully completes a payment.
payment.chargeback Order Sent when a payment must be cancelled for a chargeback.
payment.refund Order Sent when a payment must be cancelled for refund for any reasons.
payment.cancel Order Sent when a payment must be cancelled for cancel for any reasons.
user.validate User Sent when a customer initiates a payment. It’s applied for the pre-approval webhooks mode.

The Webhook object

PARAMETER TYPE DESCRIPTION
id string The unique identifier for the object.
type string The string representing the webhook’s type. Value: notification.
event string The string representing the event’s type.
live boolean Has a value true if notification originated from a live environment.
created_at DateTime The date and time in ISO 8601 when the event has been created.
expires_at DateTime The date and time in ISO 8601 when the event stops trying to deliver.
delivery_try integer The current delivery try for the event.
object Order The object representing the payload of the event with a given type. Objects of the same type share the same value.

Verifying a webhook

PaySuper signs webhook events that it sends to your endpoint allowing you to validate that they were not sent by a third-party and prevent any unauthorised actions.

The PaySuper API uses a Secret key to check the notification request.

All API requests must be made over HTTPS. Calls made over a plain HTTP will fail.

POST /your_endpoint HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Authorization: Signature sh9b1r69bjqie88n5uizqcrerhee50dypsp195mh

To check a digital signature:

1. Concatenate the request’s JSON body with your Project’s Secret key found on the Project webhooks page.

2. Apply SHA-256 hashing to the resulting string.

3. Compare the digital signature with Authorization HTTP Header value in the received notification.

CORE RESOURCES

Token

A token is an encrypted string that represents certain details of your customer (such as the customer ID, email and others), a game and purchase parameters.

Create a payment token

Code samples

curl -X POST \
  https://api.pay.super.com/api/v1/tokens \
  -H 'Content-Type: application/json' \
  -H 'X-API-SIGNATURE: YOUR_SECRET_KEY \
  -d '{
      "settings": {
          "project_id": "5dcd11bc218dc30001d7098f",
          "amount": 10,
          "currency": "USD",
          "type": "simple"
      },
      "user": {
          "id": "58799f2c2564296bd2cb",
          "address": {
            "city": "Almere",
            "country": "NL",
            "postal_code": "1326 PA",
            "state": "Flevoland"
          },
          "email": {
            "value": "user.email@example.com",
            "verified": true
          }
      }
}'

POST /api/v1/tokens

Create a payment token that encrypts details about your customer, the game and purchase parameters.

Body parameters

{
  "user": {
    "id": "string",
    "email": {
      "value": "string",
      "verified": true
    },
    "phone": {
      "value": "string",
      "verified": true
    },
    "name": {
      "value": "string"
    },
    "ip": {
      "value": "string"
    },
    "locale": {
      "value": "string"
    },
    "address": {
      "country": "string",
      "city": "string",
      "postal_code": "string",
      "state": "string"
    }
  },
  "settings": {
    "project_id": "string",
    "return_url": {
      "success": "string",
      "fail": "string"
    },
    "currency": "string",
    "amount": 0,
    "description": "string",
    "products_ids": [
      "string"
    ],
    "platform_id": "string",
    "type": "string",
    "is_buy_for_virtual_currency": true,
    "button_caption": "string",
    "metadata": {
      "parameter1": "value1"
    }
  }
}
PARAMETER TYPE DESCRIPTION
user object The customer data.
id * string The unique identifier for the customer in the merchant project.
email object The customer’s email data.
    value string The customer’s email address.
    verified boolean Whether the email has been verified on the merchant side.
phone object The customer’s phone data.
    value string The customer’s phone.
    verified boolean Whether the phone has been verified on the merchant side.
name object The customer’s name data.
    value string The customer’s name.
ip object The customer’s IP address data.
    value string The customer’s IP address.
locale object The customer’s locale data.
    value string The customer’s locale name. The Accept-Language format by RFC 7231.
address object The customer’s address data.
    country string The customer’s country. Two-letter country code in ISO 3166-1, in uppercase (for instance US).
    city string The customer’s city.
    postal_code string The customer’s postal code.
    state string The customer’s state code in ISO 3166-2.
settings object The project data.
    project_id * string The unique identifier for the Project found in the merchant account in the PaySuper Dashboard.
    return_url object The redirect URLs after the successful or failed payment.
      success string The redirect URL for a successful payment.
      fail string The redirect URL for a failed payment.
    currency string The order currency. Three-letter Currency Code ISO 4217, in uppercase. It’s required for a simple checkout payment.
    amount number The order amount. It’s required for a simple checkout payment.
    description string An arbitrary order description.
    products_ids [string] A list of unique identifiers for Project’s products. It’s required if a payment type equals to ‘product’ or ‘key’.
    platform_id string The default platform’s name for which the customer buys a key. This field is used only for the key type. Available values: steam, gog, uplay, origin, psn, xbox, nintendo, itch, egs.
    type * string The order type. It depends on your sales option: Game Keys, Virtual Items, Virtual Currency, Simple Checkout. Available values: key, product, virtual_currency, simple.
    is_buy_for_virtual_currency boolean Has a true value if an order must be processed using a virtual currency.
    button_caption string The redirect button messages after the successful or failed payment. If it has an empty value the redirect message will be set at OK.
    metadata object A string-value description that you can attach to the token object. It can be useful for storing additional information about your customer’s payment.

Responses

Example responses

200 Response

{
  "token": "string",
  "payment_form_url": "string"
}

200 Returns the payment token string and the PaySuper-hosted URL for a payment form

token string The secure string which contains encrypted information about your customer and sales option data.
payment_form_url string The PaySuper-hosted URL of a payment form.

400 Invalid request data

code string The error code.
message string The error short description.
details string The error details.

404 Not found

code string The error code.
message string The error short description.
details string The error details.

500 Internal Server Error

code string The error code.
message string The error short description.
details string The error details.

Transactions

Get the transactions list

GET /merchant/s2s/api/v1/order

Get the transactions list using filter parameters.

Use the basic HTTP authentication with the Base64 encoding of login and password joined by a single colon : , where login - the unique identifier for your PaySuper project, password - the Secret Key of that project.

Request Header:

Authorization: Basic NWU1OGVjMGZiZTUzZWE0Yzk5NmNhMDVkOlZOaGMuazw4KXpaQVB7YT==

Request parameters to filter transactions:

PARAMETER TYPE DESCRIPTION
id string The unique identifier in PaySuper.
project string[] The project list to get its transactions. If this parameter is not set, the search is performed for all projects.
status string[] The transactions’ statuses list. Available values: created, processed, canceled, rejected, refunded, chargeback, pending.
account string The unique identifier in the merchant project.
project_date_from string The period start date. Format: YYYY-MM-DDThh:ii:ss
project_date_from string The period end date. Format: YYYY-MM-DDThh:ii:ss
invoice_id string The unique identifier in the merchant project.
limit integer The number of objects returned in one page. Default value is 100.
offset integer The ranking number of the first item on the page.

Responses

Example responses

200 Response

{
  "count": 1,
  "items": [
    {
      "id": "5b25b60e-2561-468c-a326-cbb9e21d0fc5",
      "transaction": "376271699",
      "object": "order",
      "status": "processed",
      "description": "Payment by order # ffffffffffffffffffffffff",
      "canceled": false,
      "cancellation": null,
      "refunded": false,
      "receipt_email": "tets@example.com",
      "receipt_phone": "",
      "receipt_number": "",
      "receipt_url": "https://checkout.pay.super.com/pay/receipt/purchase/6aa62191-2f44-4c1d-814c-d47fbcf56e3a/5b25b60e-2561-468c-a326-cbb9e21d0fc5",
      "agreement_version": "",
      "agreement_accepted": false,
      "notify_sale": false,
      "notify_sale_email": "",
      "issuer": {
        "url": "https://checkout.pay.super.com/pay/order/5b25b60e-2561-468c-a326-cbb9e21d0fc5",
        "embedded": false,
        "reference": "",
        "reference_type": "",
        "utm_source": "",
        "utm_medium": "",
        "utm_campaign": "",
        "referrer_host": "checkout.pay.super.com"
      },
      "amount": 100,
      "currency": "RUB",
      "user": {
        "external_id": "test@example.com",
        "name": "",
        "email": "test@example.com",
        "email_verified": true,
        "phone": "",
        "phone_verified": false,
        "ip": "127.0.0.1",
        "locale": "ru-RU",
        "address": {
          "country": "UA",
          "city": "Alexandrovsk",
          "postal_code": "71610",
          "state": "23"
        },
        "metadata": null
      },
      "billing_address": null,
      "tax": {
        "type": "vat",
        "rate": 0,
        "amount": 0,
        "currency": "RUB"
      },
      "method": {
        "title": "Bank card",
        "external_id": "BANKCARD",
        "payment_system_id": "5be2d0b4b0b30d0007383gg7",
        "type": "BANKCARD",
        "saved": false,
        "card": {
          "first6": "400000",
          "last4": "0001",
          "masked": "400000...0001",
          "expiry_month": "06",
          "expiry_year": "2024",
          "brand": "MASTERCARD",
          "fingerprint": "$2a$04$vdhmWzMxN0tR/21jaGtkaOCvYVnk88P6ZGWbKLL9K5TqgsVgv8HGT",
          "secure3d": true
        },
        "wallet": null,
        "crypto_currency": null,
        "handler": "cardpay",
        "refund_allowed": true
      },
      "items": null,
      "refund": null,
      "metadata": {
        "invoiceId": "2697661"
      },
      "original_amount": 100,
      "country": "UA",
      "type": "simple",
      "platform_id": "",
      "receipt_id": "6aa62191-2f44-4c1d-814c-d47fbcf56e3a",
      "virtual_currency_amount": 0,
      "is_buy_for_virtual_currency": false,
      "charge_currency": "RUB",
      "charge_amount": 100,
      "vat_payer": "buyer",
      "is_production": true,
      "testing_case": "",
      "form_mode": "embed",
      "merchant_info": {
        "company_name": "Some Company LLC",
        "agreement_number": "0102-1234567"
      },
      "created_at": "2020-08-06T10:51:33.157Z",
      "canceled_at": "0001-01-01T00:00:00Z",
      "refunded_at": "0001-01-01T00:00:00Z"
    }
  ]
}

200 Returns the transactions list of projects

count integer The total number of found items.
items object[] or null The transactions list.

400 Invalid request data

code string The error code.
message string The error short description.
details string The error details.

500 Internal Server Error

code string The error code.
message string The error short description.
details string The error details.

ORDERS

Order

You can create a payment order with details about your customer and sales option data.

Statuses

Name Description
created It’s an initial state of the requested order but it is not processed in a payment system yet. The created order can become one of the statuses: processed, canceled, rejected.
processed The order is successfully processed in the payment system. The processed order can become refunded or chargeback.
rejected The order is rejected by the payment system with any reasons.
canceled The order is canceled by the customer.
refunded The processed order is refunded by the merchant request.
chargeback The processed order is refunded by the payment system with any reasons.

The Order object example:

{
  "id": "726d9e07-1dc8-4159-8d52-f95941066bc8",
  "transaction": "2978077",
  "object": "order",
  "status": "created",
  "description": "A summary for the purchase",
  "created_at": "2019-07-10T14:27:54.691Z",
  "canceled": false,
  "canceled_at": "",
  "cancellation": null,
  "refunded": false,
  "refunded_at": "",
  "receipt_email": "user.email@example.com",
  "receipt_phone": "",
  "receipt_number": "",
  "receipt_url": "https://dashboard.pay.super.com/receipt/purchase/efefc5d3-c2e2-415",
  "agreement_version": "",
  "agreement_accepted": false,
  "notify_sale": false,
  "notify_sale_email": "",
  "issuer": {
      "url": "https://domain.com",
      "embedded": false,
      "reference": "",
      "reference_type": "",
      "utm_source": "",
      "utm_medium": "",
      "utm_campaign": "",
      "referrer_host": "domain.com"
  },
  "amount": 595,
  "currency": "RUB",
  "user": {
      "id": "5dcf8b24b5a6990001bac2b6",
      "object": "user",
      "external_id": "0000000000001",
      "name": "User Name",
      "email": "user.email@example.com",
      "email_verified": true,
      "phone": "9112223344",
      "phone_verified": true,
      "ip": "79.137.163.2",
      "locale": "ru-RU",
      "address": {
        "country": "RU",
        "city": "Moscow",
        "postal_code": "127221",
        "state": "MOW"
      },
      "metadata": {
        "user.param1": "user.val1",
        "user.param2": "user.val2",
        "user.param3": "user.val3"
      },
      "notify_new_region": false,
      "notify_new_region_email": ""
  },
  "billing_address": {
      "country": "DE"
  },
  "tax": {
      "type": "vat",
      "rate": 0.19,
      "amount": 95,
      "currency": "RUB"
  },
  "method": {
      "title": "Bank card",
      "external_id": "BANKCARD",
      "payment_system_id": "5be2d0b4b0b30d0007383ce5",
      "saved": false,
      "card": {
        "first6": "400000",
        "last4": "0002",
        "masked": "400000...0002",
        "expiry_month": "11",
        "expiry_year": "2023",
        "brand": "VISA",
        "fingerprint": "$2a$04$9VRouYlBC.qMYQrLpmlXOeGbL2WFZDGGq/KdTeeHSfWkosgJgrWw2",
        "secure3d": true
      },
      "wallet": null,
      "crypto_currency": null,
      "refund_allowed": true
  },
  "items": null,
  "refund": null,
  "metadata": {
      "param1": "val1",
      "param2": "val2",
      "param3": "val3"
  },
  "original_amount": 500,
  "country": "DE",
  "type": "simple",
  "platform_id": "",
  "receipt_id": "efefc5d3-c2e2-4157-8789-4bfb7c1eec34",
  "virtual_currency_amount": 0,
  "is_buy_for_virtual_currency": false
}

The Order object:

Attribute Type Description
id string The unique identifier for the order in PaySuper.
transaction string The unique identifier for the transaction in the issuer system (the bank, QIWI, PayPal, etc.)
object string The string representing the object’s type. Value: order.
status string The current status of the order.
description string An arbitrary string attached to the object. If this field was not sent, the PaySuper generates it automatically.
created_at string The date and time in ISO 8601 at which the order was created.
canceled_at string The date and time in ISO 8601 at which the order was cancelled.
canceled boolean Has the value true if the current order was canceled.
cancellation object The cancellation reason. Has the value null if the order is not canceled.
  code string The cancellation reason code.
  reason string The cancellation description.
refunded boolean Has the value true if the current order was refunded.
refunded_at string The date and time in ISO 8601 at which the order was refunded.
receipt_email string The customer’s email for receipt information.
receipt_phone string The customer’s phone for receipt information.
receipt_number string The unique identifier for a receipt. Has a non-empty value if the order has refunded status.
receipt_url string The URL in PaySuper service for online access to the receipt.
agreement_version string The EULA agreement accepted by payment.
agreement_accepted boolean Has the value true if the agreement was accepted.
notify_sale boolean Has the value true if the customer confirmed to be informed about sales or discounts.
notify_sale_email string The customer’s email for sales or discounts.
issuer object Details about an issuer.
  url string The referer URL.
  embedded boolean Has the value true if the PaySuper form was embedded to collect payment.
  reference string The unique identifier for the entity linked to the order, for instance paylink ID.
  reference_type string The type of an entity linked to the order, for instance paylink.
  utm_source string The UTM-tag of the advertising system, for example: Bing Ads, Google Adwords.
  utm_medium string The UTM-tag of the traffic type, e.g.: cpc, cpm, email newsletter.
  utm_campaign string The UTM-tag of the advertising campaign, for example: Online games, Simulation game.
  referrer_host string The host of the referrer URL.
amount float The total amount for the order. A positive float with two decimal points (e.g., 1.00 to charge $1.00).
currency string The currency for the order. Three-letter Currency Code ISO 4217, in uppercase.
user object Details about a customer.
  id string The customer unique identifier on the PaySuper side.
  object string The string representing the object’s type. Value: user.
  external_id string The customer unique identifier in the merchant project.
  name string The customer’s name.
  email string The customer’s email.
  email_verified boolean Whether the customer’s email address has been verified in the merchant project.
  phone string The customer’s phone number.
  phone_verified boolean Whether the customer’s phone number has been verified in the merchant project.
  ip string The customer’s IP address.
  locale string The customer’s locale name. Four-letter language code in ISO 639, for instance en-US.
  address object Details about a customer’s address.
    country string The customer’s country. Two-letter country code in ISO 3166-1, in uppercase.
    city string The customer’s city.
    postal_code string The customer’s postal code.
    state string The customer’s state code in ISO 3166-2.
  metadata object A string-value description that you can attach to the customer object. It can be useful for storing additional information about your customer’s payment.
  notify_new_region boolean Has the value true if the customer confirmed to receive the PaySuper newsletter about the beginning of payment acceptance in new regions.
  notify_new_region_email string The customer’s email for a newsletter about the beginning of payment acceptance in new regions.
billing_address object Details about a customer’s billing address. Has a non-empty value if the customer was asked to fill it on a payment form. For all countries has a country value and for the USA has country, state and zip.
  country string The customer’s country. Two-letter country code in ISO 3166-1, in uppercase.
tax object Details about a tax.
  type string The tax type (Sales tax for USA, VAT for EU and Russia).
  rate float The current customer’s location taxes. A positive float with two decimal points.
  amount float The tax amount. A positive float with two decimal points (e.g., 1.00 to charge $1.00).
  currency string The currency for the tax. Three-letter Currency Code ISO 4217, in uppercase.
net_revenue object Details about the amount and currency of the transaction in the currency of payment to the client.
  amount float The net revenue amount. A positive float with two decimal points (e.g., 1.00 to charge $1.00).
  currency string The currency for net revenue. Three-letter Currency Code ISO 4217, in uppercase.
fee object Details about PaySuper’s commission for a transaction in the currency of payment to the client.
  amount float The fee amount. A positive float with two decimal points (e.g., 1.00 to charge $1.00).
  currency string The currency for the fee. Three-letter Currency Code ISO 4217, in uppercase.
method object Details about a payment method.
  title string The human readable method name.
  external_id string The unique identifier for the payment method.
  payment_system_id string The unique identifier for the payment system on the PaySuper side.
  saved boolean Has a value true if the payment method was saved by the customer for future usage.
  card object Details about a customer’s card.
    first6 string The first 6 digits of the card. Available only for a card method.
    last4 string The last 4 digits of the card. Available only for a card method.
    masked string The mask for a customer’s card. Available only for a card method.
    expiry_month string The validity month of the card. Available only for a card method.
    expiry_year string The validity year of the card. Available only for a card method.
    brand string The brand of the card issuer. Available only for a card method.
    fingerprint string The internal fingerprint for given card. Available only for a card method.
    secure3d string Has a value true if 3D-secure was used during payment. Available only for a card method.
  wallet object The name of the wallet. Available only for an integrated wallet payment systems.
    brand string The name of the wallet.
    account string The customer identity in the wallet.
  crypto_currency object The name of the crypto currency. Available only for a crypto currency.
    brand string The name of the crypto currency.
    address string The customer’s address in the crypto currency.
  refund_allowed boolean Has a value true if a refund is allowed.
items object[] An array of OrderItem objects associated with current Order.
  id string The unique identifier for the object.
  sku string The stock keeping unit.
  name string A localized name of the object.
  description string A localized description of the object.
  images string[] Image urls associated with the object.
  metadata object A string-value description that attached to an object on creating a product.
  code string An activation code of the object. Can be ommited if the order is not processed or type of the order does not equal key.
  platform string A platform for an activation code. Can be ommited if the order is not processed or type of the order does not equal key.
refund object Details about a refund.
  amount float The refund amount. A positive float with two decimal points (e.g., 1.00 to charge $1.00).
  currency string The currency for the tax. Three-letter Currency Code ISO 4217, in uppercase.
  reason string The refund reason.
  code string The PaySuper internal identity for the refund reason.
  receipt_number string The unique identifier for the refund receipt.
  receipt_url string The URL in PaySuper service for online access to given refund receipt.
metadata object A string-value description that you can attach to the order object. It can be useful for storing additional information about your customer payment.
original_amount float The order amount excluding any taxes and commissions.
country string Two-letter country code in ISO 3166-1, in uppercase.
type string The order type. It depends on your sales option (Game Keys, Virtual Items, the simple checkout). For products created as Game Keys use the key type, as Virtual Items - the product type, for a simple checkout - the simple type. Enum values: key, products, simple.
platform_id string The default platform identifier for which customer buys the in-game key. This field used only for a payment type key. Enum values: steam, gog, uplay, origin, psn, xbox, nintendo, itch, egs.
receipt_id string The receipt unique identifier.
virtual_currency_amount float The virtual currancy amount for the order.
is_buy_for_virtual_currency boolean Has a value true if the order created for a virtual currency.

Create a payment order

Code samples

curl -X POST \
  https://checkout.pay.super.com/api/v1/order \
  -H 'Content-Type: application/json' \
  -H 'X-API-SIGNATURE: YOUR_SECRET_KEY \
  -d '{
    "project": "5db16ae811bf0d0001fdfbd1",
    "amount": 10,
    "currency": "USD",
    "type": "simple",
  "user": {
      "external_id": "58799f2c2564296bd2cb",
      "email": "user.email@example.com",
      "email_verified": true
    }
}'

POST /api/v1/order

Create a payment order with a customer and order data

Body parameters

{
  "project": "string",
  "amount": 0,
  "currency": "string",
  "account": "string",
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "url_success": "string",
  "url_fail": "string",
  "products": [
    "string"
  ],
  "token": "string",
  "user": {
    "external_id": "string",
    "name": "string",
    "email": "string",
    "email_verified": true,
    "phone": "string",
    "phone_verified": true,
    "ip": "string",
    "locale": "string",
    "address": {
      "country": "string",
      "city": "string",
      "postal_code": "string",
      "state": "string"
    }
  },
  "order": "string",
  "type": "string",
  "platform_id": "string"
}
PARAMETER TYPE DESCRIPTION
project * string The ID of the Project found in your merchant account in the PaySuper Dashboard.
amount number The order amount as a positive number. It is required for a simple checkout payment.
currency string The currency of the order. Three-letter Currency Code ISO 4217, in uppercase. If provided, the amount will be processed in this currency. It is required for a payment when the type equals to simple.
account string The customer account in the merchant project.
description string The arbitrary order description.
metadata object A string-value description that you can attach to the order object. It can be useful for storing additional information about your customer’s payment.
url_success string The redirect URL for the successful payment. You need to enable the dynamic notify URLs option in the Project Settings to use this field.
url_fail string The redirect URL for the failed payment. You need to enable the dynamic notify URLs option in the Project Settings to use this field.
products [string] The list of unique identifiers of Products being in the Project. It is required if a payment type is equal to product or key.
token string An encrypted string that represents certain details of your customer (such as the customer ID, email and others), a game and purchase parameters. The token overrides the corresponding parameters (including required parameters) in an order object.
user object The customer data.
external_id string The unique identifier for the customer in the merchant project.
name string The customer’s name.
email string The customer’s email address.
email_verified boolean Whether the customer’s email address has been verified on the merchant side.
phone string The customer’s phone number.
phone_verified boolean Whether the customer’s phone number has been verified on the merchant side.
ip string The customer’s IP address.
locale string The customer’s locale name. The language code in ISO 639-1 (for instance en-US).
address object The customer’s address data.
    country string The customer’s country. Two-letter country code in ISO 3166-1, in uppercase (for instance US).
    city string The customer’s city.
    postal_code string The customer’s postal code.
    state string The customer’s state code in ISO 3166-2.
order string The PaySuper unique identifier for the order.
type * string The order type. It depends on your sales option (Game Keys, Virtual Items, Virtual Currency the simple checkout). For products created as Game Keys use the key type, as Virtual Items - the product type, as Virtual Currency - the virtual_currency type, for a simple checkout - the simple type. Enum values: key, product, virtual_currency, simple.
platform_id string The default platform’s name for which the customer buys a key. This field is used only for the key type. Enum values: steam, gog, uplay, origin, psn, xbox, nintendo, itch, egs.

Responses

Example responses

200 Response

{
  "id": "string",
  "payment_form_url": "string"
}

200 Returns the order ID and payment form URL

id string The unique identifier for the order.
payment_form_url string The URL of the PaySuper-hosted payment form.

400 The error code and message with the error details

code string The error code.
message string The error short description.
details string The error details.

500 Internal Server Error

code string The error code.
message string The error short description.
details string The error details.