Square sources
The token route consumes an existing provider-client source token to create customer/card data. Local customer removal does not remove the Square customer.
Example runtimes, base-address conventions and synthetic values follow response conventions.
Create a Square customer and card from token
Consume a provider source token, create a provider customer, create a provider card attached to it, retrieve the customer and import local records. This does not generate a token or charge.
POST /api/v1/user/square/token
Before you call
Use the member and resource context; apply this operation’s provider and record requirements below.
Explicit square operator uses resource payments_in_live_mode (default true) to choose production/sandbox settings. Existing square.live/test access_token, app_id and location_id are required; examples expose none of those private settings. The token must come from the existing provider client in this account/mode; no separate token-owner check is added.
Provider customer receives member name/company/email. Customer creation precedes card creation, retrieval and unchecked local saves/import/default changes.
Provider requests generate fresh internal idempotency keys per call; no caller key or replay-safe behavior is promised. A later card/local failure can leave a provider customer or card. Local auto_attach_customer_to_resource defaults true, can be disabled, and attachment exceptions are swallowed. Newly imported Square cards get local default selection; no modern method is created.
Request
JSON object required.
| Name | Location | Type / requirement | Meaning |
|---|---|---|---|
| token | JSON | required nonempty trimmed string | Existing Square source token used to create card; not member header token/local saved card ID. |
Result
HTTP 201 Top-level legacy customer record: local id, provider customer_id, provider label, local timestamps and related cards. No member wrapper or payment_method ID. Square imports card brand/last4 and last-day expiry Y-m-d when available; country can remain unset.
Example: Save a Square customer and card
Consume an existing provider-client source token. The customer excerpt shows local card 5003 after provider creation/import; provider token and saved card ID are different values.
curl -X POST "${WALLKIT_API_BASE}/api/v1/user/square/token" \
-H "token: ${USER_TOKEN}" \
-H "resource: ${RESOURCE_KEY}" \
-H "Content-Type: application/json" \
--data '{"token":"SYNTHETIC_SQUARE_SOURCE_TOKEN"}'
const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/user/square/token`, {
method: "POST",
headers: {token: process.env.USER_TOKEN, resource: process.env.RESOURCE_KEY, "Content-Type": "application/json"},
body: JSON.stringify({"token":"SYNTHETIC_SQUARE_SOURCE_TOKEN"})
});
console.log(response.status, await response.json());
import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError
body = {'token': 'SYNTHETIC_SQUARE_SOURCE_TOKEN'}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/user/square/token",
method="POST", headers={"token": os.environ["USER_TOKEN"],
"resource": os.environ["RESOURCE_KEY"], "Content-Type": "application/json"}, data=json.dumps(body).encode("utf-8"))
try:
with urlopen(request) as response:
print(response.status, json.load(response))
except HTTPError as error:
print(error.code, json.load(error))
Synthetic HTTP 201 response excerpt:
{
"id": 4003,
"pay_system": "square",
"customer_id": "SYNTHETIC_SQUARE_CUSTOMER",
"cards": [
{
"id": 5003,
"card_last4": "0000",
"expiration_date": "2030-12-31"
}
]
}
Consequential alternate
HTTP 406 incorrect_retrieve_card can follow a successful provider customer creation and failed provider card creation. Inspect provider and local state before consuming another token or repeating creation.
Recovery
| Status | Code / shape | Cause | Next action |
|---|---|---|---|
| 406 | incorrect_data / incorrect_token | Missing JSON/token. | Supply existing provider-client source token. |
| 406 | incorrect_create_payment_customer | Customer creation/retrieval fails. | Inspect configured mode/account and partial provider records. |
| 406 | incorrect_retrieve_card | Provider card creation/import failure. | Inspect created customer/card state before retry. |
| 406 | incorrect_retrieve_token | Other configuration/local failure. | Check existing account settings and local records. |
Next task
List resource cards, use local user_card_id 5003 with compatible configured Square calculation/checkout. Raw provider token is not user_card_id.
Delete a local customer record
Attempt deletion of a local customer; no Square provider customer/card deletion is called. This does not cancel membership or refund.
DELETE /api/v1/user/square/customer/{id}
Before you call
Use the member and resource context; apply this operation’s provider and record requirements below.
Lookup checks local customer owner, selected resource attachment and ID. Despite the route name, the lookup does not check for the Square provider or a particular mode. Shared local customer deletion can affect other attached resources. Cards/methods/resource associations are not explicitly cleaned up, and database cascades are not established by these source model declarations.
Request
Bodyless; id path required digits, local customer ID from owned-customer list. Not provider customer_id.
Result
HTTP 200 result boolean cast from local delete return. false is a failed delete even with HTTP 200; no returned customer projection.
Example: Remove local customer 4003
Delete an owned resource-attached local customer. result reports local deletion, not removal of the Square customer/card.
curl -X DELETE "${WALLKIT_API_BASE}/api/v1/user/square/customer/4003" \
-H "token: ${USER_TOKEN}" \
-H "resource: ${RESOURCE_KEY}"
const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/user/square/customer/4003`, {
method: "DELETE",
headers: {token: process.env.USER_TOKEN, resource: process.env.RESOURCE_KEY}
});
console.log(response.status, await response.json());
import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/user/square/customer/4003",
method="DELETE", headers={"token": os.environ["USER_TOKEN"],
"resource": os.environ["RESOURCE_KEY"]})
try:
with urlopen(request) as response:
print(response.status, json.load(response))
except HTTPError as error:
print(error.code, json.load(error))
Synthetic HTTP 200 response excerpt:
{
"result": true
}
Consequential alternate
HTTP 200 {"result":false} reports local failure. Missing/wrong scoped customer returns HTTP 409 incorrect_user_payment_customer_id; neither response describes provider cleanup.
Recovery
| Status | Code / shape | Cause | Next action |
|---|---|---|---|
| 409 | incorrect_user_payment_customer_id | No owned customer attached to selected resource at local ID. | Read owned customers/resource visibility and use the matching local ID. |
| 200 | result:false | Local delete returned false. | Inspect remaining local record; do not assume provider deletion or retry safety. |
Next task
List owned customers and resource cards to inspect remaining visibility. Provider customer cleanup is separate and not performed by this endpoint.