Payments and Refunds

Migrate from Transactions API

This section shows 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 customers requested. So we split the API into the new Payments API and a more robust Orders API. We will continue to enhance these APIs, also 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. We will continue to support the Transactions API until September 1, 2021. 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 will need to update the SDK to version 2.20190814.0 or later (or 2.22.0 or later if using the .NET SDK) to use the Payments and Refunds API. See Square Connect SDKs change log.

Migration benefits
Permalink Get a link to this section

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

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

  • Support for paying with Square Gift Cards

  • Support for collecting tips at 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

General guidance
Permalink Get a link to this section

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 (nonces) with the Payments API. There is no change to how you use the Square Payments Form or In-App Payments SDK used to generate a nonce.

  • The following are caveats:

    • The Transactions API ListTransactions response includes cash and other payments which the Payments API ( ListPayments endpoint) does not return. You can retrieve those using the SearchOrders endpoint.

    • At present there are no Webhooks available specific to Connect V2 Payments API. If you have a PAYMENT_UPDATED webhook configured, you will get notifications for Payments API payments in addition to Transactions API and POS payments. The entity_id in the webhook may be used with ( GetPayment to retrieve details about card payments.

    • Testing the Payments API is only possible in the Sandbox.


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

Examples of code migration to using Payments API and Refunds API
Permalink Get a link to this section

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

Example 1: Payment using a secure token (nonce)
Permalink Get a link to this section

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

  • The endpoint URL includes the seller location.

  • Authorization header provides the seller access token.

  • card_nonce in the body identifies payment source.

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

curl -X POST \
  https://connect.squareup.com/v2/locations/{{LOCATION-ID}}/transactions \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "idempotency_key": "{{UNIQUE-KEY}}",
  "amount_money": {
    "amount": 100,
    "currency": "USD"
  },
  "card_nonce": "cnon:CBASEIFNPdBL1ZkxDB36example",
  "note": "this is a test",
  "delay_capture": false
}'

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

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

Transactions API (Charge endpoint) Payments API (CreatePayment endpoint)
Specifying payment method Depending on the payment method, the endpoint supports different parameters in the request such as card_nonce or the customer_card_id. The endpoint supports only one parameter (source_id) to specify a payment source regardless of whether it is a card on file or a nonce.
Specifying location The endpoint requires seller location as part of the endpoint URL. The endpoint supports optional location_id parameter in the request body. If not specified, default seller location (oldest active) is assumed.
Delaying capture (obtain only payment authorization) The endpoint supports the delay_capture parameter which you set to true. The endpoint supports the autocomplete parameter which you set to false to request only authorization.
Behavior of the amount_money field The amount_money field is inclusive of tip amount. To get the base amount of the transaction you must subtract the tip amount. The amount_money field is exclusive of tip amount. The total_money field represents the total amount of the transaction.

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

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
    "idempotency_key": "{{UNIQUE-KEY}}",
    "autocomplete": true,
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "source_id": "cnon:CBASEGMfgZGSjE0_WUiNexample"
    }
}' \
'https://connect.squareup.com/v2/payments'

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

Example 2: Payment using a card on file
Permalink Get a link to this section

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

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 dentifies payment source

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

curl -X POST \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -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
}
' \
'https://connect.squareup.com/v2/locations/X9XWRESTK1CZ1/transactions'

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

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Cache-Control: no-cache' \
-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"
}
' \
'https://connect.squareup.com/v2/payments'

Example 3: Refund a payment
Permalink Get a link to this section

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

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

  • 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 -X POST \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "idempotency_key": "{{UNIQUE-KEY}}",
  "tender_id": "EKR9mDvBetVQVMKNeexample",
  "reason": "testing create refund",
  "amount_money": {
    "amount": 100,
    "currency": "USD"
  }
}' \
'https://connect.squareup.com/v2/locations/{{LOCATION-ID}}/transactions/{{TRANSACTION-ID}}/refund'

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

Transactions API (CreateRefund endpoint) Refunds API (RefundPayment endpoint)
Specifying payment method Supports the tender_id parameter in the request body. Supports the payment_id parameter in the request body.
To refund transaction tenders provide the tender_id value in the payment_id field.
Specifying seller location and transaction ID. The endpoint requires this information as part of the endpoint URL. There are no transactions to specify.

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

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
  "idempotency_key": "{{UNIQUE-KEY}}",
  "payment_id": "EKR9mDvBetVQVMKNeexample",
  "reason": "testing create refund",
  "amount_money": {
    "amount": 100,
    "currency": "USD"
  }
}' \
'https://connect.squareup.com/v2/refunds'

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

