Skip to main content

Getting Started

Welcome to the API documentation! This guide will walk you through the basics of setting up your API Key, configuring your callback URL, API key authentication, making a test request, making a payout request and making verifications.

The guide will also showcase an integration example towards the end of the page so you can quickly start integrating our API and making payouts to users in your application.

warning

It's highly recommended that you read this page in its entirety before continuing to other pages.

Base Endpoint​

Our base endpoint is https://rocheap.com/business/api for all API requests

API Key Setup​

To begin using the API, you need to obtain an API Key. Follow these steps:

  1. Settings Page:
    Visit our Business Settings page.

  2. Copy API Key:
    Once logged in, navigate to the API Key section. You'll be able to copy your key from there.
    Your API Key will be a long string of characters. Keep it secure and hidden or else your credits may get stolen!

  3. Store API Key:
    Save this key securely in some kind of environment file to be used by your application, as it will be required in all of your API requests.

Setting up the Callback URL​

The callback URL in your settings is where we'll send you updates related to your orders. It is crucial to use this feature to capture failed orders and handle them appropriately in your application (such as when a user changes the price of their gamepass during order processing and the order fails and cancels).

  1. Navigate to Settings:
    Visit our Business Settings page.

  2. Enter Callback URL:
    Input the URL where you want to receive the callback notifications. Ensure your server is configured to handle these incoming requests and that services like Cloudflare are not blocking any of the requests. Please whitelist the endpoint if necessary, as we cannot provide any IP addresses for you to whitelist.

  3. Save Changes:
    Click Save to activate the callback URL.

Test Request​

All requests must have the rocheap-api-key header. You must also include the Content-Type: 'application\json' header whenever making POST requests that require input (ex: order creation)

It's finally time to make a test request to our servers! Here's an example in NodeJS with our /ping endpoint

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';

axios.get('https://rocheap.com/business/api/ping', {
    headers: {
        'rocheap-api-key': apiKey
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error('Error:', error);
});

And if you did everything right this should be the expected response:

{ success: true, message: 'pong' }

If your request is invalid or your API Key is invalid you will receive a response similar to this:

{ success: false, error: 'Invalid API key.' }

Payout Request​

Now let's try to create a gamepass order for a user and check if it succeeded or not.

warning

Successfully creating an order does not mean that the order has completed, it simply means that the order is now scheduled for fulfillment in our system and we will notify your callback endpoint (if it's set) once the order completes or fails.

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';

async function payoutUser(robux, roblox_user_id, universe_id, place_id) {
    try {
        const headers = {
            'rocheap-api-key': apiKey
        };

        const data = {
            "robux": robux,
            "roblox_user_id": roblox_user_id,
            "universe_id": universe_id,
            "place_id": place_id,
            "custom_order_id": null
        };

        const response = await axios.post('https://rocheap.com/business/api/create_order', data, headers);
    
        return response.data;
    } catch (error) {
      return false;
    }
}

(async function(){
   let robux = 10;
   let roblox_user_id = 1;
   let universe_id = 4284924817;
   let place_id = 3927852479;

   let order = await payoutUser(roblox_user_id, robux, universe_id, place_id);
   
   if (!order) {
      console.log('Order request failed');
   }

   if (order.success) {
      console.log('Order created successfully!');
      console.log('Order details:', order);
   } else {
      console.log('Order failed to create!');
      console.log(order.status, order.failure_code);
   }
})();

The full documentation for this endpoint is available in Create Order Guide

Verifying Success and Debugging Errors​

Whenever you're dealing with our APIs please always check for the success key in our responses and callbacks as this is the most straightforward way to verify whether things went right or wrong, and do not purely rely on our status codes. If success is false we'll also provide you with one of the following:

  • An error object with code and message values. Full list here.

  • A failure_code object with code and message values in the case of order endpoints and callbacks when an order fails. You can view a list of these codes in Create Order and Order Info.

Integration Example​

Here's an example of how you may integrate ROCheap's solution in your application:

  1. Grab your API key from Business Settings and store it securely in your application (ex: .env file)

  2. Set a callback URL in Business Settings to be notified about order updates. If you're using Cloudflare please whitelist the endpoint from any security/browser checks.

  3. Query our /balance endpoint at least once every 10 minutes to stay updated with your balance and have your application notify you when your balance goes low.

  4. To pay a user, collect the necessary fields and follow the example in Create Order Guide and create the order. Make sure to keep track of the order ID we generate in the response body.

  5. Confirm whether the order was created successfully or not by checking status in the response body. Additionally we will provide a failure_code object if the order failed to create. You should notify your user if the order failed due to an error they caused (example: incorrect gamepass price). A full list of these codes are available in Create Order Guide and Get Order Info. You must configure your application to mainly check for GAMEPASS_NOT_FOUND, ORDER_FAILED_USER_ERROR and ORDER_REFUNDED failure codes when it comes to validating any user caused errors, and also for errors that may have been caused by you (like, but not limited to: INSUFFICIENT_BALANCE and USER_DOES_NOT_EXIST).

  6. Once a callback request is made to your URL, parse the request and verify its authenticity by generating a signature and comparing it to the one we provided in the rocheap-api-signature header. Check out Callbacks and Verification for an in-depth explanation of how you can do this. Next, if the order succeeded (returned a status object with code COMPLETED) there's no more action needed. If the order failed you may need to handle this appropriately in your application (ex: by refunding the user their balance)

  7. If your order has been in a PROCESSING state for too long without a callback request (ex: more than 12 hrs) or you have not received any callback requests about an order since its creation, you should routinely check the order's status using Get Order Info and have your application handle any order status changes accordingly. Sometimes, although very rarely, orders may hang in the PROCESSING state for hours until we have enough stock to fulfill them.

The next thing that we recommend you do is exploring all of our Features and Endpoints before you start integrating.

Additional Support​

If you need any additional support feel free to start a chat on our website, open a ticket in our Discord server, or message your Telegram contact if you have one and describe your issue. Our developers will work to assist you ASAP.