Manage Checkout

The Checkout API (see Checkout API Overview) provides endpoints to manage the checkout pages you created. You can update, retrieve, or delete the checkout pages.

You can use the UpdatePaymentLink endpoint to update the following payment_link fields:

• description - The optional description of the payment_link object.
• checkout_options - You should specify the entire CheckoutOptions object in the update request. If you specify only specific fields, the update operation deletes fields not included in the request.
• pre_populated_data - You only specify the PrePopulatedData fields that you want to update (or add). If a field you provided in the request doesn't exist, it gets added.

You cannot update the order_id, version, URL, or timestamp fields.

In the following example, you create a checkout page and then call UpdatePaymentLink to apply the updates:

1. Create a quick pay checkout page for $125 for auto detailing:

   Create payment link

   cURL

   The following is an example response:

   {
     "payment_link": {
       "id": "OTKXE56AZGRBPAN4",
       "version": 1,
       "order_id": "m1rS3y9B95BWRTVJVs9K3iJD4yLZY",
       "checkout_options": {
         "allow_tipping": true,
         "custom_fields": [
           {
             "title": "Special Instructions",
             "uid": "N3W4FIWOAGI7GMYV62MQ7MQ3"
           },
           {
             "title": "Would you like to be on mailing list",
             "uid": "J7ETDA6UANCFB3UIXJP5AGL6"
           }
         ],
         "ask_for_shipping_address": true
       },
       "pre_populated_data": {
         "buyer_email": "[email protected]",
         "buyer_phone_number": "+14155551212",
         "buyer_address": {
           "address_line_1": "1455 MARKET ST #600",
           "locality": "San Jose",
           "administrative_district_level_1": "CA",
           "postal_code": "94103",
           "country": "US"
         }
       },
       "url": "https://sandbox.square.link/u/J1lWcEhY",
       "created_at": "2022-04-22T02:50:39Z"
     },
     "related_resources": {
       "orders": [
         {
           "id": "C0DMgui6YFmgyURVSRtxr4EShheZY",
           "location_id": "{{LOCATION_ID}}",
           "source": {
             "name": "Test Online Checkout Application"
           },
           "line_items": [
             {
               "uid": "8YX13D1U3jO7czP8JVrAR",
               "name": "Auto Detailing",
               "quantity": "1",
               "item_type": "ITEM",
               "base_price_money": {
                 "amount": 12500,
                 "currency": "USD"
               },
               "variation_total_price_money": {
                 "amount": 12500,
                 "currency": "USD"
               },
               "gross_sales_money": {
                 "amount": 12500,
                 "currency": "USD"
               },
               "total_tax_money": {
                 "amount": 0,
                 "currency": "USD"
               },
               "total_discount_money": {
                 "amount": 0,
                 "currency": "USD"
               },
               "total_money": {
                 "amount": 12500,
                 "currency": "USD"
               }
             }
           ],
           "fulfillments": [
             {
               "uid": "bBpNrxjdQxGQP16sTmdzi",
               "type": "DIGITAL",
               "state": "PROPOSED"
             }
           ],
           "net_amounts": {
             "total_money": {
               "amount": 12500,
               "currency": "USD"
             },
             "tax_money": {
               "amount": 0,
               "currency": "USD"
             },
             "discount_money": {
               "amount": 0,
               "currency": "USD"
             },
             "tip_money": {
               "amount": 0,
               "currency": "USD"
             },
             "service_charge_money": {
               "amount": 0,
               "currency": "USD"
             }
           },
           "created_at": "2022-03-03T00:53:15.829Z",
           "updated_at": "2022-03-03T00:53:15.829Z",
           "state": "DRAFT",
           "version": 1,
           "total_money": {
             "amount": 12500,
             "currency": "USD"
           },
           "total_tax_money": {
             "amount": 0,
             "currency": "USD"
           },
           "total_discount_money": {
             "amount": 0,
             "currency": "USD"
           },
           "total_tip_money": {
             "amount": 0,
             "currency": "USD"
           },
           "total_service_charge_money": {
             "amount": 0,
             "currency": "USD"
           }
         }
       ]
     }
   }

2. Update the following fields:

   • description - Add a description.
   • checkout_options - Specify a new custom_fields ("Very Special Instructions"). You verify that both the existing custom fields are deleted.
   • pre_populated_data - Specify only the buyer_email and address_line_1 fields. You verify that all other fields are preserved.
   • fields_to_clear - Specify the field to remove checkout_options.allow_tipping.

3. Run the following UpdatePaymentLink request to apply the updates:

   Update payment link

   cURL

   Note that fields_to_clear is an array where you provide a comma-separated list of fields to delete. For example:

   "fields_to_clear": [
      "checkout_options.allow_tipping", 
      "pre_populated_data.buyer_address"
   ]

   This deletes the allow_tipping field from checkout_options and the entire buyer_address from pre_populated_data. To delete the entire checkout_options, specify the following:

   "fields_to_clear": [
      "checkout_options
   ]

You can retrieve a specific payment link by ID or all the payment links in the account. The Checkout API provides the RetrievePaymentLinks and ListPaymentLinks endpoints. Try using API Explorer to test these endpoints.

You can use the DeletePaymentLinks endpoint to delete a payment link you created.

After receiving the request, the endpoint sets the corresponding order state to CANCELED and deletes the checkout link.

{
  "id": "KFLXPQROJALW56ZX",
  "cancelled_order_id": "6nJTzvMv7nA28JSKAgDpxlg3vgFZY"
}