POS API

Payments API Integration

There is no direct way to retrieve payment details for a Point of Sale or Reader SDK payment using the Payments API. However, the transaction ID returned by the either of these SDKs on transaction completion can be used to retrieve an Order by order ID where the order ID is the transaction ID.

Note

The following procedure does not work for cash payments made with the Square Point of Sale. The resulting client transaction ID does not correspond to an order ID.

Retrieve an Order Permalink Get a link to this section

Use the transaction ID value as the Order ID as shown in the following operation:

Retrieve Order
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The response is an Order object which includes a tenders array. Each item in the array is the ID of a Payment object.

{
  "orders": [
    {
      "id": "oHyQ6w9wEc72nlKaIptsnc3CLnSZY",
      "location_id": "VJN4XSBFTVPK9",
      "line_items": [
        {
          "uid": "333r2",
          "quantity": "1",
          "name": "A Widget",
          "base_price_money": {
            "amount": 100,
            "currency": "USD"
          },
          "gross_sales_money": {
            "amount": 100,
            "currency": "USD"
          },
          "total_tax_money": {
            "amount": 0,
            "currency": "USD"
          },
          "total_discount_money": {
            "amount": 0,
            "currency": "USD"
          },
          "total_money": {
            "amount": 100,
            "currency": "USD"
          },
          "variation_total_price_money": {
            "amount": 100,
            "currency": "USD"
          }
        }
      ],
      "created_at": "2021-05-20T22:38:25.167Z",
      "updated_at": "2021-05-20T22:40:40.000Z",
      "state": "COMPLETED",
      "version": 4,
      "total_tax_money": {
        "amount": 0,
        "currency": "USD"
      },
      "total_discount_money": {
        "amount": 0,
        "currency": "USD"
      },
      "total_tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "total_money": {
        "amount": 100,
        "currency": "USD"
      },
      "closed_at": "2021-05-20T22:40:39.091Z",
      "tenders": [
        {
          "id": "l2CwYK0ox8LvhNYYFm5N8wbVFlNZY",
          "location_id": "VJN4XSBFTVPK9",
          "transaction_id": "oHyQ6w9wEc72nlKaIptsnc3CLnSZY",
          "created_at": "2021-05-20T22:40:38Z",
          "amount_money": {
            "amount": 100,
            "currency": "USD"
          },
          "type": "CARD",
          "card_details": {
            "status": "CAPTURED",
            "card": {
              "card_brand": "VISA",
              "last_4": "5858",
              "fingerprint": "sq-1-Gg4tFVdtVF6tOSc8REcyHNW1aBKSZp3iQb3ZzdVG_JtpLftLvVkQhlXizopHIGbIgQ"
            },
            "entry_method": "KEYED"
          },
          "payment_id": "l2CwYK0ox8LvhNYYFm5N8wbVFlNZY"
        }
      ],
      "total_service_charge_money": {
        "amount": 0,
        "currency": "USD"
      },
      "net_amounts": {
        "total_money": {
          "amount": 100,
          "currency": "USD"
        },
        "tax_money": {
          "amount": 0,
          "currency": "USD"
        },
        "discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "tip_money": {
          "amount": 0,
          "currency": "USD"
        },
        "service_charge_money": {
          "amount": 0,
          "currency": "USD"
        }
      },
      "source": {
        "name": "Sandbox for sq0idp-qsHFd8ECFSnT-l3YV8oeUg"
      },
      "customer_id": "W13EWDK1C4SXDCFBHM4E3S02GM"
    }
  ]
}

There should be a single Payment ID in the tenders array. Use that ID to make the following call:

Get Payment
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/payments/{payment_id} \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The response is a Payment object with the details of the payment:

{
  "payment": {
    "id": "l2CwYK0ox8LvhNYYFm5N8wbVFlNZY",
    "created_at": "2021-05-20T22:40:38.862Z",
    "updated_at": "2021-05-20T22:40:39.066Z",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "status": "COMPLETED",
    "delay_duration": "PT168H",
    "source_type": "CARD",
    "card_details": {
      "status": "CAPTURED",
      "card": {
        "card_brand": "VISA",
        "last_4": "5858",
        "exp_month": 5,
        "exp_year": 2023,
        "fingerprint": "sq-1-Gg4tFVdtVF6tOSc8REcyHNW1aBKSZp3iQb3ZzdVG_JtpLftLvVkQhlXizopHIGbIgQ",
        "card_type": "DEBIT",
        "prepaid_type": "NOT_PREPAID",
        "bin": "453275"
      },
      "entry_method": "KEYED",
      "cvv_status": "CVV_ACCEPTED",
      "avs_status": "AVS_ACCEPTED",
      "statement_description": "SQ *DEFAULT TEST ACCOUNT",
      "card_payment_timeline": {
        "authorized_at": "2021-05-20T22:40:38.973Z",
        "captured_at": "2021-05-20T22:40:39.066Z"
      }
    },
    "location_id": "VJN4XSBFTVPK9",
    "order_id": "oHyQ6w9wEc72nlKaIptsnc3CLnSZY",
    "risk_evaluation": {
      "created_at": "2021-05-20T22:40:38.974Z",
      "risk_level": "NORMAL"
    },
    "processing_fee": [
      {
        "effective_at": "2021-05-21T00:40:39.000Z",
        "type": "INITIAL",
        "amount_money": {
          "amount": 33,
          "currency": "USD"
        }
      }
    ],
    "customer_id": "W13EWDK1C4SXDCFBHM4E3S02GM",
    "total_money": {
      "amount": 100,
      "currency": "USD"
    },
    "approved_money": {
      "amount": 100,
      "currency": "USD"
    },
    "receipt_number": "l2Cw",
    "receipt_url": "https://squareupsandbox.com/receipt/preview/l2CwYK0ox8LvhNYYFm5N8wbVFlNZY",
    "delay_action": "CANCEL",
    "delayed_until": "2021-05-27T22:40:38.862Z",
    "version_token": "EyyyosIhkvX7UyqWk1lyNLDcdfBcc4ahyTDIlPYUuMN6o"
  }
}