External Payments

Applies to: Payments API | Orders API

Learn how to record external payments using Payments API.

External payments refer to any payments processed by external entities (not by Square or the seller). An external payment should be recorded with Square for bookkeeping reasons. However, the payment proceeds aren't credited to the seller's Square account. External payment examples include these buyer actions:

• A food order is made through a courier service. The service processes the payment and pays the seller with the proceeds.
• Payments made using Cash App.
• An unsupported credit card is used. For a list of Square-supported cards, see Supported Payment Methods by Country.

Apply external payments by calling CreatePayment. In the request, provide the payment amount and these additional payment details:

• source_id - Set this field to EXTERNAL.
• external_details - This field is of the ExternalPaymentDetails type.

The following is an example CreatePayment request:

• The amount_money field specifies $50 as the payment amount.
• The source_id field is set to EXTERNAL.
• The external_details field is set:
  • type is set to OTHER (for a list of types, see ExternalPaymentDetails).
  • source identifies that a "Food Delivery Service" took the payment.
  • source_fee_money specifies $5 for the transaction fee charged by the external source.

When Square receives the request, it records the payment and returns a Payment object in the response as shown:

{
   "payment":{
      "id":"dews2DlY3p3KHG6tCv922C9KTHPZY",
      "created_at":"2021-02-05T04:04:56.313Z",
      "amount_money":{
         "amount":5000,
         "currency":"USD"
      },
      "status":"COMPLETED",
      "source_type":"EXTERNAL",
      "location_id":"S8GWD5R9QB376",
      "order_id":"WCtIKDDGTP8Zp6vYVSdFdX2lW3bZY",
      "total_money":{
         "amount":5000,
         "currency":"USD"
      },
      "capabilities":[
         "EDIT_TIP_AMOUNT",
         "EDIT_TIP_AMOUNT_UP",
         "EDIT_TIP_AMOUNT_DOWN"
      ],
      "external_details":{
         "type":"OTHER",
         "source":"Food Delivery Service",
         "source_fee_money":{
            "amount":500,
            "currency":"USD"
         }
      },
      "receipt_number":"dews",
      "receipt_url":"https://squareupsandbox.com/receipt/preview/dews2DlY3p3KHG6tCv922C9KTHPZY",
      "version_token":"uZuTt7FmADaBbslopLlnz7RA8HKLcdStaFc4ECz59lZ6o"
   }
}

You can use an external payment to pay for an order. Use the PayOrder endpoint (Orders API) to complete the external payment you've attached to the order. When calling CreatePayment to make the Payment for the order, set autocomplete to false. This sets the Payment status to APPROVED as required by the PayOrder endpoint. For more information about paying for orders, see Orders integration.

• Take Payments
• Orders integration