Example 4: Payments with delay capture
Permalink Get a link to this section

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 -X POST \
  https://connect.squareup.com/v2/locations/X9XWRESTexample/transactions \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "idempotency_key": "{{UNIQUE-KEY}}",
  "amount_money": {
    "amount": 100,
    "currency": "USD"
  },
  "customer_card_id" : "ccof:65aSD6rnUryWexample",
 "customer_id" : "SV2K57WMQCS7QAMKKZQexample",
 "delay_capture": true
}'

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

Transactions API (Charge endpoint) Payments API (CreatePayment endpoint)
Specifying delayed capture option Supports the delay_capture parameter in the request body. You set it to true if you want only payment authorization. Supports the autocomplete parameter in the request body. You set it to false if you want only payment authorization.
Follow up options You can either complete the payment using CaptureTransaction endpoint or cancel it using the VoidTransaction endpoint. You can 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.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Cache-Control: no-cache' \
-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
}' \
'https://connect.squareup.com/v2/payments'

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

Example 5: Multiparty payment
Permalink Get a link to this section

This example assumes the application, integrated with Square, processes payments on behalf of the seller for a fee (referred to as an application fee). Upon receiving the request, Square splits the payment between the application developer account (who gets the fee specified) 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.

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

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

curl -X POST \
  https://connect.squareup.com/v2/locations/{{LOCATION-ID}}/transactions \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "idempotency_key": "{{UNIQUE-KEY}}",
  "amount_money": {
    "amount": 100,
    "currency": "USD"
  },
  "customer_card_id": "ccof:65aSD6rnUryWzHexample",
 "customer_id" : "SV2K57WMQCS7QAMKKZQA4example",
  "additional_recipients": [
    {
      "location_id": "P8DDS5P8JN70N",
      "description": "Application fees",
      "amount_money": {
        "amount": 20,
        "currency": "USD"
      }
    }
  ]
}

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

Transactions API (Charge endpoint) Payments API (CreatePayment endpoint)
Specifying additional recipient who gets a portion of the payment Supports the additional_recipient parameter where you specify the portion of the payment they receive. Supports the app_fee_money parameter to specify the payment portion for the additional recipient.
Specifying seller location You specify seller location in the endpoint URL. Optionally include the location_id in the request body to specify seller location. If not specified, default location is assumed.
Specifying additional recipient location Include location_id in additional_recipient parameter for the developer location.
API assumes default location.

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 -X POST \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
 -H 'Cache-Control: no-cache' \
 -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"
   }
 }' \
 'https://connect.squareup.com/v2/payments'

For more information, see Take Payments and Collect Fee.

How to access old transactions using the Payments API and Refunds APIs
Permalink Get a link to this section

You might have old transactions that you created using the deprecated Transactions API. This section explain 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 apply how the Payments 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 the Order.id. For example, the following Batch retrieve orders can return old transactions as shown. The request specifies a list of order IDs, one of which is an old transaction ID.

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

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

  • Transaction tenders (of the card types) are now payments. If the type of the Transaction.Tender ( Tender) is one of the card types, 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:

    curl https://connect.squareup.com/v2/payments \
    -H 'Square-Version: 2019-09-25' \
    -H 'Authorization: Bearer {{ACCESS_TOKEN}}'
    

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

    The transaction tenders of other non-card types (CASH or OTHER types) are not available via the Payments API at this time. These tenders are available as part of the Order object. In this case the Transaction.Tender.id maps to Order.Tender.id.

    Using the Order API you first retrieve the old transaction by specifying transaction ID as the order ID. You then search the order object for tenders of the non-cash types.

  • Refunds of transaction tenders (of the card types) can be accessed using the Refunds API. If the Transaction.Tender.type ( Tender) is any of the card types, you can access the tender refunds using the Refunds API. 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( Get payment refund) request retrieves refunds information of an old transaction. The request specifies the <Tender.id>_<Refund.id> as the refund ID in the endpoint URL.

    curl https://connect.squareup.com/v2/refunds/<Tender.id>_<Refund.id> \
    -H 'Square-Version: 2019-09-25' \
    -H 'Authorization: Bearer {{ACCESS_TOKEN}}'
    

    Refunds for the tenders of the non-card types (CASH or OTHER types) are not available via Refunds API. You need to first retrieve the order using the Orders API, by specifying transaction ID as the order ID. You then search the order for refunds.