Enroll a card authorization endpoint

curl --request PUT \
  --url https://api.lightspark.com/grid/2025-10-13/platform/card-authorization-endpoint \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://api.mycompany.com/grid/card-authorizations",
  "timeoutBehavior": "DECLINE"
}
'

const options = {
  method: 'PUT',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://api.mycompany.com/grid/card-authorizations',
    timeoutBehavior: 'DECLINE'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/platform/card-authorization-endpoint', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"url\": \"https://api.mycompany.com/grid/card-authorizations\",\n  \"timeoutBehavior\": \"DECLINE\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/platform/card-authorization-endpoint")
  .put(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "url": "https://api.mycompany.com/grid/card-authorizations",
  "timeoutBehavior": "DECLINE",
  "responseTimeoutMs": 1500,
  "createdAt": "2026-10-20T15:04:05Z",
  "updatedAt": "2026-10-20T15:04:05Z"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

{
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "reason": "<string>",
  "details": {}
}

Cards

Enroll a card authorization endpoint

Enroll the endpoint Grid calls to ask your platform for a real-time decision on each card authorization that Grid’s own checks approve. See the CARD_AUTHORIZATION.REQUEST webhook for the request your endpoint receives and the decision it must return.

Before enrolling, Grid sends your endpoint one signed CARD_AUTHORIZATION.REQUEST with data.isTest: true and example data. Answer it without running your business checks. Enrollment succeeds only if your endpoint returns 200 with a valid CardAuthorizationDecision within responseTimeoutMs; the decision in that response is ignored. Otherwise this returns 400 WEBHOOK_DELIVERY_ERROR and the enrolled endpoint, if any, is unchanged.

This setting has its own resource, outside PATCH /platform/config, because enrolling calls your endpoint and can fail on that call alone.

Calling this again replaces the enrolled endpoint. The change applies to authorizations that arrive after this call returns.

PUT

platform

card-authorization-endpoint

Enroll a card authorization endpoint

curl --request PUT \
  --url https://api.lightspark.com/grid/2025-10-13/platform/card-authorization-endpoint \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://api.mycompany.com/grid/card-authorizations",
  "timeoutBehavior": "DECLINE"
}
'

const options = {
  method: 'PUT',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://api.mycompany.com/grid/card-authorizations',
    timeoutBehavior: 'DECLINE'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/platform/card-authorization-endpoint', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"url\": \"https://api.mycompany.com/grid/card-authorizations\",\n  \"timeoutBehavior\": \"DECLINE\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/platform/card-authorization-endpoint")
  .put(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "url": "https://api.mycompany.com/grid/card-authorizations",
  "timeoutBehavior": "DECLINE",
  "responseTimeoutMs": 1500,
  "createdAt": "2026-10-20T15:04:05Z",
  "updatedAt": "2026-10-20T15:04:05Z"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

{
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Body

application/json

url

string<uri>

required

HTTPS URL that receives CARD_AUTHORIZATION.REQUEST requests. It must resolve to a public host. It can differ from the webhookEndpoint in your platform config.

Maximum string length: 255

Pattern: ^https://

Example:

"https://api.mycompany.com/grid/card-authorizations"

timeoutBehavior

enum<string>

What Grid answers when your endpoint does not return a valid decision in time. Defaults to DECLINE.

Available options:

DECLINE,

APPROVE

Example:

"DECLINE"

Response

The enrolled card authorization endpoint.

The endpoint Grid calls to ask your platform for a real-time decision on each card authorization that Grid's own checks approve.

url

string<uri>

required

HTTPS URL that receives CARD_AUTHORIZATION.REQUEST requests.

Example:

"https://api.mycompany.com/grid/card-authorizations"

timeoutBehavior

enum<string>

required

What Grid answers for a card authorization when your authorization endpoint does not return a valid decision in time.

Value	Behavior
`DECLINE`	Grid declines the authorization with `cardDeclinedReason: PLATFORM_UNAVAILABLE`.
`APPROVE`	Grid proceeds as though you approved. Grid's own funding check still applies.

A non-200 status, a body that does not match CardAuthorizationDecision, a network error, and a timeout all count as no valid decision.

Available options:

DECLINE,

APPROVE

Example:

"DECLINE"

responseTimeoutMs

integer<int32>

required

read-only

How long Grid waits for your endpoint's decision, in milliseconds, before applying timeoutBehavior. Grid sets this value.

Example:

1500

createdAt

string<date-time>

required

When an endpoint was first enrolled.

Example:

"2026-10-20T15:04:05Z"

updatedAt

string<date-time>

required

When the endpoint was last enrolled or replaced.

Example:

"2026-10-20T15:04:05Z"

Using the API

API documentation

Enroll a card authorization endpoint

Authorizations

Body

Response