Authorize payment

Request Parameters

🏷️ header · 📦 body field · unmarked parameters are query params

Parameter	Type	Required	Description
`Locally-Api-Token` 🏷️	string	Yes	Locally API token must be passed in the header to authenticate the API consumer.
`card_token` 📦	string	Yes
`mute_comms` 📦	integer	Yes
`shopper.email` 📦	string	Yes
`shopper.phone` 📦	string	Yes
`shopper.first_name` 📦	string	Yes
`shopper.last_name` 📦	string	Yes
`shopper.address` 📦	string	Yes
`shopper.city` 📦	string	Yes
`shopper.state` 📦	string	No
`shopper.zip` 📦	string	Yes
`shopper.country` 📦	string	Yes
`shopper.is_opt_in_consent` 📦	integer	Yes
`shopper.is_opt_in_consent_brand` 📦	integer	Yes

Example Request

curl 'https://www.locally.com/headless/api/1.0/cart/auth' \
--request POST \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--header 'Locally-Pl-Jwt: {{CART_HASH_JWT}}' \
--header 'Content-Type: application/json' \
--data '{
  "card_token": "seti_123XYZ",
  "mute_comms": 0,
  "shopper": {
    "email": "[email protected]",
    "phone": "+10000000000",
    "first_name": "Chester",
    "last_name": "Copperpot",
    "address": "24 Goondocks Drive",
    "city": "Mars",
    "state": "OR",
    "zip": "99456",
    "country": "US",
    "is_opt_in_consent": 0,
    "is_opt_in_consent_brand": 0
  }
}'

const response = await fetch('https://www.locally.com/headless/api/1.0/cart/auth', {
  method: 'POST',
  headers: {
    'Locally-Api-Token': '{{API_TOKEN}}',
    'Locally-Pl-Jwt': '{{CART_HASH_JWT}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    card_token: 'seti_123XYZ',
    mute_comms: 0,
    shopper: {
      email: '[email protected]',
      phone: '+10000000000',
      first_name: 'Chester',
      last_name: 'Copperpot',
      address: '24 Goondocks Drive',
      city: 'Mars',
      state: 'OR',
      zip: '99456',
      country: 'US',
      is_opt_in_consent: 0,
      is_opt_in_consent_brand: 0
    }
  })
});
const data = await response.json();

import requests

url = "https://www.locally.com/headless/api/1.0/cart/auth"

headers = {
    "Locally-Api-Token": "{{API_TOKEN}}",
    "Locally-Pl-Jwt": "{{CART_HASH_JWT}}"
}

payload = {
    "card_token": "seti_123XYZ",
    "mute_comms": 0,
    "shopper": {
        "email": "[email protected]",
        "phone": "+10000000000",
        "first_name": "Chester",
        "last_name": "Copperpot",
        "address": "24 Goondocks Drive",
        "city": "Mars",
        "state": "OR",
        "zip": "99456",
        "country": "US",
        "is_opt_in_consent": 0,
        "is_opt_in_consent_brand": 0
    }
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

Identify the cart to authorize with the Locally-Pl-Jwt header, passing the cart_hash_jwt value returned when the cart was created. card_token is a tokenized reference to the shopper's credit card — retailers using the Stripe PSP expect a SetupIntent (seti_*) token.

Example Response

{
  "success": true,
  "data": {
    "items": [
      {
        "upc": "686487455948",
        "auth": "SUCCESS",
        "in_cart": 1,
        "qty": 2
      },
      {
        "upc": "686487455955",
        "auth": "SUCCESS",
        "in_cart": 1,
        "qty": 1
      }
    ],
    "is_test": 0,
    "cart_hash": "QE3QL6",
    "cart_hash_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjYXJ0X2hhc2giOiJRRTNRTDYiLCJjcmVhdGVkX2F0IjoxNzIxNDA4MDAwfQ.sQ5xL0y3fY8pWq2ZbNvA7cRkT1uHdGmE4jXoPiC6VnM",
    "session": {
      "id": "vD2kq9mXw4bT7nR5cJ1sL8fA3gH6pZ0yE2uN4iK9"
    }
  },
  "msg": ""
}

Response Explanation

success — Boolean outcome of the call. When false, the response also carries a top-level error_code and explanatory msg — always check success, not just the HTTP status.
data.items[].auth — Per-item authorization status: SUCCESS (bank hold created), FAILED (authorization declined), SKIPPED (not attempted because another step failed), or PENDING. On any failure Locally cancels holds already created.
data.items[].in_cart — Integer flag (not boolean): 1 if the item is in the cart, 0 if it could not be added.
data.is_test — 0 for live carts, 1 for carts created with a test_* API key — test carts use a decoy payment provider and are invisible to retailers. See Testing Your Integration.
data.cart_hash — Unique short identifier for the cart. Other endpoints accept it as the hash parameter, and it appears in order URIs.
data.cart_hash_jwt — Signed token identifying this cart; unlike the session ID it never expires. Pass it as the Locally-Pl-Jwt header to retrieve, update, authorize, or commit the cart later.
data.session.id — Locally session ID, returned on every response. Replay it via the Locally-Api-Session-Id header to persist the shopper's session between calls; expired IDs are transparently replaced with fresh ones.
msg — Human-readable error text; empty string on success. In production, unexpected server errors are masked as App server error with a lookup reference — see Handling Errors in Production.