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

# Receiving Payments

> Accept fiat deposits and on-ramp to stablecoins.

## Overview

<Tip>
  This guide walks through accepting payments using the Pay-ins endpoint for granular control. For most integrations, the [Transfers API](/api/transfers/create) is the recommended starting point — specify a fiat source and stablecoin destination, and Thiqwave handles the rest.
</Tip>

Thiqwave lets you receive value as fiat deposits or convert incoming fiat directly to stablecoins. Both flows start the same way — a pay-in request.

Whether you're collecting fiat deposits or on-ramping to stablecoins, the process begins with creating a pay-in request. From there, your customers deposit funds, and Thiqwave handles the rest.

## Receiving Fiat Deposits

Accept incoming fiat payments and hold them as deposits in your Thiqwave account.

<Steps>
  <Step title="Create a pay-in request">
    Initiate a new pay-in to receive fiat from your customer.
  </Step>

  <Step title="Customer deposits funds">
    Your customer transfers funds to the bank account details provided in the pay-in response.
  </Step>

  <Step title="Funds credited">
    Once the transfer is confirmed, the funds appear in your Thiqwave balance.
  </Step>
</Steps>

### Creating a Pay-In

To create a pay-in request, POST to the `/v1/payins` endpoint with the customer's deposit amount and corridor.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thiqwave.com/v1/payins \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 50000,
      "currency": "AED",
      "corridor": "uae",
      "payment_method": "bank_transfer",
      "reference": "customer_001"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.thiqwave.com/v1/payins', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 50000,
      currency: 'AED',
      corridor: 'uae',
      payment_method: 'bank_transfer',
      reference: 'customer_001'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
    'https://api.thiqwave.com/v1/payins',
    headers={
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    json={
      'amount': 50000,
      'currency': 'AED',
      'corridor': 'uae',
      'payment_method': 'bank_transfer',
      'reference': 'customer_001'
    }
  )

  print(response.json())
  ```
</CodeGroup>

### Pay-In Response

The API returns a pay-in object with bank details and a unique reference for the deposit:

```json theme={null}
{
  "id": "payin_abc123xyz",
  "status": "pending",
  "amount": 50000,
  "currency": "AED",
  "corridor": "uae",
  "payment_method": "bank_transfer",
  "payment_details": {
    "bank_name": "Thiqwave Bank Partner",
    "account_number": "1234567890",
    "iban": "AE070012345678901234567",
    "swift_code": "THIQAEXX",
    "reference": "payin_abc123xyz"
  },
  "created_at": "2026-04-10T14:30:00Z",
  "updated_at": "2026-04-10T14:30:00Z"
}
```

<Tip>
  Share the `payment_details` with your customer so they can complete the bank transfer. They should include the `reference` in their payment memo.
</Tip>

## On-Ramping: Fiat to Stablecoin

Convert incoming fiat deposits directly to stablecoins in a single integrated flow.

<Steps>
  <Step title="Get a quote">
    Request a conversion quote for your desired stablecoin and network.
  </Step>

  <Step title="Create an on-ramp">
    Initiate the on-ramp request with your quote and destination wallet address.
  </Step>

  <Step title="Customer deposits funds">
    Your customer transfers the fiat amount to the provided bank account.
  </Step>

  <Step title="Stablecoins delivered">
    Once the deposit confirms, stablecoins are automatically transferred to the destination wallet.
  </Step>
</Steps>

### Getting a Quote

Start by fetching a quote for your on-ramp. Specify the source fiat currency, destination stablecoin, amount, and blockchain network.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thiqwave.com/v1/quotes \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "source_currency": "AED",
      "destination_currency": "USDC",
      "amount": 50000,
      "destination_network": "polygon",
      "corridor": "uae"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.thiqwave.com/v1/quotes', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      source_currency: 'AED',
      destination_currency: 'USDC',
      amount: 50000,
      destination_network: 'polygon',
      corridor: 'uae'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
    'https://api.thiqwave.com/v1/quotes',
    headers={
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    json={
      'source_currency': 'AED',
      'destination_currency': 'USDC',
      'amount': 50000,
      'destination_network': 'polygon',
      'corridor': 'uae'
    }
  )

  print(response.json())
  ```
</CodeGroup>

### Quote Response

The quote returns the exact amount you'll receive in stablecoins, along with a quote ID valid for a limited time:

```json theme={null}
{
  "id": "quote_xyz789abc",
  "source_currency": "AED",
  "destination_currency": "USDC",
  "source_amount": 50000,
  "destination_amount": "136.00",
  "destination_network": "polygon",
  "expires_at": "2026-04-10T15:30:00Z"
}
```

<Warning>
  Quotes expire after 30 minutes. Use the `quote_id` in your on-ramp request before expiry.
