Payments

List Trellis Payments provider capabilities

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

`application/json`

curl -X GET "https://example.com/payments/capabilities" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "providers": {    "property1": {      "tipping": true,      "tipAdjustment": true,      "incrementalAuthorization": true,      "offlinePayments": true,      "cardOnFile": true,      "refunds": true,      "partialRefunds": true,      "manualCapture": true,      "payAtTable": true,      "tapToPay": true,      "supportedTerminalTypes": [        "string"      ]    },    "property2": {      "tipping": true,      "tipAdjustment": true,      "incrementalAuthorization": true,      "offlinePayments": true,      "cardOnFile": true,      "refunds": true,      "partialRefunds": true,      "manualCapture": true,      "payAtTable": true,      "tapToPay": true,      "supportedTerminalTypes": [        "string"      ]    }  }}

List Trellis Payments merchant accounts

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

`application/json`

curl -X GET "https://example.com/payments/merchant-accounts" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "accounts": [    {      "id": "string",      "locationId": "string",      "provider": "mock",      "externalId": "string",      "status": "pending",      "displayName": "string",      "capabilities": {        "tipping": true,        "tipAdjustment": true,        "incrementalAuthorization": true,        "offlinePayments": true,        "cardOnFile": true,        "refunds": true,        "partialRefunds": true,        "manualCapture": true,        "payAtTable": true,        "tapToPay": true,        "supportedTerminalTypes": [          "string"        ]      },      "providerMetadata": {        "property1": null,        "property2": null      },      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}

Activate Trellis Payments for a merchant

Creates the provider-backed merchant account. Stripe is the initial adapter; Trellis owns the public account model.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider?|||

locationId?string

displayName*string

Length1 <= length

contactEmail?string

Formatemail

country?string

Length2 <= length <= 2

currency?string

Length3 <= length <= 3

`application/json`

curl -X POST "https://example.com/payments/merchant-accounts" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "displayName": "string"  }'

