# Installment Transaction Service
Search API Reference
- [Getting Started](https://developer.visa.com/capabilities/installment-transaction-service/docs-getting-started)
- [Authentication Method](https://developer.visa.com/capabilities/installment-transaction-service/docs-authentication)
- [Release Notes](https://developer.visa.com/capabilities/installment-transaction-service/docs-release-notes)
- [Error Codes](https://developer.visa.com/pages/visa-developer-error-codes)
- [Product Terms](https://developer.visa.com/capabilities/installment-transaction-service/product-terms)
- [Request & Response Codes](https://developer.visa.com/request_response_codes)
# Device Management API
Register a Payment Terminal / IoT device for invoking Seller APIs
## Enroll Payment Terminal v2 - Latest
This API is used by Merchant Participants who owns or maintains the Payment terminal to enroll the payment terminal. Enrollment of the payment terminal(s) is the primary step and pre-requisite to enable payment terminals to access other Device APIs to enable Installments. For enrollment of payment terminal, merchant participants need two public key IDs from Visa (to show device already knows the value of this key) and at least one device public key.
### Request
##### header Parameters
| | |
| --- | --- |
| ex-correlation-id | string \[ 1 .. 36 \] characters
Unique ID for every API request - an optional header. Generated by the API client. Used for end-to-end tracing/debugging. |
| v-c-idempotency-key | string 36 characters
Unique ID for every API request - an optional header. Generated by the API client. Used for idempotency. |
##### Request Body schema: application/json
| | |
| --- | --- |
| deviceAlias
required | string \[ 1 .. 50 \] characters
A supplementary ID for the device defined by the client/partner enrolling this device
- Must be unique for this client/partner
- An alias is analogous to the `vDeviceID` with the difference that it is assigned by the caller of this API
- Examples of aliases might be serial numbers and IMEIs
- The alias might be used to guarantee only one subject identity is created for the same physical device
Example: "990000862471854" |
| deviceKeys
required | Array of objects \[ 1 .. 5 \] items
Used by Visa to authenticate the JWT (Crypto Credential) sent by the Device to establish a session.
- These keys are not yet registered at Visa and the JWK does not include a 'kid', this is a "JWK by value".
- Visa will store the Device public keys and will assign one device key id ('kid') for each of these keys. The 'kid' value for a device key is a UUID generated by the Visa and is returned in the response.
- At least the key with keyFunction of `AUTHENTICITY` must be provided; otherwise, a 400 error will be returned. |
| Array
| | |
| --- | --- |
| jwk
required | object
JWK for device keys
A JSON data structure that represents a cryptographic key as per [RFC 7517](https://tools.ietf.org/html/rfc7517). |
| | | |
| --- | --- |
| crv
required | string
Default: "P-256"
Applicable only for EC key type.
Value:"P-256"
Example: "P-256" |
| kty
required | string
- The "kty" (key type) parameter identifies the cryptographic algorithm family used with the key, such as "RSA" or "EC".
- `EC` is the only supported value, for now. Future versions may provide others.
Value:"EC"
Example: "EC" |
| x
required | string
EC x Coordinate in _base64Url_ encoded value. Applicable only for EC key type. |
| y
required | string
EC y Coordinate in _base64Url_ encoded value. Applicable only for EC key type. |
| use | string
The "use" (public key use) parameter identifies the intended use of the public key.
- Required when the JWK is used to represent the device keys
- Indirectly defined by the value of `keyFunction`
- Employed to indicate whether the key is used for encrypting data or verifying the signature on data.
- `enc` must be used when the key is used for `KEY_AGREEMENT`
- `sig` must be used when the key is used for `AUTHENTICITY`
Enum:"sig""enc"
Example: "enc" | |
| keyFunction
required | string
This is the purpose of this key generated by the device.
- Visa will store the Payment Terminal/Device public keys and will assign one device key id ('kid') for each of these keys. The 'kid' value for a device key is a UUID generated by Visa and is returned in the response
- Visa keys are used for `AUTHENTICITY` and `KEY_AGREEMENT`
- `AUTHENTICITY` for the Visa Public Key associated to Authenticated Message in Visa responses occurring during Device Authentication. Used by Visa to authenticate the JWT (Crypto Credential) sent by the Device to establish a session
- `KEY_AGREEMENT` for the Visa Static Public Key associated to Key Agreement occurring during Device Authentication
- At least the key with keyFunction of `AUTHENTICITY` must be provided; otherwise, a 400 error will be returned.
Enum:"AUTHENTICITY""KEY_AGREEMENT"
Example: "AUTHENTICITY" |
| keyReference | string \[ 1 .. 2 \] characters
- Meaningful only to the caller of this API
- Used, optionally, to cross-reference with the keys between the request and response. Use numbers like '1', '2', etc.
- If not present, the response will include the keys in the same order as the request
Example: "1" | |
| deviceSoftware
required | object
Provides additional device context |
| | | |
| --- | --- |
| name
required | string <= 5 characters
The unique name or id assigned to the software on the device
Example: "SA2.0" |
| version
required | string <= 8 characters
Version associated with the client software (the software making oauth2 requests)
- String that follows the versioning scheme, ".\[.\]"
- Where the alphabet for major_version, minor_version, and patch_version is only digits.
- The patch version is optional
- Versions must be incremental sequences as comparisons might be done on them in order to apply distinct logic
- For comparison purposes the following conversion is done
- Remove the '.' separating the minor and patch versions, if any, from the string
- Convert the string into a float number
- The device clients are responsible for defining their own version numbers as long as they adhere to the scheme
Example: "2.0.11" | |
| visaKeys
required | Array of objects 2 items
Static public keys from Visa used for Key Agreement
- These 2 keys are provided by Visa (in certificates) during onboarding:
- Visa certificate with public key for AUTHENTICATION
- Visa certificate with public key for KEY_AGREEMENT
- These 2 Visa public keys must be provisioned/stored in the device after the kid is received in the enrollment response.
- These keys are "bound" to the vDeviceID returned in the enroll device API response.
- Both the Visa-generated AUTHENTICITY and KEY_AGREEMENT public keys must be present in the request.
Example: [{"jwk":{"kid":"eaa6db43","use":"enc"},"keyKind":"REFID","keyFunction":"AUTHENTICITY","keyReference":"1"},{"jwk":{"kid":"ffa6db45","use":"enc"},"keyKind":"REFID","keyFunction":"KEY_AGREEMENT","keyReference":"2"}] |
| Array
| | |
| --- | --- |
| jwk
required | object
JWK for device keys.
A JSON data structure that represents a cryptographic key as per [RFC 7517](https://tools.ietf.org/html/rfc7517). |
| | | |
| --- | --- |
| kid
required | string \[ 1 .. 8 \] characters
Key identifier for situations in which the Client Software already possesses a key known and registered at Visa.
Example: "eaa6db43" |
| use | string
The "use" (public key use) parameter identifies the intended use of the public key.
- Required when the JWK is used to represent the device keys
- Indirectly defined by the value of `keyFunction`
- Employed to indicate whether the key is used for encrypting data or verifying the signature on data.
- `enc` must be used when the key is used for `KEY_AGREEMENT`
- `sig` must be used when the key is used for `AUTHENTICITY`
Enum:"sig""enc"
Example: "enc" | |
| keyFunction
required | string
The purpose of this key generated by the device.
- Visa will store the Payment Terminal/Device public keys and will assign one device key id ('kid') for each of these keys. The 'kid' value for a device key is a UUID generated by Visa and is returned in the response
- Visa keys are used for `AUTHENTICITY` and `KEY_AGREEMENT`
- `AUTHENTICITY` for the Visa Public Key associated to Authenticated Message in Visa responses occurring during Device Authentication. Used by Visa to authenticate the JWT (Crypto Credential) sent by the Device to establish a session
- `KEY_AGREEMENT` for the Visa Static Public Key associated to Key Agreement occurring during Device Authentication
- Two keys (one each with keyFunction of `AUTHENTICITY` and `KEY_AGREEMENT`) must be provided; otherwise, a 400 error will be returned.
Enum:"AUTHENTICITY""KEY_AGREEMENT"
Example: "AUTHENTICITY" |
| keyKind
required | string
Type of the key. The value must be `REFID` as these keys refer to the certificates provided by Visa during onboarding.
Enum:"REFID""KEYID"
Example: "REFID" |
| keyReference | string \[ 1 .. 2 \] characters
- Meaningful only to the caller of this API
- Used, optionally, to cross-reference with the keys between the request and response. Use numbers like '1', '2', etc.
- If not present, the response will include the keys in the same order as the request
Example: "1" | |
| devicePreferredName | string \[ 1 .. 50 \] characters
Preferred name of the Payment Terminal
Example: "BNPL TERMINAL" |
### Responses
201
Device enrolled successfully
| | |
| --- | --- |
| x-via-hint | string \[ 1 .. 4096 \] characters
An optional hint header in response which API calller can send back to route the calls to a specific data center. |
| ex-correlation-id | string \[ 1 .. 36 \] characters
Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging. |
| v-c-idempotency-key | string 36 characters
Unique ID for the API response. v-c-idempotency-key is echoed back. Used for idempotency. |
Response Headers
##### Response Schema: application/json
| | |
| --- | --- |
| vDeviceID
required | string
Visa-generated device ID for the enrolled device |
| deviceAlias | string \[ 1 .. 50 \] characters
A supplementary ID for the device defined by the client/partner enrolling this device
- Must be unique for this client/partner
- An alias is analogous to the `vDeviceID` with the difference that it is assigned by the caller of this API
- Examples of aliases might be serial numbers and IMEIs
- The alias might be used to guarantee only one subject identity is created for the same physical device
Example: "990000862471854" |
| deviceKeys | Array of objects \[ 1 .. 5 \] items
- Used by Visa to authenticate the JWT (Crypto Credential) sent by the Device to establish a session.
- Visa will store the Device public keys and will assign one device key id ('kid') for each of these keys. |
| Array
| | |
| --- | --- |
| jwk
required | object
JWK for device keys.
A JSON data structure that represents a cryptographic key as per [RFC 7517](https://tools.ietf.org/html/rfc7517). |
| | | |
| --- | --- |
| kid
required | string 36 characters
The kid value for a device key is a UUID generated by Visa and is assigned to the Device Key used for authentication.
This kid value needs to be stored in the device and is to be used during authentication (while referring to the device key)
Example: "eaa6db43" |
| use | string
The "use" (public key use) parameter identifies the intended use of the public key.
- Required when the JWK is used to represent the device keys
- Indirectly defined by the value of `keyFunction`
- Employed to indicate whether the key is used for encrypting data or verifying the signature on data.
- `enc` must be used when the key is used for `KEY_AGREEMENT`
- `sig` must be used when the key is used for `AUTHENTICITY`
Enum:"sig""enc"
Example: "enc" | |
| keyFunction | string
Default: "KEY_AGREEMENT"
The purpose of this key, which is generated by the device.
- Typically, device keys are used for `AUTHENTICITY`; that is, the Payment Terminal/device Public Key is associated to Payment Terminal/device Authentication
- Typically, Visa keys are used for `AUTHENTICITY` and `KEY_AGREEMENT`
- `AUTHENTICITY` for the Visa Public Key associated to Authenticated Message in Visa responses occurring during Payment Terminal/Device Authentication
- `KEY_AGREEMENT` for the Visa Static Public Key associated to Key Agreement occurring during Payment Terminal/Device Authentication
Enum:"AUTHENTICITY""KEY_AGREEMENT"
Example: "AUTHENTICITY" |
| keyKind | string
Type of the key. The value must be `KEYID` because the kid is generated by Visa for device keys in this response.
Enum:"REFID""KEYID"
Example: "KEYID" |
| keyReference | string \[ 1 .. 2 \] characters
- Meaningful only to the caller of this API
- Used, optionally, to cross-reference with the keys between the request and response. Use numbers like '1', '2', etc.
- If not present, the response will include the keys in the same order as the request
Example: "1" | |
| devicePreferredName | string \[ 1 .. 50 \] characters
Preferred name of the Payment Terminal
Example: "BNPL TERMINAL" |
| visaKeys | Array of objects 2 items
- These 2 Visa public keys must be provisioned/stored in the device.
- These keys are "bound" to the vDeviceID returned in the enroll device API response.
- Both of the Visa-generated AUTHENTICITY and KEY_AGREEMENT public keys will be present in the response.
Example: [{"jwk":{"kid":"eaa6db43","use":"enc"},"keyKind":"REFID","keyFunction":"AUTHENTICITY","keyReference":"1"},{"jwk":{"kid":"ffa6db45","use":"enc"},"keyKind":"REFID","keyFunction":"KEY_AGREEMENT","keyReference":"2"}] |
| Array
| | |
| --- | --- |
| jwk
required | object
JWK for device keys.
A JSON data structure that represents a cryptographic key as per [RFC 7517](https://tools.ietf.org/html/rfc7517). |
| | | |
| --- | --- |
| kid
required | string \[ 1 .. 8 \] characters
The kid value for a device key is a UUID generated by the Visa and is assigned to the Device Key used for authentication.
This kid value needs to be stored in the device and is to be used during authentication (while referring to the device key).
Example: "eaa6db43" |
| use | string
The "use" (public key use) parameter identifies the intended use of the public key.
- Required when the JWK is used to represent the device keys
- Indirectly defined by the value of `keyFunction`
- Employed to indicate whether the key is used for encrypting data or verifying the signature on data.
- `enc` must be used when the key is used for `KEY_AGREEMENT`
- `sig` must be used when the key is used for `AUTHENTICITY`
Enum:"sig""enc"
Example: "enc" | |
| keyFunction | string
Default: "KEY_AGREEMENT"
The purpose of this key, which is generated by the device.
- Typically, device keys are used for `AUTHENTICITY`; that is, the Payment Terminal/device Public Key is associated to Payment Terminal/device Authentication
- Typically, Visa keys are used for `AUTHENTICITY` and `KEY_AGREEMENT`
- `AUTHENTICITY` for the Visa Public Key associated to Authenticated Message in Visa responses occurring during Payment Terminal/Device Authentication
- `KEY_AGREEMENT` for the Visa Static Public Key associated to Key Agreement occurring during Payment Terminal/Device Authentication
Enum:"AUTHENTICITY""KEY_AGREEMENT"
Example: "AUTHENTICITY" |
| keyKind | string
Type of the key. The value must be `REFID` because the kid is the reference to the certificate (corresponding to this key type) provided by Visa during onboarding.
Enum:"REFID""KEYID"
Example: "REFID" |
| keyReference | string \[ 1 .. 2 \] characters
- Meaningful only to the caller of this API
- Used, optionally, to cross-reference with the keys between the request and response. Use numbers like '1', '2', etc.
- If not present, the response will include the keys in the same order as the request
Example: "1" | |
---
### 400
The `errorResponse.details` part of the error response can provide a list of fields that failed data validation constraints and errorResponse.reason values for this error include:
- `invalidRequest`The API server could not understand the request; for example, base64 decoding failed, the field is not in a particular format, etc.
| | |
| --- | --- |
| ex-correlation-id | string \[ 1 .. 36 \] characters
Unique ID for the API response; ex-correlation-id is echoed back. Used for end-to-end tracing/debugging. |
### Response Headers
##### Response Schema: application/json
| | |
| --- | --- |
| errorResponse
required | object
Standard error response body provided when there is an error. |
| | | |
| --- | --- |
| reason
required | string <= 100 characters
API developers must use this field to drive their error handling logic
Example: "invalidRequest" |
| details | Array of objects
Array of fields - Data validation errors should use this array to specify fields that failed validation using the location field |
| Array
| | |
| --- | --- |
| location
required | string
The value of this field is using an expression to point to a field that failed validation.
This field is required if error details are specified.
Example: "plan.name" |
| message | string <= 1024 characters
The specific error for this field
Example: "Must be a non-empty value" |
| reason | string <= 100 characters
The specific reason for this error
Example: "Must be a non-empty single word value" | |
| message | string <= 1024 characters
Every error should have a human readable message describing the error. The message can very even for the same reason, thus providing additional details. API providers are free to change the message at any point of time. API clients should not use the message field to drive their business logic or to expose it directly to the consumers via UI or other means.
Example: "Input parameters validation failed" |
| status | integer \[ 100 .. 600 \]
3-digit HTTP Status Code
Example: 400 | |
### Responses
#### 401
API authorized error caused due to any of the following reasons:
- x-pay-token is not present, blank, or not in a valid format.
- Timestamp field not in valid UTC timestamp format.
- Version field is invalid.
- Token's timestamp is more than 8 minutes off from the current time.
- Token hash mismatch.
- APIKey not present in request.
- APIKey is not active.
- APIKey not valid.
- APIKey not active.
- Request has more than one authentication token, which is not supported
##### Response Schema: application/json
| | |
| --- | --- |
| errorResponse | object
Standard error response body provided when there is an error. |
| | | |
| --- | --- |
| reason
required | string <= 100 characters
API developers must use this field to drive their error handling logic
Example: "invalidRequest" |
| details | Array of objects
Array of fields - Data validation errors should use this array to specify fields that failed validation using the location field |
| Array
### More Responses
Various response scenarios are defined, including 404, 403, 406, 409, 410, 429, 500, 503. Each error response follows the same format as specified above.