Stripe sources and integration configuration

Create a legacy customer from token input

This customer_id field is passed into provider customer creation as a token. Supplying an existing cus_ customer identifier is not an existing-customer import through this action.

POST /api/v1/user/stripe/customer

Before you call

Use the member and resource context; apply this operation’s provider and record requirements below.

Use the legacy customer-creation context. Keep this operation’s body field and error codes as specified below.

Request

JSON object required; form fields not used.

Result

HTTP 201 top-level legacy customer record, with cards rather than payment_methods; created customer can exist without resource attachment/default. No user/profile wrapper.

curl -X POST "${WALLKIT_API_BASE}/api/v1/user/stripe/customer" \
  -H "token: ${USER_TOKEN}" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"customer_id":"tok_SYNTHETIC"}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/user/stripe/customer`, {
  method: "POST",
  headers: {token: process.env.USER_TOKEN, resource: process.env.RESOURCE_KEY, "Content-Type": "application/json"},
  body: JSON.stringify({"customer_id":"tok_SYNTHETIC"})
});
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

body = {'customer_id': 'tok_SYNTHETIC'}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/user/stripe/customer",
    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))

{
  "id": 4001,
  "pay_system": "stripe",
  "customer_id": "cus_SYNTHETIC",
  "cards": [
    {
      "id": 5001,
      "card_last4": "0000"
    }
  ]
}

Create a legacy customer with a provider token

Consume an existing provider token to create a customer and import cards. No token is generated by this route.

POST /api/v1/user/stripe/token

Before you call

Use the member and resource context; apply this operation’s provider and record requirements below.

Use the legacy customer-creation context. Keep this operation’s body field and error codes as specified below.

Request

JSON object required.

Result

HTTP 201 top-level legacy customer record, with cards rather than payment_methods; created customer can exist without resource attachment/default. No user/profile wrapper.

curl -X POST "${WALLKIT_API_BASE}/api/v1/user/stripe/token" \
  -H "token: ${USER_TOKEN}" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"token":"tok_SYNTHETIC"}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/user/stripe/token`, {
  method: "POST",
  headers: {token: process.env.USER_TOKEN, resource: process.env.RESOURCE_KEY, "Content-Type": "application/json"},
  body: JSON.stringify({"token":"tok_SYNTHETIC"})
});
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

body = {'token': 'tok_SYNTHETIC'}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/user/stripe/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))

{
  "id": 4001,
  "pay_system": "stripe",
  "customer_id": "cus_SYNTHETIC",
  "cards": []
}

Attach and persist a legacy payment method

Retrieve a provider method, attach it to the supplied provider customer, then save a local method associated with supplied local customer/card IDs. This does not confirm a PaymentIntent/SetupIntent, charge or establish a local/provider default.

POST /api/v1/user/stripe/confirm-payment-method

Before you call

Use the member and resource context; apply this operation’s provider and record requirements below.

Requires configured Stripe keys/account; initStripe uses resource payment mode and switches connected-account key when configured.

No explicit local customer/card ownership, resource membership, provider-customer match, duplicate check, or intent ID/status proof. Trusted integration must supply matching member-owned provider and local records.

Provider attachment occurs before local save; false save returns an error without undoing attachment.

No encompassing transaction/replay guarantee.

The action reads first supplied card ID but does not create or validate that card.

Request

JSON object required; nested fields are read directly without individual presence validation.

Result

HTTP 201 raw refreshed model toArray uses raw confirmed method. It has no nested user_card addition and does not use compact source DTO or modern asArray projection.

curl -X POST "${WALLKIT_API_BASE}/api/v1/user/stripe/confirm-payment-method" \
  -H "token: ${USER_TOKEN}" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"intent":{"payment_method":"pm_SYNTHETIC"},"customer":{"id":4001,"customer_id":"cus_SYNTHETIC","cards":[{"id":5001}]}}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/user/stripe/confirm-payment-method`, {
  method: "POST",
  headers: {token: process.env.USER_TOKEN, resource: process.env.RESOURCE_KEY, "Content-Type": "application/json"},
  body: JSON.stringify({"intent":{"payment_method":"pm_SYNTHETIC"},"customer":{"id":4001,"customer_id":"cus_SYNTHETIC","cards":[{"id":5001}]}})
});
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

body = {'intent': {'payment_method': 'pm_SYNTHETIC'}, 'customer': {'id': 4001, 'customer_id': 'cus_SYNTHETIC', 'cards': [{'id': 5001}]}}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/user/stripe/confirm-payment-method",
    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))

{
  "id": 3001,
  "payment_method_id": "pm_SYNTHETIC",
  "customer_id": "cus_SYNTHETIC",
  "payment_customer_id": 4001,
  "card_id": 5001
}

Delete a local customer record

Attempt deletion of the local customer. This action does not call Stripe customer deletion or explicitly remove cards/methods/resource relationships. Database relationship behavior is not established by these model definitions.

DELETE /api/v1/user/stripe/customer/{id}

Before you call

Use the member and resource context; apply this operation’s provider and record requirements below.

Lookup requires local customer owner/current resource attachment/ID. Despite the route name, the lookup does not check pay_system or mode. A local customer of another provider can match. The record can be shared with other resources; deleting it is not limited to an attachment removal. No cancellation/refund/provider erasure guarantee.

Request

Bodyless. id path required digits: local customer record ID from owned customer list, not provider customer_id.

Result

HTTP 200 result boolean from delete return value. false is a business failure even with HTTP 200; no deleted record returned.

curl -X DELETE "${WALLKIT_API_BASE}/api/v1/user/stripe/customer/4001" \
  -H "token: ${USER_TOKEN}" \
  -H "resource: ${RESOURCE_KEY}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/user/stripe/customer/4001`, {
  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/stripe/customer/4001",
    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))

