# Trusted Agent Protocol
A merchant (or bot protection service) facing specification defining how to verify the signatures provided by agents and recommendations for the use of the signed content

## Version: 1

### Servers

| URL | Description |
| --- | ----------- |
| https://sandbox.api.visa.com | Sandbox server |

---
## Visa Merchant Registry Service
 A high-performance micro service for managing merchant identities and encryption key distribution, enabling secure payment request encryption in the TAP ecosystem

### [POST] /vmrs/v1/merchants
**Create Merchant**

Register a new merchant.

#### Request Body

Merchant registration request

| Required | Schema |
| -------- | ------ |
|  Yes | **application/json**: { **"vmid"**: string, **"indicator"**: string, <br>**Available values:** "TAP", "ACG", "BOTH", **"merchantUrl"**: string, **"merchantName"**: string, **"encryptionKey"**: { **"keyName"**: string, **"algorithm"**: string, <br>**Available values:** "RSA-OAEP", "RSA-OAEP-256", "RSA-OAEP-384", "RSA-OAEP-512", **"encryptionKey"**: string, **"encryptionType"**: string, <br>**Available values:** "A256GCM", "A128GCM", "C20P", "A256CBC_HS512", "A128CBC_HS256", "A256CCM", "A128CCM", **"expirationDate"**: dateTime }, **"cryptogramType"**: string, <br>**Available values:** "TAVV", "DAVV", <br>**Default:** DAVV, **"apiIntegrations"**: { **"url"**: string, **"metadata"**: object, **"integrationSpec"**: string }, **"webIntegrations"**: { **"url"**: string, **"metadata"**: object, **"integrationSpec"**: string }, **"paymentPayloadType"**: string, <br>**Available values:** "UNENCRYPTED", "ENCRYPTED", <br>**Default:** UNENCRYPTED, **"protocolInteractions"**: [ { **"url"**: string, **"metadata"**: object, **"protocol"**: string, <br>**Available values:** "ucp", "acp", "x402", **"documentationUrl"**: string } ], **"acceptanceRelationships"**: [ string ] }<br> |

#### Responses

| Code | Description | Schema |
| ---- | ----------- | ------ |
| 201 | Merchant created successfully | **application/json**: { **"id"**: string, **"keys"**: [ { **"id"**: string, **"keyName"**: string, **"isActive"**: boolean, **"algorithm"**: string, **"createdAt"**: dateTime, **"updatedAt"**: dateTime, **"encryptionKey"**: string, **"encryptionType"**: string, **"expirationDate"**: dateTime } ], **"vmid"**: string, **"isActive"**: boolean, **"createdAt"**: dateTime, **"indicator"**: string, **"updatedAt"**: dateTime, **"merchantUrl"**: string, **"merchantName"**: string, **"cryptogramType"**: string, **"apiIntegrations"**: { **"url"**: string, **"metadata"**: object, **"integrationSpec"**: string }, **"webIntegrations"**: { **"url"**: string, **"metadata"**: object, **"integrationSpec"**: string }, **"merchantMetadata"**: object, **"paymentPayloadType"**: string, **"protocolInteractions"**: [ { **"url"**: string, **"metadata"**: object, **"protocol"**: string, <br>**Available values:** "ucp", "acp", "x402", **"documentationUrl"**: string } ], **"acceptanceRelationships"**: [ string ] }<br> |
| 409 | Conflict - merchantUrl already exists | **application/json**: { **"detail"**: string }<br> |
| 422 | Validation Error | **application/json**: { **"detail"**: [ { **"loc"**: [ string ], **"msg"**: string, **"type"**: string } ] }<br> |

---
### Schemas

#### MerchantUpdate Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| merchantUrl | string | Base merchant URL<br>*Example:* `"https://acme-updated.example.com"` | No |
| merchantName | string | Doing business as (DBA) name<br>*Example:* `"Acme Corp Updated"` | No |
| cryptogramType | string, <br>**Available values:** "TAVV", "DAVV" | Authentication method<br>*Enum:* `"TAVV"`, `"DAVV"`<br>*Example:* `"TAVV"` | No |
| apiIntegrations | { **"url"**: string, **"metadata"**: object, **"integrationSpec"**: string } |  | No |
| webIntegrations | { **"url"**: string, **"metadata"**: object, **"integrationSpec"**: string } |  | No |
| paymentPayloadType | string, <br>**Available values:** "UNENCRYPTED", "ENCRYPTED" | Credential format<br>*Enum:* `"UNENCRYPTED"`, `"ENCRYPTED"`<br>*Example:* `"UNENCRYPTED"` | No |
| protocolInteractions | [ { **"url"**: string, **"metadata"**: object, **"protocol"**: string, <br>**Available values:** "ucp", "acp", "x402", **"documentationUrl"**: string } ] | List of protocol interaction configurations | No |
| acceptanceRelationships | [ string ] | List of acceptance network relationships | No |

