Skip to content
GRYPHEM PAYGRYPHEM PAYGRYPHEM PAY Docs

Get a payment intent

GET
/v1/payment-intents/{payment_intent_id}
const intent = await gp.paymentIntents.retrieve('pi_…');
if (intent.fulfillable) {
  // the expected amount is final on-chain — safe to deliver
}

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
payment_intent_id
required
string

Header Parameters

Section titled “Header Parameters”
Gryphem-Organization
string

Active organization for dashboard sessions. Ignored for API keys (the key determines the organization).

Responses

Section titled “Responses”

200

Section titled “200”

Payment intent with quote, instructions and totals.

Media typeapplication/json
object
id
required
string
object
required
string
Allowed value: payment_intent
livemode
required
boolean
organization_id
required
string
store_id
required
string
status
required
string
Allowed values: created awaiting_payment detected confirming confirmed underpaid overpaid expired late_payment reorged manual_review resolved failed canceled
status_reason
required
One of:

Machine-readable reason recorded with a payment intent state change (status_reason, state-event and timeline reason, webhook data.status_reason). created and quote_refreshed appear in state events; additional_payment_after_settlement only in payment.review_required event data for a transfer that arrived after the intent was settled; inconsistent_evidence marks evidence that supports no allowed transition (the state is held and operators are alerted). bitcart_* reasons mirror the Bitcart invoice status of intents processed through the platform’s Bitcart account.

string
Allowed values: created quote_locked quote_refreshed transfer_seen_in_mempool waiting_for_confirmations required_confirmations_reached received_less_than_quoted received_more_than_quoted payment_after_quote_expiry late_top_up_after_partial_payment expired_without_payment block_reorganized reorg_unresolved transaction_dropped transaction_dropped_after_inclusion payment_does_not_match_active_quote inconsistent_evidence canceled_by_merchant resolved_with_recorded_reason sandbox_forced_quote_expiry additional_payment_after_settlement bitcart_pending bitcart_paid_unconfirmed bitcart_paid_partial bitcart_confirmed bitcart_complete bitcart_paid_over bitcart_expired bitcart_expired_partial bitcart_invalid bitcart_failed_confirm bitcart_refunded bitcart_unknown_status
amount
required

Decimal string. Never a float.

string
/^(0|[1-9][0-9]*)(\.[0-9]+)?$/
currency
required
string
allowed_methods
required
Array<string>
Allowed values: crypto
allowed_networks
required
Array<string>
merchant_order_id
required
string | null
description
required
string | null
customer
required
object
email
required
string | null
reference
required
string | null
metadata
required
object
<= 20 properties
key
additional properties
string
<= 500 characters
return_url
required
string | null
cancel_url
required
string | null
checkout_session_id
required
string | null
checkout_url
required
string | null
source
required
string
Allowed values: api dashboard invoice payment_link demo
invoice_id
required
string | null
payment_link_id
required
string | null
expires_at
required
string format: date-time
created_at
required
string format: date-time
updated_at
required
string format: date-time
detected_at
required
string | null format: date-time
confirmed_at
required
string | null format: date-time
quote
required
One of:
object
id
required
string
object
required
string
Allowed value: quote
network_id
required
string
asset_id
required
string
asset_symbol
required
string
decimals
required
integer
fiat_amount
required

Decimal string. Never a float.

string
/^(0|[1-9][0-9]*)(\.[0-9]+)?$/
fiat_currency
required
string
asset_amount
required

Decimal string. Never a float.

string
/^(0|[1-9][0-9]*)(\.[0-9]+)?$/
asset_amount_base_units
required

Integer amount in the asset’s smallest unit.

string
/^[0-9]+$/
rate
required

Fiat major units per one whole asset unit.

string
rate_source
required
string
rate_source_version
required
string
secondary_source
required
string | null
deviation_bps
required
integer | null
sandbox_rate
required

True when the rate is a labelled illustrative value, not market data.

boolean
spread_bps
required
integer
rounding_policy
required
string
Allowed value: ceil_to_asset_base_unit
required_confirmations
required
integer
status
required
string
Allowed values: active superseded expired
locked_at
required
string format: date-time
expires_at
required
string format: date-time
network_fee_paid_by
required
string
Allowed value: customer
platform_fee_billed_separately
required
boolean
payment_instructions
required
One of:
object
network_id
required
string
asset_id
required
string
address
required
string
amount
required

Decimal string. Never a float.

string
/^(0|[1-9][0-9]*)(\.[0-9]+)?$/
amount_base_units
required

Integer amount in the asset’s smallest unit.

string
/^[0-9]+$/
payment_uri
required

