> ## Documentation Index
> Fetch the complete documentation index at: https://walletconnect-pay-docs-wcagent-nest-api-reference-under-pay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant API Reference

> API reference for the WalletConnect Pay Merchant API used in ecommerce checkout integrations.

## 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](/payments/merchant/onboarding) |
| `Merchant-Id` | Yes | Merchant identifier from the [Merchant Dashboard](/payments/merchant/onboarding) |

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

## 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 |

<Info>
  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.
</Info>

<Warning>
  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.
</Warning>

### Request Example

```json theme={null}
{
  "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

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

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  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 TypeScript theme={null}
  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();
  ```
</CodeGroup>

### 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

<CodeGroup>
  ```bash cURL theme={null}
  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 TypeScript theme={null}
  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;
  }
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.