Afterpay and Clearpay Payments

Applications take Afterpay payments (Clearpay in the UK) using a combination of the Web Payments SDK and the Payments API. This topic explains how to use the Payments API CreatePayment endpoint on your backend to process an Afterpay or Clearpay payment. The client side is explained in Take Afterpay and Clearpay Payments. This topic refers to Afterpay and Clearpay as "Afterpay" because the same API, calling pattern, and values are used with both payment types.

In a CreatePayment request, use a Web Payments SDK payment token that represents Afterpay in the source_id field. Creating an Afterpay payment is a two-step process:

1. Generate a payment token - Your web application uses the Web Payments SDK to get an Afterpay payment token. The SDK provides the UI for the buyer to sign in to Afterpay, provides Afterpay with the cart information and checkout amount, and returns the payment token.

   Note

   The Web Payments SDK displays the Afterpay payment option only if the seller is eligible. Eligibility can be checked using the Web Payments SDK. For more information, see Check for eligibility and limitations.

2. Charge the payment token - The backend of your application makes a CreatePayment call to charge the payment token. The amount you charge must be equal to the checkout amount provided to Afterpay.

   The following shows an example CreatePayment request. The request charges $100 USD to Afterpay. The source_id field identifies Afterpay as the payment source.

   curl https://connect.squareupsandbox.com/v2/payments \
     -X POST \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Content-Type: application/json' \
     -d '{
       "idempotency_key": "{UNIQUE_KEY}",
       "source_id": "{PAYMENT_TOKEN}",
       "amount_money": {
         "amount": 10000,
         "currency": "USD"
       }
     }'

   The response is as follows:

   {
     "payment": {
       "id": "LdEGliYQbua2JINaY5npuXBnD6JZY",
       "created_at": "2021-11-30T16:54:22.271Z",
       "updated_at": "2021-11-30T16:54:22.492Z",
       "amount_money": {
         "amount": 10000,
         "currency": "USD"
       },
       "status": "COMPLETED",
       "delay_duration": "PT168H",
       "source_type": "BUY_NOW_PAY_LATER",
       "location_id": "7WQ0KXC8ZSD90",
       "order_id": "86wAYurd4ugT2BpnNptXanXnVhdZY",
       "total_money": {
         "amount": 10000,
         "currency": "USD"
       },
       "approved_money": {
         "amount": 10000,
         "currency": "USD"
       },
       "receipt_number": "LdEG",
       "receipt_url": "https://squareupsandbox.com/receipt/preview/LdE...EXAMPLE",
       "delay_action": "CANCEL",
       "delayed_until": "2021-12-07T16:54:22.271Z",
       "application_details": {
         "square_product": "ECOMMERCE_API",
         "application_id": "sq0ids-cH-HBFPwv9peECeXONN_uw"
       },
       "buy_now_pay_later_details": {
         "brand": "AFTERPAY",
         "afterpay_details": {
           "email_address": "[email protected]"
         }
       },
       "version_token": "3SM0bM7g6eZlfhgAOZV9kL8sgoGDBDOcA2VnkiHRnjx6o"
     }
   }

   The following are important response details:

   • source_type indicates the payment source as "BUY_NOW_PAY_LATER".
   • buy_now_pay_later_details appears in the resulting Payment only for the Afterpay payments.
   • email_address is the email of the Afterpay account holder, which is the buyer making the purchase.

To test Afterpay payments in the Square Sandbox, get a test payment token using one of the following methods:

• Use a Square-provided Afterpay payment token - Square provides Afterpay Sandbox payment tokens as source_id values for testing the backend component of your application.

  Use the following test payment tokens as source_id in CreatePayment requests for testing Afterpay payments in the Sandbox.

  source_id value	Error mapping	Expected behavior
  wnon:afterpay-or-clearpay-ok		The request is successful.
  wnon:afterpay-or-clearpay-declined	GENERIC_DECLINE	The request failed.

  When you use these tokens, you can test CreatePayment calls without charging an actual Afterpay account or running the client side of your application. The tokens don't represent a live Afterpay account. However, the CreatePayment endpoint returns a payment response as if the account is real.

  Note

  Be sure to make the CreatePayment call against your Square Sandbox environment (connect.squareupsandbox.com) when using these tokens.

• Run the Web Payments SDK sample application to generate a payment token - The sample provides an end-to-end Afterpay payment experience. For information about building and running the sample, see Take Afterpay and Clearpay Payments.

  1. Create an Afterpay test customer account - Use this test account to log in to Afterpay. For more information about creating an Afterpay test account and test credit card, see Afterpay Sandbox Guide.

  2. Set up a web application - Integrate the Web Payments SDK into your application.

  3. Use the Afterpay-provided credit card to make a card payment to Afterpay - After the buyer confirms the entire installment plan and provides a credit card for the first installment, Afterpay returns the confirmation to the Web Payments SDK. The SDK then generates a payment token.

  4. Create a payment using the Payments API - The application calls CreatePayment (Payments API) in the Square Sandbox by specifying the payment token.

     The payment token that the Web Payments SDK generates in Sandbox mode results in a successful CreatePayment Sandbox environment call.

Guidelines for charging Afterpay using CreatePayment include the following:

• Application developers should ensure that Afterpay supports their merchant category code (MCC). Each seller location has an MCC that describes the types of goods or services sold at that location. Certain MCCs aren't supported by Afterpay (see Check for eligibility and limitations). In such cases, the Web Payments SDK doesn't display Afterpay as a payment option.

Limitations for charging Afterpay using CreatePayment include the following:

• The Web Payments SDK shows the Afterpay payment option only if the following are true:

  • The seller is eligible for Afterpay.
  • The checkout amount is within the min/max limit set by Afterpay. Afterpay sets a min/max payment limit for each seller. This limit applies to each checkout amount. When a buyer is ready to check out, the Web Payments SDK shows the Afterpay payment option only if the checkout amount is within this range.

• Only the Web Payments SDK supports Afterpay as a payment source.

• Afterpay has specific payment size limits that differ by region and type of payment. For example, Afterpay monthly payments allow higher limits than Afterpay's "Pay in 4" payments. For more information, see Monetary amount limits.

• For credit card payments, authorization indicates that the purchase amount is within credit card limits or the buyer has enough funds on the card. An authorization puts a hold on the specific amount.

  An Afterpay payment authorization means that the buyer is charged the first installment by Afterpay and the installment plan is started.

• Afterpay allows refunds up to 120 days from the date of purchase.

• Afterpay is available in countries according to the Afterpay/Clearpay table.