Migrate from the Transactions API

Learn how to migrate from the Transactions API to the Payments API.

The Transactions API previously allowed you to create online and in-app payments. The API had limitations that prevented Square from adding features and flexibility that customers requested. As a result, Square split the API into the new Payments API and a more robust Orders API. Square continues to enhance these APIs, offering you the flexibility to use the two APIs together or separately.

The Transactions API is deprecated. Square does not plan to add any new features. Square continues to support the Transactions API until a date yet to be determined. The new Payments API is released alongside the Transactions API instead of replacing it. This gives you time to develop and test in parallel and migrate when you are ready. If you are using Square Connect SDKs, you need to update the SDK to version 2.20190814.0 or later (or 2.22.0 or later if you are using the .NET SDK) to use the Payments API and Refunds API. For more information, see Square SDKs changelog.

Link to section

Migration benefits

The Payments API and Refunds API provide the following benefits over the Transactions API:

• Support for refunds up to 1 year after the payment is taken.

• Support for paying with Square gift cards.

• Support for collecting tips at the time of payment.

• Additional information about CVV and AVS statuses, as well as improved card decline reasons.

• Simplified payment interface: location ID management is not required for creating or refunding payments.

Link to section

General guidance

The following payment processing general guidelines apply:

• Use the Connect V2 Payments API and Refunds API to process payment when developing new applications.

• You can continue to use the secure tokens with the Payments API. There is no change to how you use the Square payments form or In-App Payments SDK to generate a payment token.

• Refunds of cash and external type payments taken before 2021 are available in the V2 Orders API. These are not available using the Payments API (GetPaymentRefund or ListPaymentRefunds). For more information, see Access old transactions using the Payments API and Refunds APIs.

You can provide feedback by contacting Developer Support or joining our Slack channel.

Link to section

Code migration to use the Payments API and Refunds API

This section provides examples of how to move common payment processing tasks from the Transactions API to the Payments API.

Link to section

Example 1: Payment using a secure token

The following Transactions API (Charge endpoint) request charges $1 USD to the payment source identified by a payment token. In the request:

• The endpoint URL includes the seller location.

• The Authorization header provides the seller access token.

• card_nonce in the body identifies the payment source.

• delay_capture in the body is set to false to request immediate payment completion.

curl https://connect.squareup.com/v2/locations/{LOCATION_ID}/transactions \
  -X POST \
  -H 'Square-Version: 2021-06-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "card_nonce": "cnon:CBASEIFNPdBL1ZkxDB36example",
    "note": "this is a test",
    "delay_capture": false
  }'

After receiving the request, Square charges the payment source and deposits the funds in the Square account of the seller. The response shows the tender status as CAPTURED, indicating the payment source was successfully charged.

To migrate the preceding example to use the Payments API (CreatePayment endpoint), note the following differences in the API:

The following is an equivalent example that uses the Payments API (CreatePayment endpoint) to charge $1 USD:

curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "autocomplete": true,
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "source_id": "cnon:CBASEGMfgZGSjE0_WUiNexample"
  }'

For information about the payment object in the response, see Payment.

Link to section

Example 2: Payment using a card on file

The Payments API (CreatePayment endpoint) supports only one parameter (source_id) to specify a payment source, regardless of whether it is a card on file or a payment token.

The following Transactions API (Transactions endpoint) request charges $1 USD to the payment source identified by a card on file. In the request:

• customer_card_id identifies payment source.

• customer_id identifies the customer to whom the card on file is attached.

curl https://connect.squareup.com/v2/locations/{LOCATION_ID}/transactions \
  -X POST \
  -H 'Square-Version: 2021-06-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "customer_card_id": "ccof:65aSD6rnUryWexample",
    "customer_id":"SV2K57WMQCS7QAMKKZQexample",
    "note": "this is a test",
    "delay_capture": false
  }'

The following is an equivalent example that uses the Payments API (CreatePayment endpoint) to charge $1 USD:

curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "autocomplete": true,
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "source_id": "ccof:65aSD6rnUryWexample",
    "customer_id": "SV2K57WMQCS7QAMKKZQexample"
  }'