{  "id": "string",  "locationId": "string",  "provider": "mock",  "externalId": "string",  "status": "pending",  "displayName": "string",  "capabilities": {    "tipping": true,    "tipAdjustment": true,    "incrementalAuthorization": true,    "offlinePayments": true,    "cardOnFile": true,    "refunds": true,    "partialRefunds": true,    "manualCapture": true,    "payAtTable": true,    "tapToPay": true,    "supportedTerminalTypes": [      "string"    ]  },  "providerMetadata": {    "property1": null,    "property2": null  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Continue Trellis Payments activation

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

refreshUrl*string

Formaturi

returnUrl*string

Formaturi

`application/json`

curl -X POST "https://example.com/payments/merchant-accounts/string/onboarding-link" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "refreshUrl": "http://example.com",    "returnUrl": "http://example.com"  }'

{  "url": "http://example.com",  "expiresAt": "2019-08-24T14:15:22Z"}

Refresh Trellis Payments activation status

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

`application/json`

curl -X POST "https://example.com/payments/merchant-accounts/string/refresh" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "id": "string",  "locationId": "string",  "provider": "mock",  "externalId": "string",  "status": "pending",  "displayName": "string",  "capabilities": {    "tipping": true,    "tipAdjustment": true,    "incrementalAuthorization": true,    "offlinePayments": true,    "cardOnFile": true,    "refunds": true,    "partialRefunds": true,    "manualCapture": true,    "payAtTable": true,    "tapToPay": true,    "supportedTerminalTypes": [      "string"    ]  },  "providerMetadata": {    "property1": null,    "property2": null  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Get backend payment provider configuration

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

`application/json`

curl -X GET "https://example.com/payments/config" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "defaultProvider": "mock",  "providers": [    {      "id": "string",      "provider": "mock",      "displayName": "string",      "isEnabled": true,      "environment": "test",      "locationId": "string",      "terminalReaderId": "string",      "settings": {        "property1": null,        "property2": null      },      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "offlineCapabilities": {    "property1": true,    "property2": true  },  "providerCapabilities": {    "property1": {      "tipping": true,      "tipAdjustment": true,      "incrementalAuthorization": true,      "offlinePayments": true,      "cardOnFile": true,      "refunds": true,      "partialRefunds": true,      "manualCapture": true,      "payAtTable": true,      "tapToPay": true,      "supportedTerminalTypes": [        "string"      ]    },    "property2": {      "tipping": true,      "tipAdjustment": true,      "incrementalAuthorization": true,      "offlinePayments": true,      "cardOnFile": true,      "refunds": true,      "partialRefunds": true,      "manualCapture": true,      "payAtTable": true,      "tapToPay": true,      "supportedTerminalTypes": [        "string"      ]    }  }}

Set global backend payment provider

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

defaultProvider*|||

`application/json`

curl -X PUT "https://example.com/payments/config" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "defaultProvider": "mock"  }'

{  "defaultProvider": "mock",  "providers": [    {      "id": "string",      "provider": "mock",      "displayName": "string",      "isEnabled": true,      "environment": "test",      "locationId": "string",      "terminalReaderId": "string",      "settings": {        "property1": null,        "property2": null      },      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "offlineCapabilities": {    "property1": true,    "property2": true  },  "providerCapabilities": {    "property1": {      "tipping": true,      "tipAdjustment": true,      "incrementalAuthorization": true,      "offlinePayments": true,      "cardOnFile": true,      "refunds": true,      "partialRefunds": true,      "manualCapture": true,      "payAtTable": true,      "tapToPay": true,      "supportedTerminalTypes": [        "string"      ]    },    "property2": {      "tipping": true,      "tipAdjustment": true,      "incrementalAuthorization": true,      "offlinePayments": true,      "cardOnFile": true,      "refunds": true,      "partialRefunds": true,      "manualCapture": true,      "payAtTable": true,      "tapToPay": true,      "supportedTerminalTypes": [        "string"      ]    }  }}

List configured payment providers

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

`application/json`

curl -X GET "https://example.com/payments/providers" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "providers": [    {      "id": "string",      "provider": "mock",      "displayName": "string",      "isEnabled": true,      "environment": "test",      "locationId": "string",      "terminalReaderId": "string",      "settings": {        "property1": null,        "property2": null      },      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}

Create payment provider configuration

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider*|||

displayName?string

isEnabled?boolean

environment?|

locationId?string

terminalReaderId?string

credentials?

settings?

`application/json`

curl -X POST "https://example.com/payments/providers" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "provider": "mock"  }'

{  "id": "string",  "provider": "mock",  "displayName": "string",  "isEnabled": true,  "environment": "test",  "locationId": "string",  "terminalReaderId": "string",  "settings": {    "property1": null,    "property2": null  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Update payment provider configuration

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider*|||

displayName?string

isEnabled?boolean

environment?|

locationId?string

terminalReaderId?string

credentials?

settings?

`application/json`

curl -X PUT "https://example.com/payments/providers/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "provider": "mock"  }'

{  "id": "string",  "provider": "mock",  "displayName": "string",  "isEnabled": true,  "environment": "test",  "locationId": "string",  "terminalReaderId": "string",  "settings": {    "property1": null,    "property2": null  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Enqueue an offline payment action

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider?|||

actionType*string

idempotencyKey*string

Length1 <= length

orderId?string

paymentIntentId?string

terminalReaderId?string

payload?

`application/json`

curl -X POST "https://example.com/payments/offline-queue" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "actionType": "string",    "idempotencyKey": "string"  }'

{  "id": "string",  "provider": "mock",  "actionType": "string",  "idempotencyKey": "string",  "orderId": "string",  "paymentIntentId": "string",  "terminalReaderId": "string",  "status": "pending",  "payload": {    "property1": null,    "property2": null  },  "result": {    "property1": null,    "property2": null  },  "errorMessage": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "processedAt": "2019-08-24T14:15:22Z"}

List known terminal readers

Modeled for Stripe Terminal smart readers, especially WisePOS E. Local records are merged with Stripe-managed reader state where available.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

`application/json`

curl -X GET "https://example.com/terminal/readers" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "readers": [    {      "id": "string",      "provider": "mock",      "merchantPaymentAccountId": "string",      "externalId": "string",      "providerMetadata": {        "property1": null,        "property2": null      },      "configuredProvider": "mock",      "providerConfigurationId": "string",      "providerReaderId": "string",      "label": "string",      "deviceType": "bbpos_wisepos_e",      "locationId": "string",      "status": "online",      "actionStatus": "idle",      "assignment": {        "orderId": "string",        "stationLabel": "string"      },      "lastSeenAt": "2019-08-24T14:15:22Z"    }  ]}

Create a terminal reader registration

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

registrationCode*string

label*string

locationId*string

externalLocationId?string

provider?|||

configuredProvider?|||

providerConfigurationId?string

deviceType?|||||||

`application/json`

curl -X POST "https://example.com/terminal/readers" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "registrationCode": "string",    "label": "string",    "locationId": "string"  }'

{  "id": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerMetadata": {    "property1": null,    "property2": null  },  "configuredProvider": "mock",  "providerConfigurationId": "string",  "providerReaderId": "string",  "label": "string",  "deviceType": "bbpos_wisepos_e",  "locationId": "string",  "status": "online",  "actionStatus": "idle",  "assignment": {    "orderId": "string",    "stationLabel": "string"  },  "lastSeenAt": "2019-08-24T14:15:22Z"}

Register a WisePOS E reader

Maps to Stripe Terminal reader registration. For sandbox development, Stripe supports simulated WisePOS E registration codes.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

registrationCode*string

label*string

locationId*string

externalLocationId?string

provider?|||

configuredProvider?|||

providerConfigurationId?string

deviceType?|||||||

`application/json`

curl -X POST "https://example.com/terminal/readers/register" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "registrationCode": "string",    "label": "string",    "locationId": "string"  }'

{  "id": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerMetadata": {    "property1": null,    "property2": null  },  "configuredProvider": "mock",  "providerConfigurationId": "string",  "providerReaderId": "string",  "label": "string",  "deviceType": "bbpos_wisepos_e",  "locationId": "string",  "status": "online",  "actionStatus": "idle",  "assignment": {    "orderId": "string",    "stationLabel": "string"  },  "lastSeenAt": "2019-08-24T14:15:22Z"}

Update terminal reader configuration

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

registrationCode?string

label?string

locationId?string

externalLocationId?string

provider?|||

configuredProvider?|||

providerConfigurationId?string

deviceType?|||||||

`application/json`

curl -X PUT "https://example.com/terminal/readers/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerMetadata": {    "property1": null,    "property2": null  },  "configuredProvider": "mock",  "providerConfigurationId": "string",  "providerReaderId": "string",  "label": "string",  "deviceType": "bbpos_wisepos_e",  "locationId": "string",  "status": "online",  "actionStatus": "idle",  "assignment": {    "orderId": "string",    "stationLabel": "string"  },  "lastSeenAt": "2019-08-24T14:15:22Z"}

Assign a reader to an order or station

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

orderId?string

stationLabel?string

`application/json`

curl -X POST "https://example.com/terminal/readers/string/assign" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerMetadata": {    "property1": null,    "property2": null  },  "configuredProvider": "mock",  "providerConfigurationId": "string",  "providerReaderId": "string",  "label": "string",  "deviceType": "bbpos_wisepos_e",  "locationId": "string",  "status": "online",  "actionStatus": "idle",  "assignment": {    "orderId": "string",    "stationLabel": "string"  },  "lastSeenAt": "2019-08-24T14:15:22Z"}

Search named tabs

Toast-inspired open tab lookup for bar and service workflows. Matches by tab name, order number, table label, and order identifier.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

`application/json`

curl -X GET "https://example.com/payments/tabs" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "tabs": [    {      "paymentIntentId": "string",      "orderId": "string",      "orderNumber": 0,      "locationId": "string",      "attributedStaffUserId": "string",      "attributedShiftId": "string",      "tableLabel": "string",      "tabName": "string",      "tabStatus": "open",      "checkState": "open",      "amount": 0,      "authorizedAmount": 0,      "capturedAmount": 0,      "tipAmount": 0,      "refundedAmount": 0,      "openedAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}

Open a named bar tab with card preauthorization

Creates a payment-backed tab record that stays open until the preauthorized card is captured and the check is closed.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

orderId*string

tabName*string

Length1 <= length

preauthAmount*integer

Range1 <= value

currency*string

Length3 <= length <= 3

readerId?string

metadata?

`application/json`

curl -X POST "https://example.com/payments/tabs" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "orderId": "string",    "tabName": "string",    "preauthAmount": 1,    "currency": "str"  }'

{  "id": "string",  "orderId": "string",  "locationId": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerPaymentIntentId": "string",  "paymentState": "pending",  "readerId": "string",  "amount": 0,  "currency": "string",  "captureMethod": "manual",  "status": "requires_payment_method",  "tenderType": "card_present",  "processorStatus": "OPEN",  "checkState": "open",  "refundStatus": "none",  "authorizedAmount": 0,  "capturedAmount": 0,  "refundedBaseAmount": 0,  "refundedTipAmount": 0,  "refundedAmount": 0,  "pendingTipAmount": 0,  "tipStatus": "none",  "tipEntrySource": "capture",  "tipPendingReason": "awaiting_adjustment",  "closedByStaffUserId": "string",  "attributedStaffUserId": "string",  "attributedShiftId": "string",  "attributedAt": "2019-08-24T14:15:22Z",  "splitTenderGroupId": "string",  "tipAmount": 0,  "tabName": "string",  "tabStatus": "open",  "preauthAmount": 1,  "metadata": {    "property1": "string",    "property2": "string"  },  "paidAt": "2019-08-24T14:15:22Z",  "capturedAt": "2019-08-24T14:15:22Z",  "closedAt": "2019-08-24T14:15:22Z",  "reopenedAt": "2019-08-24T14:15:22Z",  "tipAdjustedAt": "2019-08-24T14:15:22Z",  "voidedAt": "2019-08-24T14:15:22Z",  "refundedAt": "2019-08-24T14:15:22Z",  "refunds": [    {      "id": "string",      "amount": 0,      "tipAmount": 0,      "totalAmount": 1,      "reason": "string",      "lineItems": [        {          "orderLineId": "string",          "title": "string",          "subtotalAmount": 0,          "taxAmount": 0,          "totalAmount": 1        }      ],      "approvedByStaffUserId": "string",      "approvedAt": "2019-08-24T14:15:22Z"    }  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

List payment intents for reporting

Returns the authoritative payment and refund ledger for one tenant, optionally scoped to a restaurant location.

Query Parameters

locationId?string

Length1 <= length

createdAfter?string

Formatdate-time

createdBefore?string

Formatdate-time

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

`application/json`

curl -X GET "https://example.com/payments/intents" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "paymentIntents": [    {      "id": "string",      "orderId": "string",      "locationId": "string",      "provider": "mock",      "merchantPaymentAccountId": "string",      "externalId": "string",      "providerPaymentIntentId": "string",      "paymentState": "pending",      "readerId": "string",      "amount": 0,      "currency": "string",      "captureMethod": "manual",      "status": "requires_payment_method",      "tenderType": "card_present",      "processorStatus": "OPEN",      "checkState": "open",      "refundStatus": "none",      "authorizedAmount": 0,      "capturedAmount": 0,      "refundedBaseAmount": 0,      "refundedTipAmount": 0,      "refundedAmount": 0,      "pendingTipAmount": 0,      "tipStatus": "none",      "tipEntrySource": "capture",      "tipPendingReason": "awaiting_adjustment",      "closedByStaffUserId": "string",      "attributedStaffUserId": "string",      "attributedShiftId": "string",      "attributedAt": "2019-08-24T14:15:22Z",      "splitTenderGroupId": "string",      "tipAmount": 0,      "tabName": "string",      "tabStatus": "open",      "preauthAmount": 1,      "metadata": {        "property1": "string",        "property2": "string"      },      "paidAt": "2019-08-24T14:15:22Z",      "capturedAt": "2019-08-24T14:15:22Z",      "closedAt": "2019-08-24T14:15:22Z",      "reopenedAt": "2019-08-24T14:15:22Z",      "tipAdjustedAt": "2019-08-24T14:15:22Z",      "voidedAt": "2019-08-24T14:15:22Z",      "refundedAt": "2019-08-24T14:15:22Z",      "refunds": [        {          "id": "string",          "amount": 0,          "tipAmount": 0,          "totalAmount": 1,          "reason": "string",          "lineItems": [            {              "orderLineId": "string",              "title": "string",              "subtotalAmount": 0,              "taxAmount": 0,              "totalAmount": 1            }          ],          "approvedByStaffUserId": "string",          "approvedAt": "2019-08-24T14:15:22Z"        }      ],      "authorization": {        "mode": "disabled",        "actorRoles": [          "string"        ],        "overrideStaffUserId": "string",        "overrideReason": "string",        "approvedAt": "2019-08-24T14:15:22Z"      },      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}

Create a payment intent

Platform payment session for POS collection. Supports split tender, named tabs, and local non-card settlement while keeping the public contract compatible with existing payment intent flows.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

orderId?string

amount*integer

Range1 <= value

currency*string

Length3 <= length <= 3

captureMethod?|

tipAmount?integer

Range0 <= value

metadata?

tenderType?|||

giftCardCode?string

Length1 <= length

splitTenderGroupId?string

tabName?string

collectionStrategy?||

`application/json`

curl -X POST "https://example.com/payments/intents" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "amount": 1,    "currency": "str"  }'

{  "id": "string",  "orderId": "string",  "locationId": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerPaymentIntentId": "string",  "paymentState": "pending",  "readerId": "string",  "amount": 0,  "currency": "string",  "captureMethod": "manual",  "status": "requires_payment_method",  "tenderType": "card_present",  "processorStatus": "OPEN",  "checkState": "open",  "refundStatus": "none",  "authorizedAmount": 0,  "capturedAmount": 0,  "refundedBaseAmount": 0,  "refundedTipAmount": 0,  "refundedAmount": 0,  "pendingTipAmount": 0,  "tipStatus": "none",  "tipEntrySource": "capture",  "tipPendingReason": "awaiting_adjustment",  "closedByStaffUserId": "string",  "attributedStaffUserId": "string",  "attributedShiftId": "string",  "attributedAt": "2019-08-24T14:15:22Z",  "splitTenderGroupId": "string",  "tipAmount": 0,  "tabName": "string",  "tabStatus": "open",  "preauthAmount": 1,  "metadata": {    "property1": "string",    "property2": "string"  },  "paidAt": "2019-08-24T14:15:22Z",  "capturedAt": "2019-08-24T14:15:22Z",  "closedAt": "2019-08-24T14:15:22Z",  "reopenedAt": "2019-08-24T14:15:22Z",  "tipAdjustedAt": "2019-08-24T14:15:22Z",  "voidedAt": "2019-08-24T14:15:22Z",  "refundedAt": "2019-08-24T14:15:22Z",  "refunds": [    {      "id": "string",      "amount": 0,      "tipAmount": 0,      "totalAmount": 1,      "reason": "string",      "lineItems": [        {          "orderLineId": "string",          "title": "string",          "subtotalAmount": 0,          "taxAmount": 0,          "totalAmount": 1        }      ],      "approvedByStaffUserId": "string",      "approvedAt": "2019-08-24T14:15:22Z"    }  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Retrieve a payment intent

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

`application/json`

curl -X GET "https://example.com/payments/intents/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "id": "string",  "orderId": "string",  "locationId": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerPaymentIntentId": "string",  "paymentState": "pending",  "readerId": "string",  "amount": 0,  "currency": "string",  "captureMethod": "manual",  "status": "requires_payment_method",  "tenderType": "card_present",  "processorStatus": "OPEN",  "checkState": "open",  "refundStatus": "none",  "authorizedAmount": 0,  "capturedAmount": 0,  "refundedBaseAmount": 0,  "refundedTipAmount": 0,  "refundedAmount": 0,  "pendingTipAmount": 0,  "tipStatus": "none",  "tipEntrySource": "capture",  "tipPendingReason": "awaiting_adjustment",  "closedByStaffUserId": "string",  "attributedStaffUserId": "string",  "attributedShiftId": "string",  "attributedAt": "2019-08-24T14:15:22Z",  "splitTenderGroupId": "string",  "tipAmount": 0,  "tabName": "string",  "tabStatus": "open",  "preauthAmount": 1,  "metadata": {    "property1": "string",    "property2": "string"  },  "paidAt": "2019-08-24T14:15:22Z",  "capturedAt": "2019-08-24T14:15:22Z",  "closedAt": "2019-08-24T14:15:22Z",  "reopenedAt": "2019-08-24T14:15:22Z",  "tipAdjustedAt": "2019-08-24T14:15:22Z",  "voidedAt": "2019-08-24T14:15:22Z",  "refundedAt": "2019-08-24T14:15:22Z",  "refunds": [    {      "id": "string",      "amount": 0,      "tipAmount": 0,      "totalAmount": 1,      "reason": "string",      "lineItems": [        {          "orderLineId": "string",          "title": "string",          "subtotalAmount": 0,          "taxAmount": 0,          "totalAmount": 1        }      ],      "approvedByStaffUserId": "string",      "approvedAt": "2019-08-24T14:15:22Z"    }  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Create a Stripe Terminal connection token

Returns a short-lived Stripe Terminal connection token for the native iOS Terminal SDK. The secret Stripe API key remains on the backend.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

locationId?string

paymentIntentId?string

`application/json`

curl -X POST "https://example.com/payments/stripe-terminal/connection-token" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'

{  "secret": "string"}

Create a Stripe Terminal iOS SDK session

Returns the Stripe PaymentIntent client secret, publishable key, and Terminal location for Tap to Pay on iPhone collection.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

deviceKind?|

simulated?boolean

terminalId?string

`application/json`

curl -X POST "https://example.com/payments/intents/string/stripe-terminal-session" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'

{  "provider": "stripe",  "paymentIntentId": "string",  "merchantPaymentAccountId": "string",  "stripePaymentIntentId": "string",  "clientSecret": "string",  "publishableKey": "string",  "locationId": "string",  "amount": 1,  "currency": "string",  "captureMethod": "manual",  "simulated": true,  "sdkCreatesPaymentIntent": true,  "supportsOffline": true,  "requestIncrementalAuthorization": true,  "sandboxSimulationAvailable": true,  "terminalExternalId": "string",  "terminalType": "string",  "merchantDisplayName": "string"}

Reconcile a Stripe Terminal iOS SDK result

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

status*||||

stripePaymentIntentId?string

idempotencyKey?string

Length1 <= length

sdkStatus?string

failureMessage?string

rawPayment?

`application/json`

curl -X POST "https://example.com/payments/intents/string/stripe-terminal-reconcile" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "status": "requires_capture"  }'

{  "id": "string",  "orderId": "string",  "locationId": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerPaymentIntentId": "string",  "paymentState": "pending",  "readerId": "string",  "amount": 0,  "currency": "string",  "captureMethod": "manual",  "status": "requires_payment_method",  "tenderType": "card_present",  "processorStatus": "OPEN",  "checkState": "open",  "refundStatus": "none",  "authorizedAmount": 0,  "capturedAmount": 0,  "refundedBaseAmount": 0,  "refundedTipAmount": 0,  "refundedAmount": 0,  "pendingTipAmount": 0,  "tipStatus": "none",  "tipEntrySource": "capture",  "tipPendingReason": "awaiting_adjustment",  "closedByStaffUserId": "string",  "attributedStaffUserId": "string",  "attributedShiftId": "string",  "attributedAt": "2019-08-24T14:15:22Z",  "splitTenderGroupId": "string",  "tipAmount": 0,  "tabName": "string",  "tabStatus": "open",  "preauthAmount": 1,  "metadata": {    "property1": "string",    "property2": "string"  },  "paidAt": "2019-08-24T14:15:22Z",  "capturedAt": "2019-08-24T14:15:22Z",  "closedAt": "2019-08-24T14:15:22Z",  "reopenedAt": "2019-08-24T14:15:22Z",  "tipAdjustedAt": "2019-08-24T14:15:22Z",  "voidedAt": "2019-08-24T14:15:22Z",  "refundedAt": "2019-08-24T14:15:22Z",  "refunds": [    {      "id": "string",      "amount": 0,      "tipAmount": 0,      "totalAmount": 1,      "reason": "string",      "lineItems": [        {          "orderLineId": "string",          "title": "string",          "subtotalAmount": 0,          "taxAmount": 0,          "totalAmount": 1        }      ],      "approvedByStaffUserId": "string",      "approvedAt": "2019-08-24T14:15:22Z"    }  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Create a Square Mobile Payments SDK session

Returns the backend-approved Square client configuration for the native iOS POS. The iPad/iPhone uses Square Mobile Payments SDK for Square Stand, readers, and Tap to Pay on iPhone, then reconciles the result back to this Trellis payment intent.

Path Parameters

id*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

paymentAttemptId?string

Length1 <= length

processingMode?||

deviceKind?|

Response Body

`application/json`

curl -X POST "https://example.com/payments/intents/string/square-session" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'

{  "provider": "square",  "paymentIntentId": "string",  "amount": 1,  "currency": "string",  "squareApplicationId": "string",  "squareLocationId": "string",  "accessToken": "string",  "environment": "sandbox",  "paymentAttemptId": "string",  "referenceId": "string",  "processingMode": "onlineOnly",  "autocomplete": true,  "supportsOffline": true,  "supportsTapToPay": true}

Reconcile a Square Mobile Payments SDK result

Path Parameters

id*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

status*||||

providerPaymentId?string

providerPaymentLocalId?string

amount?integer

Range0 <= value

tipAmount?integer

Range0 <= value

idempotencyKey?string

Length1 <= length

processingMode?||

receiptUrl?string

cardBrand?string

last4?string

entryMethod?string

failureMessage?string

rawPayment?

Response Body

`application/json`

curl -X POST "https://example.com/payments/intents/string/square-reconcile" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "status": "completed"  }'

{  "id": "string",  "orderId": "string",  "locationId": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerPaymentIntentId": "string",  "paymentState": "pending",  "readerId": "string",  "amount": 0,  "currency": "string",  "captureMethod": "manual",  "status": "requires_payment_method",  "tenderType": "card_present",  "processorStatus": "OPEN",  "checkState": "open",  "refundStatus": "none",  "authorizedAmount": 0,  "capturedAmount": 0,  "refundedBaseAmount": 0,  "refundedTipAmount": 0,  "refundedAmount": 0,  "pendingTipAmount": 0,  "tipStatus": "none",  "tipEntrySource": "capture",  "tipPendingReason": "awaiting_adjustment",  "closedByStaffUserId": "string",  "attributedStaffUserId": "string",  "attributedShiftId": "string",  "attributedAt": "2019-08-24T14:15:22Z",  "splitTenderGroupId": "string",  "tipAmount": 0,  "tabName": "string",  "tabStatus": "open",  "preauthAmount": 1,  "metadata": {    "property1": "string",    "property2": "string"  },  "paidAt": "2019-08-24T14:15:22Z",  "capturedAt": "2019-08-24T14:15:22Z",  "closedAt": "2019-08-24T14:15:22Z",  "reopenedAt": "2019-08-24T14:15:22Z",  "tipAdjustedAt": "2019-08-24T14:15:22Z",  "voidedAt": "2019-08-24T14:15:22Z",  "refundedAt": "2019-08-24T14:15:22Z",  "refunds": [    {      "id": "string",      "amount": 0,      "tipAmount": 0,      "totalAmount": 1,      "reason": "string",      "lineItems": [        {          "orderLineId": "string",          "title": "string",          "subtotalAmount": 0,          "taxAmount": 0,          "totalAmount": 1        }      ],      "approvedByStaffUserId": "string",      "approvedAt": "2019-08-24T14:15:22Z"    }  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Send a payment intent to a reader

Starts the server-side handoff from the POS API to a WisePOS E checkout lane and marks the payment as authorized for capture-oriented restaurant workflows.

Path Parameters

id*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

readerId*string

Response Body

`application/json`

curl -X POST "https://example.com/payments/intents/string/collect-on-reader" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "readerId": "string"  }'

{  "id": "string",  "orderId": "string",  "locationId": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerPaymentIntentId": "string",  "paymentState": "pending",  "readerId": "string",  "amount": 0,  "currency": "string",  "captureMethod": "manual",  "status": "requires_payment_method",  "tenderType": "card_present",  "processorStatus": "OPEN",  "checkState": "open",  "refundStatus": "none",  "authorizedAmount": 0,  "capturedAmount": 0,  "refundedBaseAmount": 0,  "refundedTipAmount": 0,  "refundedAmount": 0,  "pendingTipAmount": 0,  "tipStatus": "none",  "tipEntrySource": "capture",  "tipPendingReason": "awaiting_adjustment",  "closedByStaffUserId": "string",  "attributedStaffUserId": "string",  "attributedShiftId": "string",  "attributedAt": "2019-08-24T14:15:22Z",  "splitTenderGroupId": "string",  "tipAmount": 0,  "tabName": "string",  "tabStatus": "open",  "preauthAmount": 1,  "metadata": {    "property1": "string",    "property2": "string"  },  "paidAt": "2019-08-24T14:15:22Z",  "capturedAt": "2019-08-24T14:15:22Z",  "closedAt": "2019-08-24T14:15:22Z",  "reopenedAt": "2019-08-24T14:15:22Z",  "tipAdjustedAt": "2019-08-24T14:15:22Z",  "voidedAt": "2019-08-24T14:15:22Z",  "refundedAt": "2019-08-24T14:15:22Z",  "refunds": [    {      "id": "string",      "amount": 0,      "tipAmount": 0,      "totalAmount": 1,      "reason": "string",      "lineItems": [        {          "orderLineId": "string",          "title": "string",          "subtotalAmount": 0,          "taxAmount": 0,          "totalAmount": 1        }      ],      "approvedByStaffUserId": "string",      "approvedAt": "2019-08-24T14:15:22Z"    }  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Increase an uncaptured payment authorization

Path Parameters

id*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount*integer

Range1 <= value

reason?string

Lengthlength <= 500

Response Body

`application/json`

curl -X POST "https://example.com/payments/intents/string/increment-authorization" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "amount": 1  }'

{  "id": "string",  "orderId": "string",  "locationId": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerPaymentIntentId": "string",  "paymentState": "pending",  "readerId": "string",  "amount": 0,  "currency": "string",  "captureMethod": "manual",  "status": "requires_payment_method",  "tenderType": "card_present",  "processorStatus": "OPEN",  "checkState": "open",  "refundStatus": "none",  "authorizedAmount": 0,  "capturedAmount": 0,  "refundedBaseAmount": 0,  "refundedTipAmount": 0,  "refundedAmount": 0,  "pendingTipAmount": 0,  "tipStatus": "none",  "tipEntrySource": "capture",  "tipPendingReason": "awaiting_adjustment",  "closedByStaffUserId": "string",  "attributedStaffUserId": "string",  "attributedShiftId": "string",  "attributedAt": "2019-08-24T14:15:22Z",  "splitTenderGroupId": "string",  "tipAmount": 0,  "tabName": "string",  "tabStatus": "open",  "preauthAmount": 1,  "metadata": {    "property1": "string",    "property2": "string"  },  "paidAt": "2019-08-24T14:15:22Z",  "capturedAt": "2019-08-24T14:15:22Z",  "closedAt": "2019-08-24T14:15:22Z",  "reopenedAt": "2019-08-24T14:15:22Z",  "tipAdjustedAt": "2019-08-24T14:15:22Z",  "voidedAt": "2019-08-24T14:15:22Z",  "refundedAt": "2019-08-24T14:15:22Z",  "refunds": [    {      "id": "string",      "amount": 0,      "tipAmount": 0,      "totalAmount": 1,      "reason": "string",      "lineItems": [        {          "orderLineId": "string",          "title": "string",          "subtotalAmount": 0,          "taxAmount": 0,          "totalAmount": 1        }      ],      "approvedByStaffUserId": "string",      "approvedAt": "2019-08-24T14:15:22Z"    }  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Capture an authorized payment

Path Parameters

id*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount?integer

Range1 <= value

tipAmount?integer

Range0 <= value

pendingTipAmount?integer

Range0 <= value

tipEntrySource?||

closeCheck?boolean

Response Body

`application/json`

curl -X POST "https://example.com/payments/intents/string/capture" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "orderId": "string",  "locationId": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerPaymentIntentId": "string",  "paymentState": "pending",  "readerId": "string",  "amount": 0,  "currency": "string",  "captureMethod": "manual",  "status": "requires_payment_method",  "tenderType": "card_present",  "processorStatus": "OPEN",  "checkState": "open",  "refundStatus": "none",  "authorizedAmount": 0,  "capturedAmount": 0,  "refundedBaseAmount": 0,  "refundedTipAmount": 0,  "refundedAmount": 0,  "pendingTipAmount": 0,  "tipStatus": "none",  "tipEntrySource": "capture",  "tipPendingReason": "awaiting_adjustment",  "closedByStaffUserId": "string",  "attributedStaffUserId": "string",  "attributedShiftId": "string",  "attributedAt": "2019-08-24T14:15:22Z",  "splitTenderGroupId": "string",  "tipAmount": 0,  "tabName": "string",  "tabStatus": "open",  "preauthAmount": 1,  "metadata": {    "property1": "string",    "property2": "string"  },  "paidAt": "2019-08-24T14:15:22Z",  "capturedAt": "2019-08-24T14:15:22Z",  "closedAt": "2019-08-24T14:15:22Z",  "reopenedAt": "2019-08-24T14:15:22Z",  "tipAdjustedAt": "2019-08-24T14:15:22Z",  "voidedAt": "2019-08-24T14:15:22Z",  "refundedAt": "2019-08-24T14:15:22Z",  "refunds": [    {      "id": "string",      "amount": 0,      "tipAmount": 0,      "totalAmount": 1,      "reason": "string",      "lineItems": [        {          "orderLineId": "string",          "title": "string",          "subtotalAmount": 0,          "taxAmount": 0,          "totalAmount": 1        }      ],      "approvedByStaffUserId": "string",      "approvedAt": "2019-08-24T14:15:22Z"    }  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Adjust tip on a paid or closed check

Path Parameters

id*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tipAmount*integer

Range0 <= value

tipEntrySource?||

closeCheck?boolean

Response Body

`application/json`

curl -X POST "https://example.com/payments/intents/string/tip-adjust" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "tipAmount": 0  }'

{  "id": "string",  "orderId": "string",  "locationId": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerPaymentIntentId": "string",  "paymentState": "pending",  "readerId": "string",  "amount": 0,  "currency": "string",  "captureMethod": "manual",  "status": "requires_payment_method",  "tenderType": "card_present",  "processorStatus": "OPEN",  "checkState": "open",  "refundStatus": "none",  "authorizedAmount": 0,  "capturedAmount": 0,  "refundedBaseAmount": 0,  "refundedTipAmount": 0,  "refundedAmount": 0,  "pendingTipAmount": 0,  "tipStatus": "none",  "tipEntrySource": "capture",  "tipPendingReason": "awaiting_adjustment",  "closedByStaffUserId": "string",  "attributedStaffUserId": "string",  "attributedShiftId": "string",  "attributedAt": "2019-08-24T14:15:22Z",  "splitTenderGroupId": "string",  "tipAmount": 0,  "tabName": "string",  "tabStatus": "open",  "preauthAmount": 1,  "metadata": {    "property1": "string",    "property2": "string"  },  "paidAt": "2019-08-24T14:15:22Z",  "capturedAt": "2019-08-24T14:15:22Z",  "closedAt": "2019-08-24T14:15:22Z",  "reopenedAt": "2019-08-24T14:15:22Z",  "tipAdjustedAt": "2019-08-24T14:15:22Z",  "voidedAt": "2019-08-24T14:15:22Z",  "refundedAt": "2019-08-24T14:15:22Z",  "refunds": [    {      "id": "string",      "amount": 0,      "tipAmount": 0,      "totalAmount": 1,      "reason": "string",      "lineItems": [        {          "orderLineId": "string",          "title": "string",          "subtotalAmount": 0,          "taxAmount": 0,          "totalAmount": 1        }      ],      "approvedByStaffUserId": "string",      "approvedAt": "2019-08-24T14:15:22Z"    }  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Move a settled payment to a different check

Path Parameters

id*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

orderId*string

Length1 <= length

managerOverrideStaffUserId?string

overrideReason?string

Response Body

`application/json`

curl -X POST "https://example.com/payments/intents/string/move" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "orderId": "string"  }'

{  "paymentIntent": {    "id": "string",    "orderId": "string",    "locationId": "string",    "provider": "mock",    "merchantPaymentAccountId": "string",    "externalId": "string",    "providerPaymentIntentId": "string",    "paymentState": "pending",    "readerId": "string",    "amount": 0,    "currency": "string",    "captureMethod": "manual",    "status": "requires_payment_method",    "tenderType": "card_present",    "processorStatus": "OPEN",    "checkState": "open",    "refundStatus": "none",    "authorizedAmount": 0,    "capturedAmount": 0,    "refundedBaseAmount": 0,    "refundedTipAmount": 0,    "refundedAmount": 0,    "pendingTipAmount": 0,    "tipStatus": "none",    "tipEntrySource": "capture",    "tipPendingReason": "awaiting_adjustment",    "closedByStaffUserId": "string",    "attributedStaffUserId": "string",    "attributedShiftId": "string",    "attributedAt": "2019-08-24T14:15:22Z",    "splitTenderGroupId": "string",    "tipAmount": 0,    "tabName": "string",    "tabStatus": "open",    "preauthAmount": 1,    "metadata": {      "property1": "string",      "property2": "string"    },    "paidAt": "2019-08-24T14:15:22Z",    "capturedAt": "2019-08-24T14:15:22Z",    "closedAt": "2019-08-24T14:15:22Z",    "reopenedAt": "2019-08-24T14:15:22Z",    "tipAdjustedAt": "2019-08-24T14:15:22Z",    "voidedAt": "2019-08-24T14:15:22Z",    "refundedAt": "2019-08-24T14:15:22Z",    "refunds": [      {        "id": "string",        "amount": 0,        "tipAmount": 0,        "totalAmount": 1,        "reason": "string",        "lineItems": [          {            "orderLineId": "string",            "title": "string",            "subtotalAmount": 0,            "taxAmount": 0,            "totalAmount": 1          }        ],        "approvedByStaffUserId": "string",        "approvedAt": "2019-08-24T14:15:22Z"      }    ],    "authorization": {      "mode": "disabled",      "actorRoles": [        "string"      ],      "overrideStaffUserId": "string",      "overrideReason": "string",      "approvedAt": "2019-08-24T14:15:22Z"    },    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "sourceOrder": null,  "destinationOrder": null}

Refund or void a payment

Path Parameters

id*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount?integer

Range0 <= value

tipAmount?integer

Range0 <= value

reason?string

lineItems?array<>

managerOverrideStaffUserId?string

overrideReason?string

Response Body

`application/json`

curl -X POST "https://example.com/payments/intents/string/refund" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "orderId": "string",  "locationId": "string",  "provider": "mock",  "merchantPaymentAccountId": "string",  "externalId": "string",  "providerPaymentIntentId": "string",  "paymentState": "pending",  "readerId": "string",  "amount": 0,  "currency": "string",  "captureMethod": "manual",  "status": "requires_payment_method",  "tenderType": "card_present",  "processorStatus": "OPEN",  "checkState": "open",  "refundStatus": "none",  "authorizedAmount": 0,  "capturedAmount": 0,  "refundedBaseAmount": 0,  "refundedTipAmount": 0,  "refundedAmount": 0,  "pendingTipAmount": 0,  "tipStatus": "none",  "tipEntrySource": "capture",  "tipPendingReason": "awaiting_adjustment",  "closedByStaffUserId": "string",  "attributedStaffUserId": "string",  "attributedShiftId": "string",  "attributedAt": "2019-08-24T14:15:22Z",  "splitTenderGroupId": "string",  "tipAmount": 0,  "tabName": "string",  "tabStatus": "open",  "preauthAmount": 1,  "metadata": {    "property1": "string",    "property2": "string"  },  "paidAt": "2019-08-24T14:15:22Z",  "capturedAt": "2019-08-24T14:15:22Z",  "closedAt": "2019-08-24T14:15:22Z",  "reopenedAt": "2019-08-24T14:15:22Z",  "tipAdjustedAt": "2019-08-24T14:15:22Z",  "voidedAt": "2019-08-24T14:15:22Z",  "refundedAt": "2019-08-24T14:15:22Z",  "refunds": [    {      "id": "string",      "amount": 0,      "tipAmount": 0,      "totalAmount": 1,      "reason": "string",      "lineItems": [        {          "orderLineId": "string",          "title": "string",          "subtotalAmount": 0,          "taxAmount": 0,          "totalAmount": 1        }      ],      "approvedByStaffUserId": "string",      "approvedAt": "2019-08-24T14:15:22Z"    }  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Reopen a closed paid check

Toast-inspired reopen behavior. Closed checks move back to paid, the order remains in its paid state, and the reopened check becomes available for further changes.

Path Parameters

orderId*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

managerOverrideStaffUserId?string

overrideReason?string

Response Body

`application/json`

curl -X POST "https://example.com/payments/orders/string/reopen-check" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'

{  "orderId": "string",  "orderStatus": "string",  "checkState": "paid",  "reopenedPaymentIntentIds": [    "string"  ],  "authorization": {    "mode": "disabled",    "actorRoles": [      "string"    ],    "overrideStaffUserId": "string",    "overrideReason": "string",    "approvedAt": "2019-08-24T14:15:22Z"  }}

Cancel the current reader action

Path Parameters

readerId*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

`application/json`

curl -X POST "https://example.com/terminal/readers/string/cancel-action" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "message": "string"}

List provider settlements for operator reconciliation

Query Parameters

provider?|||

status?||||

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

`application/json`

curl -X GET "https://example.com/payments/provider-settlements" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "settlements": [    {      "id": "string",      "tenantId": "string",      "provider": "mock",      "providerSettlementId": "string",      "currency": "string",      "grossAmount": 0,      "feeAmount": 0,      "refundAmount": 0,      "disputeAmount": 0,      "netAmount": 0,      "status": "pending",      "settledAt": "string",      "payload": {        "property1": null,        "property2": null      },      "createdAt": "string",      "updatedAt": "string",      "created": true    }  ],  "total": 0}

Record a provider settlement

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider*|||

providerSettlementId*string

Length1 <= length

currency*string

Length3 <= length <= 3

grossAmount*integer

Range0 <= value

feeAmount*integer

Range0 <= value

refundAmount?integer

Range0 <= value

disputeAmount?integer

Range0 <= value

netAmount*integer

status*||||

settledAt?string

payload?

Response Body

`application/json`

curl -X POST "https://example.com/payments/provider-settlements" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "provider": "mock",    "providerSettlementId": "string",    "currency": "str",    "grossAmount": 0,    "feeAmount": 0,    "netAmount": 0,    "status": "pending"  }'

{  "id": "string",  "tenantId": "string",  "provider": "mock",  "providerSettlementId": "string",  "currency": "string",  "grossAmount": 0,  "feeAmount": 0,  "refundAmount": 0,  "disputeAmount": 0,  "netAmount": 0,  "status": "pending",  "settledAt": "string",  "payload": {    "property1": null,    "property2": null  },  "createdAt": "string",  "updatedAt": "string",  "created": true}

List provider payouts for operator reconciliation

Query Parameters

provider?|||

status?||||

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

`application/json`

curl -X GET "https://example.com/payments/provider-payouts" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "payouts": [    {      "id": "string",      "tenantId": "string",      "provider": "mock",      "providerPayoutId": "string",      "currency": "string",      "amount": 0,      "status": "pending",      "expectedArrivalAt": "string",      "paidAt": "string",      "reconciledAt": "string",      "varianceAmount": 0,      "payload": {        "property1": null,        "property2": null      },      "createdAt": "string",      "updatedAt": "string",      "created": true,      "settlements": [        {          "id": "string",          "tenantId": "string",          "provider": "mock",          "providerSettlementId": "string",          "currency": "string",          "grossAmount": 0,          "feeAmount": 0,          "refundAmount": 0,          "disputeAmount": 0,          "netAmount": 0,          "status": "pending",          "settledAt": "string",          "payload": {            "property1": null,            "property2": null          },          "createdAt": "string",          "updatedAt": "string",          "created": true        }      ]    }  ],  "total": 0}

Record a provider payout

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider*|||

providerPayoutId*string

Length1 <= length

currency*string

Length3 <= length <= 3

amount*integer

Range0 <= value

status*||||

expectedArrivalAt?string

paidAt?string

payload?

Response Body

`application/json`

curl -X POST "https://example.com/payments/provider-payouts" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "provider": "mock",    "providerPayoutId": "string",    "currency": "str",    "amount": 0,    "status": "pending"  }'

{  "id": "string",  "tenantId": "string",  "provider": "mock",  "providerPayoutId": "string",  "currency": "string",  "amount": 0,  "status": "pending",  "expectedArrivalAt": "string",  "paidAt": "string",  "reconciledAt": "string",  "varianceAmount": 0,  "payload": {    "property1": null,    "property2": null  },  "createdAt": "string",  "updatedAt": "string",  "created": true,  "settlements": [    {      "id": "string",      "tenantId": "string",      "provider": "mock",      "providerSettlementId": "string",      "currency": "string",      "grossAmount": 0,      "feeAmount": 0,      "refundAmount": 0,      "disputeAmount": 0,      "netAmount": 0,      "status": "pending",      "settledAt": "string",      "payload": {        "property1": null,        "property2": null      },      "createdAt": "string",      "updatedAt": "string",      "created": true    }  ]}

Create a durable provider payment attempt

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

paymentIntentId?string

provider*|||

operationType*|||

amount*integer

Range1 <= value

currency*string

Length3 <= length <= 3

metadata?

maxAttempts?integer

Range1 <= value <= 25

Response Body

`application/json`

curl -X POST "https://example.com/payments/provider-attempts" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "provider": "mock",    "operationType": "authorize",    "amount": 1,    "currency": "str"  }'

{  "id": "string",  "tenantId": "string",  "paymentIntentId": "string",  "provider": "mock",  "operationType": "authorize",  "amount": 1,  "currency": "string",  "status": "queued",  "requestIdempotencyKey": "string",  "providerIdempotencyKey": "string",  "providerReference": "string",  "metadata": {    "property1": null,    "property2": null  },  "outcome": {    "property1": null,    "property2": null  },  "attemptCount": 0,  "maxAttempts": 1,  "availableAt": "string",  "claimedBy": "string",  "claimToken": "string",  "claimedAt": "string",  "leaseExpiresAt": "string",  "lastError": "string",  "createdByStaffUserId": "string",  "createdAt": "string",  "updatedAt": "string",  "completedAt": "string",  "replayed": true,  "events": [    {      "id": "string",      "eventType": "string",      "fromStatus": "queued",      "toStatus": "queued",      "attemptNumber": 0,      "workerId": "string",      "detail": {        "property1": null,        "property2": null      },      "occurredAt": "string"    }  ]}

Ingest an idempotent provider dispute event

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider*|||

providerEventId*string

Length1 <= length

providerDisputeId*string

Length1 <= length

providerPaymentReference?string

amount*integer

Range1 <= value

currency*string

Length3 <= length <= 3

status*|||||

reason?string

evidenceDueAt?string

providerCreatedAt?string

payload?

Response Body

`application/json`

curl -X POST "https://example.com/payments/provider-events/disputes" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "provider": "mock",    "providerEventId": "string",    "providerDisputeId": "string",    "amount": 1,    "currency": "str",    "status": "warning_needs_response"  }'

{  "id": "string",  "tenantId": "string",  "provider": "mock",  "providerDisputeId": "string",  "providerPaymentReference": "string",  "paymentAttemptId": "string",  "amount": 1,  "currency": "string",  "status": "warning_needs_response",  "reason": "string",  "evidenceDueAt": "string",  "providerCreatedAt": "string",  "payload": {    "property1": null,    "property2": null  },  "createdAt": "string",  "updatedAt": "string",  "closedAt": "string",  "replayed": true,  "created": true,  "events": [    {      "id": "string",      "providerEventId": "string",      "eventType": "string",      "status": "warning_needs_response",      "payload": {        "property1": null,        "property2": null      },      "occurredAt": "string"    }  ]}

Get a provider payment dispute and state history

Path Parameters

disputeId*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

`application/json`

curl -X GET "https://example.com/payments/disputes/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "id": "string",  "tenantId": "string",  "provider": "mock",  "providerDisputeId": "string",  "providerPaymentReference": "string",  "paymentAttemptId": "string",  "amount": 1,  "currency": "string",  "status": "warning_needs_response",  "reason": "string",  "evidenceDueAt": "string",  "providerCreatedAt": "string",  "payload": {    "property1": null,    "property2": null  },  "createdAt": "string",  "updatedAt": "string",  "closedAt": "string",  "replayed": true,  "created": true,  "events": [    {      "id": "string",      "providerEventId": "string",      "eventType": "string",      "status": "warning_needs_response",      "payload": {        "property1": null,        "property2": null      },      "occurredAt": "string"    }  ]}

Reconcile a provider payout to settlements

Path Parameters

payoutId*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

settlementIds*array<>

Items1 <= items

Response Body

`application/json`

curl -X POST "https://example.com/payments/provider-payouts/string/reconcile" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "settlementIds": [      "string"    ]  }'

{  "id": "string",  "tenantId": "string",  "provider": "mock",  "providerPayoutId": "string",  "currency": "string",  "amount": 0,  "status": "pending",  "expectedArrivalAt": "string",  "paidAt": "string",  "reconciledAt": "string",  "varianceAmount": 0,  "payload": {    "property1": null,    "property2": null  },  "createdAt": "string",  "updatedAt": "string",  "created": true,  "settlements": [    {      "id": "string",      "tenantId": "string",      "provider": "mock",      "providerSettlementId": "string",      "currency": "string",      "grossAmount": 0,      "feeAmount": 0,      "refundAmount": 0,      "disputeAmount": 0,      "netAmount": 0,      "status": "pending",      "settledAt": "string",      "payload": {        "property1": null,        "property2": null      },      "createdAt": "string",      "updatedAt": "string",      "created": true    }  ]}

Get a provider payout and linked settlements

Path Parameters

payoutId*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

`application/json`

curl -X GET "https://example.com/payments/provider-payouts/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "id": "string",  "tenantId": "string",  "provider": "mock",  "providerPayoutId": "string",  "currency": "string",  "amount": 0,  "status": "pending",  "expectedArrivalAt": "string",  "paidAt": "string",  "reconciledAt": "string",  "varianceAmount": 0,  "payload": {    "property1": null,    "property2": null  },  "createdAt": "string",  "updatedAt": "string",  "created": true,  "settlements": [    {      "id": "string",      "tenantId": "string",      "provider": "mock",      "providerSettlementId": "string",      "currency": "string",      "grossAmount": 0,      "feeAmount": 0,      "refundAmount": 0,      "disputeAmount": 0,      "netAmount": 0,      "status": "pending",      "settledAt": "string",      "payload": {        "property1": null,        "property2": null      },      "createdAt": "string",      "updatedAt": "string",      "created": true    }  ]}

Get a durable provider payment attempt and event history

Path Parameters

attemptId*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

`application/json`

curl -X GET "https://example.com/payments/provider-attempts/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"

{  "id": "string",  "tenantId": "string",  "paymentIntentId": "string",  "provider": "mock",  "operationType": "authorize",  "amount": 1,  "currency": "string",  "status": "queued",  "requestIdempotencyKey": "string",  "providerIdempotencyKey": "string",  "providerReference": "string",  "metadata": {    "property1": null,    "property2": null  },  "outcome": {    "property1": null,    "property2": null  },  "attemptCount": 0,  "maxAttempts": 1,  "availableAt": "string",  "claimedBy": "string",  "claimToken": "string",  "claimedAt": "string",  "leaseExpiresAt": "string",  "lastError": "string",  "createdByStaffUserId": "string",  "createdAt": "string",  "updatedAt": "string",  "completedAt": "string",  "replayed": true,  "events": [    {      "id": "string",      "eventType": "string",      "fromStatus": "queued",      "toStatus": "queued",      "attemptNumber": 0,      "workerId": "string",      "detail": {        "property1": null,        "property2": null      },      "occurredAt": "string"    }  ]}

Lease the next provider payment attempt

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

workerId*string

Length1 <= length

leaseSeconds?integer

Range1 <= value <= 900

Response Body

`application/json`

curl -X POST "https://example.com/payments/provider-attempts/claim" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "workerId": "string"  }'

{  "id": "string",  "tenantId": "string",  "paymentIntentId": "string",  "provider": "mock",  "operationType": "authorize",  "amount": 1,  "currency": "string",  "status": "queued",  "requestIdempotencyKey": "string",  "providerIdempotencyKey": "string",  "providerReference": "string",  "metadata": {    "property1": null,    "property2": null  },  "outcome": {    "property1": null,    "property2": null  },  "attemptCount": 0,  "maxAttempts": 1,  "availableAt": "string",  "claimedBy": "string",  "claimToken": "string",  "claimedAt": "string",  "leaseExpiresAt": "string",  "lastError": "string",  "createdByStaffUserId": "string",  "createdAt": "string",  "updatedAt": "string",  "completedAt": "string",  "replayed": true,  "events": [    {      "id": "string",      "eventType": "string",      "fromStatus": "queued",      "toStatus": "queued",      "attemptNumber": 0,      "workerId": "string",      "detail": {        "property1": null,        "property2": null      },      "occurredAt": "string"    }  ]}

Execute a leased provider payment attempt

Path Parameters

attemptId*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

claimToken*string

Length1 <= length

Response Body

`application/json`

curl -X POST "https://example.com/payments/provider-attempts/string/execute" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "claimToken": "string"  }'