#### KeyResponse Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | string | Unique key identifier (UUID)<br>*Example:* `"a1b2c384-56c7-48d9-be0f-1e2d3c4b5a6f"` | Yes |
| keyName | string | Key name<br>*Example:* `"primary-key"` | Yes |
| isActive | boolean | Whether the key is active<br>*Example:* `false` | Yes |
| algorithm | string | Key wrapping algorithm<br>*Example:* `"RSA-OAEP"` | Yes |
| createdAt | dateTime | Creation timestamp<br>*Example:* `"2024-01-15T10:30:00Z"` | Yes |
| updatedAt | dateTime | Last update timestamp<br>*Example:* `"2024-01-15T10:30:00Z"` | Yes |
| merchantId | string | Merchant identifier<br>*Example:* `"7f4c82a1-305e-4f9c-8d2a-1b3e5f7c502a"` | Yes |
| merchantName | string | Merchant name<br>*Example:* `"Acme Corp"` | Yes |
| encryptionKey | string | Base64-encoded asymmetric public key<br>*Example:* `"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."` | Yes |
| encryptionType | string | Content encryption algorithm<br>*Example:* `"A256GCM"` | Yes |
| expirationDate | dateTime | Key expiration date<br>*Example:* `"2026-12-31T23:59:59Z"` | No |

#### KeyCreate Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| keyName | string | Unique identifier for the key<br>*Example:* `"primary-key"` | Yes |
| algorithm | string, <br>**Available values:** "RSA-OAEP", "RSA-OAEP-256", "RSA-OAEP-384", "RSA-OAEP-512" | Key wrapping algorithm<br>*Enum:* `"RSA-OAEP"`, `"RSA-OAEP-256"`, `"RSA-OAEP-384"`, `"RSA-OAEP-512"`<br>*Example:* `"RSA-OAEP"` | Yes |
| encryptionKey | string | Base64-encoded asymmetric public key (DER, PEM, JWK, or OpenSSH format)<br>*Example:* `"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."` | Yes |
| encryptionType | string, <br>**Available values:** "A256GCM", "A128GCM", "C20P", "A256CBC_HS512", "A128CBC_HS256", "A256CCM", "A128CCM" | Content encryption algorithm<br>*Enum:* `"A256GCM"`, `"A128GCM"`, `"C20P"`, `"A256CBC_HS512"`, `"A128CBC_HS256"`, `"A256CCM"`, `"A128CCM"`<br>*Example:* `"A256GCM"` | Yes |
| expirationDate | dateTime | Key expiration date (must be in the future)<br>*Example:* `"2026-12-31T23:59:59Z"` | No |

#### CredentialsResponse Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| vmid | string | Visa Merchant ID<br>*Example:* `"40010030273"` | No |
| message | string | Message indicating default response when merchant not found<br>*Example:* `"Merchant not found, returning default configuration"` | No |
| merchantId | string | Merchant unique identifier<br>*Example:* `"7f4c82a1-305e-4f9c-8d2a-1b3e5f7c502a"` | Yes |
| merchantUrl | string | Base merchant URL<br>*Example:* `"https://acme.example.com"` | Yes |
| merchantName | string | Doing business as (DBA) name<br>*Example:* `"Acme Corp"` | Yes |
| encryptionKey | { **"id"**: string, **"keyName"**: string, **"isActive"**: boolean, **"algorithm"**: string, **"createdAt"**: dateTime, **"updatedAt"**: dateTime, **"encryptionKey"**: string, **"encryptionType"**: string, **"expirationDate"**: dateTime } |  | No |
| cryptogramType | string | Authentication method<br>*Example:* `"DAVV"` | No |
| paymentPayloadType | string | Credential format<br>*Example:* `"UNENCRYPTED"` | No |

#### MessageResponse Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| message | string | Response message<br>*Example:* `"Operation completed successfully"` | Yes |

