Payment Life Cycles

Overview

As discussed in the Basic Integration: Process Payments article, payments can go through various life cycles prior to landing in one of the three closing statuses: completed, failed, or canceled.

Fig. 1: A payment is created with the auto_capture parameter set to false and processes successfully.
Fig. 2: A payment is created with the auto_capture parameter set to false and then cancels.
Fig. 3: A payment is created with the auto_capture parameter set to true and processes successfully.
Fig. 4: An ACH payment is created and processes successfully.
Fig. 5: Any payment is created and then fails.
Fig. 6: A payment is created, enters manual review, and then processes successfully.
Fig. 7: A payment is created, enters manual review, and then fails.
Fig. 8: A payment is created, processes successfully, and is the held in the account's reserved balance.
Fig. 9: A payment is created, processes successfully, and is then refunded.
Fig. 10: A payment is created, processes successfully, and is then disputed.



Closing Status: completed

Before a given payment lands in the completed closing status, there are 7 possible different payment lifecycles it could go through.

1. A payment is created with the auto_capture parameter set to false and processes succesfully.

see Fig. 1

2. A payment is created, gets queued for a manual review by WePay, and passes review successfully.

see Fig. 6

  • Call POST /payments.
  • WePay sends the payments.in_review notification (must be subscribed) and the payment is in a pending status.
  • The payment passes WePay review.
  • WePay sends the payments.completed notification (must be subscribed) and the payment moves to a completed status.

3. A payment is processed successfully and then gets held in reserves.

see Fig. 8

  • Call POST /payments.
  • The payment goes through any lifecycle ending in the completed closing state.
  • Use the owner.path parameter value to call GET /accounts/{id}.
  • Examine the account’s balances.currencies.{currency}.reserve; if there is a reserve balance greater than 0, then reconcile the completed payment against the reserve balance.

4. An ACH payment is created and processes successfully.

see Fig. 4

  • Call POST /payments with a payment_bank_us payment method or token.
  • The ACH payment will be in a standard 2 business day hold and have a pending status.
  • Assuming that no manual review by WePay is required, WePay sends the payments.completed notification (must be subscribed) and the ACH payment will move into a completed status.

5. A payment is created with the auto_capture parameter set to true and processes successfully.

see Fig. 3

  • Call POST /payments (the auto_capture parameter can be set to true or omitted from the call).
  • If the payment queues for a manual review from WePay, then WePay sends the payments.in_review notification (must be subscribed) and the payment is in a pending status.
  • If the payment queued for a manual review from WePay, then WePay sends the payments.completed notification (must be subscribed) and the payment moves to a completed status.
  • If the payment did not queue for a manual review from WePay, then WePay sends the payments.completed notification (must be subscribed) and the payment moves to a completed status right away.

6. A payment is created, processes successfully, and is then refunded.

see Fig. 9

  • Consider any of the above life cycles with a payment in a completed status.
  • A refund needs to be issued, so your platofmr calls POST /refunds.
  • The payment API object will remain in a completed status, but the amount_refundable will change according to the refund’s amount.

7. A payment is created, processes successfully, and is then disputed.

see Fig. 10

  • Consider any of the above life cycles with a payment in a completed status.
  • The card issuer starts the chargeback process, and a dispute is created.
  • WePay sends the disputes.created notification (must be subscribed).
  • Call GET /disputes/{id} using to the ID provided in the notification.
  • The payment will remain in a completed status, and the outcome of the dispute will be reflected in the dispute’s status.

 

Closing Status: failed

Before a given payment lands in the failed closing status, there are few possible different payment lifecycles it could go through.

1. A payment synchronously fails.

see Fig. 5

2. A credit card or ACH payment asynchronously fails WePay’s manual review.

see Fig. 7

  • Call POST /payments
  • WePay sends the payments.in_review notification (must be subscribed) and the payment is in a pending status.
  • The payment fails manual review, WePay sends the payments.failed notification (must be subscribed), and the payment is in a failed status.
  • In response to the notification, your platform should make a GET /payments/{id} call. The following will return in the failure_reason parameter:
{
  "failure_reason": {
    "reason_code": "REVIEW",
    "reason_message": "Failed to capture the payment.",
    "details": {
      "detail_code": "risk_review",
      "detail_message": "The payment could not be captured as it failed risk review"
     }
   }
}

3. An ACH payment asynchronously fails.

see Fig 5

  • Call POST /payments.
  • The payment is in a pending status.
  • WePay will send the payments.failed notification (must be subscribed), and the payment is in a failed status.
  • In response to the notification, your platform should make a GET /payments/{id} call.
  • WePay will return one of the following ACH-specific failure_reason.reason_code values:
    • ECHECK_FRAUD
    • BANK_NOT_CONFIRMED
    • BANK_SYSTEM_ERROR
  • Examine the ACH failure details for guidance on next steps.

Here’s an example of ACH-specific failure_reason JSON:

{
  "failure_reason": {
    "reason_code": "BANK_NOT_CONFIRMED",
    "reason_message": "Failed to capture the payment due to incorrect information",
    "details": {
      "detail_code": "R04",
      "detail_message": "Invalid account number"
    }
  }
}

4. A credit card payment asynchronously fails.

see Fig. 5

  • Call POST /payments.
  • The payment may or may not go into a pending status.
  • WePay will send the payments.failed notification (must be subscribed), and the payment will be in a failed status.
  • In response to the notification, your platform should make a GET /payments/{id} call.
  • WePay will return the following credit-card-specific failure_reason JSON:
{
  "failure_reason": {
    "reason_code": "NOT_CAPTURED",
    "reason_message": "Failed to capture the payment",
    "details": {
      "detail_code": "XX",
      "detail_message": "XX"
    }
  }
}
  • For more information on credit-card-specific details values, see their possible values.

 

Closing Status: canceled

Before a given payment lands in the canceled closing status, there are a few possible different payment lifecycles it could go through.

1. A payment is created with the auto_capture parameter set to false and a POST /payments/{id}/cancel call is made.

see Fig. 2

  • Call POST /payments with the auto_capture parameter set to false.
  • The payment will be in a pending status.
  • Call POST /payments/{id}/cancel.
  • WePay will send the payments.canceled notification (must be subscribed), and the payment will be in a canceled status.