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 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 Square Point of Sale. The resulting client transaction ID does not correspond to an order ID.
Use the transaction ID value as the Order ID
as shown in the following operation:
1
2
3
4
curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
-H 'Square-Version: 2023-01-19' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'
The response is an Order
object that includes a tenders
array. Each item in the array is the ID of a Payment
object.
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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
{
"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:
1
2
3
4
curl https://connect.squareupsandbox.com/v2/payments/{payment_id} \
-H 'Square-Version: 2023-01-19' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'
The response is a Payment
object with the details of the payment.
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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
"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"
}
}
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.