Payment claims

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

The payment claim object

string

Unique identifier with pymt_claim_ prefix (e.g., pymt_claim_abc123def456).

string

Always "payment_claim".

string

Claim status: pending, approved, or rejected.

string

Claimed transaction amount.

string

Blockchain transaction hash provided by customer.

string

Reason for rejection. null if not rejected.

string

When the claim was approved or rejected (ISO 8601). null if pending.

string

The customer who submitted the claim.

string

Currency code (e.g., BTC, ETH).

string

The receiving address ID.

string

The receiving address.

integer

User ID who approved or rejected. null if pending.

string

Created transaction ID. null if not approved.

string

When the claim was submitted (ISO 8601).

string

When the claim was last updated (ISO 8601).

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).

integer

default:"1"

Page number for pagination. Results are returned 25 items per page.

string

Filter by status. One of: pending, approved, rejected.

curl https://api.gettrxn.com/v1/crypto_payment_claims \
  -H "Authorization: Bearer $TRXN_TOKEN"

Filtering by status

curl "https://api.gettrxn.com/v1/crypto_payment_claims?status=pending" \
  -H "Authorization: Bearer $TRXN_TOKEN"

Response

{
  "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.

string

required

The payment claim’s ID (e.g., pymt_claim_abc123def456).

curl https://api.gettrxn.com/v1/crypto_payment_claims/pymt_claim_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN"

Response

{
  "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.

string

required

The payment claim’s ID (e.g., pymt_claim_abc123def456).

curl -X POST https://api.gettrxn.com/v1/crypto_payment_claims/pymt_claim_abc123def456/approval \
  -H "Authorization: Bearer $TRXN_TOKEN"

Response

{
  "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

{
  "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.

string

required

The payment claim’s ID (e.g., pymt_claim_abc123def456).

string

Reason for rejection. Defaults to "No reason provided" if omitted.

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"
  }'

Response

{
  "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

Customer submits a payment claim via a payment claim link.
Claim appears with pending status.
Review the claim by checking the transaction on the blockchain.
Approve the claim (creates a crypto transaction) or reject it with a reason.
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

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.

Introduction

Core resources

Billing

Crypto

Webhooks

Payment claims

The payment claim object

List payment claims

Filtering by status

Get payment claim

Approve payment claim

Error when claim is not pending

Reject payment claim

Payment claim statuses

Workflow

Webhooks

Sandbox support

​The payment claim object

​List payment claims

​Filtering by status

​Get payment claim

​Approve payment claim

​Error when claim is not pending

​Reject payment claim

​Payment claim statuses

​Workflow

​Webhooks

​Sandbox support

The payment claim object

List payment claims

Filtering by status

Get payment claim

Approve payment claim

Error when claim is not pending

Reject payment claim

Payment claim statuses

Workflow

Webhooks

Sandbox support