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

# Payment claims

> View, approve, and reject cryptocurrency payment claims submitted by customers. Payment claims go through a review workflow before transactions are created.

This API allows you to view, approve, and reject cryptocurrency payment claims submitted by customers.

## The payment claim object

<ResponseField name="id" type="string">
  Unique identifier with `pymt_claim_` prefix (e.g., `pymt_claim_abc123def456`).
</ResponseField>

<ResponseField name="object" type="string">
  Always `"payment_claim"`.
</ResponseField>

<ResponseField name="status" type="string">
  Claim status: `pending`, `approved`, or `rejected`.
</ResponseField>

<ResponseField name="amount" type="string">
  Claimed transaction amount.
</ResponseField>

<ResponseField name="transaction_id" type="string">
  Blockchain transaction hash provided by customer.
</ResponseField>

<ResponseField name="rejection_reason" type="string">
  Reason for rejection. `null` if not rejected.
</ResponseField>

<ResponseField name="approved_at" type="string">
  When the claim was approved or rejected (ISO 8601). `null` if pending.
</ResponseField>

<ResponseField name="customer_id" type="string">
  The customer who submitted the claim.
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code (e.g., `BTC`, `ETH`).
</ResponseField>

<ResponseField name="to_address_id" type="string">
  The receiving address ID.
</ResponseField>

<ResponseField name="to_address" type="string">
  The receiving address.
</ResponseField>

<ResponseField name="approved_by_id" type="integer">
  User ID who approved or rejected. `null` if pending.
</ResponseField>

<ResponseField name="crypto_transaction_id" type="string">
  Created transaction ID. `null` if not approved.
</ResponseField>

<ResponseField name="created_at" type="string">
  When the claim was submitted (ISO 8601).
</ResponseField>

<ResponseField name="updated_at" type="string">
  When the claim was last updated (ISO 8601).
</ResponseField>

## List payment claims

```
GET /v1/crypto_payment_claims
```

Retrieves a paginated list of all payment claims in your account. Claims are ordered by creation date (newest first).

<ParamField query="page" type="integer" default="1">
  Page number for pagination. Results are returned 25 items per page.
</ParamField>

<ParamField query="status" type="string">
  Filter by status. One of: `pending`, `approved`, `rejected`.
</ParamField>

```bash theme={null}
curl https://api.gettrxn.com/v1/crypto_payment_claims \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

#### Filtering by status

```bash theme={null}
curl "https://api.gettrxn.com/v1/crypto_payment_claims?status=pending" \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "crypto_payment_claims": [
    {
      "id": "pymt_claim_abc123def456",
      "object": "payment_claim",
      "status": "pending",
      "amount": "0.5",
      "transaction_id": "0x1234567890abcdef...",
      "rejection_reason": null,
      "approved_at": null,
      "customer_id": "cust_xyz789",
      "currency": "BTC",
      "to_address_id": "addr_abc123",
      "to_address": "bc1q...",
      "approved_by_id": null,
      "crypto_transaction_id": null,
      "created_at": "2025-01-25T12:00:00Z",
      "updated_at": "2025-01-25T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pages": 3,
    "count": 67
  }
}
```

## Get payment claim

```
GET /v1/crypto_payment_claims/:id
```

Retrieves a specific payment claim by ID.

<ParamField path="id" type="string" required>
  The payment claim's ID (e.g., `pymt_claim_abc123def456`).
</ParamField>

```bash theme={null}
curl https://api.gettrxn.com/v1/crypto_payment_claims/pymt_claim_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "id": "pymt_claim_abc123def456",
  "object": "payment_claim",
  "status": "pending",
  "amount": "0.5",
  "transaction_id": "0x1234567890abcdef...",
  "rejection_reason": null,
  "approved_at": null,
  "customer_id": "cust_xyz789",
  "currency": "BTC",
  "to_address_id": "addr_abc123",
  "to_address": "bc1q...",
  "approved_by_id": null,
  "crypto_transaction_id": null,
  "created_at": "2025-01-25T12:00:00Z",
  "updated_at": "2025-01-25T12:00:00Z"
}
```

## Approve payment claim

```
POST /v1/crypto_payment_claims/:crypto_payment_claim_id/approval
```

Approves a pending payment claim. This creates a corresponding crypto transaction record.

<ParamField path="crypto_payment_claim_id" type="string" required>
  The payment claim's ID (e.g., `pymt_claim_abc123def456`).
</ParamField>

```bash theme={null}
curl -X POST https://api.gettrxn.com/v1/crypto_payment_claims/pymt_claim_abc123def456/approval \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "id": "pymt_claim_abc123def456",
  "object": "payment_claim",
  "status": "approved",
  "amount": "0.5",
  "transaction_id": "0x1234567890abcdef...",
  "rejection_reason": null,
  "approved_at": "2025-01-25T14:30:00Z",
  "customer_id": "cust_xyz789",
  "currency": "BTC",
  "to_address_id": "addr_abc123",
  "to_address": "bc1q...",
  "approved_by_id": 123,
  "crypto_transaction_id": "trxn_new789xyz",
  "created_at": "2025-01-25T12:00:00Z",
  "updated_at": "2025-01-25T14:30:00Z"
}
```

### Error when claim is not pending

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Payment claim is not pending",
    "param": "status"
  }
}
```

## Reject payment claim

```
POST /v1/crypto_payment_claims/:crypto_payment_claim_id/rejection
```

Rejects a pending payment claim with an optional reason.

<ParamField path="crypto_payment_claim_id" type="string" required>
  The payment claim's ID (e.g., `pymt_claim_abc123def456`).
</ParamField>

<ParamField body="reason" type="string">
  Reason for rejection. Defaults to `"No reason provided"` if omitted.
</ParamField>

```bash theme={null}
curl -X POST https://api.gettrxn.com/v1/crypto_payment_claims/pymt_claim_abc123def456/rejection \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Transaction not found on blockchain"
  }'
```

```json Response theme={null}
{
  "id": "pymt_claim_abc123def456",
  "object": "payment_claim",
  "status": "rejected",
  "amount": "0.5",
  "transaction_id": "0x1234567890abcdef...",
  "rejection_reason": "Transaction not found on blockchain",
  "approved_at": "2025-01-25T14:30:00Z",
  "customer_id": "cust_xyz789",
  "currency": "BTC",
  "to_address_id": "addr_abc123",
  "to_address": "bc1q...",
  "approved_by_id": 123,
  "crypto_transaction_id": null,
  "created_at": "2025-01-25T12:00:00Z",
  "updated_at": "2025-01-25T14:30:00Z"
}
```

## Payment claim statuses

| Status     | Description                                     |
| ---------- | ----------------------------------------------- |
| `pending`  | Awaiting review -- can be approved or rejected. |
| `approved` | Payment verified and transaction created.       |
| `rejected` | Payment claim was rejected.                     |

## Workflow

1. Customer submits a payment claim via a payment claim link.
2. Claim appears with `pending` status.
3. Review the claim by checking the transaction on the blockchain.
4. Approve the claim (creates a crypto transaction) or reject it with a reason.
5. Approved claims can be allocated to invoices.

## Webhooks

The following webhook events are triggered for payment claims:

| Event                     | Description                    |
| ------------------------- | ------------------------------ |
| `payment_claim.submitted` | When a new claim is submitted. |
| `payment_claim.approved`  | When a claim is approved.      |
| `payment_claim.rejected`  | When a claim is rejected.      |

## Sandbox support

<Note>
  The API respects sandbox scoping. If your API token is associated with a sandbox, you can only access claims created in that sandbox. Approved and rejected claims are isolated from production data.
</Note>