Learn how to migrate from using the deprecated V1 Payments API to using the Square Payments API.
The following information helps you migrate from the Connect V1 Payments API to the correct Square API counterparts. For general guidance about the differences between Connect V1 and Square APIs, see General Guidance.
Code relying on the following V1 Payments API endpoints must be updated to avoid breaking when the V1 Payments API reaches retirement:
- V1
RetrievePayment - V1
ListPayment
- Deprecation: 2021-05-13
- Retirement: 2023-07-17
If you need help migrating to the Square API or need more time to complete your migration, contact Developer Support, join our Discord community, or reach out to your Square account manager.
The RetrievePayment endpoint is replaced by the Square GetPayment endpoint. The following sections provide mapping information about the request fields, path parameters, and response fields.
| V1 RetrievePayment path parameter | Square GetPayment path parameter |
|---|---|
location_id | N/A |
payment_id | payment_id |
The V1 RetrievePayment endpoint returns payment information as a set of fields in the response body, while the Square GetPayment endpoint returns a Payment object. This Payment object provides an order_id, if available, which you can use to retrieve the Order object.
Important
If you want to retrieve the associated Order, your application needs ORDERS_READ OAuth permission to call the RetrieveOrder endpoint.
| V1 RetrievePayment response field | Mapping to Square Payment or Order object field |
|---|---|
id | Payment.id |
merchant_id | Payment.location_id |
created_at | Payment.created_at |
creator_id | Payment.team_member_id |
device | Payment.device_details |
device.id | Payment.device_details.device_id |
device.name | Payment.device_details.device_name |
payment_url | N/A. The field isn't available. |
receipt_url | Payment.receipt_url |
inclusive_tax_money | No direct field mapping. Instead, manually aggregate across the objects in Orders.taxes where OrderLineItemTax.type is INCLUSIVE. |
additive_tax_money | No direct field mapping. Instead, manually aggregate across the objects in Orders.taxes where OrderLineItemTax.type is ADDITIVE. |
tax_money | Order.total_tax_money |
tip_money | Payment.tip_money |
discount_money | Order.total_discount_money |
total_collected_money | Order.net_amounts.total_money |
processing_fee_money | Payment.processing_fee |
net_total_money | This field represents the final balance of sale and return amounts, so the mapping varies by order type. For more information, see Mapping net_total_money. |
refunded_money | Payment.refunded_money |
swedish_rounding_money | Orders.rounding_adjuestment |
gross_sales_money | Payment.total_money |
net_sales_money | Calculate the value: Payment.total_money minus Order.total_tax_money. |
inclusive_tax | No direct field mapping. Instead, manually aggregate across the objects in Orders.taxes where OrderLineItemTax.type is INCLUSIVE. |
additive_tax | No direct field mapping. Instead, manually aggregate across the objects in Orders.taxes where OrderLineItemTax.type is ADDITIVE. |
tender | There are no multiple tenders. The Payment represents a single tender. |
tenders.id | Payment.id |
tenders.type | Payment.source_type |
tenders.name | There are no tenders in the Payment object. Instead, use source_type as tenders.name. |
tenders.employee_id | Payment.team_member_id |
tenders.receipt_url | Payment.receipt_url |
tenders.card_brand | Payment.card_details.card.card_brand |
tenders.pan_suffix | Payment.card_details.card.last_4 |
tenders.entry_method | Payment.card_details.entry_method |
tenders.payment_note | Payment.note |
tenders.total_money | Payment.total_money |
tenders.tendered_money | Payment.cash_details.amount_money |
tenders.tendered_at | Payment.created_at |
tenders.settled_at | Payment.card_details.card_payment_timeline.captured_at |
tenders.change_back_money | Payment.cash_details.change_back_money |
tenders.refunded_money | Orders.refunds.amount_money |
tenders.is_exchange | You can determine whether the order is an exchange order by verifying the presence of the line_items and returns in the Order object. |
refunds | Retrieve Payment.refund_ids and then use the Refunds API to retrieve the PaymentRefund objects. |
refunds.type | You can determine whether the refund is full or partial based on the refund amount (PaymentRefund.amount_money) relative to the original order (Order.total_money). |
refunds.reason | PaymentRefund.reason |
refunds.refunded_money | PaymentRefund.amount_money |
refunds.refunded_processing_fee_money | PaymentRefund.processing_fee.amount_money |
refunds.refunded_tax_money | Order.returns.return_amounts.tax_money |
refunds.refunded_additive_tax_money | No direct field mapping. Instead, manually aggregate across the objects in Order.returns.return_taxes where return_taxes.type is ADDITIVE. |
refunds.refunded_additive_tax | No direct field mapping. Instead, manually aggregate across the objects in Order.returns.return_taxes where return_taxes.type is ADDITIVE. |
refunds.refunded_inclusive_tax_money | No direct field mapping. Instead, manually aggregate across the objects in Order.returns.return_taxes where return_taxes.type is INCLUSIVE. |
refunds.refunded_inclusive_tax | No direct field mapping. Instead, manually aggregate across the objects in Order.returns.return_taxes where return_taxes.type is INCLUSIVE. |
refunds.refunded_tip_money | Order.returns.return_amounts.tip_money |
refunds.refunded_discount_money | Order.returns.return_amounts.tax_money |
refunds.refunded_surcharge_money | Order.returns.return_amounts.service_charge_money |
refunds.refunded_surcharges | Order.returns.return_service_charges |
refunds.created_at | PaymentRefund.created_at |
refunds.processed_at | N/A. This field isn't available. |
refunds.payment_id | PaymentRefund.payment_id |
refunds.merchant_id | PaymentRefund.location_id |
refunds.is_exchange | You can determine whether the refund is related to an exchange by verifying the sum of the line_items.total_money with the sum of returns.return_amounts in the Order object. |
itemizations | Order.line_items |
itemizations.name | OrderLineItem.name |
itemizations.quantity | OrderLineItem.quantity |
itemizations.itemization_type | OrderLineItem.item_type |
itemizations.item_detail | Use the OrderLineItem.catalog_object_id to retrieve the catalog information. |
itemizations.item_detail.category_name | Use the OrderLineItem.catalog_object_id to retrieve the catalog information. |
itemizations.item_detail.sku | N/A. Not available in a Payment or Order object. |
itemizations.item_detail.item_id | OrderLineItem.catalog_object_id |
itemizations.item_detail.item_variation_id | OrderLineItem.catalog_object_id |
itemizations.notes | OrderLineItem.note |
itemizations.item_variation_name | OrderLineItem.variation_name |
itemizations.total_money | OrderLineItem.total_money |
itemizations.single_quantity_money | OrderLineItem.base_price_money |
itemizations.gross_sales_money | OrderLineItem.gross_sales_money |
itemizations.discount_money | OrderLineItem.total_discount_money |
itemizations.net_sales_money | No direct field mapping. Instead, add OrderLineItem.gross_sales_money and OrderLineItem.total_discount_money. |
itemizations.taxes | OrderLineItem.applied_taxes.OrderLineItemAppliedTax |
itemizations.taxes.name | Order.taxes.name |
itemizations.taxes.applied_money | OrderLineItemAppliedTax.applied_money |
itemizations.taxes.rate | Order.taxes.percentage |
itemizations.taxes.inclusion_type | Order.taxes.type |
itemizations.taxes.fee_id | OrderLineItem.applied_taxes.tax_uid |
itemizations.discounts | OrderLineItem.applied_discounts.OrderLineItemAppliedDiscount |
itemizations.discounts.name | Order.discounts.name |
itemizations.discounts.applied_money | OrderLineItemAppliedDiscount.applied_money. Note that this amount is a positive integer, unlike the negative integer used for amount in the V1 Payments API. |
itemizations.discounts.discount_id | OrderLineItemAppliedDiscount.discount_uid |
itemizations.modifiers | OrderLineItem.modifiers.OrderLineItemModifier |
itemizations.modifiers.name | OrderLineItemModifier.name |
itemizations.modifiers.applied_money | OrderLineItemModifier.total_price_money |
itemizations.modifiers.modifier_option_id | OrderLineItemModifier.catalog_object_id |
surcharge_money | Order.total_service_charge_money |
surcharges | Order.service_charges.OrderServiceCharge |
surcharges.name | OrderServiceCharge.name |
surcharges.applied_money | OrderServiceCharge.applied_money |
surcharges.rate | OrderServiceCharge.percentage |
surcharges.amount_money | OrderServiceCharge.amount_money |
surcharges.type | OrderServiceCharge.type |
surcharges.taxable | OrderServiceCharge.taxable |
surcharges.taxes | OrderServiceCharge.applied_taxes |
surcharges.surcharge_id | OrderServiceCharge.catalog_object_id |
is_partial | To determine whether the order is partially paid, do the following: 1. From the Payment object, get the order_id and retrieve the Order using the Orders API. 2. For each tender in Order.tenders, get the payment_id and retrieve the Payment object. 3. Aggregate the Payment.total_money values only for the completed payments (Payment status is COMPLETED). 4. If the resulting sum is less than the Order.total_money, the order is partially paid. |
The ListPayments endpoint is replaced by the Square ListPayments endpoint. The following sections provide mapping information about the request fields, path parameters, and response fields.
Important
The ListPayments endpoint returns declined payments (FAILED status). The V1 ListPayments endpoint doesn't return declined payments.
The following table shows how the V1 ListPayments path parameters map to the Square ListPayments endpoint.
| V1 ListPayments path parameter | Square ListPayments path parameter |
|---|---|
location_id | Not available as a path parameter, but you can specify it as a location_id query parameter. |
The following table shows how the V1 ListPayments query parameters map to the Square ListPayments endpoint.
| V1 ListPayments query parameter | Square ListPayments query parameter |
|---|---|
order | sort_order |
begin_time | begin_time |
end_time | end_time |
limit | limit |
batch_token | cursor |
include_partial | N/A |
The V1 ListPayments endpoint returns payment information as an array of items in the response body, which are V1Payment objects. The Square ListPayments endpoint returns an array of Square Payment objects. The new Payment object provides an order_id, which you can use to retrieve the Order object.
V1 ListPayments items response field | Mapping to Square Payment or Order object field |
|---|---|
V1Payment | Payment object |
id | id |
additive_tax | No direct field mapping. Instead, manually aggregate across the objects in Orders.taxes where OrderLineItemTax.type is ADDITIVE. |
additive_tax_money | No direct field mapping. Instead, manually aggregate across the objects in Orders.taxes where OrderLineItemTax.type is ADDITIVE. |
created_at | created_at |
creator_id | team_member_id |
device | device_details |
discount_money | Order.total_discount_money |
gross_sales_money | total_money |
inclusive_tax | No direct field mapping. Instead, manually aggregate across the objects in Orders.taxes where OrderLineItemTax.type is INCLUSIVE. |
inclusive_tax_money | No direct field mapping. Instead, manually aggregate across the objects in Orders.taxes where OrderLineItemTax.type is INCLUSIVE. |
is_partial | To determine if the order isn't fully paid, do the following: 1. From the Payment object, get the order_id and retrieve the Order using the Orders API. 2. Check the order.state for COMPLETED. If not completed, the order is unpaid or partially paid. |
itemizations | Order.line_items |
merchant_id | location_id |
net_sales_money | total_money minus Order.total_tax_money |
net_total_money | This field represents the final balance of sale and return amounts, so the mapping varies by order type. For more information, see Mapping net_total_money. |
payment_url | Not available. |
processing_fee_money | processing_fee |
receipt_url | receipt_url |
refunded_money | Order.return_amounts.total_money |
refunds | Retrieve refund_ids and then use the Refunds API to retrieve the PaymentRefund objects. |
surcharge_money | Order.total_service_charge_money |
surcharges | Order.service_charges |
swedish_rounding_money | Orders.rounding_adjuestment |
tax_money | Order.total_tax_money |
tender | Multiple tenders are represented in the Order.tenders field. The Payment represents a single tender. |
tip_money | tip_money |
total_collected_money | Order.net_amounts.total_money |
In a V1 payment response, the net_total_money field represents the final balance of sale and return amounts. Mapping to the equivalent Order field depends on the type of order, as follows:
Standard sale transactions - If the corresponding order contains a
net_amountsfield, use the following mapping:net_total_money=Order.net_amounts.total_moneyStandard return transactions - If the corresponding order contains a
return_amountsfield and the return amount is not zero, use the following mapping:net_total_money=Order.return_amounts.total_moneyNote that
net_total_moneyamounts are negative for return orders butreturn_amounts.total_moneyamounts are positive.All other transactions - If the previous conditions don't apply, use the following mapping:
net_total_money=Order.total_money