#### KeyResponseWithoutMerchant Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | string | Unique key identifier (UUID)<br>*Example:* `"a1b2c384-56c7-48d9-be0f-1e2d3c4b5a6f"` | Yes |
| keyName | string | Key name<br>*Example:* `"primary-key"` | Yes |
| isActive | boolean | Whether the key is active<br>*Example:* `false` | Yes |
| algorithm | string | Key wrapping algorithm<br>*Example:* `"RSA-OAEP"` | Yes |
| createdAt | dateTime | Creation timestamp<br>*Example:* `"2024-01-15T10:30:00Z"` | Yes |
| updatedAt | dateTime | Last update timestamp<br>*Example:* `"2024-01-15T10:30:00Z"` | Yes |
| encryptionKey | string | Base64-encoded asymmetric public key<br>*Example:* `"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."` | Yes |
| encryptionType | string | Content encryption algorithm<br>*Example:* `"A256GCM"` | Yes |
| expirationDate | dateTime | Key expiration date<br>*Example:* `"2026-12-31T23:59:59Z"` | No |

#### ProtocolInteraction Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| url | string | Endpoint URL for protocol interaction<br>*Example:* `"https://api.example.com/ucp"` | Yes |
| metadata | object | Additional protocol configuration (max 10KB)<br>*Example:* `{"version":"1.0","features":["payments"]}` | No |
| protocol | string, <br>**Available values:** "ucp", "acp", "x402" | Communication protocol type<br>*Enum:* `"ucp"`, `"acp"`, `"x402"`<br>*Example:* `"ucp"` | Yes |
| documentationUrl | string | URL to protocol documentation<br>*Example:* `"https://docs.example.com/ucp"` | No |

#### ErrorResponse Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| detail | string | Error description<br>*Example:* `"Resource not found"` | Yes |

#### ApiIntegrations Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| url | string | Endpoint URL for API integration<br>*Example:* `"https://api.example.com/v1"` | Yes |
| metadata | object | Additional API configuration (max 10KB)<br>*Example:* `{"rateLimit":1000}` | No |
| integrationSpec | string | Integration specification URL<br>*Example:* `"https://docs.example.com/rest-v1"` | Yes |

#### KeyUpdate Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| keyName | string | Unique identifier for the key<br>*Example:* `"updated-key"` | No |
| algorithm | string, <br>**Available values:** "RSA-OAEP", "RSA-OAEP-256", "RSA-OAEP-384", "RSA-OAEP-512" | Key wrapping algorithm<br>*Enum:* `"RSA-OAEP"`, `"RSA-OAEP-256"`, `"RSA-OAEP-384"`, `"RSA-OAEP-512"`<br>*Example:* `"RSA-OAEP-256"` | No |
| encryptionKey | string | Base64-encoded asymmetric public key<br>*Example:* `"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."` | No |
| encryptionType | string, <br>**Available values:** "A256GCM", "A128GCM", "C20P", "A256CBC_HS512", "A128CBC_HS256", "A256CCM", "A128CCM" | Content encryption algorithm<br>*Enum:* `"A256GCM"`, `"A128GCM"`, `"C20P"`, `"A256CBC_HS512"`, `"A128CBC_HS256"`, `"A256CCM"`, `"A128CCM"`<br>*Example:* `"A256GCM"` | No |
| expirationDate | dateTime | Key expiration date (must be in the future)<br>*Example:* `"2027-12-31T23:59:59Z"` | No |