Link to section

Example 3: Refund a payment

The following Transactions API (CreateRefund endpoint) request refunds $1 USD. In the request:

• The endpoint URL provides both the transaction ID and seller location.

• The Authorization header provides the access token of the seller. Square takes funds out of the Square Balance of the seller to refund the customer.

• tender_id in the body provides the payment ID being refunded.

curl https://connect.squareup.com/v2/locations/{LOCATION_ID}/transactions/{TRANSACTION_ID}/refund \
  -X POST \
  -H 'Square-Version: 2021-06-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "tender_id": "EKR9mDvBetVQVMKNeexample",
    "reason": "testing create refund",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    }
  }'

To migrate the preceding example to use the Refunds API (RefundPayment endpoint), note the following differences in the API:

The following is an equivalent example that uses the Refunds API (RefundPayment endpoint) to refund $1 USD:

curl https://connect.squareupsandbox.com/v2/refunds \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "payment_id": "EKR9mDvBetVQVMKNeexample",
    "reason": "testing create refund",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    }
  }'

For more information about the Refund object in the response, see PaymentRefund.

Link to section

Example 4: Payments with delay capture

The following Transactions API (Charge endpoint) request charges $1 USD to a card on file. The request specifies delay_capture=true in the body to only obtain payment authorization.

curl https://connect.squareup.com/v2/locations/{LOCATION_ID}/transactions/{TRANSACTION_ID}/refund \
  -X POST \
  -H 'Square-Version: 2021-06-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "customer_card_id" : "ccof:65aSD6rnUryWexample",
    "customer_id" : "SV2K57WMQCS7QAMKKZQexample",
    "reason": "a reason",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "delay_capture": true
  }'

To migrate the preceding example to use the Payments API (CreatePayment endpoint), note the following differences in the API:

The following is an equivalent example using the Payments API (CreatePayment endpoint) to charge $1 USD and requests delayed capture by setting the autocomplete parameter to false in the request body.

curl https://connect.squareup.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "source_id": "ccof:65aSD6rnUryWexample",
    "customer_id": "SV2K57WMQCS7QAMKKZQexample",
    "autocomplete": false
  }'

For information about the Payment object in the response, see Payment.

Link to section

Example 5: Multiparty payment

This example assumes that the application, integrated with Square, processes payments on behalf of the seller for a fee (referred to as an application fee). After receiving the request, Square splits the payment between the application developer account (who gets the specified fee) and the seller (who gets the rest of the funds minus Square charges).

In the example, both the seller and application developer are independent Square accounts.

The following Transactions API (Charge endpoint) request charges $1 USD and gives $0.20 USD to the developer. The seller gets the rest of the amount (minus the Square fee) In the request:

• The endpoint URL specifies the seller location.

• The additional_recipient parameter in the body specifies the application fee and location of the application developer.

• The Authorization header specifies the OAuth access token that identifies the seller and developer accounts. Square uses this information when splitting the payment.

curl https://connect.squareup.com/v2/locations/{LOCATION_ID}/transactions \
  -X POST \
  -H 'Square-Version: 2021-06-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "additional_recipients": [
      {
        "location_id": "P8DDS5P8JN70N",
        "description": "Application fees",
        "amount_money": {
          "amount": 20,
          "currency": "USD"
        }
      }
    ],
    "customer_card_id": "ccof:65aSD6rnUryWzHexample",
    "customer_id" : "SV2K57WMQCS7QAMKKZQA4example"
  }'

To migrate the preceding example to use the Payments API (CreatePayment endpoint), note the following differences:

The following is an equivalent example that uses the Payments API (CreatePayment endpoint) to charge $1 USD and gives $0.20 USD to the developer:

curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "source_id": "ccof:CLr9K6X7rbjJw9example",
    "customer_id": "SV2K57WMQCS7QAMKKZQA4example",
    "app_fee_money": {
      "amount": 20,
      "currency": "USD"
    }
  }'

For more information, see Take Payments and Collect Fees.

Link to section

Access old transactions using the Payments API and Refunds APIs

