Get Payment Status

POST

/payments/status

Retrieves detailed information about a specific payment by its ID. This endpoint automatically checks for updates from the payment processor for pending or processing payments before responding.

Request Parameters

Parameter	Type	Description
transaction_id required	string	The unique identifier of the transaction to retrieve

Example Request

POST /payments/status
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Parameters

Parameter	Type	Description
transaction_id	string	Unique identifier for the transaction
status	string	Current status of the payment (see Status Values table below)
payment_type	string	Type of payment based on amount received: "full", "partial", or "overpayment"
amount_usd	number	The payment amount in USD
amount_crypto	number	The payment amount in cryptocurrency
blockchain	string	The blockchain network used for the payment
token	string	The cryptocurrency token used for payment
address	string	The cryptocurrency address for the payment
tx_hash	string	The blockchain transaction hash (if payment is confirming, confirmed, or completed)
created_at	string	ISO 8601 timestamp of when the payment was created
updated_at	string	ISO 8601 timestamp of when the payment was last updated
expiry_time	string	ISO 8601 timestamp of when the payment request expires
custom_id	string	Your custom identifier for the payment (if provided)
customer_email	string	Email address of the customer (if provided)
callback_url	string	URL for callback notifications (if provided)
callback_sent	boolean	Indicates whether a callback notification has been sent
notes	string	Additional notes about the payment (if provided)

Example Response

{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "payment_type": "full",
  "amount_usd": 100.00,
  "amount_crypto": 0.05,
  "blockchain": "ETH",
  "token": "USDT",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "created_at": "2025-04-16T13:30:25.123Z",
  "updated_at": "2025-04-16T14:45:30.456Z",
  "expiry_time": "2025-04-16T14:30:25.123Z",
  "custom_id": "ORDER-12345",
  "customer_email": "[email protected]",
  "callback_url": "https://your-site.com/payment/callback",
  "callback_sent": true,
  "notes": null
}

Status Values

Status	Description
pending	Initial state, waiting for payment
partially_paid	Some funds received, but less than expected amount
confirming	Full payment received, waiting for blockchain confirmations
confirmed	Payment has received the required number of confirmations
completed	Payment has been fully confirmed and processed
failed	Payment failed due to technical issues
expired	Payment time window has elapsed without receiving full payment

Payment Type Values

Payment Type	Description
full	The received amount matches the expected amount exactly
partial	The received amount is less than the expected amount
overpayment	The received amount exceeds the expected amount

Webhook Events

When a payment status changes, a webhook notification is sent to your callback URL with the standardized event type payment_status_update. See our Implementing Webhook Callbacks guide for details.

Error Codes

Status Code	Error Code	Description
400	invalid_request	The request was malformed or missing required parameters
401	authentication_failed	Authentication failed. Check your API key or OAuth 2.0 access token
403	insufficient_permissions	Your API key does not have permission to view this payment
404	transaction_not_found	Transaction with the specified ID was not found
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint
500	payment_provider_error	An error occurred when checking the payment status with the payment processor

Notes

• This endpoint replaces the previous GET /payments/:paymentId endpoint.
• When checking a payment with status pending, partially_paid, or confirming, this endpoint will automatically check for updates from the payment processor before responding.
• The tx_hash field is only populated once a transaction has been identified on the blockchain.
• The payment_type field helps identify whether the customer sent the exact amount, less than expected (partial payment), or more than expected (overpayment).
• For completed payments, you can view the blockchain transaction details directly using a blockchain explorer by following the tx_hash.
• Payments typically remain in the system for at least 30 days after completion or expiration.
• The status values match those used in webhook notifications, providing a consistent status lifecycle across the API.

iGaming Integration Note

This endpoint is essential for online casino platforms to verify deposit confirmations. After a player initiates a deposit, periodically poll this endpoint to check the payment status and update the player's balance once the status becomes completed.