NAV Navbar
shell ruby
  • Introduction
  • Authentication
  • Pagination
  • Orders
  • Products
  • Product Groups
  • Selly Pay
  • Webhooks
  • Errors
  • Introduction

    Welcome to the Selly API. You can use our API to access Selly API endpoints to build your own systems on top of our platform.

    We have official API wrappers in Shell, Ruby. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    Authentication

    To authorize, use this code:

    curl "https://selly.gg/api/"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    
    require 'selly'
    
    # This library will automatically handle the Authorization header and encoding it
    Selly.api_key = 'your api key'
    Selly.api_email = 'your account email'
    

    Make sure to use the correct API authentication attributes

    Selly uses API keys via the Authorization header to allow access to the API. You can retrieve and receive a new Selly API key at your settings page.

    The Authorization header is made up of your account's email and API key in the format email:api_key and then encoded via base64.

    Selly expects a valid Authorization header to be included in all requests and that it looks like the following:

    Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk=

    In this example, if we decode the string we'll receive youremail:thisisyourAPIKey which when split would mean that the email provided is youremail and the API key is thisisyourAPIKey.

    Pagination

    An example of paginating orders:

    curl "https://selly.gg/api/orders?page=10"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    
    Selly::Orders::List(page: 10)
    

    Selly offers the ability to paginate any list or index resource. The X-Total-Pages header returns teh total number of pages for the resources at the specific endpoint you're using.

    Query Parameters

    Parameter Default Description
    page 1 Used for pagination

    Orders

    Order Object

    {
        "id": "fd87d909-fbfc-466c-964a-5478d5bc066a",
        "product_id": "upgrade",
        "email": "alishia@yahoo.com",
        "ip_address": "88.96.129.5",
        "country_code": "US",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36",
        "value": "0.03",
        "currency": "USD",
        "gateway": "Bitcoin",
        "risk_level": 10,
        "status": 100,
        "delivered": "SERIAL-12345-12345",
        "crypto_value": null,
        "crypto_address": null,
        "referral": null,
        "usd_value": "0.03",
        "exchange_rate": "1.0",
        "custom": {
          "0": "SomeInput"
        },
        "created_at": "2016-11-27T14:20:34.000Z",
        "updated_at": "2016-12-05T21:31:15.000Z"
      }
    

    Attributes

    Get All Orders

    Selly::Orders.list
    
    curl "https://selly.gg/api/orders"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    [
        {
        "id": "89ac7499-efc3-4f5b-a2fd-c00fec6aa480",
        "product_id": "ac24a3",
        "email": "john@gmail.com",
        "ip_address": "132.26.9.4",
        "country_code": "US",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2357.124 Safari/537.36",
        "value": "0.03",
        "currency": "USD",
        "gateway": "Bitcoin",
        "risk_level": 9,
        "status": 0,
        "delivered": null,
        "crypto_value": null,
        "crypto_address": null,
        "referral": null,
        "usd_value": "0.03",
        "exchange_rate": "1.0",
        "custom": {
          "0": "MyUsername"
        },
        "created_at": "2015-06-11T18:32:01.000Z",
        "updated_at": "2017-02-14T17:47:27.000Z"
      },
      {
        "id": "fd87d909-fbfc-466c-964a-5478d5bc066a",
        "product_id": "upgrade",
        "email": "alishia@yahoo.com",
        "ip_address": "88.96.129.5",
        "country_code": "US",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36",
        "value": "0.03",
        "currency": "USD",
        "gateway": "Bitcoin",
        "risk_level": 10,
        "status": 100,
        "delivered": "SERIAL-12345-12345",
        "crypto_value": null,
        "crypto_address": null,
        "referral": null,
        "usd_value": "0.03",
        "exchange_rate": "1.0",
        "custom": {
          "0": "SomeInput"
        },
        "created_at": "2016-11-27T14:20:34.000Z",
        "updated_at": "2016-12-05T21:31:15.000Z"
      }
    ]
    

    This endpoint retrieves all orders.

    HTTP Request

    GET https://selly.gg/api/orders

    Query Parameters

    Parameter Default Description
    page 1 Used for pagination

    Get a Specific Order

    Selly::Orders.get('fd87d909-fbfc-466c-964a-5478d5bc066a')
    
    curl "https://selly.gg/api/orders/fd87d909-fbfc-466c-964a-5478d5bc066a"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    {
        "id": "fd87d909-fbfc-466c-964a-5478d5bc066a",
        "product_id": "upgrade",
        "email": "alishia@yahoo.com",
        "ip_address": "88.96.129.5",
        "country_code": "US",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36",
        "value": "0.03",
        "currency": "USD",
        "gateway": "Bitcoin",
        "risk_level": 10,
        "status": 100,
        "delivered": "SERIAL-12345-12345",
        "crypto_value": null,
        "crypto_address": null,
        "referral": null,
        "usd_value": "0.03",
        "exchange_rate": "1.0",
        "custom": {
          "0": "SomeInput"
        },
        "created_at": "2016-11-27T14:20:34.000Z",
        "updated_at": "2016-12-05T21:31:15.000Z"
      }
    

    This endpoint retrieves a specific order.

    HTTP Request

    GET https://selly.gg/api/orders/:ID

    URL Parameters

    Parameter Description
    ID The ID of the order to retrieve

    Products

    Product Object

    {
        "id": "ac24a3",
        "title": "Awesome Product",
        "description": "My description",
        "stock": 2094,
        "price": "0.5",
        "currency": "EUR",
        "product_type": 2,
        "bitcoin": true,
        "paypal": true,
        "stripe": true,
        "litecoin": true,
        "dash": true,
        "ethereum": true,
        "perfect_money": true,
        "private": false,
        "unlisted": true,
        "seller_note": "Thanks for buying my product",
        "maximum_quantity": null,
        "minimum_quantity": 1,
        "custom": {},
        "created_at": "2016-05-15T14:02:47.000Z",
        "updated_at": "2017-08-12T23:37:13.000Z"
    }
    

    Attributes

    Get All Products

    Selly::Products.list
    
    curl "https://selly.gg/api/products"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    [
        {
            "id": "ac24a3",
            "title": "Awesome Product",
            "description": "My description",
            "stock": 2094,
            "price": "0.5",
            "currency": "EUR",
            "product_type": 2,
            "bitcoin": true,
            "paypal": true,
            "stripe": true,
            "litecoin": true,
            "dash": true,
            "ethereum": true,
            "perfect_money": true,
            "private": false,
            "unlisted": true,
            "seller_note": "Thanks for buying my product",
            "maximum_quantity": null,
            "minimum_quantity": 1,
            "custom": {},
            "created_at": "2016-05-15T14:02:47.000Z",
            "updated_at": "2017-08-12T23:37:13.000Z"
        },
        {
            "id": "d8b3cdb7",
            "title": "Dynamic E-book",
            "description": "Testing the description",
            "stock": "∞",
            "price": "1.0",
            "currency": "USD",
            "product_type": 3,
            "bitcoin": true,
            "paypal": true,
            "stripe": true,
            "litecoin": false,
            "dash": false,
            "ethereum": false,
            "perfect_money": false,
            "private": true,
            "unlisted": true,
            "seller_note": "",
            "maximum_quantity": null,
            "minimum_quantity": 1,
            "custom": {},
            "created_at": "2017-03-25T20:12:20.000Z",
            "updated_at": "2017-03-25T20:14:14.000Z"
        }
    
    ]
    

    This endpoint retrieves all products.

    HTTP Request

    GET https://selly.gg/api/products

    Query Parameters

    Parameter Default Description
    page 1 Used for pagination

    Get a Specific Product

    Selly::Products.get('ac24a3')
    
    curl "https://selly.gg/api/products/ac24a3"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    {
        "id": "ac24a3",
        "title": "Awesome Product",
        "description": "My description",
        "stock": 2094,
        "price": "0.5",
        "currency": "EUR",
        "product_type": 2,
        "bitcoin": true,
        "paypal": true,
        "stripe": true,
        "litecoin": true,
        "dash": true,
        "ethereum": true,
        "perfect_money": true,
        "private": false,
        "unlisted": true,
        "seller_note": "Thanks for buying my product",
        "maximum_quantity": null,
        "minimum_quantity": 1,
        "custom": {},
        "created_at": "2016-05-15T14:02:47.000Z",
        "updated_at": "2017-08-12T23:37:13.000Z"
    }
    

    This endpoint retrieves a specific product.

    HTTP Request

    GET https://selly.gg/api/products/:ID

    URL Parameters

    Parameter Description
    ID The ID of the product to retrieve

    Dynamic Products

    The Dynamic product type is a product type that is fetched externally. Selly will send a Webhook to the dynamic_url and will set the delivered_info of the Order to be the plain text response truncated to 500 characters.

    A common use case of a dynamic product would be license generation or any product that must be generated.

    Product Groups

    Product Group Object

    {
        "id": "ba6a15",
        "title": "Awesome Product Group",
        "product_ids": ["ac24a3"],
        "created_at": "2016-05-15T14:02:47.000Z",
        "updated_at": "2017-08-12T23:37:13.000Z"
    }
    

    Attributes

    Get All Product Groups

    Selly::ProductGroups.list
    
    curl "https://selly.gg/api/product_groups"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    [
        {
            "id": "ba6a15",
            "title": "Awesome Product Group",
            "product_ids": ["ac24a3"],
            "created_at": "2016-05-15T14:02:47.000Z",
            "updated_at": "2017-08-12T23:37:13.000Z"
        },
        {
           "id": "12abc3e",
           "title": "Another Product Group",
           "product_ids": ["ac24a3", "32156a"],
           "created_at": "2016-05-15T14:02:47.000Z",
           "updated_at": "2017-08-12T23:37:13.000Z"
        }
    ]
    

    This endpoint retrieves all product groups.

    HTTP Request

    GET https://selly.gg/api/product_groups

    Query Parameters

    Parameter Default Description
    page 1 Used for pagination

    Get a Specific Product Group

    Selly::ProductGroups.get('ba6a15')
    
    curl "https://selly.gg/api/product_groups/ba6a15"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    {
        "id": "ba6a15",
        "title": "Awesome Product Group",
        "product_ids": ["ac24a3"],
        "created_at": "2016-05-15T14:02:47.000Z",
        "updated_at": "2017-08-12T23:37:13.000Z"
    }
    

    This endpoint retrieves a specific product group.

    HTTP Request

    GET https://selly.gg/api/product_groups/:ID

    URL Parameters

    Parameter Description
    ID The ID of the product group to retrieve

    Selly Pay

    Selly Pay provides a method of implementing a realtime checkout experience for any e-commerce platform and supporting a range of payment methods in one place.

    With Selly Pay there is no Product that the order bases some information off, which allows for complete access to our payment systems without having to create a unique Product for every alteration a Payment may have. This also means that Selly does not handle any delivery of the "product" purchased, we'll only send a Webhook.

    For the gateway chosen in the Payment, you must have the correct information (e.g your Bitcoin address if the gateway is Bitcoin) set in your settings.

    For each Payment a unique URL will be returned. The customer will have to be redirected to this URL in order to access the checkout page.

    Create a Payment

    curl -X POST "https://selly.gg/api/pay"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
      -d '{"title:"Selly Pay Example", "gateway":"Bitcoin", "email":"customer@email.com", "value":"10", "currency":"USD", "return_url":"https://website.com/return", "webhook_url":"https://website.com/webhook?secret=cEZMeEVlTz"}'
    
    Selly::Pay::Create(
      title: 'Selly Pay Example',
      gateway: 'Bitcoin',
      email: 'customer@email.com',
      value: 10.00,
      currency: 'USD',
      return_url: 'https://website.com/return',
      webhook_url: 'https://website.com/webhook?secret=cEZMeEVlTz'
    )
    

    The above command returns JSON structured like this:

    {
        "url": "https://selly.gg/payments/a78b04cf0272a193baca53416db510b84feae099/OTZ6di92LytKcnRmY0pmVTdEV0h3S3BUM1Fnb0ZURFp6cytOUEhWcEZMeEVlTzBjZHFzZFVlRGxabmZvWUtSR2kybHhyc0FHeHdUaHhwOWEzN3A1eFE9PS0tRXhHdk5SWU5TM2NWQWlhZzAwc3FqQT09--acf55a4be40ad6336f9ce7f9fbc063785851720e"
    }
    

    The customer should be redirected to this URL to activate the checkout experience

    Attributes

    Webhooks

    A example webhook notification on a paid order event

    {
        "id": "fd87d909-fbfc-466c-964a-5478d5bc066a",
        "product_id": "upgrade",
        "email": "alishia@yahoo.com",
        "ip_address": "88.96.129.5",
        "country_code": "US",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36",
        "value": "0.03",
        "currency": "USD",
        "gateway": "Bitcoin",
        "risk_level": 10,
        "status": 100,
        "delivered": "SERIAL-12345-12345",
        "crypto_value": null,
        "crypto_address": null,
        "referral": null,
        "usd_value": "0.03",
        "exchange_rate": "1.0",
        "custom": {},
        "webhook_type": 1,
        "created_at": "2016-11-27T14:20:34.000Z",
        "updated_at": "2016-12-05T21:31:15.000Z"
      }
    

    Webhooks are a HTTP callback event that is sent to the Webhook URL specified for the affected order. All webhook requests are sent as a POST request and are handled independently from the event, asynchronously.

    The content sent in the webhook is a JSON object of the resource that the webhook is related to. If it was a order webhook, a order object will be sent.

    Each webhook request contains a webhook_type parameter

    Webhooks can be simulated via our webhook simulator.

    Webhook Type Meaning
    1 Order paid
    2 Order chargeback/reversal
    3 Dynamic product
    4 Product out of stock
    5 Product reached stock warning level

    Errors

    Errors are returned in a JSON structured like this:

    {
      "status": false,
      "errors": "Unable to authenticate"
    }
    

    The errors attribute may also be a array if there are multiple errors stacked

    The Selly API uses the following error codes:

    Status Code Meaning
    400 Bad Request - Invalid parameters
    401 Unauthorized - Unable to authenticate
    403 Forbidden - The request is not allowed
    404 Not Found - The specified resource could not be found.
    406 Not Acceptable - You requested a format that isn't json.
    429 Too Many Requests - You have reached the rate limit
    500 Internal Server Error - We had a problem with our server. Try again later.
    503 Service Unavailable - We're temporarily offline for maintenance. Please try again later.