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

Payment Methods

User and location payment methods management

Remove the prepaid payment method from a location

DELETE
/api/v1/locations/{locationId}/payment-methods/prepaid

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

locationId*string

Location ID

Match^[1-9][0-9]*$

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/v1/locations/string/payment-methods/prepaid"
null

Add the prepaid payment method to a location

PUT
/api/v1/locations/{locationId}/payment-methods/prepaid

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

locationId*string

Location ID

Match^[1-9][0-9]*$

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/api/v1/locations/string/payment-methods/prepaid"
{  "status": "success",  "data": {    "paymentMethod": "prepaid",    "enabled": true  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Create Adyen zero-value auth session for self-service card linking

POST
/api/v1/loyalty/adyen-card-session

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.

returnUrl*string

Return URL after Adyen Drop-in completes

channel?string

Client channel — defaults to Web

Value in

  • "Web"
  • "iOS"
  • "Android"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/loyalty/adyen-card-session" \  -H "Content-Type: application/json" \  -d '{    "returnUrl": "string"  }'
{  "status": "success",  "data": {    "sessionId": "string",    "sessionData": "string",    "clientKey": "string",    "environment": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Finalize Adyen zero-auth session and store card token

POST
/api/v1/loyalty/finalize-card-session

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.

sessionId*string

Adyen session ID from adyen-card-session response

sessionResult*string

sessionResult token from Adyen Drop-in onPaymentCompleted

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/loyalty/finalize-card-session" \  -H "Content-Type: application/json" \  -d '{    "sessionId": "string",    "sessionResult": "string"  }'
{  "status": "success",  "data": {    "card": {      "id": "string",      "brand": "string",      "last4": "string",      "expiryMonth": 0,      "expiryYear": 0,      "isDefault": true,      "isTokenized": true,      "nickname": "string"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}
POST
/api/v1/loyalty/link-payment-method

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.

purchaseIntentId*string

Purchase intent ID containing card data

email?string

User email (required if no phone)

Formatemail
phone?string

User phone number (required if no email)

enrollInProgram?boolean

Whether to also enroll in loyalty program

locationId?number

Location ID for enrollment (required if enrollInProgram)

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/loyalty/link-payment-method" \  -H "Content-Type: application/json" \  -d '{    "purchaseIntentId": "string"  }'
{  "status": "success",  "data": {    "user": {      "id": 0,      "isNewUser": true    },    "paymentMethod": {      "linked": true,      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "brand": "string",      "last4": "string"    },    "enrollment": {      "enrolled": true,      "pointsAwarded": 0,      "newBalance": 0    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}
POST
/api/v1/loyalty/staff-link-payment-method

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.

purchaseIntentId*string

Purchase intent ID containing card data

userId*number

User ID to link the card to

locationId*number

Location ID for enrollment context

consentMethod*"verbal"

Must be verbal for staff-assisted flow

Value in

  • "verbal"
retailerUserId*number

Staff member who captured verbal consent

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/loyalty/staff-link-payment-method" \  -H "Content-Type: application/json" \  -d '{    "purchaseIntentId": "string",    "userId": 0,    "locationId": 0,    "consentMethod": "verbal",    "retailerUserId": 0  }'
{  "status": "success",  "data": {    "cardLinked": true,    "enrolled": true,    "pointsAwarded": 0  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Search users by name, email, or phone (staff)

GET
/api/v1/loyalty/user-search

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Query Parameters

q*string

Search term (name, email, or phone)

Length2 <= length
purchaseIntentId?string

Optional purchase intent ID for tab member auto-suggest

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/loyalty/user-search?q=string"
{  "status": "success",  "data": {    "users": [      {        "id": 0,        "email": "string",        "firstName": "string",        "lastName": "string",        "phone": "string"      }    ],    "autoSuggested": {      "userId": 0,      "firstName": "string",      "lastName": "string",      "email": "string",      "autoSuggested": true    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get loyalty status for a purchase

GET
/api/v1/purchases/{purchaseIntentId}/loyalty-status

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

purchaseIntentId*string

Purchase intent ID

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/purchases/string/loyalty-status"
{  "status": "success",  "data": {    "loyaltyScenario": "POINTS_EARNED",    "pointsEarned": {      "points": 0,      "newBalance": 0    },    "enrollmentOffer": {      "programId": 0,      "programName": "string",      "potentialPoints": 0    },    "cardLinkOffer": {      "programId": 0,      "programName": "string",      "potentialPoints": 0,      "brand": "string",      "last4": "string"    },    "user": {      "id": 0,      "email": "string"    },    "location": {      "id": 0,      "name": "string",      "hasLoyaltyProgram": true    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

List payment methods for a specific user (staff view)

GET
/api/v1/retailer/users/{userId}/payment-methods

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

userId*string

User ID

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/retailer/users/string/payment-methods"
{  "status": "success",  "data": {    "paymentMethods": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "nickname": "string",        "brand": "string",        "last4": "string",        "expiryMonth": 0,        "expiryYear": 0,        "isDefault": true,        "isTokenized": true,        "lastUsedAt": "2019-08-24T14:15:22Z",        "createdAt": "2019-08-24T14:15:22Z"      }    ],    "defaultStoredMethodId": "string",    "lastUsedStoredMethodId": "string",    "lastUsedKind": "card",    "savedSwish": {      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",      "payerAlias": "string",      "lastUsedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

List saved payment methods

GET
/api/v1/users/me/payment-methods

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/users/me/payment-methods"
{  "status": "success",  "data": {    "paymentMethods": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "nickname": "string",        "brand": "string",        "last4": "string",        "expiryMonth": 0,        "expiryYear": 0,        "isDefault": true,        "isTokenized": true,        "lastUsedAt": "2019-08-24T14:15:22Z",        "createdAt": "2019-08-24T14:15:22Z"      }    ],    "defaultStoredMethodId": "string",    "lastUsedStoredMethodId": "string",    "lastUsedKind": "card",    "savedSwish": {      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",      "payerAlias": "string",      "lastUsedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Update payment method

PATCH
/api/v1/users/me/payment-methods/{id}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Payment method UUID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

nickname*string

Custom nickname for the card

Length1 <= length <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/v1/users/me/payment-methods/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "nickname": "string"  }'
{  "status": "success",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "nickname": "string",    "brand": "string",    "last4": "string",    "expiryMonth": 0,    "expiryYear": 0,    "isDefault": true,    "isTokenized": true,    "lastUsedAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Remove saved payment method

DELETE
/api/v1/users/me/payment-methods/{id}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Payment method UUID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/v1/users/me/payment-methods/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "status": "success",  "data": {    "message": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Set default payment method

POST
/api/v1/users/me/payment-methods/{id}/default

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Payment method UUID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/users/me/payment-methods/497f6eca-6276-4993-bfeb-53cbbbba6f08/default"
{  "status": "success",  "data": {    "message": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Purchase Intents

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

Prepaid Types

Prepaid payment categories for externally-paid tabs (e.g. third-party channels)