You might have old transactions that you created using the deprecated Transactions API. This section explains how you can view these transactions using the Payments API, Refunds API, and Orders API.

The following is an example Transaction object created by the V2 Transactions API (Charge endpoint). The transaction shows one Tender object and one Refund object.

{
  "transaction": {
    "id": "5apT3UsV4eJW2GpWyWkAtLmeV",
    "location_id": "X9XWRESTK1CZ1",
    "created_at": "2019-10-21T18:54:01Z",
    "tenders": [
      {
        "id": "sOt7GR6knQVf8tcZwQd3rsMF",
        "location_id": "X9XWRESTK1CZ1",
        "transaction_id": "5apT3UsV4eJW2GpWyWkAtLmeV",
        "created_at": "2019-10-21T18:54:00Z",
                ...
        }
      }
    ],
    "refunds": [
      {
        "id": "MnBifltgmC7XJAClam95S",
        "location_id": "X9XWRESTK1CZ1",
        "transaction_id": "5apT3UsV4eJW2GpWyWkAtLmeV",
        "tender_id": "sOt7GR6knQVf8tcZwQd3rsMF",
        "created_at": "2019-10-21T19:10:40Z",
                ...
      }
    ],
    ...
  }
}

The following guidelines describe how the Payments API and Refunds API work when dealing with these old transactions.

• Old transactions are now orders. You use the Orders API to access the old transactions. The old Transaction.id maps to Order.id. For example, the following BatchRetrieveOrders can return old transactions as shown. The request specifies a list of order IDs, one of which is an old transaction ID.

  Batch Retrieve Orders

  cURL

  • cURL
  • C#
  • Java
  • PHP
  • Python
  • Ruby
  • Node.js

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12

  curl https://connect.squareupsandbox.com/v2/orders/batch-retrieve \
    -X POST \
    -H 'Square-Version: 2022-09-21' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{
      "order_ids": [
        "old_transaction_id",
        "order_id_1",
        "order_id_2"
      ]
    }'

  Try in API Explorer

  The response includes three Order objects, one of which is the old transaction.

• Transaction tenders of all types (card, cash, or other) are now payments. Regardless of the Transaction.Tender (Tender) type (card, cash, or other), the tenders are available as the Payment objects. The Tender.id maps to Payment.id. The Payments API (GetPayment and ListPayments endpoints) can return these tenders as the Payment objects. The following is an example ListPayments request:

  List Payments

  cURL

  • cURL
  • C#
  • Java
  • PHP
  • Python
  • Ruby
  • Node.js

  Copy

  • 1
  • 2
  • 3
  • 4

  curl https://connect.squareupsandbox.com/v2/payments \
    -H 'Square-Version: 2022-09-21' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'Content-Type: application/json'

  Try in API Explorer

  The response can include both the payments created using the Payments API (CreatePayment endpoint) and the tenders created using the Transactions API.

• Refunds of transaction tenders of all types (card, cash, or other) can be accessed using the Refunds API. Regardless of the Transaction.Tender.type (Tender) type (card, cash, or other), you can access the tender refunds using the Refunds API (with one caveat). In this case, the refund ID is the concatenation of the tender ID and refund ID with an underline, for example Tender.id_Refund.id.

  The following Get payment refund(GetPaymentRefund) request retrieves refunds information about an old transaction. The request specifies the <Tender.id>_<Refund.id> as the refund ID in the endpoint URL.

  List Payment Refunds

  cURL

  • cURL
  • C#
  • Java
  • PHP
  • Python
  • Ruby
  • Node.js

  Copy

  • 1
  • 2
  • 3
  • 4

  curl https://connect.squareupsandbox.com/v2/refunds \
    -H 'Square-Version: 2022-09-21' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'Content-Type: application/json'

  Try in API Explorer
  Note

  Refunds of cash and external type payments taken before 2021 are available in the V2 Orders API. These are not available using the Payments API (GetPaymentRefund or ListPaymentRefunds). Using the Orders API, you first retrieve the old transaction by specifying the transaction ID as the order ID. You then search the order object for refunds.