---
title: 'Grateful API Reference'
description: 'Complete API reference for the Grateful Payments API. Includes endpoints for creating, configuring, and tracking crypto payments.'
---

import Link from 'next/link';
import { Callout } from 'nextra/components';

# API Reference

Complete reference documentation for the Grateful Payments API.

## Base URL

All API requests should be made to:

```
https://merchant.grateful.me/api
```

## Authentication

All API requests require authentication using your API key in the `x-api-key` header.

```js
headers: {
  'Content-Type': 'application/json',
  'x-api-key': '<your-api-key>'
}
```

<Callout emoji="🔐">
  Get your API key from your [merchant
  dashboard](https://merchant.grateful.me/settings/integrations).
</Callout>

## Endpoints

### Payments

| Endpoint                              | Description                                                                  |
| ------------------------------------- | ---------------------------------------------------------------------------- |
| `POST /payments/new`                  | [Create a new payment](/grateful/api-reference/create-payment)               |
| `GET /payments/:paymentId`            | [Get payment details](/grateful/api-reference/get-payment)                   |
| `POST /payments/configure/:paymentId` | [Configure payment token & chain](/grateful/api-reference/configure-payment) |
| `GET /payments/:paymentId/status`     | [Get payment status](/grateful/api-reference/payment-status)                 |

## Payment Flow

1. **Create** - Call `POST /payments/new` to create a payment request
2. **Redirect** - Send customer to the returned `url`
3. **Configure** - Customer (or your system) configures token and chain selection
4. **Pay** - Customer sends funds to the deposit address
5. **Confirm** - Poll status or receive webhook notification