Learn how to migrate from using the deprecated V1 Payments API to using the Square Payments API.
Connect V1 Migration

Migrate from the Connect V1 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: TBD

If you need help migrating to the Square API or need more time to complete your migration,

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 parameterSquare GetPayment path parameter
location_idN/A
payment_idpayment_id

The V1 RetrievePayment endpoint returns payment information as a set of fields in the response body, whereas 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 then your application needs the ORDERS_READ OAuth permission to call the RetrieveOrder endpoint.

V1 RetrievePayment response fieldMapping to Square Payment or Order object field
idPayment.id
merchant_idPayment.location_id
created_atPayment.created_at
creator_idPayment.team_member_id
devicePayment.device_details
device.idPayment.device_details.device_id
device.namePayment.device_details.device_name
payment_urlN/A. The field is not available.
receipt_urlPayment.receipt_url
inclusive_tax_moneyNo direct field mapping. Instead, you aggregate manually across the objects in Orders.taxes where OrderLineItemTax.type is INCLUSIVE.
additive_tax_moneyNo direct field mapping. Instead, you aggregate manually across the objects in Orders.taxes where OrderLineItemTax.type is ADDITIVE.
tax_moneyOrder.total_tax_money
tip_moneyPayment.tip_money
discount_moneyOrder.total_discount_money
total_collected_moneyYou calculate the value: Order.net_amounts.total_money minus Payment.processing_fee.
processing_fee_moneyPayment.processing_fee
net_total_moneyOrder.net_amounts.total_money - Payment.processing_fee
refunded_moneyPayment.refunded_money
swedish_rounding_moneyOrders.rounding_adjuestment
gross_sales_moneyPayment.total_money
net_sales_moneyYou calculate the value: Payment.total_money minus Order.total_tax_money.
inclusive_taxNo direct field mapping. Instead, you aggregate manually across the objects in Orders.taxes where OrderLineItemTax.type is INCLUSIVE.
additive_taxNo direct field mapping. Instead, you aggregate manually across the objects in Orders.taxes where OrderLineItemTax.type is ADDITIVE.
tenderThere are no multiple tenders. The Payment represents a single tender.
tenders.idPayment.id
tenders.typePayment.source_type
tenders.nameThere are no tenders in the Payment object. You might use source_type as tenders.name.
tenders.employee_idPayment.team_member_id
tenders.receipt_urlPayment.receipt_url
tenders.card_brandPayment.card_details.card.card_brand
tenders.pan_suffixPayment.card_details.card.last_4
tenders.entry_methodPayment.card_details.entry_method
tenders.payment_notePayment.note
tenders.total_moneyPayment.total_money
tenders.tendered_moneyPayment.cash_details.amount_money
tenders.tendered_atPayment.created_at
tenders.settled_atPayment.card_details.card_payment_timeline.captured_at
tenders.change_back_moneyPayment.cash_details.change_back_money
tenders.refunded_moneyOrders.refunds.amount_money
tenders.is_exchangeYou can derive whether the order is an exchange order by verifying the presence of the line_items and returns in the Order object.
refundsYou first retrieve Payment.refund_ids and then use the Refunds API to retrieve the PaymentRefund objects.
refunds.typeYou 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.reasonPaymentRefund.reason
refunds.refunded_moneyPaymentRefund.amount_money
refunds.refunded_processing_fee_moneyPaymentRefund.processing_fee.amount_money
refunds.refunded_tax_moneyOrder.returns.return_amounts.tax_money
refunds.refunded_additive_tax_moneyNo direct field mapping. Instead, you aggregate manually across the objects in Order.returns.return_taxes where return_taxes.type is ADDITIVE.
refunds.refunded_additive_taxNo direct field mapping. Instead, you aggregate manually across the objects in Order.returns.return_taxes where return_taxes.type is ADDITIVE.
refunds.refunded_inclusive_tax_moneyNo direct field mapping. Instead, you aggregate manually across the objects in Order.returns.return_taxes where return_taxes.type is INCLUSIVE.
refunds.refunded_inclusive_taxNo direct field mapping. Instead, you aggregate manually across the objects in Order.returns.return_taxes where return_taxes.type is INCLUSIVE.
refunds.refunded_tip_moneyOrder.returns.return_amounts.tip_money
refunds.refunded_discount_moneyOrder.returns.return_amounts.tax_money
refunds.refunded_surcharge_moneyOrder.returns.return_amounts.service_charge_money
refunds.refunded_surchargesOrder.returns.return_service_charges
refunds.created_atPaymentRefund.created_at
refunds.processed_atN/A. This field is not available.
refunds.payment_idPaymentRefund.payment_id
refunds.merchant_idPaymentRefund.location_id
refunds.is_exchangeYou can derive 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.
itemizationsOrder.line_items
itemizations.nameOrderLineItem.name
itemizations.quantityOrderLineItem.quantity
itemizations.itemization_typeOrderLineItem.item_type
itemizations.item_detailYou can use the OrderLineItem.catalog_object_id to retrieve the catalog information.
itemizations.item_detail.category_nameYou can use the `OrderLineItem.catalog_object_id to retrieve the catalog information.
itemizations.item_detail.skuN/A. Not available in a Payment or Order object.
itemizations.item_detail.item_idOrderLineItem.catalog_object_id
itemizations.item_detail.item_variation_idOrderLineItem.catalog_object_id
itemizations.notesOrderLineItem.note
itemizations.item_variation_nameOrderLineItem.variation_name
itemizations.total_moneyOrderLineItem.total_money
itemizations.single_quantity_moneyOrderLineItem.base_price_money
itemizations.gross_sales_moneyOrderLineItem.gross_sales_money
itemizations.discount_moneyOrderLineItem.total_discount_money
itemizations.net_sales_moneyNo direct field mapping. Instead, you add OrderLineItem.gross_sales_money and OrderLineItem.total_discount_money.
itemizations.taxesOrderLineItem.applied_taxes.OrderLineItemAppliedTax
itemizations.taxes.nameOrder.taxes.name
itemizations.taxes.applied_moneyOrderLineItemAppliedTax.applied_money
itemizations.taxes.rateOrder.taxes.percentage
itemizations.taxes.inclusion_typeOrder.taxes.type
itemizations.taxes.fee_idOrderLineItem.applied_taxes.tax_uid
itemizations.discountsOrderLineItem.applied_discounts.OrderLineItemAppliedDiscount
itemizations.discounts.nameOrder.discounts.name
itemizations.discounts.applied_moneyOrderLineItemAppliedDiscount.applied_money
itemizations.discounts.discount_idOrderLineItemAppliedDiscount.discount_uid
itemizations.modifiersOrderLineItem.modifiers.OrderLineItemModifier
itemizations.modifiers.nameOrderLineItemModifier.name
itemizations.modifiers.applied_moneyOrderLineItemModifier.total_price_money
itemizations.modifiers.modifier_option_idOrderLineItemModifier.catalog_object_id
surcharge_moneyOrder.total_service_charge_money
surchargesOrder.service_charges.OrderServiceCharge
surcharges.nameOrderServiceCharge.name
surcharges.applied_moneyOrderServiceCharge.applied_money
surcharges.rateOrderServiceCharge.percentage
surcharges.amount_moneyOrderServiceCharge.amount_money
surcharges.typeOrderServiceCharge.type
surcharges.taxableOrderServiceCharge.taxable
surcharges.taxesOrderServiceCharge.applied_taxes
surcharges.surcharge_idOrderServiceCharge.catalog_object_id
is_partialTo 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.

The following table shows how the V1 ListPayments path parameters map to the Square ListPayments endpoint.

V1 ListPayments path parameterSquare ListPayments path parameter
location_idNot 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 parameterSquare ListPayments query parameter
ordersort_order
begin_timebegin_time
end_timeend_time
limitlimit
batch_tokencursor
include_partialN/A

The V1 ListPayments endpoint returns payment information as an array of V1 Payment objects in the response body, whereas the Square ListPayments endpoint returns an array of Square Payment objects. This Payment object provides an order_id, if available, which you can use to retrieve the Order object.

V1 ListPayments response fieldMapping to Square Payment or Order object field
itemsPayment object
items.idPayment.id
items.additive_taxNo direct field mapping. Instead, you aggregate manually across the objects in Orders.taxes where OrderLineItemTax.type is ADDITIVE.
items.additive_tax_moneyNo direct field mapping. Instead, you aggregate manually across the objects in Orders.taxes where OrderLineItemTax.type is ADDITIVE.
items.created_atPayment.created_at
items.creator_idPayment.team_member_id
items.devicePayment.device_details
items.discount_moneyOrder.total_discount_money
items.gross_sales_moneyPayment.total_money
items.inclusive_taxNo direct field mapping. Instead, you aggregate manually across the objects in Orders.taxes where OrderLineItemTax.type is INCLUSIVE.
items.inclusive_tax_moneyNo direct field mapping. Instead, you aggregate manually across the objects in Orders.taxes where OrderLineItemTax.type is INCLUSIVE.
items.is_partialTo 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.
items.itemizationsOrder.line_items
items.merchant_idPayment.location_id
items.net_sales_moneyPayment.total_money minus Order.total_tax_money
items.net_total_moneyOrder.net_amounts.total_money
items.payment_urlNot available.
items.processing_fee_moneyPayment.processing_fee
items.receipt_urlPayment.receipt_url
items.refunded_moneyOrder.return_amounts.total_money
items.refundsYou first retrieve Payment.refund_ids and then use the Refunds API to retrieve the PaymentRefund objects.
items.surcharge_moneyOrder.total_service_charge_money
items.surchargesOrder.service_charges
items.swedish_rounding_moneyOrders.rounding_adjuestment
items.tax_moneyOrder.total_tax_money
items.tenderThere are no multiple tenders. The Payment represents a single tender.
items.tip_moneyPayment.tip_money
items.total_collected_moneyOrder.net_amounts.total_money minus Payment.processing_fee

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