Recurring Payments Flow

This flow allows a merchant to persist Clearpay as a payment method. There are two main flows, depending upon whether storing Clearpay as a payment method is in the context of a payment or not.

• If in the context of making a payment, the merchant adds billing agreement details into the Create Checkout call and Clearpay returns a billing agreement ID at the end of the purchase flow. The Merchant should follow flow 1b below.
• If NOT in the context of making a payment, the merchant utilizes the billing agreement approval flow, which is outlined in 1a below.

1a. Billing Agreement Approval Flow

1. Merchant calls the Setup Billing Agreement Approval endpoint to retrieve an Clearpay billing agreement approval token.
2. Merchant uses the token in combination with the JavaScript afterpay.js to direct the customer through the Clearpay screenflow.
3. Customer completes the Clearpay screenflow and is returned to the merchant website.

• If the customer clicks “confirm”, they will be returned to the merchant website with the billingAgreementApprovalToken and a status of “SUCCESS”.
• If the customer cancels, they will be returned to the merchant website with the billingAgreementApprovalToken and a status of “CANCELLED”.

4. Merchant calls the Create Billing Agreement endpoint to create the billing agreement.

• Merchant stores the token of the Agreement object, and presents the customer with a stored Clearpay account confirmation page.

1b. Checkout and Billing Agreement Approval Flow

This flow completes the payment and billing agreement approval, and starts the customer’s payment plan. If the merchant prefers to use Immediate Payment Flow, the full order amount is also settled to the merchant’s Clearpay Merchant Account. If the merchant prefers to use Deferred Payment Flow, settlement timing and amounts are determined by the merchant’s usage of the Capture Payment endpoint.

1. Merchant calls the Get Configuration endpoint to retrieve Clearpay order limits, possibly as part of an asynchronous scheduled background process.
2. Merchant stores these minimum and maximum order values server-side.
3. Separately, at the checkout, the merchant uses the stored Clearpay minimum and maximum order values to determine if Clearpay is presented as an available payment method.
4. Merchant calls the Create Checkout endpoint to retrieve an Clearpay order token. The payload for the Create Checkout endpoint includes an Agreement object telling Clearpay that the merchant would like to store Clearpay as a payment method for recurring payments.
5. Merchant uses the token in combination with the JavaScript afterpay.js to direct the customer through the Clearpay screenflow.
6. Customer completes the Clearpay screenflow and is returned to the merchant website.

• If the customer clicks “confirm”, they will be returned to the merchant website with the orderToken and a status of “SUCCESS”.
• If the customer cancels, they return to the merchant website with the orderToken and a status of “CANCELLED”.

7. Depending on if the merchant is utilizing Immediate Payment Flow or Deferred Payment Flow, the Merchant will call Capture Full Payment (Immediate Payment Flow) or Auth (Deferred Payment Flow).

• Payment status (“APPROVED” or “DECLINED”) is only known once Capture Full Payment or Auth has been completed.
• If the payment was approved by Clearpay, the merchant presents the customer with an order confirmation/receipt page.
• If the payment was declined by Clearpay (e.g. the customer’s card details are entered incorrectly), the merchant presents an appropriate message to the customer at the checkout.
• The merchant persists the ID returned in the Agreement object from the Capture Full Payment or Auth calls. This will be used when initiating recurring payments.

Once complete, at any point in the future, the merchant can complete a recurring payment utilizing Create Recurring Payment (Immediate Capture) as defined in 2a below, or utilizing Authorize Recurring Payment (Deferred Capture) as defined in 2b below. For more detail on the differences between Immediate Capture and Deferred Capture, please see Payment Flows.

2a. Create Recurring Payment (Immediate Capture)

This flow allows for a merchant to initiate payments from a customer who has previously agreed to a Billing Agreement via 1a or 1b above. Upon success, it starts the customer’s payment plan, and the full order amount is also settled to the merchant’s Clearpay Merchant Account. If the merchant prefers to use Deferred Payment Flow, settlement timing and amounts will be determined by the merchant’s usage of the Capture Payment endpoint.

1. Merchant calls the Get Configuration endpoint to retrieve Clearpay order limits, possibly as part of an asynchronous scheduled background process.
2. Merchant stores these minimum and maximum order values server-side.
3. Merchant calls the Create Recurring Payment (Immediate Capture) endpoint to capture the payment.

• Payment status (“APPROVED” or “DECLINED”) is only known once Create Recurring Payment (Immediate Capture) has been completed.
• If the payment was approved by Clearpay, the merchant contacts the customer with an order confirmation/receipt.
• If the payment was declined by Clearpay (e.g. the customer’s card could not be charged), the merchant communicates an appropriate message to the customer.

2b. Authorize Recurring Payment (Deferred Capture)

This flow allows for a merchant to initiate payments from a customer who has previously agreed to a Billing Agreement via 1a or 1b above. Upon success, it starts the customer’s payment plan. Settlement timing and amounts will be determined by the merchant’s usage of the Capture Payment endpoint.

1. Merchant calls the Get Configuration endpoint to retrieve Clearpay order limits, possibly as part of an asynchronous scheduled background process.
2. Merchant stores these minimum and maximum order values server-side.
3. Merchant calls the Authorize Recurring Payment (Deferred Capture) endpoint to confirm the order.

• Payment status (“APPROVED” or “DECLINED”) is only known once Authorize Recurring Payment (Deferred Capture) has been completed.
• If the payment was approved by Clearpay, merchant stores the id of the Payment, and the expires timestamp of the “AUTH_APPROVED” Payment Event, and contacts the customer with an order confirmation/receipt.
• If the payment was declined by Clearpay (e.g. the customer’s card could not be charged), the merchant communicates an appropriate message to the customer.

At this time, the merchant will call the Capture Payment endpoint to capture the authorization. Please see Deferred Payment Flow for more detail.