{  "id": "string",  "tenantId": "string",  "paymentIntentId": "string",  "provider": "mock",  "operationType": "authorize",  "amount": 1,  "currency": "string",  "status": "queued",  "requestIdempotencyKey": "string",  "providerIdempotencyKey": "string",  "providerReference": "string",  "metadata": {    "property1": null,    "property2": null  },  "outcome": {    "property1": null,    "property2": null  },  "attemptCount": 0,  "maxAttempts": 1,  "availableAt": "string",  "claimedBy": "string",  "claimToken": "string",  "claimedAt": "string",  "leaseExpiresAt": "string",  "lastError": "string",  "createdByStaffUserId": "string",  "createdAt": "string",  "updatedAt": "string",  "completedAt": "string",  "replayed": true,  "events": [    {      "id": "string",      "eventType": "string",      "fromStatus": "queued",      "toStatus": "queued",      "attemptNumber": 0,      "workerId": "string",      "detail": {        "property1": null,        "property2": null      },      "occurredAt": "string"    }  ]}

Retrieve an ambiguous provider payment outcome

Path Parameters

attemptId*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

workerId*string

Length1 <= length

Response Body

`application/json`

curl -X POST "https://example.com/payments/provider-attempts/string/recover" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "workerId": "string"  }'

{  "id": "string",  "tenantId": "string",  "paymentIntentId": "string",  "provider": "mock",  "operationType": "authorize",  "amount": 1,  "currency": "string",  "status": "queued",  "requestIdempotencyKey": "string",  "providerIdempotencyKey": "string",  "providerReference": "string",  "metadata": {    "property1": null,    "property2": null  },  "outcome": {    "property1": null,    "property2": null  },  "attemptCount": 0,  "maxAttempts": 1,  "availableAt": "string",  "claimedBy": "string",  "claimToken": "string",  "claimedAt": "string",  "leaseExpiresAt": "string",  "lastError": "string",  "createdByStaffUserId": "string",  "createdAt": "string",  "updatedAt": "string",  "completedAt": "string",  "replayed": true,  "events": [    {      "id": "string",      "eventType": "string",      "fromStatus": "queued",      "toStatus": "queued",      "attemptNumber": 0,      "workerId": "string",      "detail": {        "property1": null,        "property2": null      },      "occurredAt": "string"    }  ]}

