You are viewing a non-production environment — the API surface may differ from production.
Developers
Payments API

Purchase Intents

Payment intents for purchases — create, track, and settle a payment

Create a purchase intent (v3 — purchase-service backed)

POST
/api/v3/purchase-intents

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

locationId*integer
mode*string

Value in

  • "upfront"
  • "items"
  • "amount"
  • "remainder"
tabId?string
Formatuuid
tabMemberId?string
Formatuuid
kitchenDispatchItemIds?array<>
amountCents?integer
Range0 <= value
tipAmountCents?integer
Range0 <= value
voucherCodes?array<string>
cart?array<any>
paymentMethod*
savePaymentMethod?boolean
idempotencyKey*string
Length1 <= length <= 200
clientRequestId?string
quoteId?string
guestSessionId?string
metadata?

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v3/purchase-intents" \  -H "Content-Type: application/json" \  -d '{    "locationId": 0,    "mode": "upfront",    "paymentMethod": {      "type": "string"    },    "idempotencyKey": "string"  }'
{  "status": "success",  "data": {    "purchaseIntentId": "7c933f97-ad75-490a-be55-2ca143239cc3",    "state": "string",    "expiresAt": "string",    "correlationId": "string",    "pspInstruction": {}  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get a purchase intent (v3)

GET
/api/v3/purchase-intents/{id}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string
Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v3/purchase-intents/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "status": "success",  "data": {    "purchaseIntentId": "7c933f97-ad75-490a-be55-2ca143239cc3",    "state": "string",    "kind": "string",    "amount": 0,    "currency": "string",    "correlationId": "string",    "metadata": {},    "locationId": 0,    "createdAt": "string",    "updatedAt": "string",    "expiresAt": "string",    "mode": "string",    "amountCents": 0,    "tipAmountCents": 0,    "currencyCode": "string",    "purchaseId": 0,    "tabId": "string",    "tabMemberId": "string",    "providerRoute": "string",    "resultCode": "string",    "action": {},    "pspReference": "string",    "refusalReason": "string",    "refusalReasonCode": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Cancel a purchase intent (v3)

POST
/api/v3/purchase-intents/{id}/cancel

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason?string
Lengthlength <= 500
guestSessionId?string
tabMemberId?string
Formatuuid
requireConfirmedCancellation?boolean

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v3/purchase-intents/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel" \  -H "Content-Type: application/json" \  -d '{}'
{  "status": "success",  "data": {    "purchaseIntentId": "7c933f97-ad75-490a-be55-2ca143239cc3",    "state": "string",    "kind": "string",    "amount": 0,    "currency": "string",    "correlationId": "string",    "metadata": {},    "locationId": 0,    "createdAt": "string",    "updatedAt": "string",    "expiresAt": "string",    "mode": "string",    "amountCents": 0,    "tipAmountCents": 0,    "currencyCode": "string",    "purchaseId": 0,    "tabId": "string",    "tabMemberId": "string",    "providerRoute": "string",    "resultCode": "string",    "action": {},    "pspReference": "string",    "refusalReason": "string",    "refusalReasonCode": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Submit additional PSP details (v3)

POST
/api/v3/purchase-intents/{id}/submit-details

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

details*
guestSessionId?string
tabMemberId?string
Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v3/purchase-intents/497f6eca-6276-4993-bfeb-53cbbbba6f08/submit-details" \  -H "Content-Type: application/json" \  -d '{    "details": {}  }'
{  "status": "success",  "data": {    "purchaseIntentId": "7c933f97-ad75-490a-be55-2ca143239cc3",    "state": "string",    "kind": "string",    "amount": 0,    "currency": "string",    "correlationId": "string",    "metadata": {},    "locationId": 0,    "createdAt": "string",    "updatedAt": "string",    "expiresAt": "string",    "mode": "string",    "amountCents": 0,    "tipAmountCents": 0,    "currencyCode": "string",    "purchaseId": 0,    "tabId": "string",    "tabMemberId": "string",    "providerRoute": "string",    "resultCode": "string",    "action": {},    "pspReference": "string",    "refusalReason": "string",    "refusalReasonCode": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Poll a Cloud Terminal purchase (v3)

POST
/api/v3/purchase-intents/{id}/terminal/status

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string
Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v3/purchase-intents/497f6eca-6276-4993-bfeb-53cbbbba6f08/terminal/status"
{  "status": "success",  "data": {    "purchaseIntentId": "7c933f97-ad75-490a-be55-2ca143239cc3",    "state": "string",    "terminalOutcome": "success"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v3/purchase-intents/preview

POST
/api/v3/purchase-intents/preview

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

locationId*integer

Location ID

kdiIds*array<>

Kitchen dispatch item UUIDs to include in the cart

tipCents?integer

Optional tip in cents

Range0 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v3/purchase-intents/preview" \  -H "Content-Type: application/json" \  -d '{    "locationId": 0,    "kdiIds": [      "0cd882f6-cd33-4f43-bd43-5262dca78168"    ]  }'
{  "status": "success",  "data": {    "subtotalCents": 0,    "discountCents": 0,    "surplusUserFeeCents": 0,    "surplusUserFeeBps": 0,    "tipCents": 0,    "totalCents": 0,    "currencyCode": "string",    "hasSurplusItems": true  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Checkout

Cart pricing quotes before payment

Payment Methods

User and location payment methods management