Learn how to use the Square Payments API to record external payments.
Payments API

External Payments

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 are not 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:

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.

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "source_id": "EXTERNAL",
    "amount_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "external_details": {
      "type": "OTHER",
      "source": "Food Delivery Service",
      "Source_id": "FDS-111",
      "source_fee_money": {
        "amount": 500,
        "currency": "USD"
      }
    }
  }'

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

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
{
   "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 have 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.

Important

If you use the Orders API with a non-Square payments provider, Square charges a transaction fee. For more information, see Orders API fee structure.

We've made improvements to our docs.
Prefer the old format?