> For the complete documentation index, see [llms.txt](https://docs.coindpay.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coindpay.xyz/landing/start/developers/payments-order.md).

# Payments Order

<mark style="color:$info;">Query the status and details of a specific payments order by its product transaction rampId.</mark>

{% hint style="warning" %}
This feature is intended only for merchants who require customized order details rendering.\
In most cases, integration simply requires enabling [Integration](/landing/start/developers/integration.md#webhooks-callback) to receive order event notifications and handling the callback accordingly.
{% endhint %}

***

### API

```typescript
GET /payment/order
```

Example:

```typescript
GET {API_DOMAIN}/payment/order?rampId=0xabc123dd
```

{% hint style="info" %}
API\_DOMAIN [Developers](/landing/start/developers.md#environment)
{% endhint %}

### Query Params

<table><thead><tr><th width="174.61981201171875">Name</th><th width="139.75531005859375">Type</th><th width="150.4375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>rampId</code></td><td>string*</td><td>✅ Required</td><td>Unique merchant transaction id <code>merchant_transaction_id</code></td></tr></tbody></table>

### Authentication Headers

{% hint style="info" %}
API requests are rate-limited. Please avoid excessive calls.
{% endhint %}

<table><thead><tr><th width="175.1978759765625">Name</th><th width="140.4322509765625">Type</th><th width="149.6927490234375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>x-appid</code></td><td>string*</td><td>✅ Required</td><td>Your merchant <code>appid</code></td></tr><tr><td><code>x-signature</code></td><td>string*</td><td>✅ Required</td><td>HMAC-SHA256 signature generated from your <code>API Secret</code></td></tr></tbody></table>

#### **Generating the Signature**

The `x-signature` is generated by signing your `appid` with your `API Secret` using HMAC-SHA256.

```typescript
import { createHmac } from 'crypto'

export function createHmacSignature(secret: string, data: string): string {
  return createHmac('sha256', secret).update(data).digest('hex')
}
```

> 1. This endpoint supports both crypto and fiat payments, and the `rampId` value must be globally unique.
> 2. The `rampId` represents the unique `merchant_transaction_id` used for transactions between the developer and the consumer, and is stored in the database as `rampId`.

***

### Success Response

✅  200 - Success Example

{% tabs %}
{% tab title="Fiat" %}

```json
{
  "ok": true,
  "data": {
    "id": "690e31d***ba6ef8215",
    "payeeId": "1_N1yAE6D***v1oTd6Uoz",
    "appid": "business_app_abc123",
    "name": "David Lin",
    "email": "David123@gmail.com",
    "payer": "0x68b37Db3E727***d0B76195eB929Db649",
    "payMethod": "card",
    "rampId": "24615901***47304960",
    "rampType": "pay",
    "rampStatus": "completed",
    "chain": "BASE",
    "symbol": "USDC",
    "fiatCoin": "AED",
    "fiatAmount": 70,
    "amount": 17.852559,
    "reserveAmount": 0.892628,
    "afterReserveAmount": 16.95987,
    "usd": 19.12,
    "signature": "0xa280***e8fec1",
    "settledAt": "2025-11-07T17:55:08.220Z",
    "createdAt": "2025-11-07T17:52:17.293Z",
    "updatedAt": "2025-11-07T17:55:10.100Z"
  }
}
```

{% endtab %}

{% tab title="Crypto" %}

```json
{
  "ok": true,
  "data": {
    "id": "payment_abc123",
    "appid": "business_app_abc123",
    "payeeId": "QSZMC90***7uNdUtxO",
    "payer": "8wKpf1bphwVPCqG3uy75JuWqN2m7uCLVrKeMZLmAdhx3",
    "name": "Henry",
    "email": "xxx@coindpay.xyz",
    "message": "hhhha",
    "signature": "uVkv29hDtjCJnrSxN4b6BifbC7k229P7pzZ...uJrANpecFfNfw2vmpApDoqMsxqY4x1sTF",
    "chain": "Solana",
    "amount": 5.25,
    "usd": 5.25,
    "symbol": "USDC",
    "contract": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  }
}
```

{% endtab %}
{% endtabs %}

***

### Error Response

**404 - Not found**

```json
{
  "ok": false,
  "message": "Payment not found ˙◠˙"
}
```

**401 -** Invalid signature

```json
{
  "ok": false,
  "message": "Invalid signature ˙◠˙"
}
```

***

### cURL Request

{% code overflow="wrap" %}

```bash
curl "https://api.coindpay.xyz/payment/order?rampId=0xabc123dd" \
  -H "x-appid: YOUR_APP_ID" \
  -H "x-signature: YOUR_SIGNATURE"
```

{% endcode %}

### Full Order Fields

| Field                | Type     | Description                                                                                                                                                        |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                 | string\* | Unique payment Id                                                                                                                                                  |
| `uuid`               | string\* | Internal Id of the payee (receiver) for webhooks data-key  <kbd>appid</kbd>                                                                                        |
| `payeeId`            | string\* | Product or service Id                                                                                                                                              |
| `rampId`             | string?  | Order ID that is paid for through Ramps service provider（The **`merchant_transaction_id`** provided by the merchants）                                              |
| `name`               | string?  | Payer name (optional)                                                                                                                                              |
| `email`              | string\* | Payer email (optional)                                                                                                                                             |
| `message`            | string?  | Payment memo (optional)                                                                                                                                            |
| `payer`              | string\* | Payer wallet (crypto or fiat-stablecoin settlement type)                                                                                                           |
| `payMethod`          | string?  | Fiat payment method type (e.g., apple/google/card...)                                                                                                              |
| `rampType`           | string?  | Payment type (pay/buy/sell)  through multi-provider                                                                                                                |
| `rampStatus`         | string?  | Order status of payment completed through bank or on-chain service.                                                                                                |
| `rampFeedback`       | string?  | Order exception or failure tips (returned by certain banks; in most cases this field may be empty)                                                                 |
| `fiatCoin`           | string?  | Fiat currency code (e.g., USD)                                                                                                                                     |
| `fiatAmount`         | float?   | Fiat amount paid (if any)                                                                                                                                          |
| `usd`                | float?   | USD-pegged pay-in amount (auto-converted using real-time exchange rates)                                                                                           |
| `amount`             | float\*  | Settled token amount after applicable payment processing, gateway, network, and platform fees have been deducted, but before any reserve requirements are applied. |
| `reserveAmount`      | float?   | The reserve amount held for merchants with reserves enabled.                                                                                                       |
| `afterReserveAmount` | float?   | Final settled token amount after applicable reserve deductions. If no reserve requirements apply, this field may be omitted or equal to `amount`                   |
| `chain`              | string\* | Blockchain name (e.g., solana, ethereum)                                                                                                                           |
| `symbol`             | string\* | Token symbol (e.g., USDT, USDC)                                                                                                                                    |
| `contract`           | string?  | Contract address of the token (Used in crypto payments or exchanges type)                                                                                          |
| `signature`          | string\* | The fiat currency to crypto exchange process has been completed, with a unique on-chain hash.                                                                      |
| `settledAt`          | date?    | Order Settlement Timestamp                                                                                                                                         |
| `createdAt`          | date\*   | Order Creation Timestamp                                                                                                                                           |
| `updatedAt`          | date\*   | Order Update Timestamp                                                                                                                                             |

***

### Notes

* It works with both on-chain and off-chain payments (crypto, ramps, card, etc.)
* If no payment is found for the given `signature` and `rampId`, `ok` will be `false`
* The `rampId` refers to the unique `merchant_transaction_id` generated by the developer or merchant for a consumer.
* <mark style="color:purple;">Please use real payment id and other params to integrate and test the API.</mark>