{
  "result": true
}

Read Stripe integration authorization guidance

Return authorization URLs or local connection guidance for live and test modes. This returns JSON; it does not redirect the browser, exchange a code or save connection credentials.

GET /api/v1/integrations/stripe/oauth

Before you call

Use the authorized administrator context for actor permissions, resource selection and base-key requirements.

Requires existing global stripe mode-specific app_client_id/auth_redirect_url and scopes/response_type configuration. All-four-field settings presence determines deauthorize, not a provider account check. The application owns callback correlation/authorization because the generated state is the resource public key and code exchange does not validate it.

Request

Bodyless; no mode parameter. Both modes are inspected. No collection/pagination.

Result

HTTP 200 status string ok with live/test objects.

curl -X GET "${WALLKIT_API_BASE}/api/v1/integrations/stripe/oauth" \
  -H "token: ${ADMIN_TOKEN}" \
  -H "resource: ${RESOURCE_KEY}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/stripe/oauth`, {
  method: "GET",
  headers: {token: process.env.ADMIN_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/integrations/stripe/oauth",
    method="GET", headers={"token": os.environ["ADMIN_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))

{
  "status": "ok",
  "live": {
    "type": "authorize",
    "authorize_url": "https://example.com/SYNTHETIC_PROVIDER_AUTHORIZATION_URL"
  },
  "test": {
    "type": "deauthorize",
    "authorize_url": ""
  }
}

Exchange a Stripe integration authorization code

Exchange an existing provider callback code and attempt to save connected-account credentials in resource settings. This is integration configuration, not member login or payment.

POST /api/v1/integrations/stripe/oauth

Before you call

Use the authorized administrator context for actor permissions, resource selection and base-key requirements.

Existing callback handling must correlate authorized admin/resource/mode and supplied code. Handler does not accept/validate state or bind the code to an independently checked account owner.

Global mode-specific Wallkit Stripe private key is used for exchange.

If provider stripe_user_id exists, returned provider livemode selects the settings slot, which can differ from requested mode.

The entire resource settings array is saved with that stripe_connect slot replaced; save boolean is unchecked.

Provider exchange precedes local save: response success does not guarantee persisted credentials and an error does not make code replay safe.

Saving a resource can also clear that resource’s guest content-view records when default_guest_subscription_id exists but is false.

Request

JSON object required.

Result

HTTP 200 only the following projection, not raw OAuth response.

curl -X POST "${WALLKIT_API_BASE}/api/v1/integrations/stripe/oauth" \
  -H "token: ${ADMIN_TOKEN}" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"code":"SYNTHETIC_PROVIDER_OAUTH_CODE","mode":"test"}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/stripe/oauth`, {
  method: "POST",
  headers: {token: process.env.ADMIN_TOKEN, resource: process.env.RESOURCE_KEY, "Content-Type": "application/json"},
  body: JSON.stringify({"code":"SYNTHETIC_PROVIDER_OAUTH_CODE","mode":"test"})
});
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

body = {'code': 'SYNTHETIC_PROVIDER_OAUTH_CODE', 'mode': 'test'}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/integrations/stripe/oauth",
    method="POST", headers={"token": os.environ["ADMIN_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))

{
  "status": "ok",
  "mode": "test",
  "access_token": "SYNTHETIC_PRIVATE_PROVIDER_ACCESS_TOKEN",
  "refresh_token": "SYNTHETIC_PRIVATE_PROVIDER_REFRESH_TOKEN",
  "stripe_user_id": "acct_SYNTHETIC",
  "stripe_publishable_key": "SYNTHETIC_PROVIDER_PUBLISHABLE_KEY"
}

Clear Stripe connection settings and conditionally deauthorize

Clear the selected resource connection slot and conditionally call provider deauthorization. This is not member logout, source deletion, subscription cancellation or refund.

POST /api/v1/integrations/stripe/deauthorize

Before you call

Use the authorized administrator context for actor permissions, resource selection and base-key requirements.

Requires existing saved stripe_user_id for chosen mode and global mode_app_client_id.

The handler constructs a presence validator but does not run it; operator validation enforces live/test instead.

Provider deauthorization happens only when the selected resource’s partner has at most one resource with complete connection settings in that mode.

The count does not compare stripe_user_id values: another resource’s different connected account can suppress this provider call.

Local credentials are cleared regardless when that branch completes.

Provider call precedes unchecked resource save; no provider/local atomic rollback or replay promise.

Resource settings save can clear guest content-view records when default_guest_subscription_id exists but is false.

Request

JSON object required.

Result

HTTP 200 status string ok; no provider response or saved settings projection. Selected stripe_connect mode slot is attempted replacement with access_token, refresh_token, stripe_user_id and stripe_publishable_key all null. Success does not prove provider authorization was revoked or local save persisted.

curl -X POST "${WALLKIT_API_BASE}/api/v1/integrations/stripe/deauthorize" \
  -H "token: ${ADMIN_TOKEN}" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"mode":"test"}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/stripe/deauthorize`, {
  method: "POST",
  headers: {token: process.env.ADMIN_TOKEN, resource: process.env.RESOURCE_KEY, "Content-Type": "application/json"},
  body: JSON.stringify({"mode":"test"})
});
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

body = {'mode': 'test'}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/integrations/stripe/deauthorize",
    method="POST", headers={"token": os.environ["ADMIN_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))

{
  "status": "ok"
}