Installment Transaction Service API Reference
Installment Transaction Service
Search API Reference
- Getting Started
- Authentication Method
- Release Notes
- Error Codes
- Product Terms
- 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 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. |
| --- | --- |
| 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 AUTHENTICITYEnum:"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. |
| --- | --- |
| 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 AUTHENTICITYEnum:"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 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. |
| --- | --- |
| 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 AUTHENTICITYEnum:"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 AuthenticationEnum:"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. |
| --- | --- |
| 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 AUTHENTICITYEnum:"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 AuthenticationEnum:"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:
invalidRequestThe 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.