Submit a customer's one-time code

client.paymentHandles.verify(, , ?): PaymentHandleConnection { connect_id, handle, status }

POST/v3/payments/handles/{handle}/verify

Completes the ceremony connect started: verifies the code, records the customer’s consent, and stores the connection. Returns connected on success, after which payments for this handle no longer need the customer present.

The code reaches you however your channel works — typically the customer replies with it in the thread. Codes are single-use and short-lived; if one has expired, call connect again for a fresh connect_id.

ParametersExpand Collapse

handle: string

body: PaymentHandleVerifyParams { code, connect_id }

code: string

The one-time code the customer received.

connect_id: string

The id returned by connect.

ReturnsExpand Collapse

PaymentHandleConnection { connect_id, handle, status }

connect_id?: string

Returned only by connect, and only while the ceremony is pending. Nothing on our side persists it — it comes back from the provider and is required again to verify — so hold it until you submit the code.

handle?: string

status?: "not_connected" | "pending" | "connected" | "revoked"

One of the following:

"not_connected"

"pending"

"connected"

"revoked"

Submit a customer's one-time code

import LinqAPIV3 from '@linqapp/sdk';

const client = new LinqAPIV3({
  apiKey: process.env['LINQ_API_V3_API_KEY'], // This is the default and can be omitted
});

const paymentHandleConnection = await client.paymentHandles.verify('handle', {
  code: '482913',
  connect_id: 'cs_01HZY8',
});

console.log(paymentHandleConnection.connect_id);

{
  "connect_id": "cs_01HZY8",
  "handle": "+14155550123",
  "status": "connected"
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}

Returns Examples

{
  "connect_id": "cs_01HZY8",
  "handle": "+14155550123",
  "status": "connected"
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}