Skip to content
GRYPHEM PAYGRYPHEM PAYGRYPHEM PAY Docs

Payment needs a decision

POST

Sent for underpaid, overpaid (together with payment.confirmed), late-payment and manual-review states, and when a transfer arrives after the intent was settled (status_reason: additional_payment_after_settlement).

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Gryphem-Signature
required
string
/^t=[0-9]+(,v1=[0-9a-f]{64})+$/

t=<unix seconds>,v1=<hex> — HMAC-SHA256 keyed with the endpoint’s full whsec_… secret over <t>.<raw request body>. While a rotated secret is still valid, one v1= value is sent per valid secret: accept the delivery if any value matches (constant-time comparison) and reject timestamps outside your tolerance (the official SDKs default to 300 seconds).

Example 

t=1760961600,v1=186aa47526353adc39a808f8e0bd84f501a5a6a1f483572b1f8a3eab3ed44cc8
Gryphem-Event-Id
required
string

Same as event_id in the body. Delivery is at-least-once — deduplicate on this value.

Gryphem-Event-Type
required
string
Allowed values: payment_intent.created invoice.awaiting_payment payment.detected payment.confirming payment.confirmed payment.expired payment.review_required payment.reorged payment.resolved payment.canceled webhook.test merchant.verification_updated payout.requested payout.approved payout.rejected payout.canceled payout.sent payout.completed payout.failed
Gryphem-Delivery-Id
required
string

One delivery per event and endpoint; the id stays the same across retries.

Gryphem-Delivery-Attempt
required
integer
>= 1

1 for the first attempt, incremented on every retry.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Body of the payment.review_required webhook.

object
event_id
required
string
event_type
required
string
Allowed values: payment_intent.created invoice.awaiting_payment payment.detected payment.confirming payment.confirmed payment.expired payment.review_required payment.reorged payment.resolved payment.canceled webhook.test merchant.verification_updated payout.requested payout.approved payout.rejected payout.canceled payout.sent payout.completed payout.failed
api_version
required
string
created_at
required
string format: date-time
merchant_id
required
string
store_id
required
string | null
environment
required
string
Allowed values: test live
object
required
object
type
required
string
id
required
string
event_type
required
string
Allowed value: payment.review_required
object
required
object
type
required
string
Allowed value: payment_intent
id
required
string
data
required
One of:

Snapshot of the payment intent right after the transition (data of payment.* events and invoice.awaiting_payment).

object
status
required
string
Allowed values: created awaiting_payment detected confirming confirmed underpaid overpaid expired late_payment reorged manual_review resolved failed canceled
previous_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

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 amount in currency, e.g. 59.90.

string
currency
required
string
merchant_order_id
required
string | null
fulfillable
required

True for confirmed and overpaid, and for resolved with an accepting resolution — the expected amount is final, so goods may be delivered.

boolean
quote
required
One of:
null
totals
required
One of:
null

Responses

Section titled “Responses”

2XX

Section titled “2XX”

Any 2xx response within 10 seconds marks the delivery as succeeded. The response body is only kept as a short excerpt for troubleshooting.

default

Section titled “default”

Any other outcome — a non-2xx status, a redirect (never followed), a timeout or a network error — is retried with exponential backoff (base × 2^(attempt − 1), capped at 6 hours, with 50–100% jitter; 10 attempts in the default configuration) and then moved to the dead-letter queue. 410 Gone stops retries immediately.