pilot

Step 2: Bind a device {#tms-ctf-stepup-ext-webapp-step2}
========================================================

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`{#tms-ctf-stepup-ext-webapp-step2_d31e67}  
**Test in Saudi Arabia:** `POST ``https://apitest.sa.cybersource.com``/tms/v2/tokenized-cards/{id}/bindings`{#tms-ctf-stepup-ext-webapp-step2_d31e75}  
The *`{id}`* is the identifier of the tokenized card.

Required Fields for Binding a Device {#tms-ctf-stepup-ext-webapp-step2-reqfields}
=================================================================================

[deviceInformation.platformType](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-platform-type.md "")
:

[authenticatedIdentities.data](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/authenticated-ids-aa/authenticated-ids-data.md "")
:
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](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/authenticated-ids-aa/authenticated-ids-provider.md "")
:

Related Information
-------------------

* [API Field Reference for the REST API](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/rest-api-fields-intro.md "")
  {#tms-ctf-stepup-ext-webapp-step2-reqfields_d38e142}

REST Example: Binding a Device {#tms-ctf-stepup-ext-webapp-step2-ex-rest}
=========================================================================

Request

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

{#tms-ctf-stepup-ext-webapp-step2-ex-rest_d62e24}  
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."
    }
  ]
}
```