## Authentication

Every request to the Merchant API requires the following headers:

| Header         | Required   | Description                                                            |
|----------------|------------|------------------------------------------------------------------------|
| `Content-Type` | Conditional| Must be `application/json` for requests with a JSON body              |
| `Api-Key`      | Yes        | Partner API key from the [Merchant Dashboard](https://docs.walletconnect.com/payments/merchant/onboarding) |
| `Merchant-Id`  | Yes        | Merchant identifier from the [Merchant Dashboard](https://docs.walletconnect.com/payments/merchant/onboarding) |

Keep your `Api-Key` secret. Never expose it in client-side code — all API calls should be made from your backend server.

## Base URLs

| Environment | URL                                       |
|-------------|-------------------------------------------|
| Production  | `https://api.pay.walletconnect.com`      |
| Staging     | `https://staging.api.pay.walletconnect.com` |

## Create Payment

Creates a new payment for the buyer to complete on the WalletConnect Pay checkout portal.

```
POST /v1/merchant/payment
```

### Request Body

| Field              | Type   | Required | Description                                                |
|--------------------|--------|----------|------------------------------------------------------------|
| `amount`           | object | Yes      | The payment amount                                         |
| `amount.unit`     | string | Yes      | Currency in `iso4217/{CODE}` format (e.g., `iso4217/USD`) |
| `amount.value`    | string | Yes      | Amount in minor units as a string (e.g., `"5000"` for $50.00) |
| `referenceId`     | string | Yes      | Your internal order or reference identifier                   |
| `checkout`        | object | No       | Checkout redirect configuration                               |
| `checkout.successUrl` | string | No    | HTTPS URL to redirect the buyer after a successful payment    |
| `checkout.errorUrl`   | string | No    | HTTPS URL to redirect the buyer after a failed payment     |

The `amount.value` is expressed in the currency’s **minor units**. For USD, `"5000"` equals $50.00 (5000 cents). For JPY (which has no minor unit), `"5000"` equals ¥5,000.

Both `successUrl` and `errorUrl` must be valid HTTPS URLs. If either is missing or invalid, the redirect feature is disabled entirely for that payment — the checkout portal will show generic terminal views instead.

### Request Example

```
{
  "amount": {
    "unit": "iso4217/USD",
    "value": "5000"
  },
  "referenceId": "order_abc123",
  "checkout": {
    "successUrl": "https://yourstore.com/order/abc123/success",
    "errorUrl": "https://yourstore.com/order/abc123/failed"
  }
}
```

### Response

| Field      | Type   | Description                                                                  |
|------------|--------|------------------------------------------------------------------------------|
| `paymentId` | string | Unique payment identifier (e.g., `pay_xxx`)                                 |
| `gatewayUrl`| string | URL to the checkout portal for this payment — use this to redirect the buyer |
| `status`    | string | Initial payment status (typically `pending`)                                 |
| `expiresAt` | integer| Unix timestamp (seconds) when the payment expires                             |
| `isFinal`   | boolean| Whether the payment is already in a terminal state                            |
| `pollInMs`  | integer| Suggested polling interval in milliseconds for status checks                  |

### Response Example

```
{
  "paymentId": "pay_abc123def456",
  "gatewayUrl": "https://pay.walletconnect.com/?pid=pay_abc123def456",
  "status": "pending",
  "expiresAt": 1709831400,
  "isFinal": false,
  "pollInMs": 1000
}
```

### Code Examples

**cURL**

```
curl -X POST https://api.pay.walletconnect.com/v1/merchant/payment \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Merchant-Id: YOUR_MERCHANT_ID" \
  -d '{
    "amount": {
      "unit": "iso4217/USD",
      "value": "5000"
    },
    "referenceId": "order_abc123",
    "checkout": {
      "successUrl": "https://yourstore.com/order/abc123/success",
      "errorUrl": "https://yourstore.com/order/abc123/failed"
    }
  }' 
```

**TypeScript**

```
const response = await fetch(
  "https://api.pay.walletconnect.com/v1/merchant/payment",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Api-Key": process.env.WCP_API_KEY,
      "Merchant-Id": process.env.WCP_MERCHANT_ID,
    },
    body: JSON.stringify({
      amount: {
        unit: "iso4217/USD",
        value: String(order.totalCents),
      },
      referenceId: order.id,
      checkout: {
        successUrl: `${process.env.BASE_URL}/order/${order.id}/success`,
        errorUrl: `${process.env.BASE_URL}/order/${order.id}/failed`,
      },
    }),
  }
);

const { paymentId, gatewayUrl } = await response.json();
```

### Error Responses

| Status Code | Description                                          |
|-------------|------------------------------------------------------|
| `400`      | Invalid request — check required fields and format     |
| `401`      | Invalid or missing API key                             |
| `404`      | Merchant not found for the given `Merchant-Id`       |
| `500`      | Internal server error                                  |

## Verify Payment Status

After the buyer completes (or abandons) the checkout, verify the payment status from your backend.

```
GET /v1/merchant/payment/{id}/status
```

### Path Parameters

| Parameter | Type   | Description                                         |
|-----------|--------|-----------------------------------------------------|
| `id`      | string | The `paymentId` returned when creating the payment  |

### Headers

| Header     | Required | Description                       |
|------------|----------|-----------------------------------|
| `Api-Key`  | Yes      | Partner API key                   |
| `Merchant-Id`| Yes   | Merchant identifier                |

### Response

| Field      | Type    | Description                                       |
|------------|---------|---------------------------------------------------|
| `status`   | string  | Payment status (see below)                         |
| `isFinal`  | boolean | Whether the payment has reached a terminal state   |

### Payment Statuses

| Status    | Terminal | Description                                           |
|-----------|----------|-------------------------------------------------------|
| `pending` | No       | Payment created, waiting for buyer action            |
| `processing`| No     | Transaction submitted, awaiting on-chain confirmation |
| `succeeded`| Yes     | Payment completed successfully                         |
| `failed`  | Yes      | Payment failed or was rejected                         |
| `expired` | Yes      | Payment window closed without completion               |

### Code Example

**cURL**

```
curl https://api.pay.walletconnect.com/v1/merchant/payment/pay_abc123def456/status \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Merchant-Id: YOUR_MERCHANT_ID"
```

**TypeScript**

```
async function verifyPaymentStatus(paymentId: string): Promise<string> {
  const response = await fetch(
    `https://api.pay.walletconnect.com/v1/merchant/payment/${paymentId}/status`,
    {
      headers: {
        "Api-Key": process.env.WCP_API_KEY,
        "Merchant-Id": process.env.WCP_MERCHANT_ID,
      },
    }
  );

const { status, isFinal } = await response.json();
  return status;
}
```