Payee Choice States

Overview

This page documents the states associated with Payee Choice payments.

Note that the webhooks identified below are not the full list – only the ones associated with the states are outlined here. The full list of available webhooks is in Event Reference.

Payment Request States

The corresponding transaction status is displayed where available. Where the transaction has not yet been created, the transaction state is shown as n/a.

State	isEndState	Description	Webhook	Corresponding Transaction state
Created		The Payment Request was structurally correct and recorded		n/a
Invalid	X	The Payment Request was structurally accurate but contained invalid entries		n/a
Initiated		The Payment Request passed validation and was accepted	PaymentRequestInitiated	n/a
Input Needed		Awaiting recipient information, capture process active	See Recipient Capture States	n/a
Unsuccessful Input	X	Recipient information can no longer or will not be provided		n/a
Pending		The Payment Request has all information required to begin processing		n/a
Processing		The Payment Request is processing and attempting to create a transaction	See Processing States	Pending, Grouping, Payment, Queued, Risk, CancellationReq
Succeeded	X (most)	The Payment Request created a transaction, processed and paid out; end state unless returned	PaymentRequestSucceeded	Succeeded
Returned	X	Paid out transaction returned to Vitesse	PaymentRequestTransactionReturned	Returned
Failed	X	The Payment Request could not be processed	PaymentRequestFailed	Failed, No TX, Invalid
Cancelled	X	The Payment Request was cancelled before entering Processing	PaymentRequestCancelled	Cancelled

📘
A payment request can be cancelled only if it is in one of the following states: Initiated, Input Needed, Pending. After a Payment Request has generated a Transaction, only the Transaction can be cancelled.

Recipient Capture States

Recipient Capture State	isEndState	Description	Webhooks	Corresponding Payment Request state	Corresponding Transaction state
Active		Awaiting action from recipient		Input Needed	n/a
Completed	X	Recipient has provided payment method	RecipientCaptureCompleted	Pending, Processing, Succeeded, Returned, Failed, Cancelled
Cancelled	X	Payment Request cancelled	RecipientCaptureCancelled	Cancelled
Expired	X	Link expired	RecipientCaptureExpired	n/a
Declined	X	Recipient refused the payment	RecipientCaptureDeclined	Unsuccessful Input
Blocked	X	5 incorrect passphrases entered	RecipientCaptureBlocked	Unsuccessful Input

Processing States

Processing State	Description	Webhook	Corresponding PR State	Corresponding Transaction Status
Pending	Awaiting processing to commence (scheduled for specific date/time)		Processing	n/a
In Process	Processing of the PR has commenced		Processing	n/a
Aborted	Processing stopped without a Transaction being created		Pending	n/a
Transaction Created	PR successfully created a Transaction	PaymentRequestTransactionCreated	Processing, Succeeded, Returned, Failed	Pending, PendingGrouping, PendingPayment, Queued, Risk, CancellationRequested