Learn how to move from processing payments with the Transactions API to using the Square Payments API. Also, learn how to access old transactions.
Payments API and Refunds API

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 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 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.

The Payments API and Refunds API provide these benefits:

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

  • Support for paying with Square Gift Cards and other payment methods.

  • Support for collecting tips at the time of payment.

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

The following payment processing general guidelines apply:

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

  • You can continue to use payment 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 Square 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.

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

The following Transactions API Charge 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.

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 between the Transactions API and the Payments API:

ActionTransactions API
(Charge endpoint)
Payments API
(CreatePayment endpoint)
Specifying payment methodDepending on the payment method, the endpoint supports different fields in the request, such as card_nonce or the customer_card_id.The endpoint supports only one field (source_id) to specify a payment source regardless of whether it is a card on file or a payment token.
Specifying locationThe endpoint requires the seller location as part of the endpoint URL.The endpoint supports the optional location_id field in the request body. If it is not specified, the default seller location (oldest active) is assumed.
Delaying capture (obtain only payment authorization)The endpoint supports the delay_capture field, which you set to true.The endpoint supports the autocomplete field, which you set to false to request only authorization.
Behavior of the amount_money fieldThe amount_money field includes the tip amount. To get the base amount of the transaction, subtract the tip amount.The amount_money field excludes the tip amount. The total_money field represents the total amount of the transaction including tip and fees.
idempotency_key lengthMax length 192Max length 45

The following is a Payments API example using the CreatePayment endpoint to charge $1 USD:

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -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.

The Payments API CreatePayment endpoint supports the source_id field to set a payment source, which can be a card on file ID or a payment token.

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

  • customer_card_id identifies payment source, which is the ID of a card on file.

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

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

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -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"
  }'

The following Transactions API CreateRefund 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.

To migrate the preceding example to use the Refunds API RefundPayment endpoint, note the following differences between the Transactions API and the Refunds API:

ActionTransactions API
(CreateRefund endpoint)
Refunds API
(RefundPayment endpoint)
Specifying the payment methodSupports the tender_id field in the request body.Supports the payment_id field in the request body.
To refund transaction tenders provide the tender_id value in the payment_id field.
Seller location and transaction ID.The endpoint requires this information as part of the endpoint URL.The ID of the original Payment is provided.

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

Refund Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/refunds \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -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.

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 obtain an authorization to charge the card.

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

ActionTransactions API
(Charge endpoint)
Payments API
(CreatePayment endpoint)
Specifying the delayed capture optionSupports the delay_capture field in the request body. Set it to true if you want only payment authorization.Supports the autocomplete payment in the request body. Set it to false if you want only payment authorization.
Follow-up optionsComplete the payment using the CaptureTransaction endpoint or cancel it using the VoidTransaction endpoint.Use the CompletePayment and CancelPayment endpoints.

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.

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareup.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -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.

This example assumes that the application developer collects a fee for each payment processed on behalf of the seller (known as an application fee). After processing the payment, Square splits the payment funds between the application developer account (who gets the application fee) and the seller (who gets the rest of the funds minus the Square payment processing charges).

In the example, the seller and developer have separate 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 payment processing fee). In the request:

  • The endpoint URL specifies the seller location.

  • The additional_recipient field 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.

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

ActionTransactions API
Charge endpoint)
Payments API
(CreatePayment endpoint)
Specifying an additional recipient who gets a portion of the paymentSupports the additional_recipient field with the payment amount they receive.Supports the app_fee_money field to specify the application fee for the developer.
Specifying the seller locationSet the seller location in the endpoint URL.You can include the location_id in the request body to specify the seller location. If it is not specified, the default location is assumed.
Specifying an additional recipient locationInclude location_id in the additional_recipient field for the developer location.API assumes the default location.

The following example uses the Payments API CreatePayment endpoint to charge $1 USD and gives $0.20 USD to the developer:

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -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.

You might have old transactions created with the Transactions API. This section explains how you can get these transactions using the Payments API, Refunds API, or Orders API.

This is an example Transaction object created by the Transactions API Charge endpoint. The transaction has Tender and Refund objects.

  • 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
{
  "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 get these old transactions.

  • Transactions are now returned as orders. Use the Orders API to access the old transactions. The Transaction.id from the previous example maps to an Order.id. The following BatchRetrieveOrders can return old transactions as shown. The request specifies a list of order IDs, one of which is also the ID of an old transaction.

    Batch Retrieve Orders
    • 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: 2023-01-19' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "order_ids": [
          "old_transaction_id",
          "order_id_1",
          "order_id_2"
        ]
      }'

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

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

    List Payments
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/payments \
      -H 'Square-Version: 2023-01-19' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    The response can include payments created with the Payments API CreatePayment endpoint and tenders created with the Transactions API charge.

  • 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. The refund ID is the concatenation of the tender ID and refund ID with an underline (for example, Tender.id_Refund.id).

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

    List Payment Refunds
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/refunds \
      -H 'Square-Version: 2023-01-19' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    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.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.