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
Session holds the payment authorization from the consumer.
| Event | Description |
|---|---|
| created | The session has been created with the consumer information by the seller. |
| consumer_connected | The consumer has verified and linked their phone number. |
| fi_account_connected | The consumer has linked a bank account. |
| authorized | The consumer has completed the authorization. |
| authorize_failed | The consumer authorization has failed. Possible error scenarios are documented here. |
| finalized | The 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. |
Errors
| Error code | Description |
|---|---|
| invalid_session_type | Session type is not 'consumer_checkout' |
| session_not_started | Session authorization hasn't been started by the customer yet, and the session is not in the started status |
| session_not_finalizable | Session has not been authorized by the customer yet and is not in the completed status (authorized event hasn't been called yet) |
Order
Order holds the order information in the seller's order management system, along with the Session authorization.
| Event | Description |
|---|---|
| created | The seller has created an order. |
| total_finalized | A balance check has been run again, with the change in order amount. |
| canceled | The order has been cancelled by the seller. |
| charged | The seller has captured the payment. A charge is also created at this point, hence the charge.created event is also emitted. |
Errors
| Error code | Description |
|---|---|
| order_not_total_finalizable | Order wasn't successfully created with the submitted status. |
| order_not_chargable | Order not in total_finalized status, hence it cannot be charged. |
| order_amount_zero | A charge was created on a total amount(sum of order amount, tip and fee) of zero. |
| consumer_insufficient_balance | Consumer did not have sufficient balance when trying to finalize the order amount |
| order_not_cancelable | The order has already been charged or canceled |
Charge
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.
| Event | Description |
|---|---|
| created | Swifter has initiated an ACH transaction. |
| succeeded | The ACH transaction has been successful. |
| failed | The ACH transaction has returned. |
Errors
| Error code | Description |
|---|---|
| missing_consumer | Missing reference to the consumer info in the order entity |
| missing_consumer_fi_account | Missing reference to the consumer bank account details in the order entity |
| missing_business_fi_account | Missing reference to the seller's bank account details in the order entity |
| charge_not_retryable | The charge is not in the failed status |
| charge_not_in_retryable_period | The charge was created before 30 days and has crossed the retryable period |