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

### 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": 17.85,
    "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": "uVkv29hDtjCJnrSxN4b6BifbC7k229P7pzZXX3NVp1Rq9Tc8B6TU4NuJrANpecFfNfw2vmpApDoqMsxqY4x1sTF",
    "chain": "SOON",
    "chainId": 1151111081099710,
    "amount": 0.0018715,
     "usd": 5.2,
    "symbol": "ETH",
    "contract": "11111111111111111111111111111111"
  }
}
```

{% 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?  | Name of the payer (optional)                                                                                          |
| `email`              | string\* | Email of the payer (optional)                                                                                         |
| `message`            | string?  | Optional payment message                                                                                              |
| `payer`              | string\* | Wallet address (for crypto payments)                                                                                  |
| `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 Ramps service provider                                                      |
| `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)                                                                                             |
| `chain`              | string\* | Blockchain name (e.g., solana, ethereum)                                                                              |
| `symbol`             | string\* | Token symbol (e.g., USDT, USDC)                                                                                       |
| `contract`           | string?  | Contract address of the token                                                                                         |
| `amount`             | float\*  | Settled Token Amount (After Tax)                                                                                      |
| `reserveAmount`      | float?   | The reserve amount held for merchants with reserves enabled.                                                          |
| `afterReserveAmount` | float?   | Settled Token Amount (After Tax and Reserve)                                                                          |
| `usd`                | float\*  | Real-time USD pegged order amount (including FX spread, banking fees, and related service costs)                      |
| `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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coindpay.xyz/landing/start/developers/payments-order.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.