Integration Guide

The purpose of this guide is to help developers quickly get started with the integration of the Cashramp API. This guide should be used with the rest of the API documentation.

Preliminary Setup

1. Create an account

To get started, create an account for your business over at https://cashramp.co/commerce. You'll need to submit some bio-data about yourself and your business, after which you'll get access to the Cashramp Developer dashboard.

2. Generate API keys

To generate your API key, navigate to the Settings page on your Cashramp Developer dashboard.

  • Click the "Generate Keys" button to generate your first Cashramp API keys.

  • You'll receive a Public Key, Private Key, and a Webhook Token. Save your Private Key and Webhook Token somewhere safe and secret (ideally in your production application's environment variables).

  • If your production application's webhook endpoint is set up, you can connect it at this point.

3. Your first API call

If you completed the first two steps, you're ready to make your first API call. Let's try a simple query to retrieve the countries you need when initiating a payment.

Here's a sample JavaScript code using the Axios HTTP library.

const axios = require('axios');

const api = axios.create({
    baseURL: 'https://api.useaccrue.com/cashramp/api/graphql',
    headers: { 'Authorization': `Bearer ${process.env.CASHRAMP_API_SECRET_KEY}` } });

async function _makeRequest(action, payload) {
    try {
        const response = await api.post("", payload);
        if (response.status == 200) {
            if (response.data.errors) {
                return { success: false, error: response.data.errors[0].message };
            } else {
                return { success: true, result: response.data.data[action] };
            }
        }
    } catch (err) {
        return { success: false, error: err.message }
    }
}

function getCountries() {
    const query = `
        query {
            countries {
                id
                code
                name
            }
        }
    `;
    
    // `countries` here matches the `countries` field in the query above.
    return _makeRequest("countries", { query });
}

4. Initiate a payment

  • To initiate a hosted payment, you can use these mutations:

  • Once you initiate a payment request, you'll receive a link to a hosted payment page. You must redirect your user to the URL so they can complete the payment. At this point, the status of the payment request will be created.

  • As soon as the user is assigned an agent to process the deposit, the status of the payment request will be changed to picked_up.

    • You will receive a webhook notification about this change if you've set up a webhook endpoint as outlined in Step 2 above.

  • As soon as a payment request is completed, its status will be changed to completed.

    • You will receive a webhook notification about this change if you've set up a webhook endpoint as outlined in Step 2 above.

5. Conclusion

When you receive a webhook notification that a payment has been completed or canceled, it is recommended that you double-check by fetching the payment and confirming the status. If the status matches, you can release value to your customer as your internal business logic outlines.

  • Your Cashramp balance should also reflect the successful conclusion of the payment request.

Last updated