> For the complete documentation index, see [llms.txt](https://docs.cashramp.co/cashramp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cashramp.co/cashramp/introduction/integration-guide.md).

# Integration Guide

Cashramp's API is built on GraphQL, providing a flexible and powerful way to integrate African currency payments with stablecoin settlements. This guide walks you through the key concepts and common integration patterns.

## Authentication

All API requests require authentication using Bearer tokens:

{% tabs %}
{% tab title="NodeJS SDK" %}

```javascript
import Cashramp from "cashramp";

const cashramp = new Cashramp({
  env: "production", // or "test" for staging
  secretKey: process.env.CSHRMP_SECRET_KEY,
});
```

{% endtab %}

{% tab title="Ruby SDK" %}

```ruby
require "cashramp"

client = Cashramp::Client.initialize(
  env: :production, # or :test for staging
  secret_key: ENV["CSHRMP_SECRET_KEY"]
)
```

{% endtab %}

{% tab title="Go SDK" %}

```go
import (
  "os"
  cashrampsdk "github.com/rockets-hq/cashramp-sdk-go"
)

client, err := cashrampsdk.InitialiseClient(
  "live", // or "test" for staging
  os.Getenv("CSHRMP_SECRET_KEY"),
)
if err != nil {
  panic(err)
}
```

{% endtab %}

{% tab title="Node (axios)" %}

```javascript
import axios from "axios";

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

{% endtab %}

{% tab title="Python (requests)" %}

```python
import os
import requests

CASHRAMP_URL = "https://api.useaccrue.com/cashramp/api/graphql"

cashramp = requests.Session()
cashramp.headers.update({
    "Authorization": f"Bearer {os.environ['CSHRMP_SECRET_KEY']}",
    "Content-Type": "application/json",
})
```

{% endtab %}

{% tab title="Ruby (net/http)" %}

```ruby
require "net/http"
require "uri"
require "json"

CASHRAMP_URL = URI("https://api.useaccrue.com/cashramp/api/graphql")

def cashramp_request(query, variables = {})
  http = Net::HTTP.new(CASHRAMP_URL.host, CASHRAMP_URL.port)
  http.use_ssl = true
  req = Net::HTTP::Post.new(CASHRAMP_URL)
  req["Authorization"] = "Bearer #{ENV['CSHRMP_SECRET_KEY']}"
  req["Content-Type"] = "application/json"
  req.body = { query: query, variables: variables }.to_json
  JSON.parse(http.request(req).body)
end
```

{% endtab %}

{% tab title="Go (net/http)" %}

```go
package main

import (
  "bytes"
  "encoding/json"
  "net/http"
  "os"
)

const cashrampURL = "https://api.useaccrue.com/cashramp/api/graphql"

func cashrampRequest(query string, variables map[string]any) (*http.Response, error) {
  body, _ := json.Marshal(map[string]any{"query": query, "variables": variables})
  req, err := http.NewRequest("POST", cashrampURL, bytes.NewBuffer(body))
  if err != nil {
    return nil, err
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("CSHRMP_SECRET_KEY"))
  req.Header.Set("Content-Type", "application/json")
  return http.DefaultClient.Do(req)
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl https://api.useaccrue.com/cashramp/api/graphql \
  -H "Authorization: Bearer $CSHRMP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ account { id accountBalance } }" }'
```

{% endtab %}
{% endtabs %}

For detailed authentication setup, see [Authentication](/cashramp/introduction/authentication.md).

## Core Concepts

### 1. Integration Options

Cashramp offers three integration patterns:

| Type                                                   | Use Case                | Implementation          |
| ------------------------------------------------------ | ----------------------- | ----------------------- |
| [**Hosted Ramp**](/cashramp/hosted-ramp/overview.md)   | Drop-in checkout UI     | Redirect to hosted page |
| [**Direct Ramp**](/cashramp/direct-ramp/overview.md)   | Server-side collections | Pure API integration    |
| [**Onchain Ramp**](/cashramp/onchain-ramp/overview.md) | Wallet/DApp integration | URL with parameters     |

### 2. Payment Lifecycle

All payment flows follow this general lifecycle:

| Status      | Description      | Webhook Event |
| ----------- | ---------------- | ------------- |
| `created`   | Initial request  | -             |
| `picked_up` | Agent assigned   | Yes           |
| `completed` | Funds settled    | Yes           |
| `canceled`  | Request canceled | Yes           |

### 3. Webhooks

Cashramp sends webhooks for important state changes:

```javascript
// Example webhook payload
{
  "event_type": "payment_request.updated",
  "data": {
    "id": "...",
    "status": "completed",
    "amount": "100.00",
    "currency": "usd"
  }
}
```

For more details, see [Webhooks](/cashramp/introduction/webhooks.md).