Configure a signed provider payment webhook endpoint using a secret reference

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider*|

currentSecretRef*string

Length5 <= length <= 204

notificationUrl?string

Length8 <= length <= 2048

signatureToleranceSeconds?integer

Range60 <= value <= 900

Response Body

`application/json`

curl -X POST "https://example.com/payments/provider-webhooks/configurations" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "provider": "stripe",    "currentSecretRef": "string"  }'

{  "id": "string",  "tenantId": "string",  "provider": "stripe",  "endpointKey": "string",  "callbackPath": "string",  "notificationUrl": "string",  "enabled": true,  "currentSecretRef": "string",  "previousSecretRef": "string",  "previousValidUntil": "string",  "signatureToleranceSeconds": 0,  "createdAt": "string",  "updatedAt": "string"}

Rotate a provider payment webhook secret reference with bounded overlap

Path Parameters

configurationId*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

currentSecretRef*string

Length5 <= length <= 204

overlapSeconds?integer

Range60 <= value <= 604800

Response Body

`application/json`

curl -X POST "https://example.com/payments/provider-webhooks/configurations/string/rotate" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "currentSecretRef": "string"  }'

{  "id": "string",  "tenantId": "string",  "provider": "stripe",  "endpointKey": "string",  "callbackPath": "string",  "notificationUrl": "string",  "enabled": true,  "currentSecretRef": "string",  "previousSecretRef": "string",  "previousValidUntil": "string",  "signatureToleranceSeconds": 0,  "createdAt": "string",  "updatedAt": "string"}

