> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payments.sardine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Integration

# API Integration Guide

Welcome! This guide will walk you through integrating with our API — from authentication and setup to placing orders and receiving updates.

## 1. Obtain Credentials

To access the API, you must first obtain your **API key** and **secret**. These authenticate your requests and track usage.

### Steps:

* **Contact the Sardine integration team.** They will generate a `client_id` and `client_secret` for your use.
* Store both the `client_id` and `client_secret` securely.

> **Security Tip:** Never expose your secret in frontend apps. Use a backend service to interact with the API.

## 2. Retrieve Supported Geo Coverage, Assets, and Payment Methods

Use the following endpoints to fetch dynamic metadata for your UI:

* `GET /v1/geo-coverage` — Supported countries/regions.
* `GET /v1/supported-tokens` — Available cryptocurrencies and fiat currencies.

Use this info to populate dropdowns and validate inputs client-side.

## 3. Onboard a User

Before placing an order, the user must be onboarded and registered in the system.

### Endpoint

```
POST /v1/customers
```

### Sample Payload

```json theme={null}
{
  "email": "user@example.com",
  "phone": "+1234567890",
  "country": "US"
}
```

### Response

Returns a `customerId` which must be used in all user-specific operations.

## 4. User Verification (KYC)

Depending on jurisdiction or transaction volume, KYC verification may be required.

### Endpoint

```
POST /v1/onramp/customers/{id}/verify
```

You may be asked to:

* Upload an ID document.
* Submit a selfie.
* Redirect to a hosted KYC flow.

### Response

Returns a `verification_status`:

* `pending`
* `approved`
* `rejected`

## 5. Fetch a Quote

Before placing an order, fetch a quote to show the user a guaranteed rate and fee breakdown.

### Endpoint

```
POST /v1/quotes
```

### Sample Payload

```json theme={null}
{
  "user_id": "abc123",
  "asset": "BTC",
  "fiat_currency": "USD",
  "amount": "100.00",
  "payment_method": "card"
}
```

### Response Includes:

* Exchange rate
* Fees
* Quote expiry
* `quote_id` (used when placing an order)

## 6. Execute an Order

Place an order based on an approved quote.

### Endpoint

```
POST /v1/orders
```

### Sample Payload

```json theme={null}
{
  "user_id": "abc123",
  "quote_id": "quote789",
  "payment_method": "card",
  "destination_wallet": {
    "type": "crypto",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "asset": "BTC"
  }
}
```

### Response:

Includes `order_id` and the initial status.

## 7. Get Status Updates via Webhooks

Set up webhooks to get real-time updates on order progress and compliance events.

### Steps:

* Register your webhook URL in the Developer Portal.
* Your endpoint should be HTTPS and respond with `2xx`.

### Sample Webhook Payload:

```json theme={null}
{
  "event": "order.status.updated",
  "order_id": "order123",
  "status": "completed",
  "timestamp": "2025-04-17T12:34:56Z"
}
```

> Validate webhook signatures and implement retry logic for maximum reliability.

## 8. Fetch the Order Status

Poll this endpoint for order updates if webhooks aren’t available or for manual checks.

### Endpoint

```
GET /v1/orders/{order_id}
```

### Response Includes:

* Current status: `pending`, `processing`, `completed`, `failed`
* Timestamps
* Payment and asset transfer details

## You're All Set!

Once these steps are implemented, you’ll have full integration from onboarding to real-time tracking. For additional topics like error handling, retries, or sandbox mode, check out the [Extended Developer Docs](https://your-api-domain.com/docs).