On This Page

Step 2: Bind a device

This section describes how to create a device binding.

Endpoint

Test:

POST https://apitest.cybersource.com/tms/v2/tokenized-cards/{id}/bindings

Production:

POST https://api.cybersource.com/tms/v2/tokenized-cards/{id}/bindings

Production in India:

POST https://api.in.cybersource.com/tms/v2/tokenized-cards/{id}/bindings

Production in Saudi Arabia:

POST https://api.sa.cybersource.com/tms/v2/tokenized-cards/{id}/bindings

Test in Saudi Arabia:

POST https://apitest.sa.cybersource.com/tms/v2/tokenized-cards/{id}/bindings

The {id}
is the identifier of the tokenized card.

Required Fields for Binding a Device

deviceInformation.platformType
authenticatedIdentities.data: When
authenticatedIdentities.provider
is set to
CLIENT_DEVICE_CERT_JWS
, this field is a JSON Web Signature (JWS) made up of these elements:
Header
:
alg
: Signature algorithm (e.g.,
"PS256"
for RSA-PSS with SHA-256)
kid
: Client device ID (e.g.,
"1234"
)
typ
:
"JOSE"
cty
:
"application/json"
(payload content type)
iat
: UTC timestamp when transaction was created/signed
Payload
{ "clientDeviceID": "<clientDeviceID>", "clientReferenceID": "<clientCorrelationId>", "vProvisionedTokenID": "<tokenizedCard.tokenReferenceId>", "nonce": "<Random 5 digit number>" }
Signature
Algorithm: RSA-PSS
with SHA-256 and MGF1
alg
in header set to
"PS256"; When
authenticatedIdentities.provider
is set to
VISA_PAYMENT_PASSKEY
, the value of this field is from the iframe.
authenticatedIdentities.provider

Related Information

API Field Reference for the REST API

REST Example: Binding a Device

Request

{
  "authenticatedIdentities": [
    {
      "data": "<JWS>",
      "provider": "CLIENT_DEVICE_CERT_JWS",
    }
  ],
  "deviceInformation": {
    "platformType": "WEB"
  }
}

Response to a Successful Request: Binding Approved

{
  "action": "BINDING_COMPLETED"
}

Response to a Successful Request: Device and Token Already Bound

{
  "action": "BINDING_COMPLETED"
}

Response to a Successful Request: Binding Challenged

{
  "action": "STEP_UP_AUTHENTICATE",
  "stepUpOptions": [
    {
      "method": "<stepUpRequest[].method:OTP_SMS (method=OTPSMS)>",
      "value": "<stepUpRequest[].value>",
      "source": "<stepUpRequest[].source>",
      "id": "<stepUpRequest[].identifier>"
    },
    {
      "method": "<stepUpRequest[].method:OTP_EMAIL(method=OTPEMAIL)>",
      "value": "<stepUpRequest[].value>",
      "source": "<stepUpRequest[].source>",
      "id": "<stepUpRequest[].identifier>"
    },
    {
      "method": "<stepUpRequest[].method:OTP_ONLINE_BANKING (method=OTPONLINEBANKING)>",
      "value": "<stepUpRequest[].value>",
      "source": "<stepUpRequest[].source>",
      "id": "<stepUpRequest[].identifier>"
    },
    {
      "method": "<stepUpRequest[].method:APP_TO_APP (method=APP-TO-APP)>",
      "value": "<stepUpRequest[].value>",
      "source": "<stepUpRequest[].source>",
      "id": "<stepUpRequest[].identifier>",
      "requestPayload": "<stepUpRequest[].requestPayload>"
    },
    {
      "method": "<stepUpRequest[].method:APP_TO_APP (method=APP-TO-APP)>",
      "value": "<stepUpRequest[].value>",
      "source": "<stepUpRequest[].source>",
      "id": "<stepUpRequest[].identifier>",
      "requestPayload": "<stepUpRequest[].requestPayload>",
      "platformType": "WEB (platformType=WEB)",
      "subMethod": "3DS (subMethod=THREE-DS)"
    },
    {
      "method": "<stepUpRequest[].method:CUSTOMER_SERVICE (method=CUSTOMERSERVICE)>",
      "value": "<stepUpRequest[].value>",
      "id": "<stepUpRequest[].identifier>"
    },
    {
      "method": "<stepUpRequest[].method:OUTBOUND_CALL (method=OUTBOUNDCALL)>",
      "value": "<stepUpRequest[].value>",
      "id": "<stepUpRequest[].identifier>"
    }
  ]
}

Binding Declined

{
  "errors": [
    {
      "type": "declined",
      "message": "The card association request was declined."
    }
  ]
}