Receive a signed Stripe payment webhook

Path Parameters

endpointKey*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

stripe-signature*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

[key: string]?unknown

Response Body

`application/json`

curl -X POST "https://example.com/webhooks/payments/stripe/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "stripe-signature: string" \  -H "Content-Type: application/json" \  -d '{    "property1": null,    "property2": null  }'

{  "provider": "stripe",  "providerEventId": "string",  "eventType": "string",  "status": "processed",  "replayed": true,  "effect": {    "kind": "string",    "factId": "string",    "status": "string",    "applied": true  }}

Receive a signed Square payment webhook

Path Parameters

endpointKey*string

Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

"hexclave"

x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

x-square-hmacsha256-signature*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

[key: string]?unknown

Response Body

`application/json`

curl -X POST "https://example.com/webhooks/payments/square/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "x-square-hmacsha256-signature: string" \  -H "Content-Type: application/json" \  -d '{    "property1": null,    "property2": null  }'

{  "provider": "stripe",  "providerEventId": "string",  "eventType": "string",  "status": "processed",  "replayed": true,  "effect": {    "kind": "string",    "factId": "string",    "status": "string",    "applied": true  }}

200application/json

200application/json

201application/json

200application/json

200application/json

200application/json

200application/json

200application/json

201application/json

200application/json

202application/json

200application/json

201application/json

201application/json

200application/json

200application/json

200application/json

201application/json

200application/json

201application/json

200application/json

200application/json

200application/json

200application/json

200application/json

200application/json

200application/json

200application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`