Skip to main content

Linque Setup

Basis Theory enables Linque per tenant. There is nothing to request in the Portal; contact your Basis Theory representative. Do the steps on this page once per tenant, then continue to the implementation guide.

Environments​

Linque is served from the Basis Theory API hosts you already use.

EnvironmentBase URL
Sandboxhttps://api.btsandbox.com/linque
Productionhttps://api.basistheory.com/linque

Point Elements at the sandbox with apiBaseUrl: 'https://api.btsandbox.com'. The sandbox discovers a fixed test wallet and sends no SMS to the reserved test numbers, so the whole flow can be exercised without a phone. See the testing reference.

Access Controls​

You need a Basis Theory tenant and application.

There is no separate Linque credential. You authenticate with the Basis Theory application key you already use, and access is scoped through that application. Revoking the application also revokes its Linque access.

Create a Public Application in the Portal with these permissions:

PermissionAllows
linque:verification:createSend and submit a phone verification code
linque:credential:readList and verify discovered cards
token:createTokenize a card the shopper enters manually

Both Linque permissions can be granted to a publishable application, because a browser holds nothing else. The permission says your application may use Linque; it is not what limits a call to one shopper.

That is the session key's job. A publishable key on its own cannot read or verify discovered cards. After the shopper verifies their phone number, Linque returns a short-lived session key scoped to that shopper. Send it as BT-LINQUE-SESSION. This is Linque's shopper session, not a Basis Theory session key; the two are never interchangeable.

When you use the SDK, you never handle the session key yourself. It is issued on the verify call and attached to later requests for you. A server-to-server integration using a private key does not need a session key.

Linque tokenizes a discovered card when it is verified, so the application needs no token permission for that. Grant token:create only if your checkout tokenizes manually entered cards with the same key.

Neither Linque permission appears in the Portal until Linque is enabled for the tenant.

Confirm the Setup Works​

Send a code to a reserved test number with your publishable key. A 201 with sms_sent: false means the tenant is enabled and the key holds the permission. A 403 with type: "feature_unavailable" means Linque is not enabled for the tenant yet.

Send a verification code
curl 'https://api.btsandbox.com/linque/verifications' \
  -X 'POST' \
  -H 'BT-API-KEY: <PUBLIC_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{
    "first_name": "Ada",
    "last_name": "Morgan",
    "phone": "+14155551212"
  }'
Response
{
  "verification_id": "ver_...",
  "sms_sent": false
}
Last updated on