#### MerchantCreate Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| vmid | string | Visa Merchant ID (optional)<br>*Example:* `"40010030273"` | No |
| indicator | string, <br>**Available values:** "TAP", "ACG", "BOTH" | Transaction processing type<br>*Enum:* `"TAP"`, `"ACG"`, `"BOTH"`<br>*Example:* `"TAP"` | Yes |
| merchantUrl | string | Base merchant URL<br>*Example:* `"https://acme.example.com"` | Yes |
| merchantName | string | Doing business as (DBA) name for agent interactions<br>*Example:* `"Acme Corp"` | Yes |
| encryptionKey | { **"keyName"**: string, **"algorithm"**: string, <br>**Available values:** "RSA-OAEP", "RSA-OAEP-256", "RSA-OAEP-384", "RSA-OAEP-512", **"encryptionKey"**: string, **"encryptionType"**: string, <br>**Available values:** "A256GCM", "A128GCM", "C20P", "A256CBC_HS512", "A128CBC_HS256", "A256CCM", "A128CCM", **"expirationDate"**: dateTime } |  | No |
| cryptogramType | string, <br>**Available values:** "TAVV", "DAVV", <br>**Default:** DAVV | Authentication method (default: DAVV)<br>*Enum:* `"TAVV"`, `"DAVV"`<br>*Example:* `"DAVV"` | No |
| apiIntegrations | { **"url"**: string, **"metadata"**: object, **"integrationSpec"**: string } |  | No |
| webIntegrations | { **"url"**: string, **"metadata"**: object, **"integrationSpec"**: string } |  | No |
| paymentPayloadType | string, <br>**Available values:** "UNENCRYPTED", "ENCRYPTED", <br>**Default:** UNENCRYPTED | Credential format (default: UNENCRYPTED)<br>*Enum:* `"UNENCRYPTED"`, `"ENCRYPTED"`<br>*Example:* `"UNENCRYPTED"` | No |
| protocolInteractions | [ { **"url"**: string, **"metadata"**: object, **"protocol"**: string, <br>**Available values:** "ucp", "acp", "x402", **"documentationUrl"**: string } ] | List of protocol interaction configurations | No |
| acceptanceRelationships | [ string ] | List of acceptance network relationships<br>*Example:* `["visa","mastercard"]` | No |

#### WebIntegrations Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| url | string | Endpoint URL for web integration<br>*Example:* `"https://web.example.com/api"` | Yes |
| metadata | object | Additional integration configuration (max 10KB)<br>*Example:* `{"retries":3,"timeout":30}` | No |
| integrationSpec | string | Integration specification URL<br>*Example:* `"https://docs.example.com/openapi3.0"` | Yes |

#### MerchantKeysListResponse Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| keys | [ { **"id"**: string, **"keyName"**: string, **"isActive"**: boolean, **"algorithm"**: string, **"createdAt"**: dateTime, **"updatedAt"**: dateTime, **"encryptionKey"**: string, **"encryptionType"**: string, **"expirationDate"**: dateTime } ] | List of encryption keys | Yes |
| merchantId | string | Merchant identifier<br>*Example:* `"7f4c82a1-305e-4f9c-8d2a-1b3e5f7c502a"` | Yes |
| merchantName | string | Merchant name<br>*Example:* `"Acme Corp"` | Yes |

#### ValidationError Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| detail | [ { **"loc"**: [ string ], **"msg"**: string, **"type"**: string } ] |  | No |

#### MerchantResponse Schema

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | string | Unique merchant identifier (UUID)<br>*Example:* `"7f4c82a1-305e-4f9c-8d2a-1b3e5f7c502a"` | Yes |
| keys | [ { **"id"**: string, **"keyName"**: string, **"isActive"**: boolean, **"algorithm"**: string, **"createdAt"**: dateTime, **"updatedAt"**: dateTime, **"encryptionKey"**: string, **"encryptionType"**: string, **"expirationDate"**: dateTime } ] | List of encryption keys associated with the merchant | No |
| vmid | string | Visa Merchant ID<br>*Example:* `"40010030273"` | No |
| isActive | boolean | Whether the merchant is active<br>*Example:* `true` | Yes |
| createdAt | dateTime | Creation timestamp<br>*Example:* `"2024-01-15T10:30:00Z"` | Yes |
| indicator | string | Transaction processing type<br>*Example:* `"TAP"` | Yes |
| updatedAt | dateTime | Last update timestamp<br>*Example:* `"2024-01-15T10:30:00Z"` | Yes |
| merchantUrl | string | Base merchant URL<br>*Example:* `"https://acme.example.com"` | Yes |
| merchantName | string | Doing business as (DBA) name<br>*Example:* `"Acme Corp"` | Yes |
| cryptogramType | string | Authentication method<br>*Example:* `"DAVV"` | No |
| apiIntegrations | { **"url"**: string, **"metadata"**: object, **"integrationSpec"**: string } |  | No |
| webIntegrations | { **"url"**: string, **"metadata"**: object, **"integrationSpec"**: string } |  | No |
| merchantMetadata | object | Additional merchant metadata | No |
| paymentPayloadType | string | Credential format<br>*Example:* `"UNENCRYPTED"` | No |
| protocolInteractions | [ { **"url"**: string, **"metadata"**: object, **"protocol"**: string, <br>**Available values:** "ucp", "acp", "x402", **"documentationUrl"**: string } ] | List of protocol interaction configurations | No |
| acceptanceRelationships | [ string ] | List of acceptance network relationships | No |
