Payment Lifecycles

In this article, we'll discuss the different lifecycles a payment can go through.

We'll first talk about a payment from our perspective to help you understand payment flows. Once a payment is created, it will end with one of the below statuses:

• completed: The payment has processed and can be found either in the available or reserved balance of the account.
• canceled: The payment has been canceled by the platform and will not show in the account's balance.
• failed: The payment has not processed due to either an error or a decline.

Payments will progress through the different statuses according to the Payment Status Flow below:  

Payment Flows

It's important to first think about the user experience for payers paying on your Platform. Are they going to input credit card information every time they wish to pay for a good or service? Or will they add a credit card one-time to your platform, which you'll then charge for every payment? Does your platform have a recurring monthly payment option? Use the table below as an approximate guide to figure out which payment flow you'll need.

When interfacing with the /payments and /payment_methods endpoints, you have an option to collect data using tokenization, instead of capturing raw information like credit card numbers. We always recommend using Tokenization, but will cover both methods. Note, we currently support credit cards and bank accounts as accepted form of payments.

Payment Status

Closing Status: completed

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

• Call POST /payments.
• Payment is in a pending status.
• Call POST /payments/{id}/capture within 7 days.
• Payment is in a completed status.

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

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

2.5 A payment is created with the auto_capture parameter set to false, gets queued for manual review, and passes review successfully,

• Call POST /payments.
• We send the payments.in_review notification (must be subscribed) and the payment is in a pending status.
• The payment passes our review.
• We send the payments.manual_review_passed notification (must be subscribed).
• Call POST /payments/{id}/capture.
• Payment is in a completed status.

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

• Call POST /payments.
• The payment goes through any lifecycle ending in the completed closing state.
• We recommend you check the transaction status in Partner Center. It will have a status of COMPLETED - RESERVED when completed.
• For more information on reserves, please see our Risk Certification and How Payouts Work guides.

4. An ACH payment is created and processes successfully.

• 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 us is required, we send 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.

• 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 us:
  • We send the payments.in_review notification (must be subscribed) and the payment is in a pending status.
  • Once the review is completed successfully, we send the payments.manual_review_passed notification (must be subscribed) and the payment moves to a completed status.
• If the payment did not queue for a manual review from us, then we send 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.

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

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

• 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.
• We send 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

1. A payment synchronously fails.

• Call POST /payments.
• We may respond with any of the following payment-specific API error codes:
  • MERCHANT_ACCOUNT_CANNOT_ACCEPT_PAYMENTS
  • TRANSACTION_DECLINED
  • UNSUPPORTED_CURRENCY

2. A credit card or ACH payment asynchronously fails our manual review.

• Call POST /payments
• We send the payments.in_review notification (must be subscribed) and the payment is in a pending status.
• The payment fails manual review, we send the payments.failed notification (must be subscribed), and the payment is in a failed status.
• In response to the notification, we recommend that your platform either examine the payload.failure_reason structure, or 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.

• Call POST /payments.
• The payment is in a pending status.
• We will send the payments.failed notification (must be subscribed), and the payment is in a failed status.
• In response to the notification, we recommend that your platform make a GET /payments/id call.
  • We 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.

{
  "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.

• Call POST /payments.
• The payment may or may not go into a pending status.
• We will send the payments.failed notification (must be subscribed), and the payment will be in a failed status.
• In response to the notification, we recommend that your platform make a GET /payments/id call.
  • We 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

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

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