The lifecycle of payments on Swifter


Payment lifecycle

A Swifter ACH payment comprises of the three objects - Session, Order and Charge, which represent the auth and capture workflow. The various states that these objects transition through in the payment lifecycle, are detailed below. These events are exposed as Webhooks.


Session holds the payment authorization from the consumer.

createdThe session has been created with the consumer information by the seller.
consumer_connectedThe consumer has verified and linked their phone number.
fi_account_connectedThe consumer has linked a bank account.
authorizedThe consumer has completed the authorization.
authorize_failedThe consumer authorization has failed. Possible error scenarios are documented here.
finalizedThe seller has acknowledged the authorization. This happens automatically during the creation of an order, hence this event is emitted along with the order.created event.


Error codeDescription
invalid_session_typeSession type is not 'consumer_checkout'
session_not_startedSession authorization hasn't been started by the customer yet, and the session is not in the started status
session_not_finalizableSession has not been authorized by the customer yet and is not in the completed status (authorized event hasn't been called yet)


Order holds the order information in the seller's order management system, along with the Session authorization.

createdThe seller has created an order.
total_finalizedA balance check has been run again, with the change in order amount.
canceledThe order has been cancelled by the seller.
chargedThe seller has captured the payment. A charge is also created at this point, hence the charge.created event is also emitted.


Error codeDescription
order_not_total_finalizableOrder wasn't successfully created with the submitted status.
order_not_chargableOrder not in total_finalized status, hence it cannot be charged.
order_amount_zeroA charge was created on a total amount(sum of order amount, tip and fee) of zero.
consumer_insufficient_balanceConsumer did not have sufficient balance when trying to finalize the order amount
order_not_cancelableThe order has already been charged or canceled


Charge holds the captured payment information for the Order. Since ACH transactions are asynchronous and can take between 2-5 days for a transaction to be completed, it is a process fully managed by Swifter, and the state changes are held in the Charge object.

createdSwifter has initiated an ACH transaction.
succeededThe ACH transaction has been successful.
failedThe ACH transaction has returned.


Error codeDescription
missing_consumerMissing reference to the consumer info in the order entity
missing_consumer_fi_accountMissing reference to the consumer bank account details in the order entity
missing_business_fi_accountMissing reference to the seller's bank account details in the order entity
charge_not_retryableThe charge is not in the failed status
charge_not_in_retryable_periodThe charge was created before 30 days and has crossed the retryable period