BIP21 / EIP-681 style URI for wallet apps and QR codes.

string
contract_address
required
string | null
memo_required
required
boolean
totals
required
One of:
object
asset_id
required
string
decimals
required
integer
expected
required

Decimal string. Never a float.

string
/^(0|[1-9][0-9]*)(\.[0-9]+)?$/
expected_base_units
required

Integer amount in the asset’s smallest unit.

string
/^[0-9]+$/
received
required

Decimal string. Never a float.

string
/^(0|[1-9][0-9]*)(\.[0-9]+)?$/
received_base_units
required

Integer amount in the asset’s smallest unit.

string
/^[0-9]+$/
confirmed
required

Decimal string. Never a float.

string
/^(0|[1-9][0-9]*)(\.[0-9]+)?$/
confirmed_base_units
required

Integer amount in the asset’s smallest unit.

string
/^[0-9]+$/
remaining
required

Decimal string. Never a float.

string
/^(0|[1-9][0-9]*)(\.[0-9]+)?$/
remaining_base_units
required

Integer amount in the asset’s smallest unit.

string
/^[0-9]+$/
required_confirmations
required
integer | null
resolution
required
One of:
object
kind
required
string
Allowed values: accepted accepted_partial accepted_overpayment refunded_offchain rejected
note
required
string
actor_type
required
string
actor_id
required
string | null
resolved_at
required
string format: date-time
fulfillable
required

True only when the expected amount is final on-chain (confirmed / overpaid, or resolved as accepted).

boolean
processor
required
One of:

Present when the intent is processed through the platform’s Bitcart account: custodial, the customer pays platform wallets and the funds are owed to the merchant (see /v1/balances).

object
name
required
string
Allowed values: bitcart
custodial
required
boolean
status
required

Bitcart invoice status: not_started until the checkout opens the invoice, then pending, paid, confirmed, complete, expired, invalid or refunded.

string
exception_status
required

None, paid_partial, paid_over or failed_confirm.

string
processor_invoice_id
required
string | null
expires_at
required
string | null format: date-time
paid_asset
required
string | null
sent_amount
required
string | null
tx_hashes
required
Array<string>
credited
required

The received funds were credited to the merchant balance.

boolean
methods
required
Array<object>
object
asset
required

Asset key: coin symbol, plus the chain for tokens (btc, usdt-eth).

string
symbol
required
string
chain
required
string
name
required
string
amount
required

Exact decimal amount to send in this asset.

string
rate
required

Exchange rate Bitcart used (invoice currency per unit of the asset).

string
address
required
string
payment_url
required

Wallet URI (BIP21 / EIP-681 style) for QR codes.

string
divisibility
required
integer
contract
required
string | null

Example 

{
  "object": "payment_intent",
  "status": "created",
  "status_reason": "created",
  "amount": "59.90",
  "allowed_methods": [
    "crypto"
  ],
  "source": "api",
  "quote": {
    "object": "quote",
    "fiat_amount": "59.90",
    "asset_amount": "59.90",
    "asset_amount_base_units": "99834",
    "rounding_policy": "ceil_to_asset_base_unit",
    "status": "active",
    "network_fee_paid_by": "customer",
    "platform_fee_billed_separately": true
  },
  "payment_instructions": {
    "amount": "59.90",
    "amount_base_units": "99834"
  },
  "totals": {
    "expected": "59.90",
    "expected_base_units": "99834",
    "received": "59.90",
    "received_base_units": "99834",
    "confirmed": "59.90",
    "confirmed_base_units": "99834",
    "remaining": "59.90",
    "remaining_base_units": "99834"
  },
  "resolution": {
    "kind": "accepted"
  },
  "processor": {
    "name": "bitcart"
  }
}

401

Section titled “401”

Missing or invalid credentials.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error
code
required
string
message
required
string
param
string
request_id
required
string

Example 

{
  "error": {
    "type": "invalid_request_error"
  }
}

403

Section titled “403”

Authenticated but not permitted.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error
code
required
string
message
required
string
param
string
request_id
required
string

Example 

{
  "error": {
    "type": "invalid_request_error"
  }
}

404

Section titled “404”

Resource not found (or not visible to this tenant).

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error
code
required
string
message
required
string
param
string
request_id
required
string

Example 

{
  "error": {
    "type": "invalid_request_error"
  }
}

429

Section titled “429”

Too many requests. See Retry-After.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error
code
required
string
message
required
string
param
string
request_id
required
string

Example 

{
  "error": {
    "type": "invalid_request_error"
  }
}

Headers

Section titled “Headers”
Retry-After
integer