Submit a customer's one-time code

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.

Path ParametersExpand Collapse

handle: string

Body ParametersJSONExpand Collapse

code: string

The one-time code the customer received.

connect_id: string

The id returned by connect.

ReturnsExpand Collapse

PaymentHandleConnection object { connect_id, handle, status }

connect_id: optional 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: optional string

status: optional "not_connected" or "pending" or "connected" or "revoked"

One of the following:

"not_connected"

"pending"

"connected"

"revoked"

Submit a customer's one-time code

curl https://api.linqapp.com/api/partner/v3/payments/handles/$HANDLE/verify \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY" \
    -d '{
          "code": "482913",
          "connect_id": "cs_01HZY8"
        }'

{
  "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
}