Getting Started

Quickstart

Make your first API call and pull live merchant data in under 5 minutes

This guide walks you through authenticating, listing your merchants, and pulling pricing data — the three calls you’ll make in almost every integration.

1

Get your API key

You’ll need an X-Partner-API-Key to authenticate. If you don’t have one yet, see the Authentication guide to request one from the Aurora Payments team.

2

Check connectivity

Verify the API is reachable with a health check (no auth required):

$curl https://getmodulate.dev/api/partner/health

A healthy response looks like:

1{
2  "data": {
3    "status": "ok",
4    "version": "v1",
5    "database": "connected"
6  },
7  "meta": {
8    "request_id": "req_abc123",
9    "api_version": "v1",
10    "timestamp": "2025-01-15T10:30:00Z"
11  },
12  "errors": []
13}
3

List your merchants

Pull the first page of merchants in your portfolio:

$curl https://getmodulate.dev/api/partner/merchants?page_size=25 \
>  -H "X-Partner-API-Key: YOUR_API_KEY"

Every response uses the {data, meta, errors} envelope. List endpoints include pagination details in meta:

1{
2  "data": [
3    {
4      "merchant_id": "925700000233734",
5      "dba_name": "Sunrise Coffee Co",
6      "legal_name": "Sunrise Coffee LLC",
7      "status": "active",
8      "processor": "TSYS",
9      "mcc_code": "5812",
10      "state": "CA",
11      "city": "San Francisco",
12      "onboarding_date": "2024-03-15T00:00:00+00:00",
13      "last_data_refresh": "2025-01-15T10:30:00+00:00",
14      "pci_compliance": {
15        "status": "compliant",
16        "saq_due_date": "2025-12-31T00:00:00+00:00",
17        "last_updated": "2025-01-10T00:00:00+00:00"
18      }
19    }
20  ],
21  "meta": {
22    "request_id": "req_abc123",
23    "api_version": "v1",
24    "page": 1,
25    "page_size": 25,
26    "total_count": 142,
27    "total_pages": 6,
28    "has_next": true,
29    "has_prev": false,
30    "source": "risecrm",
31    "as_of": "2025-01-15T10:30:00+00:00"
32  },
33  "errors": []
34}
4

Get current pricing for a merchant

Use a merchant_id from the previous step to fetch their current TSYS pricing:

$curl https://getmodulate.dev/api/partner/merchants/925700000233734/pricing/tsys/current \
>  -H "X-Partner-API-Key: YOUR_API_KEY"

The pricing response includes a computed summary and the full fee breakdown by category:

1{
2  "data": {
3    "merchant_id": "925700000233734",
4    "pricing_model": "IC+",
5    "summary": {
6      "pricing_model": "IC+",
7      "pricing_text": "IC+ 15 bps + $0.10",
8      "primary_rate_bps": 15,
9      "other_volume_fee_bps": 10,
10      "effective_rate_bps": 25,
11      "per_transaction_fee": "0.10",
12      "monthly_fee": "9.95",
13      "annual_fee": null,
14      "exceptions": [
15        { "card_type": "Amex", "rate": 2.95 }
16      ]
17    },
18    "categories": [
19      {
20        "name": "Discount",
21        "items": [
22          {
23            "fee_item_name": "Discount Rate",
24            "percent": 0.15,
25            "per_item": null,
26            "billing_frequency": "Monthly"
27          }
28        ]
29      }
30    ],
31    "as_of": "2025-01-01T00:00:00+00:00"
32  },
33  "meta": {
34    "request_id": "req_def456",
35    "api_version": "v1",
36    "source": "bigquery",
37    "as_of": "2025-01-01T00:00:00+00:00"
38  },
39  "errors": []
40}

Response envelope

Every endpoint returns the same envelope structure:

1{
2  "data": { },   // Single object or array
3  "meta": { },   // Request ID, pagination, data source, freshness timestamp
4  "errors": []   // Empty on success; error details on failure
5}

List endpoints add pagination fields to meta: page, page_size, total_count, total_pages, has_next, has_prev.

Pagination

All list endpoints support page and page_size query parameters:

$# Get page 3 with 50 results per page
$curl "https://getmodulate.dev/api/partner/merchants?page=3&page_size=50" \
>  -H "X-Partner-API-Key: YOUR_API_KEY"

Use has_next from the response meta to drive pagination loops:

1page = 1
2while True:
3    response = client.get("/api/partner/merchants", params={"page": page, "page_size": 100})
4    body = response.json()
5
6    for merchant in body["data"]:
7        process(merchant)
8
9    if not body["meta"]["has_next"]:
10        break
11    page += 1

Incremental sync

Use updated_since on supported endpoints to fetch only records that changed since your last sync — ideal for keeping a local cache up to date:

$curl "https://getmodulate.dev/api/partner/merchants?updated_since=2025-02-01T00:00:00Z" \
>  -H "X-Partner-API-Key: YOUR_API_KEY"

Supported on: merchants list, merchant residuals, and available reports.

Error handling

Failed requests return the same envelope with an empty data and populated errors:

1{
2  "data": null,
3  "meta": { "request_id": "req_xyz789", "api_version": "v1" },
4  "errors": [
5    {
6      "code": "MERCHANT_NOT_IN_PORTFOLIO",
7      "message": "Merchant not found or not in your portfolio"
8    }
9  ]
10}

Common status codes:

StatusMeaning
401Missing or invalid API key
403Merchant not in your portfolio or insufficient scope
404Resource not found
429Rate limit exceeded — check Retry-After header
503Upstream data source temporarily unavailable

Need help?

Contact help@getmodulate.dev or reach out to your account manager.