</Warning>

### Creating an On-Ramp

Once you have a valid quote, create an on-ramp request with the destination wallet address and network:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thiqwave.com/v1/bridging/onramp \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "quote_id": "quote_xyz789abc",
      "destination_address": "0x742d35Cc6634C0532925a3b844Bc2e7595f42aED",
      "destination_network": "polygon"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.thiqwave.com/v1/bridging/onramp', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      quote_id: 'quote_xyz789abc',
      destination_address: '0x742d35Cc6634C0532925a3b844Bc2e7595f42aED',
      destination_network: 'polygon'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
    'https://api.thiqwave.com/v1/bridging/onramp',
    headers={
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    json={
      'quote_id': 'quote_xyz789abc',
      'destination_address': '0x742d35Cc6634C0532925a3b844Bc2e7595f42aED',
      'destination_network': 'polygon'
    }
  )

  print(response.json())
  ```
</CodeGroup>

### On-Ramp Response

The on-ramp object contains the fiat deposit details and stablecoin destination:

```json theme={null}
{
  "id": "bridge_def456ghi",
  "type": "onramp",
  "status": "pending",
  "source": {
    "amount": 50000,
    "currency": "AED"
  },
  "destination": {
    "amount": "136.00",
    "currency": "USDC",
    "network": "polygon",
    "address": "0x742d35Cc6634C0532925a3b844Bc2e7595f42aED"
  },
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc2e7595f42aED",
  "blockchain": "polygon",
  "payment_details": {
    "bank_name": "Thiqwave Bank Partner",
    "account_number": "1234567890",
    "iban": "AE070012345678901234567",
    "swift_code": "THIQAEXX",
    "reference": "bridge_def456ghi"
  },
  "created_at": "2026-04-10T14:30:00Z",
  "updated_at": "2026-04-10T14:30:00Z"
}
```

<Tip>
  Share the `payment_details` with your customer. They deposit the fiat amount, and stablecoins automatically arrive at the destination address once confirmed.
</Tip>

## Payment Methods

Available payment methods depend on your corridor and local regulations. Each corridor supports different deposit methods:

| Corridor             | Payment Methods                                          |
| -------------------- | -------------------------------------------------------- |
| UAE                  | Bank transfers, instant payment networks, mobile wallets |
| Egypt                | Bank transfers, mobile money                             |
| Additional corridors | Bank transfers (primary method)                          |

<Note>
  Payment method support varies by corridor and may change based on local regulatory requirements. Check the corridor-specific documentation for the most current options.
</Note>

## Tracking Status

Monitor pay-ins and on-ramps throughout their lifecycle using status updates and webhooks.

### Status Lifecycle

Both pay-ins and on-ramps progress through defined states:

| Status       | Description                                               |
| ------------ | --------------------------------------------------------- |
| `pending`    | Request created, awaiting customer deposit                |
| `processing` | Deposit received and being verified                       |
| `completed`  | Fiat credited (pay-in) or stablecoins delivered (on-ramp) |
| `failed`     | Deposit failed verification or transaction rejected       |

### Webhook Events

Subscribe to webhooks to receive real-time status notifications:

* `payin.completed` — Fiat deposit successfully credited
* `payin.failed` — Pay-in request failed
* `bridge.completed` — On-ramp stablecoins delivered
* `bridge.failed` — On-ramp request failed

See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Best Practices

Follow these recommendations to ensure smooth payment flows:

<Steps>
  <Step title="Use webhooks for notifications">
    Subscribe to webhook events instead of polling the API. This ensures you're notified immediately when deposits arrive or on-ramps complete.
  </Step>

  <Step title="Implement idempotency keys">
    Include idempotency keys in pay-in and on-ramp requests to prevent duplicate transactions if requests are retried.
  </Step>

  <Step title="Validate amounts before submission">
    Check that the deposit amount meets your minimum requirements and doesn't exceed any limits before creating a request.
  </Step>

  <Step title="Handle quote expiry">
    For on-ramps, create the on-ramp request promptly after receiving a quote. Quotes expire after 30 minutes.
  </Step>

  <Step title="Test in staging first">
    Always test your integration in the staging environment before going live.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Sending Payments" href="/guides/sending-payments" icon="arrow-up-right">
    Send fiat transfers or bridge stablecoins to wallets.
  </Card>

  <Card title="Webhooks" href="/guides/webhooks" icon="webhook">
    Set up real-time event notifications.
  </Card>

  <Card title="Pay-ins API" href="/api/payins/create" icon="api">
    Full API reference for pay-in requests.
  </Card>

  <Card title="Bridging API" href="/api/bridging/create" icon="link">
    Full API reference for on-ramp and bridge operations.
  </Card>
</CardGroup>