For Agentic Commerce, American Express will issue enrollment identifiers, proof-of-intent, and tokenized payment credentials, and will enforce a secure Account → Enrollment → Intent → Token lifecycle during payment transactions.
The APIs described in this specification enable partners to:
How the APIs Fit Together
The API suite follows a stepwise lifecycle from enrollment through transaction completion.
1. Account Enrollment
Partners enroll eligible accounts to enable tokenization and obtain an enrollment identifier.
During enrollment:
Some enrollments may require additional authentication or step-up verification before becoming active. Enrolled accounts can later be unenrolled to revoke tokenization access.
Outcome: An active enrollment that can be used to create intents and request payment credentials.
2. Intent Creation
An intent represents a user's purchase goal and can be created with an enrollment identifier.
An intent:
American Express network evaluates intent context and risk and may require additional verification before the intent becomes active.
Outcome: An intent identifier that represents an authorized purchase context.
3. Payment Credential Request
Tokenized payment credentials are issued for an active intent.
During this step:
Outcome: Tokenized payment credentials used to complete a transaction.
4. Transaction Completion
Partners acknowledge the transaction outcome using the issued token.The purchase completion step acknowledges whether the transaction was approved or declined.
5. Notifications
Partners receive notifications on status change for enrollment, intent.
Outcome: Ongoing visibility for enrollment and intent.
Lifecycle Summary
At a high level, the APIs are typically used in the following sequence:
Not all flows require every step to occur synchronously. Depending on the use case, steps may be deferred, repeated, or handled by different actors (such as agents, vaults, or payment processors).
The American Express API Security and Authentication guide is available at American Express API Security and Authentication guide. The OAuth 2.0 guide is available at OAuth 2.0 guide.
Changelogv1.0.0 - Initial Release
Enrolls an account for agent-executed commerce. This API supports a two-phase enrollment flow when additional verification is required.
Creates an intent associated with an enrolled account for agent-executed purchases. This API supports a multi-step flow when additional authentication is required:
Updates an existing intent associated with an enrolled account. This API supports a multi-step flow when additional authentication is required:
Intent updates are limited to supported parameters such as maximum amount and expiration. To modify other attributes, the existing intent must be cancelled and a new intent created.
", "operationId": "updateIntent", "requestBody": { "required": true, "description": "Request to update an existing intent associated with an enrolled account. The request payload is JWE-encrypted on the wire.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIntentsRequest" }, "examples": { "updateIntentBeforeStepUpVerification": { "summary": "Submit updated intent for validation and risk assessment.", "value": { "enrollmentId": "enr_8f3a9c2d7b6e4a1f", "prompt": { "promptSummary": "Buy a new premium smartphone under $1100 with fast delivery", "nlpConfidence": 0.94 }, "expirationTs": "2026-03-22T18:30:00Z", "spendControl": { "maxAmount": "1100", "currency": "USD", "expirationTs": "2026-03-22T18:30:00Z" }, "agent": { "llmVersion": "gpt-4.1", "llmPlatform": "AI_PLATFORM", "agentName": "NexusAI" }, "shipment": { "shippingEmail": "someone@example.com", "shippingMethod": "EXPEDITED", "shippingPhoneNumber": "+14155552671", "shippingAddress": { "addressLine1": "300 Juniper Lane", "addressLine2": "Apt 4B", "city": "New York", "state": "NY", "country": "US", "postalCode": "12345" } }, "orderContext": { "merchants": [ { "name": "Example Store", "merchantId": 987654, "url": "https://www.example.com", "appName": "Example Merchant App", "seNumber": "123456789012", "categoryName": "Electronics", "metadata": { "storeType": "official", "additionalProperty": "string" } } ], "totalAmount": "1099", "currency": "USD", "orderId": "order_789456123", "allowPartialOrder": "NO", "type": "INTENT", "items": [ { "itemId": "item_001", "merchantId": 987654, "name": "Premium Smartphone 256GB", "unitAmount": "1099", "currency": "USD", "quantity": 1, "condition": "new", "category": "Smartphones", "brand": "Example Brand", "imageLink": "https://example.com/images/product-image", "isRefundable": "YES", "isGiftCard": "NO", "isRecurBill": "NO", "purchaseCriteria": [ { "type": "PRICE", "fromDate": "2026-03-20T18:30:00Z", "toDate": "2026-03-22T18:30:00Z", "pricePreference": "MAXIMUM_PRICE", "maxAmount": "1100", "currency": "USD", "isShippingIncluded": "YES" } ], "metadata": { "modelNumber": "A3101", "releaseYear": "2025", "color": "Black Titanium", "additionalProperty": "string" } } ] }, "maxAllowedTransactions": "1", "risk": { "account": { "panTenureOnFile": 24, "accountRiskScore": "2", "recentSecurityActivity": "10", "mostRecentAccountPaymentMethodChangeActivity": 30, "partnerStepUp": "NO", "agentAccountLocale": "en-US" }, "device": { "deviceId": "device_abc123", "deviceName": "John's Phone", "deviceType": "Phone", "ipAddress": "192.0.2.1", "deviceRiskScore": "3", "deviceTenure": 12, "tlsFingerprint": "771,4865-4866-4867-49195-49196,0-11-10-35,29-23-24,0", "location": { "longitude": "-74.0060", "latitude": "40.7128" } }, "metadata": { "ipReputation": "low_risk", "additionalProperty": "string" } }, "user": { "firstName": "Jane", "lastName": "Jones", "billingAddress": { "addressLine1": "300 Juniper Lane", "addressLine2": "Apt 4B", "city": "New York", "state": "NY", "country": "US", "postalCode": "12345" }, "userEmailHash": "b4c9a289323b21a01c3e940f150eb9b8b6c8f0d3a9a5f8c2e5d7f6a1b2c3d4e5", "userPhoneNumberHash": "a3f5c2e9d4b7c1a8f6e2d3c4b5a6978877665544332211ffeeddccbbaa998877", "email": "someone@example.com" }, "purchaseDecision": "NON-DELEGATED" } }, "updateIntentAfterStepUpVerification": { "summary": "The follow-up request after completing step-up verification.", "value": { "enrollmentId": "enr_8f3a9c2d7b6e4a1f", "stepUpVerification": { "stepUpSessionId": "sess_9f3a7c2d8b6e4a1f", "issuerSurfaceAuthenticationResponse": { "authenticationToken": "rt_7a9c3d5e8f1b4a2c9d0e6f3a1b2c4d5e" } } } }, "encryptedPayloadReference": { "summary": "Encrypted payload (on the wire)", "value": { "encryptedPayload": "Cancels an existing intent associated with an enrolled account.
", "operationId": "cancelIntent", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInvalidFieldsResponse" }, "examples": { "invalidInputData": { "value": { "error": { "code": 10001, "description": "Invalid input data", "type": "USER_EXCEPTION", "param": "intentId" } } }, "mandatoryDataMissing": { "value": { "error": { "code": 10003, "description": "Mandatory data missing", "type": "USER_EXCEPTION", "param": "intentId" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorizedResponse" }, "example": null } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResourceNotFoundResponse" }, "example": null } } }, "422": { "description": "Unprocessable entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBusinessExceptionResponse" }, "examples": { "intentStateNotSupported": { "value": { "error": { "code": 30402, "description": "The request is not supported for the current intent state", "type": "BUSINESS_EXCEPTION" } } } } } } }, "500": { "description": "Service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSystemDownResponse" }, "example": { "error": { "code": "20001", "description": "Internal server error", "type": "SYSTEM_EXCEPTION" } } } } } } } }, "/payments/digital/v1/agentic-commerce/paymentcredentials": { "post": { "parameters": [ { "$ref": "#/components/parameters/Authorization" }, { "$ref": "#/components/parameters/TrackingId" }, { "$ref": "#/components/parameters/AgentId" }, { "$ref": "#/components/parameters/ContentType" } ], "tags": [ "Payment Credentials" ], "summary": "Request payment credentials", "description": "Generates tokenized payment credentials associated with an approved intent. This API supports a multi-step flow when additional authentication is required:
The response of the API will have the payment credentials. If step-up authentication is completed asynchronously and if applicable, American Express will notify the partner via the notification API. The partner can then call payment credentials API again to retrieve the payment credentials.
", "operationId": "paymentCredentials", "requestBody": { "required": true, "description": "A request to obtain tokenized payment credentials for an approved intent. The request payload is JWE-encrypted on the wire.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCredentialsRequest" }, "examples": { "createPaymentCredentialsBeforeStepUpVerification": { "summary": "The initial request for generating payment credentials (before step-up verification)", "value": { "risk": { "account": { "panTenureOnFile": 24, "accountRiskScore": "2", "recentSecurityActivity": "10", "mostRecentAccountPaymentMethodChangeActivity": 30, "partnerStepUp": "YES", "agentAccountLocale": "en-US" }, "device": { "deviceId": "device_abc123", "deviceName": "John's Phone", "deviceType": "Phone", "ipAddress": "192.0.2.1", "deviceRiskScore": "3", "deviceTenure": 12, "tlsFingerprint": "771,4865-4866-4867-49195-49196,0-11-10-35,29-23-24,0", "location": { "longitude": "-74.0060", "latitude": "40.7128" } }, "metadata": { "ipReputation": "low_risk", "additionalProperty": "string" } }, "agent": { "llmVersion": "gpt-4.1", "llmPlatform": "AI_PLATFORM", "agentName": "NexusAI" }, "shipment": { "shippingEmail": "someone@example.com", "shippingMethod": "EXPEDITED", "shippingPhoneNumber": "+14155552671", "shippingAddress": { "firstName": "Jane", "lastName": "Jones", "addressLine1": "300 Juniper Lane", "addressLine2": "Apt 4B", "city": "New York", "state": "NY", "country": "US", "postalCode": "12345" } }, "user": { "firstName": "Jane", "lastName": "Jones", "billingAddress": { "addressLine1": "300 Juniper Lane", "addressLine2": "Apt 4B", "city": "New York", "state": "NY", "country": "US", "postalCode": "12345" }, "userEmailHash": "b4c9a289323b21a01c3e940f150eb9b8b6c8f0d3a9a5f8c2e5d7f6a1b2c3d4e5", "userPhoneNumberHash": "a3f5c2e9d4b7c1a8f6e2d3c4b5a6978877665544332211ffeeddccbbaa998877", "email": "someone@example.com" }, "orderContext": { "merchants": [ { "url": "https://www.example.com", "name": "Example Store", "merchantId": 987654, "seNumber": "123456789012", "sellerId": "seller_example_official", "categoryName": "Electronics", "policies": { "termsOfService": "https://www.example.com/terms", "returnPolicy": "https://www.example.com/returns", "returnWindow": "14" }, "metadata": { "storeType": "official", "region": "US", "fulfillmentModel": "first_party", "additionalProperty": "string" } } ], "totalAmount": "1099", "currency": "USD", "orderId": "order_789456123", "allowPartialOrder": "NO", "type": "CART", "items": [ { "itemId": "item_001", "merchantId": 987654, "name": "Premium Smartphone 256GB", "unitAmount": "1099", "currency": "USD", "quantity": 1, "condition": "new", "category": "Smartphones", "brand": "Example Brand", "imageLink": "https://example.com/images/product-image", "isRefundable": "YES", "isGiftCard": "NO", "isRecurBill": "NO", "purchaseCriteria": [ { "type": "PRICE", "fromDate": "2026-03-20T18:30:00Z", "toDate": "2026-03-22T18:30:00Z", "pricePreference": "MAXIMUM_PRICE", "maxAmount": "1200", "currency": "USD", "isShippingIncluded": "YES" } ], "metadata": { "modelNumber": "A3101", "releaseYear": "2025", "color": "Black Titanium", "additionalProperty": "string" } } ] }, "proofOfIntent": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImludGVudC1rZXktMSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhbWV4LXRzcCIsInN1YiI6ImVucm9sbG1lbnRfOGYzYTljMmQ3YjZlNGExZiIsImludGVudElkIjoiaW50ZW50Xzg3NjU0MzIxIiwibWVyY2hhbnRJZCI6Ijk4NzY1NCIsImFtb3VudCI6IjEwOTkiLCJjdXJyZW5jeSI6IlVTRCIsInNjb3BlIjoiaW50ZW50IiwiaWF0IjoxNzQyMzQyMjAwLCJleHAiOjE3NDIzNDU4MDB9.c2lnbmF0dXJlX3BsYWNlaG9sZGVy", "purchaseDecision": "NON-DELEGATED", "requestedPaymentCredentialsCount": 1 } }, "createPaymentCredentialsAfterStepUpVerification": { "summary": "The follow-up request after completing step-up verification.", "value": { "proofOfIntent": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImludGVudC1rZXktMSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhbWV4LXRzcCIsInN1YiI6ImVucm9sbG1lbnRfOGYzYTljMmQ3YjZlNGExZiIsImludGVudElkIjoiaW50ZW50Xzg3NjU0MzIxIiwibWVyY2hhbnRJZCI6Ijk4NzY1NCIsImFtb3VudCI6IjEwOTkiLCJjdXJyZW5jeSI6IlVTRCIsInNjb3BlIjoiaW50ZW50IiwiaWF0IjoxNzQyMzQyMjAwLCJleHAiOjE3NDIzNDU4MDB9.c2lnbmF0dXJlX3BsYWNlaG9sZGVy", "stepUpVerification": { "stepUpSessionId": "sess_9f3a7c2d8b6e4a1f", "safeKeyAuthenticationResponse": { "riskToken": "eyJraWQiOiIxMjM0NTY3ODkwIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ1c2VyX2lkIn0.signature" }, "issuerSurfaceAuthenticationResponse": { "authenticationToken": "rt_7a9c3d5e8f1b4a2c9d0e6f3a1b2c4d5e" }, "securePushAuthenticationResponse": { "authenticationToken": "rt_7a9c3d5e8f1b4a2c9d0e6f3a1b2c4d5e" }, "validateAuthenticationCode": { "value": "482913" } } } }, "encryptedPayloadReference": { "summary": "Encrypted payload (on the wire)", "value": { "encryptedPayload": "Request body content type
Default: 'application/json'
" }, "IntentId": { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Intent identifier" } }, "schemas": { "EncryptedRequestResponse": { "type": "object", "description": "JWE-encrypted request/response payload for APIs.", "format": "JWE-encrypted request/response payload", "properties": { "encryptedPayload": { "type": "string", "description": "The JWE-encrypted payload" } }, "required": [ "encryptedPayload" ] }, "EnrollmentsRequest": { "description": "A request to initiate or complete an enrollment.The request payload is JWE-encrypted on the wire as seen in the model [EncryptedRequestResponse](#components-schemas-EncryptedRequestResponse). The application/json schema shows the decrypted model for reference, with an encrypted example included.", "oneOf": [ { "type": "object", "title": "The initial request used for account validation and risk assessment (before step-up authentication).", "description": "The initial request used for account validation and risk assessment.", "properties": { "account": { "allOf": [ { "$ref": "#/components/schemas/Account" } ], "description": "Account details for the enrollment." }, "risk": { "allOf": [ { "$ref": "#/components/schemas/EnrollmentsRisk" } ], "description": "Risk and device context associated with the request." }, "user": { "allOf": [ { "$ref": "#/components/schemas/User" } ], "description": "The Customer's information associated with the enrollment." }, "agent": { "allOf": [ { "$ref": "#/components/schemas/Agent" } ], "description": "The metadata describing the agent initiating the request." }, "termsAndConditions": { "allOf": [ { "$ref": "#/components/schemas/TermsAndConditions" } ], "description": "Terms and conditions accepted by the Customer." } }, "required": [ "account", "risk", "user", "agent" ] }, { "type": "object", "title": "The follow-up request used to complete enrollment after step-up authentication", "description": "The Follow-up request used to complete enrollment after step-up authentication.", "properties": { "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account. Required when submitting step-up verification. Returned in the initial enrollment response." }, "stepUpVerification": { "allOf": [ { "$ref": "#/components/schemas/StepUpVerification" } ], "description": "The step-up verification details for completing authentication." } }, "required": [ "enrollmentId", "stepUpVerification" ] } ] }, "EnrollmentsResponse": { "type": "object", "description": "The response returned for an enrollment request. The response varies based on whether step-up authentication is required.", "oneOf": [ { "$ref": "#/components/schemas/EnrollmentsResponseBeforeStepUp" }, { "$ref": "#/components/schemas/EnrollmentsResponseAfterStepUp" } ] }, "EnrollmentsResponseBeforeStepUp": { "type": "object", "title": "The response returned when enrollment is pending additional authentication. Includes details required to complete step-up verification.", "description": "The response returned when enrollment is pending additional authentication. Includes details required to complete step-up verification.", "properties": { "stepUpAuthenticationRequired": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether additional authentication is required to complete enrollment. When YES, the stepUpSessionId and availableChallenges fields will be populated." }, "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account." }, "enrollmentStatus": { "type": "string", "enum": [ "PENDING_STEP_UP" ], "description": "The current status of the enrollment." }, "stepUpSessionId": { "type": "string", "description": "An identifier for the step-up session associated with the enrollment." }, "accountMetadata": { "allOf": [ { "$ref": "#/components/schemas/AccountMetadata" } ], "description": "The metadata associated with the enrolled account." }, "issuer": { "allOf": [ { "$ref": "#/components/schemas/Issuer" } ], "description": "The issuer details associated with the enrolled account." }, "availableChallenges": { "allOf": [ { "$ref": "#/components/schemas/availableChallenges" } ], "description": "A list of available authentication challenges for completing step-up verification." } }, "required": [ "stepUpAuthenticationRequired", "enrollmentId", "enrollmentStatus", "stepUpSessionId", "accountMetadata", "issuer", "availableChallenges" ] }, "EnrollmentsResponseAfterStepUp": { "type": "object", "title": "The response returned after enrollment is successfully completed following step-up authentication. Includes account details associated with the enrollment.", "description": "The response returned after enrollment is successfully completed following step-up authentication. Includes account details associated with the enrollment.", "properties": { "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account." }, "enrollmentStatus": { "type": "string", "enum": [ "ACTIVE" ], "description": "The current status of the enrollment." }, "accountMetadata": { "$ref": "#/components/schemas/AccountMetadata" }, "issuer": { "$ref": "#/components/schemas/Issuer" } }, "required": [ "enrollmentId", "enrollmentStatus", "accountMetadata", "issuer" ] }, "IntentsRequest": { "type": "object", "properties": { "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account." }, "prompt": { "$ref": "#/components/schemas/PromptDetails" }, "expirationTs": { "type": "string", "format": "date-time", "description": "The intent expiration date and time in ISO 8601 format" }, "spendControl": { "$ref": "#/components/schemas/SpendControl" }, "agent": { "$ref": "#/components/schemas/Agent" }, "shipment": { "$ref": "#/components/schemas/ShipmentDetails" }, "orderContext": { "$ref": "#/components/schemas/OrderContext" }, "maxAllowedTransactions": { "type": "string", "description": "Indicates the maximum allowed transactions authorized by the user to complete the purchase." } }, "required": [ "expirationTs", "shipment", "agent" ] }, "CreateIntentsRequest": { "description": "The request payload is JWE-encrypted on the wire as seen in the model [EncryptedRequestResponse](#components-schemas-EncryptedRequestResponse). The application/json schema shows the decrypted model for reference, with an encrypted example included.", "oneOf": [ { "title": "The initial request for intent validation and risk assessment (before step-up verification)", "allOf": [ { "$ref": "#/components/schemas/IntentsRequest" }, { "type": "object", "description": "The initial request for intent validation and risk assessment (before step-up verification)", "properties": { "risk": { "$ref": "#/components/schemas/IntentsRisk" }, "user": { "$ref": "#/components/schemas/IntentsUser" }, "purchaseDecision": { "type": "string", "enum": [ "NON-DELEGATED", "DELEGATED" ], "description": "Indicates whether a purchase is executed with explicit Card Member approval at the time of transaction or delegated to an Agent for autonomous execution." } }, "required": [ "enrollmentId", "prompt", "spendControl", "risk", "purchaseDecision" ] } ] }, { "title": "The follow-up request after completing step-up verification.", "allOf": [ { "type": "object", "description": "The follow-up request after completing step-up verification.", "properties": { "enrollmentId": { "type": "string", "description": "The enrolled account's unique identifier" }, "stepUpVerification": { "$ref": "#/components/schemas/StepUpVerification" } }, "required": [ "enrollmentId", "stepUpVerification" ] } ] } ] }, "UpdateIntentsRequest": { "description": "The request payload is JWE-encrypted on the wire as seen in the model [EncryptedRequestResponse](#components-schemas-EncryptedRequestResponse). The application/json schema shows the decrypted model for reference, with an encrypted example included.", "oneOf": [ { "title": "The initial request for update (before step-up verification)", "allOf": [ { "$ref": "#/components/schemas/IntentsRequest" }, { "type": "object", "description": "The initial request for update (before step-up verification)", "properties": { "risk": { "$ref": "#/components/schemas/IntentsRisk" }, "user": { "$ref": "#/components/schemas/IntentsUser" }, "purchaseDecision": { "type": "string", "enum": [ "NON-DELEGATED", "DELEGATED" ], "description": "Indicates whether a purchase is executed with explicit Card Member approval at the time of transaction or delegated to an Agent for autonomous execution." } }, "required": [ "enrollmentId", "prompt", "spendControl", "risk", "purchaseDecision" ] } ] }, { "title": "The follow-up request after completing step-up verification.", "allOf": [ { "type": "object", "description": "The follow-up request after completing step-up verification.", "properties": { "enrollmentId": { "type": "string", "description": "The enrolled account's unique identifier" }, "stepUpVerification": { "$ref": "#/components/schemas/StepUpVerification" } }, "required": [ "enrollmentId", "stepUpVerification" ] } ] } ] }, "IntentsResponse": { "oneOf": [ { "$ref": "#/components/schemas/IntentsResponseBeforeStepUp" }, { "$ref": "#/components/schemas/IntentsResponseAfterStepUp" } ] }, "IntentsResponseBeforeStepUp": { "type": "object", "title": "The response returned when additional authentication is required to proceed with the intent.", "description": "The response returned when additional authentication is required to proceed with the intent.", "properties": { "stepUpAuthenticationRequired": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether additional authentication is required." }, "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account." }, "intentId": { "type": "string", "description": "A unique identifier for the intent." }, "intentStatus": { "type": "string", "enum": [ "PENDING_STEP_UP" ], "description": "The current status of the intent." }, "stepUpSessionId": { "type": "string", "description": "The identifier for the step-up session associated with the intent." }, "availableChallenges": { "allOf": [ { "$ref": "#/components/schemas/availableChallenges" } ], "description": "The authentication challenges available to complete step-up verification." } }, "required": [ "stepUpAuthenticationRequired", "enrollmentId", "intentStatus", "intentId", "stepUpSessionId", "availableChallenges" ] }, "IntentsResponseAfterStepUp": { "type": "object", "title": "The response returned after successful step-up authentication for the intent.", "description": "The response returned after successful step-up authentication for the intent.", "properties": { "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account." }, "intentId": { "type": "string", "description": "A unique identifier for the intent." }, "intentStatus": { "type": "string", "enum": [ "ACTIVE" ], "description": "The current status of the intent." }, "proofOfIntent": { "type": "string", "description": "A signed JSON web token associated with the intent." } }, "required": [ "enrollmentId", "intentId", "intentStatus", "proofOfIntent" ] }, "PaymentCredentialsRequest": { "description": "A request to obtain payment credentials for an approved intent. The request payload is JWE-encrypted as seen in the model [EncryptedRequestResponse](#components-schemas-EncryptedRequestResponse). The application/json schema shows the decrypted model for reference, with an encrypted example included.", "oneOf": [ { "type": "object", "title": "The initial request to obtain payment credentials for an approved intent.", "description": "The initial request to obtain payment credentials for an approved intent.", "properties": { "risk": { "$ref": "#/components/schemas/Risk" }, "agent": { "$ref": "#/components/schemas/Agent" }, "shipment": { "$ref": "#/components/schemas/PaymentCredentialsShipmentDetails" }, "user": { "$ref": "#/components/schemas/PaymentCredentialsUser" }, "orderContext": { "allOf": [ { "$ref": "#/components/schemas/PaymentCredentialsOrderContext" } ], "required": [ "merchants" ] }, "purchaseDecision": { "type": "string", "enum": [ "NON-DELEGATED", "DELEGATED" ], "description": "Indicates whether a purchase is executed with explicit Card Member approval at the time of transaction or delegated to an Agent for autonomous execution." }, "requestedPaymentCredentialsCount": { "type": "integer", "description": "The number of payment credentials the Partner is requesting for the order context. Default value is 1." } }, "required": [ "agent", "shipment", "orderContext" ] }, { "type": "object", "title": "The follow-up request after step-up verification.", "description": "The follow-up request after step-up verification.", "properties": { "proofOfIntent": { "type": "string", "description": "A signed JSON web token received part of create intent response." }, "stepUpVerification": { "$ref": "#/components/schemas/StepUpVerification" } }, "required": [ "proofOfIntent", "stepUpVerification" ] } ] }, "PaymentCredentialsResponse": { "type": "object", "description": "The response payload will be JWE-encrypted as seen in the model [EncryptedRequestResponse](#components-schemas-EncryptedRequestResponse)", "oneOf": [ { "$ref": "#/components/schemas/PaymentCredentialsWithStepUpResponse" }, { "$ref": "#/components/schemas/PaymentCredentialsWithoutStepUpResponse" } ] }, "PaymentCredentialsWithStepUpResponse": { "type": "object", "title": "The response returned when additional authentication is required to obtain payment credentials.", "description": "The response returned when additional authentication is required to obtain payment credentials.The response payload will be JWE-encrypted as seen in the model [EncryptedRequestResponse](#components-schemas-EncryptedRequestResponse)", "properties": { "stepUpAuthenticationRequired": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether additional authentication is required." }, "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account." }, "paymentCredentialId": { "type": "string", "description": "A unique identifier for the payment credential." }, "paymentCredentialStatus": { "type": "string", "enum": [ "PENDING_STEP_UP" ], "description": "The current status of the payment credential." }, "stepUpSessionId": { "type": "string", "description": "The identifier for the step-up session associated with the request." }, "availableChallenges": { "$ref": "#/components/schemas/availableChallenges" } }, "required": [ "stepUpAuthenticationRequired", "enrollmentId", "paymentCredentialStatus", "paymentCredentialId", "stepUpSessionId", "availableChallenges" ] }, "PaymentCredentialsWithoutStepUpResponse": { "type": "object", "title": "The response returned when payment credentials are successfully generated.", "description": "The response returned when payment credentials are successfully generated. The response payload will be JWE-encrypted as seen in the model [EncryptedRequestResponse](#components-schemas-EncryptedRequestResponse)", "properties": { "paymentCredentials": { "type": "array", "description": "The payment credentials associated with the order.", "items": { "description": "The payment credential details for a specific merchant.", "properties": { "merchantId": { "type": "integer", "description": "The identifier of the Merchant.", "example": "abc12345" }, "tokenNumber": { "type": "string", "description": "The tokenized account number issued for the payment.", "pattern": "^[0-9]{15}$", "example": "000000000000000" }, "expiryMonth": { "type": "string", "description": "Expiry month of the token, in MM format.The month must be between 01 and 12.", "pattern": "^(0[1-9]|1[0-2])$", "example": "09" }, "expiryYear": { "type": "string", "description": "The expiry year of the token, in YYYY format.", "pattern": "^[0-9]{4}$", "example": "2026" }, "dcsc": { "type": "string", "description": "A four-digit Dynamic Card Security Code (DCSC) associated with the token.", "pattern": "^[0-9]{4}$", "example": "0000" } }, "required": [ "tokenNumber", "expiryYear", "expiryMonth", "dcsc" ] } } }, "required": [ "paymentCredentials" ] }, "PaymentCredentialsCompleteRequest": { "type": "object", "description": "A request to provide the outcome of a payment authorization. The request payload is JWE-encrypted as seen in the model [EncryptedRequestResponse](#components-schemas-EncryptedRequestResponse)", "properties": { "authIdentifier": { "type": "string", "description": "A unique identifier for the authorization request." }, "authStatus": { "type": "string", "enum": [ "APPROVED", "DECLINED", "RETURNED" ], "description": "The authorization outcome for the request." }, "orderContext": { "description": "The order details associated with the authorization. Required when input is tokenNumber.", "allOf": [ { "$ref": "#/components/schemas/PaymentCredentialsOrderContext" } ] }, "tokenNumber": { "type": "string", "description": "The tokenized account number used for the transaction.", "pattern": "^[0-9]{15}$" } }, "required": [ "authIdentifier", "authStatus", "tokenNumber" ] }, "NotificationsRequest": { "type": "object", "description": "The notification payload containing updates related to enrollment, intent, or payment credentials. The payload will be JWE-encrypted as seen in the model [EncryptedRequestResponse](#components-schemas-EncryptedRequestResponse)", "oneOf": [ { "title": "The notification payload containing updates related to enrollment. The payload will be JWE-encrypted on the wire.", "properties": { "notificationType": { "type": "string", "enum": [ "ENROLLMENT_UPDATE" ], "description": "The type of notification." }, "enrollmentStatus": { "type": "string", "enum": [ "ACTIVE", "SUSPEND", "CANCEL", "RESUME" ], "description": "The updated status of the enrollment." }, "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account." }, "stepUpSessionId": { "type": "string", "description": "The identifier for the step-up session associated with the enrollment." } }, "required": [ "enrollmentId", "enrollmentStatus", "notificationType" ] }, { "title": "The notification payload containing updates related to intent. The payload will be JWE-encrypted on the wire.", "properties": { "notificationType": { "type": "string", "enum": [ "INTENT_UPDATE" ], "description": "The type of notification." }, "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account." }, "intentStatus": { "type": "string", "enum": [ "ACTIVE", "CANCEL" ], "description": "The current status of the intent." }, "proofOfIntent": { "type": "string", "description": "A signed JSON web token associated with the intent." }, "stepUpSessionId": { "type": "string", "description": "The identifier for the step-up session associated with the intent." } }, "required": [ "notificationType", "enrollmentId", "intentStatus", "proofOfIntent" ] }, { "title": "The notification payload containing updates related to payment credentials. The payload will be JWE-encrypted on the wire.", "properties": { "notificationType": { "type": "string", "enum": [ "PAYMENT_CREDENTIAL_UPDATE" ], "description": "The type of notification." }, "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account." }, "paymentCredentialStatus": { "type": "string", "enum": [ "ACTIVE", "CANCEL" ], "description": "The current status of the payment credential." }, "stepUpSessionId": { "type": "string", "description": "The identifier for the step-up session associated with the request." } }, "required": [ "notificationType", "enrollmentId", "paymentCredentialStatus" ] } ] }, "UnenrollmentsRequest": { "type": "object", "description": "Request to remove an enrolled account. The request payload will be JWE-encrypted as seen in the model [EncryptedRequestResponse](#components-schemas-EncryptedRequestResponse)", "properties": { "enrollmentId": { "type": "string", "description": "A unique identifier for the enrolled account." }, "initiator": { "type": "string", "enum": [ "AGENT", "USER" ], "description": "Indicates the source that triggered the unenrollment action, distinguishing between user-initiated and agent-initiated requests." }, "reasonCode": { "type": "string", "description": "A predefined code representing the reason for unenrollment, used to support auditability, compliance, and operational decisioning.", "enum": [ "USER_REQUESTED", "PRIVACY_CONCERNS", "SWITCHED_ACCOUNT", "DATA_SHARING_DECLINED", "FAILED_AUTHENTICATION", "ACCOUNT_COMPROMISED", "SUSPICIOUS_ACTIVITY", "RISK_POLICY_VIOLATION", "TERMS_VIOLATION" ] } }, "required": [ "enrollmentId", "initiator", "reasonCode" ] }, "StepUpVerification": { "type": "object", "description": "The step-up verification details for completing authentication. Required when submitting a step-up challenge response. This object will depend on the challenge type returned in the initial API response when the step-up flow is initiated.", "properties": { "stepUpSessionId": { "type": "string", "description": "The identifier for the step-up session associated with the request." } }, "required": [ "stepUpSessionId" ], "oneOf": [ { "type": "object", "title": "The response object for SafeKey® authentication challenge", "description": "This object will depend on the challenge type returned in the initial API response when the step-up flow is initiated.", "properties": { "safeKeyAuthenticationResponse": { "type": "object", "description": "The result of SafeKey® authentication.", "properties": { "riskToken": { "type": "string", "description": "The encrypted risk token used for SafeKey® authentication." } }, "required": [ "riskToken" ] } }, "required": [ "safeKeyAuthenticationResponse" ] }, { "type": "object", "title": "The response object for issuer surface authentication challenge", "properties": { "issuerSurfaceAuthenticationResponse": { "type": "object", "description": "The result of issuer surface authentication for step-up integration.", "properties": { "authenticationToken": { "type": "string", "description": "The encrypted authentication token used for authentication using ISSUER_SURFACE." } }, "required": [ "authenticationToken" ] } }, "required": [ "issuerSurfaceAuthenticationResponse" ] }, { "type": "object", "title": "The response object for SECURE_PUSH authentication challenge", "properties": { "securePushAuthenticationResponse": { "type": "object", "description": "Confirmation when authentication is complete using SECURE_PUSH", "properties": { "authenticationToken": { "type": "string", "description": "The encrypted authentication token used for authentication using SECURE_PUSH" } }, "required": [ "authenticationToken" ] } }, "required": [ "securePushAuthenticationResponse" ] }, { "type": "object", "title": "The response object for SMS_OTP or EMAIL_OTP authentication challenge", "properties": { "validateAuthenticationCode": { "type": "object", "description": "The one-time passcode entered by the user for step-up verification using SMS_OTP or EMAIL_OTP.", "properties": { "value": { "type": "string", "description": "The one-time passcode entered by the user" } }, "required": [ "value" ] } }, "required": [ "validateAuthenticationCode" ] } ] }, "availableChallenges": { "type": "array", "description": "The authentication challenges available for completing step-up verification.", "items": { "anyOf": [ { "properties": { "type": { "type": "string", "enum": [ "ISSUER_SURFACE" ], "description": "The authentication method." }, "issuerSurface": { "type": "object", "description": "Issuer surface authentication details.", "properties": { "url": { "type": "string", "description": "URL for initiating issuer surface authentication." }, "authenticationToken": { "type": "string", "description": "The encrypted authentication token associated with the authentication request." } }, "required": [ "url", "authenticationToken" ] } }, "required": [ "issuerSurface", "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "SECURE_PUSH" ], "description": "The authentication method." }, "securePushAuthentication": { "type": "object", "description": "Secure push authentication details.", "properties": { "authenticationToken": { "type": "string", "description": "The encrypted authentication token associated with the authentication request." } }, "required": [ "url", "riskToken" ] } }, "required": [ "securePushAuthentication", "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "SAFEKEY" ], "description": "The authentication method." }, "safeKeyAuthentication": { "type": "object", "description": "SafeKey® authentication details.", "properties": { "riskToken": { "type": "string", "description": "The encrypted risk token associated with the authentication request." }, "messageCategory": { "type": "string", "enum": [ "01", "02" ], "description": "SafeKey® message category." }, "threeDSRequestorAuthenticationInd": { "type": "string", "enum": [ "81", "82" ], "description": "SafeKey® authentication indicator." } }, "required": [ "riskToken", "messageCategory", "threeDSRequestorAuthenticationInd" ] } }, "required": [ "safeKeyAuthentication", "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "SMS_OTP" ], "description": "The authentication method." }, "channelId": { "type": "string", "description": "A unique identifier of the phone channel to deliver OTP." }, "value": { "type": "string", "description": "The masked phone number where the OTP will be delivered." } }, "required": [ "channelId", "value", "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "EMAIL_OTP" ], "description": "The authentication method." }, "channelId": { "type": "string", "description": "A unique identifier of the email channel to deliver OTP." }, "value": { "type": "string", "description": "The masked email address where the OTP will be delivered." } }, "required": [ "channelId", "value", "type" ] } ] } }, "AccountMetadata": { "type": "object", "description": "The metadata associated with the enrolled account.", "properties": { "displayPanNumber": { "type": "string", "description": "Last four digits of the Primary Account Number (PAN)." }, "productName": { "type": "string", "description": "The product name associated with the account." }, "cardArt": { "allOf": [ { "$ref": "#/components/schemas/CardArt" } ], "description": "A visual representation of the Card associated with the account." }, "paymentAccountReference": { "type": "string", "maxLength": 29, "description": "A non-financial reference assigned to each unique Primary Account Number (PAN) and used to link a Payment Account represented by that PAN to affiliated Payment Tokens. The value is a 29-character uppercase alphanumeric string." } }, "required": [ "displayPanNumber", "productName", "cardArt", "paymentAccountReference" ] }, "CardArt": { "type": "object", "properties": { "cardArtUrl": { "type": "string", "description": "The URL for the card artwork." }, "foregroundColor": { "type": "string", "description": "The foreground color associated with the card artwork." } }, "required": [ "cardArtUrl", "foregroundColor" ] }, "Issuer": { "type": "object", "description": "Issuer details associated with the account.", "properties": { "issuerLogoUrl": { "type": "string", "description": "The URL for the Issuer logo." }, "issuerName": { "type": "string", "description": "The name of the Issuer." }, "issuerTermsUrl": { "type": "string", "description": "The URL for the Issuer terms and conditions." }, "issuerContactNumber": { "type": "string", "description": "The Customer's support contact number for the Issuer." } }, "required": [ "issuerLogoUrl", "issuerName", "issuerContactNumber" ] }, "ShipmentDetails": { "type": "object", "description": "Shipping and delivery information associated with the purchase. For digital goods, deliveryEmail is required. For physical goods, shippingAddress with postalCode is required.", "properties": { "shippingEmail": { "type": "string", "description": "The email address associated with the order." }, "shippingMethod": { "type": "string", "enum": [ "SAME_DAY", "OVERNIGHT", "EXPEDITED", "STANDARD" ], "description": "The shipping method selected for the order." }, "shippingPhoneNumber": { "type": "string", "description": "The contact phone number associated with the order." }, "shippingAddress": { "allOf": [ { "$ref": "#/components/schemas/ShippingAddress" } ], "description": "The shipping address for physical goods. Required when the item is classified as a physical good.", "required": [ "postalCode" ] }, "deliveryEmail": { "type": "string", "description": "The email address for delivery notifications and confirmations. Required when the item is classified as a digital good." } } }, "PaymentCredentialsShipmentDetails": { "type": "object", "description": "The shipping and delivery details associated with the purchase. Use deliveryEmail for digital goods and shippingAddress with postalCode for physical goods.", "properties": { "shippingEmail": { "type": "string", "description": "The email address associated with the order." }, "shippingMethod": { "type": "string", "enum": [ "SAME_DAY", "OVERNIGHT", "EXPEDITED", "STANDARD" ], "description": "The shipping method selected for the order." }, "shippingPhoneNumber": { "type": "string", "description": "The contact phone number associated with the order." }, "shippingAddress": { "allOf": [ { "$ref": "#/components/schemas/PaymentCredentialsAddress" } ], "description": "The shipping address for physical goods. Required when the item is classified as a physical good." }, "deliveryEmail": { "type": "string", "description": "The email address for delivery notifications and confirmations. Required when the item is classified as a digital good." } } }, "PaymentCredentialsOrderContext": { "type": "object", "description": "Order details used to generate payment credentials, including merchants and associated items.", "properties": { "merchants": { "$ref": "#/components/schemas/PaymentCredentialsMerchants" }, "totalAmount": { "type": "string", "description": "The total amount for the order across all merchants." }, "currency": { "type": "string", "description": "The currency code for the order amount, in ISO 4217 format." }, "orderId": { "type": "string", "description": "A unique identifier for the order." }, "allowPartialOrder": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether the agent is allowed to proceed if some items are unavailable." }, "type": { "type": "string", "enum": [ "INTENT", "CART" ], "description": "Indicates the stage of the order. INTENT represents a preliminary selection or preference. CART represents a finalized set of items ready for purchase." } }, "anyOf": [ { "properties": { "items": { "$ref": "#/components/schemas/Items" } } }, { "properties": { "airlineItems": { "$ref": "#/components/schemas/Airline" } } } ], "required": [ "totalAmount", "currency" ] }, "OrderContext": { "type": "object", "description": "Order-level details including merchants, items, and purchase context.", "properties": { "merchants": { "allOf": [ { "$ref": "#/components/schemas/Merchants" } ], "description": "Merchants associated with the order." }, "totalAmount": { "type": "string", "description": "The total amount for the order across all merchants." }, "currency": { "type": "string", "description": "The currency code for the order amount, in ISO 4217 format." }, "orderId": { "type": "string", "description": "A unique identifier of the order" }, "allowPartialOrder": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether the agent is allowed to proceed if some items are unavailable." }, "type": { "type": "string", "enum": [ "INTENT", "CART" ], "description": "Indicates the stage of the order. INTENT represents a preliminary selection or preference. CART represents a finalized set of items ready for purchase." } }, "anyOf": [ { "properties": { "items": { "$ref": "#/components/schemas/Items" } } }, { "properties": { "airlineItems": { "$ref": "#/components/schemas/Airline" } } } ] }, "PurchaseCriteria": { "type": "array", "description": "Criteria for the purchase", "items": { "properties": { "type": { "type": "string", "description": "The type of criteria applied to the item.", "enum": [ "PRICE", "DATE" ] }, "fromDate": { "type": "string", "description": "Start of the date range for fulfillment. Required when the type is DATE.", "format": "date-time" }, "toDate": { "type": "string", "description": "End of the date range for fulfillment. Required when the type is DATE.", "format": "date-time" }, "pricePreference": { "type": "string", "description": "Price preference for the item. Required when the type is PRICE.", "enum": [ "MINIMUM_PRICE", "BETWEEN_RANGE", "MAXIMUM_PRICE" ] }, "maxAmount": { "type": "string", "description": "Maximum price for the item. Required when the pricePreference is BETWEEN_RANGE." }, "minAmount": { "type": "string", "description": "Minimum price for the item. Required when the pricePreference is BETWEEN_RANGE." }, "currency": { "type": "string", "description": "The currency code for the price values, in ISO 4217 format." }, "isShippingIncluded": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether shipping cost is included in the price." }, "dependentItems": { "allOf": [ { "$ref": "#/components/schemas/DependentItems" } ], "description": "Dependencies that must be satisfied before the item can be purchased." } } } }, "DependentItems": { "type": "array", "description": "Items that must satisfy defined conditions before this item can be purchased.", "items": { "properties": { "dependentItemId": { "type": "string", "description": "The identifier of the item that this item depends on." } } } }, "PaymentCredentialsMerchants": { "type": "array", "description": "Merchants associated with the order and their related details.", "items": { "description": "The details of an individual Merchant in the order.", "properties": { "name": { "type": "string", "description": "Display name of the Merchant." }, "merchantId": { "type": "integer", "description": "The identifier of the Merchant." }, "seNumber": { "type": "string", "description": "Service establishment number associated with the Merchant." }, "sellerId": { "type": "string", "description": "The identifier of the seller." }, "categoryName": { "type": "string", "description": "Category associated with the Merchant." }, "policies": { "type": "object", "description": "Seller-specific policies associated with the Merchant.", "properties": { "termsOfService": { "type": "string", "description": "The URL for the seller terms of service." }, "returnPolicy": { "type": "string", "description": "The URL for the seller return policy." }, "returnWindow": { "type": "string", "description": "The number of days allowed for returns." } } }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/Metadata" } ], "description": "A generic merchant metadata container allowing arbitrary string key-value pairs. Keys must be strings and values must be strings." } }, "oneOf": [ { "title": "Merchant URL", "properties": { "url": { "type": "string", "description": "The Merchant's URL." } }, "required": [ "url" ] }, { "title": "Merchant App", "properties": { "appName": { "type": "string", "description": "The app name of the Merchant." } }, "required": [ "appName" ] } ] } }, "Merchants": { "type": "array", "description": "Details of the Merchants and associated items in the cart.", "items": { "properties": { "name": { "type": "string", "description": "The Merchant's display/registered name." }, "merchantId": { "type": "integer", "description": "The Merchant's identifier." }, "url": { "type": "string", "description": "The Merchant's URL." }, "appName": { "type": "string", "description": "The app name of the Merchant." }, "seNumber": { "type": "string", "description": "Service establishment number associated with the Merchant." }, "categoryName": { "type": "string", "description": "The Merchant's category name." }, "metadata": { "allOf": [ { "description": "A generic merchant metadata container allowing arbitrary string key-value pairs. Keys must be strings and values must be strings." }, { "$ref": "#/components/schemas/Metadata" } ] } } } }, "Items": { "type": "array", "description": "Line items associated with the order. Typically used for merchandise, retail, or electronics purchases.", "items": { "type": "object", "description": "The details of an individual item in the order.", "properties": { "itemId": { "type": "string", "description": "A unique identifier for the item within the order." }, "merchantId": { "type": "integer", "description": "The identifier of the Merchant associated with the item." }, "name": { "type": "string", "description": "The name of the item." }, "unitAmount": { "type": "string", "description": "The unit price of the item." }, "currency": { "type": "string", "description": "The currency code for the item price, in ISO 4217 format. Required when unitAmount is provided." }, "quantity": { "type": "integer", "description": "The quantity of the item." }, "condition": { "type": "string", "description": "The condition of the item, such as new, refurbished, or used." }, "category": { "type": "string", "description": "The category associated with the item." }, "brand": { "type": "string", "description": "The brand associated with the item." }, "imageLink": { "type": "string", "description": "The main product image URL." }, "isRefundable": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether the item is refundable." }, "isGiftCard": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether the item is a gift card." }, "isRecurBill": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether the item represents a recurring purchase." }, "purchaseCriteria": { "allOf": [ { "$ref": "#/components/schemas/PurchaseCriteria" } ], "description": "Constraints or preferences associated with the item." }, "metadata": { "allOf": [ { "description": "A generic item metadata container allowing arbitrary string key-value pairs. Keys must be strings and values must be strings." }, { "$ref": "#/components/schemas/Metadata" } ] } }, "required": [ "itemId", "name", "isGiftCard" ] } }, "Airline": { "type": "array", "description": "Line items associated with airline bookings.", "items": { "type": "object", "description": "The details of an individual airline booking.", "properties": { "itemId": { "type": "string", "description": "A unique identifier for the item within the order." }, "passengerName": { "type": "string", "description": "The name of the passenger associated with the booking." }, "origin": { "type": "string", "description": "The origin airport, represented as a three-letter IATA code." }, "destination": { "type": "string", "description": "The destination airport, represented as a three-letter IATA code." }, "carrier": { "type": "string", "description": "The airline carrier for the booking." }, "isInsuranceOpted": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether travel insurance has been selected." }, "isRefundable": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether the booking is refundable." }, "unitAmount": { "type": "string", "description": "The price of the booking, per unit." }, "currency": { "type": "string", "description": "The currency code for the amount, in ISO 4217 format." }, "purchaseCriteria": { "allOf": [ { "$ref": "#/components/schemas/PurchaseCriteria" } ], "description": "Constraints or preferences associated with the booking." }, "metadata": { "allOf": [ { "description": "A generic airlineItem metadata container allowing arbitrary string key-value pairs. Keys must be strings and values must be strings." }, { "$ref": "#/components/schemas/Metadata" } ] } }, "required": [ "itemId", "passengerName" ] } }, "PromptDetails": { "type": "object", "description": "The natural language context associated with the intent.", "properties": { "promptSummary": { "type": "string", "description": "A summary of the purchase intent derived from user input." }, "nlpConfidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "example": 0.92, "description": "The confidence score associated with the interpreted intent. Values range from 0 to 1, where higher values indicate greater confidence in the prediction." } }, "required": [ "promptSummary" ] }, "SpendControl": { "type": "object", "description": "Constraints applied to the payment method.", "properties": { "maxAmount": { "type": "string", "description": "The maximum amount that can be charged using the payment method." }, "currency": { "type": "string", "description": "The currency code for the amount, in ISO 4217 format." }, "expirationTs": { "type": "string", "format": "date-time", "description": "The expiration timestamp for the payment method." } }, "required": [ "maxAmount", "currency" ] }, "Account": { "type": "object", "description": "The PAN details needed to enroll in agent-executed commerce.", "properties": { "type": { "type": "string", "enum": [ "CARD_NUMBER" ], "description": "Specifies the type of the account identifier provided in the request. Use CARD_NUMBER for a Primary Account Number (PAN)" }, "panNumber": { "type": "string", "description": "The American Express Credit Card Number. The PAN must be 15 digits as per the ISO/IEC 7812 standard.", "pattern": "^[0-9]{15}$" }, "expiryMonth": { "type": "string", "description": "The expiry month of the account in MM format. The month must be between 01 and 12.", "pattern": "^(0[1-9]|1[0-2])$" }, "expiryYear": { "type": "string", "description": "The expiry year of the account in YYYY format. The year must be the current year or later.", "pattern": "^[0-9]{4}$" }, "cid": { "type": "string", "description": "A four-digit Card Identification Number (CID) associated with the Primary Account Number (PAN). Required when the type is CARD_NUMBER and the risk.account.fpanSource is USER_INPUT, indicating that the Card details were manually entered by the user.", "pattern": "^[0-9]{4}$" } }, "required": [ "type", "panNumber", "expiryMonth", "expiryYear" ] }, "IntentsUser": { "type": "object", "description": "The Customer identity information associated with the request.", "properties": { "firstName": { "type": "string", "description": "The Customer's first name." }, "lastName": { "type": "string", "description": "The Customer's last name." }, "billingAddress": { "$ref": "#/components/schemas/IntentsAddress" }, "userEmailHash": { "type": "string", "description": "A hashed representation of the email address generated using the PBKDF2WithHmacSHA256 algorithm with 10 iterations." }, "userPhoneNumberHash": { "type": "string", "description": "A hashed representation of the phone number generated using the PBKDF2WithHmacSHA256 algorithm with 10 iterations." } }, "oneOf": [ { "title": "Email Address", "properties": { "email": { "type": "string", "description": "The Customer's email address in RFC 5322 format.", "format": "email" } } }, { "title": "Phone Number", "properties": { "phone": { "type": "string", "description": "The Customer's phone number in international format, starting with + followed by a string of digits between zero and nine with a minimum length of 11 digits." } } } ] }, "PaymentCredentialsUser": { "type": "object", "description": "The Customer's identity information associated with the request.", "properties": { "firstName": { "type": "string", "description": "The Customer's first name." }, "lastName": { "type": "string", "description": "The Customer's last name." }, "billingAddress": { "$ref": "#/components/schemas/PaymentCredentialsBillingAddress" }, "userEmailHash": { "type": "string", "description": "A hashed representation of the email address generated using the PBKDF2WithHmacSHA256 algorithm with 10 iterations." }, "userPhoneNumberHash": { "type": "string", "description": "A hashed representation of the phone number generated using the PBKDF2WithHmacSHA256 algorithm with 10 iterations." }, "email": { "type": "string", "description": "The Customer's email address in RFC 5322 format.", "format": "email" }, "phone": { "type": "string", "description": "The Customer's phone number in international format, starting with + followed by a string of digits between zero and nine with a minimum length of 11 digits" } } }, "User": { "type": "object", "description": "The Customer's identity information associated with the enrollment.", "properties": { "accountId": { "type": "string", "description": "A stable identifier for the Customer within the partner system (other than email ID or phone number)." }, "firstName": { "type": "string", "description": "The Customer's first name." }, "lastName": { "type": "string", "description": "The Customer's last name." }, "billingAddress": { "$ref": "#/components/schemas/Address" }, "userEmailHash": { "type": "string", "description": "A hashed representation of the Customer's email address. Generated using PBKDF2WithHmacSHA256 with 10 iterations." }, "userPhoneNumberHash": { "type": "string", "description": "A hashed representation of the Customer's phone number. Generated using PBKDF2WithHmacSHA256 with 10 iterations." } }, "oneOf": [ { "title": "Email Address", "properties": { "email": { "type": "string", "description": "The Customer's email address in RFC 5322 format.", "format": "email" } }, "required": [ "email" ] }, { "title": "Phone Number", "properties": { "phone": { "type": "string", "description": "The Customer's phone number in international format, starting with '+' followed by digits." } }, "required": [ "phone" ] } ], "required": [ "accountId", "firstName", "lastName", "billingAddress" ] }, "ShippingAddress": { "type": "object", "description": "Conditional. Required when the purchased item is classified as a physical good. Shipping address associated with the item(s) being purchased.", "properties": { "addressLine1": { "type": "string", "description": "The first line of the address." }, "addressLine2": { "type": "string", "description": "The second line of the address." }, "city": { "type": "string", "description": "The city of the address." }, "state": { "type": "string", "description": "The state of the address." }, "country": { "type": "string", "description": "The country of the address in ISO 3166-1 alpha-2 format." }, "postalCode": { "type": "string", "description": "The Postal Code of the address." } } }, "IntentsAddress": { "type": "object", "description": "The enrolling user's billing address.", "properties": { "addressLine1": { "type": "string", "description": "The first line of the address." }, "addressLine2": { "type": "string", "description": "The second line of the address." }, "city": { "type": "string", "description": "The city of the address." }, "state": { "type": "string", "description": "The state of the address." }, "country": { "type": "string", "description": "The country of the address in ISO 3166-1 alpha-2 format." }, "postalCode": { "type": "string", "description": "The Postal Code of the address." } } }, "PaymentCredentialsBillingAddress": { "type": "object", "description": "The enrolling user's billing address", "properties": { "addressLine1": { "type": "string", "description": "The first line of the address." }, "addressLine2": { "type": "string", "description": "The second line of the address." }, "city": { "type": "string", "description": "The city of the address." }, "state": { "type": "string", "description": "The state of the address." }, "country": { "type": "string", "description": "The country of the address in ISO 3166-1 alpha-2 format." }, "postalCode": { "type": "string", "description": "The Postal Code of the address." } } }, "PaymentCredentialsAddress": { "type": "object", "description": "The shipping address associated with the purchase. Required when the item is classified as a physical good.", "properties": { "firstName": { "type": "string", "description": "The Customer's first name." }, "lastName": { "type": "string", "description": "The Customer's last name." }, "addressLine1": { "type": "string", "description": "The first line of the address." }, "addressLine2": { "type": "string", "description": "The second line of the address." }, "city": { "type": "string", "description": "The city associated with the address." }, "state": { "type": "string", "description": "The state or region associated with the address." }, "country": { "type": "string", "description": "The country code for the address, in ISO 3166-1 alpha-2 format." }, "postalCode": { "type": "string", "description": "The Postal Code associated with the address." } }, "required": [ "postalCode" ] }, "Address": { "type": "object", "description": "The billing address associated with the account being enrolled.", "properties": { "addressLine1": { "type": "string", "description": "The first line of the address." }, "addressLine2": { "type": "string", "description": "The second line of the address." }, "city": { "type": "string", "description": "The city of the address." }, "state": { "type": "string", "description": "The state of the address." }, "country": { "type": "string", "description": "Country of the address in ISO 3166-1 alpha-2 format." }, "postalCode": { "type": "string", "description": "The Postal Code of the address." } }, "required": [ "addressLine1", "addressLine2", "city", "state", "country", "postalCode" ] }, "Agent": { "type": "object", "description": "Information about the agent facilitating the commerce transaction.", "properties": { "llmVersion": { "type": "string", "description": "The version of the language model used by the agent." }, "llmPlatform": { "type": "string", "enum": [ "OPEN_AI" ], "description": "The platform hosting the language model used by the agent." }, "agentName": { "type": "string", "description": "The name of the agent or application initiating the request." } }, "required": [ "llmVersion", "llmPlatform", "agentName" ] }, "Metadata": { "type": "object", "properties": {}, "additionalProperties": { "type": "string" }, "example": { "ipReputation": "low_risk", "additionalProperty": "string" } }, "EnrollmentsRisk": { "description": "Risk signals related to enrollments. These signals are used to assess the risk of enrolling a card into agent-executed commerce. The risk assessment can be used by the Agent to determine whether to allow the enrollment, require additional verification, or block the enrollment altogether.", "type": "object", "properties": { "account": { "$ref": "#/components/schemas/AccountRisk" }, "device": { "allOf": [ { "$ref": "#/components/schemas/DeviceRisk" } ], "description": "Risk signals related to the device on which the account is being enrolled.", "required": [ "deviceId", "ipAddress" ] }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/Metadata" } ], "description": "A generic enrollmentRisk metadata container allowing arbitrary string key-value pairs. Keys must be strings and values must be strings." } }, "required": [ "account", "device" ] }, "IntentsRisk": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/IntentsAccountRisk" }, "device": { "$ref": "#/components/schemas/IntentsDeviceRisk" }, "order": { "$ref": "#/components/schemas/IntentsOrderRisk" }, "metadata": { "allOf": [ { "description": "A generic risk metadata container allowing arbitrary string key-value pairs. Keys must be strings and values must be strings." }, { "$ref": "#/components/schemas/Metadata" } ] } }, "required": [ "device", "order" ] }, "Risk": { "type": "object", "description": "Risk and device context associated with the request.", "properties": { "account": { "allOf": [ { "$ref": "#/components/schemas/PaymentCredentialsAccountRisk" } ] }, "device": { "allOf": [ { "$ref": "#/components/schemas/PaymentCredentialsDeviceRisk" } ] }, "order": { "allOf": [ { "$ref": "#/components/schemas/PaymentCredentialsOrderRisk" } ] }, "metadata": { "allOf": [ { "description": "A generic risk metadata container allowing arbitrary string key-value pairs. Keys must be strings and values must be strings." }, { "$ref": "#/components/schemas/Metadata" } ] } } }, "IntentsAccountRisk": { "type": "object", "description": "Account-level risk signals associated with the request.", "properties": { "panTenureOnFile": { "type": "number", "description": "The number of weeks since the User added the Card account details on file." }, "accountRiskScore": { "type": "string", "description": "A risk score provided by the Partner indicating the assessed risk level of the account, on a scale of 1-5 (1 = Very Low, 2 = Low, 3 = Medium, 4 = High, 5 = Very High)." }, "recentSecurityActivity": { "type": "string", "description": "Time elapsed (in days) since the most recent password or two-factor authentication change." }, "mostRecentAccountPaymentMethodChangeActivity": { "type": "number", "description": "The number of days since the User changed his recent payment method." }, "partnerStepUp": { "type": "string", "enum": [ "YES", "NO" ], "description": "A value to determine if the user has been stepped-up by the agent." }, "agentAccountLocale": { "type": "string", "description": "The locale identifier (e.g., `en-US`, `en-GB`) representing the region of the agent's financial account. Used to determine currency, payment rails, formatting, and compliance behavior." } } }, "PaymentCredentialsAccountRisk": { "type": "object", "description": "Account-level risk signals associated with the request.", "properties": { "panTenureOnFile": { "type": "number", "description": "The number of weeks since the card account was first stored on file with the Partner." }, "accountRiskScore": { "type": "string", "description": "A risk score provided by the Partner for the account, on a scale of 1-5 (1 = Very Low, 2 = Low, 3 = Medium, 4 = High, 5 = Very High)." }, "recentSecurityActivity": { "type": "string", "description": "The number of days since the most recent password or two-factor authentication change." }, "mostRecentAccountPaymentMethodChangeActivity": { "type": "number", "description": "The number of days since the most recent change to the account's payment method." }, "partnerStepUp": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether the user has already completed step-up authentication with the Partner." }, "agentAccountLocale": { "type": "string", "description": "The locale associated with the agent's account, used for regional formatting and compliance behavior." } } }, "AccountRisk": { "type": "object", "description": "Risk signals related to the account being enrolled.", "properties": { "actionChannel": { "type": "string", "enum": [ "WEB", "IOS", "ANDROID", "OTHER" ], "description": "The client platform from which the enrollment request originated. WEB indicates a browser-based flow, IOS and ANDROID indicate native mobile applications. This field is used for channel-specific processing and risk evaluation." }, "panTenureOnFile": { "type": "number", "description": "The number of weeks since the card account was first stored on file with the Partner. Represents the tenure of the account and may be used as a risk signal." }, "accountRiskScore": { "type": "string", "description": "A risk score provided by the Partner for the account. Values range from 1 (Very Low) to 5 (Very High)., on a scale of 1-5 (1 = Very Low, 2 = Low, 3 = Medium, 4 = High, 5 = Very High)." }, "distinctBillingLastNameCount": { "type": "string", "description": "The number of distinct billing last names associated with the account." }, "recentSecurityActivity": { "type": "string", "description": "The number of days since the most recent password or two-factor authentication change." }, "emailTenure": { "type": "number", "description": "The number of weeks since the email address was first associated with the account." }, "mostRecentAccountPaymentMethodChangeActivity": { "type": "number", "description": "The number of days since the most recent change to the account's payment method." }, "fpanSource": { "type": "string", "enum": [ "USERINPUT", "ONFILE", "OTHER" ], "description": "The source from which the Primary Account Number (FPAN) was obtained." }, "accountAndCardNameMatch": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether the account holder name matches the cardholder name." }, "agentAccountLocale": { "type": "string", "description": "The locale of the Agent's account, used for regional formatting and compliance behavior." } }, "required": [ "actionChannel", "fpanSource" ] }, "IntentsDeviceRisk": { "type": "object", "description": "Device-level risk signals associated with the request.", "properties": { "deviceId": { "type": "string", "description": "A unique identifier for device used; stays consistent between sessions." }, "deviceName": { "type": "string", "description": "Recognizable device name identifier for device used; stays consistent between sessions." }, "deviceType": { "type": "string", "enum": [ "Phone", "Tablet", "Watch", "Wearable", "Other" ], "description": "The type of the device used" }, "ipAddress": { "type": "string", "description": "The IP address of the device." }, "deviceRiskScore": { "type": "string", "description": "A risk score provided by the Partner indicating the assessed risk level of the device, on a scale of 1-5 (1 = Very Low, 2 = Low, 3 = Medium, 4 = High, 5 = Very High)." }, "deviceTenure": { "type": "number", "description": "The number of weeks since the User first used this device on this account" }, "tlsFingerprint": { "type": "string", "description": "The fingerprint of the device." }, "location": { "type": "object", "description": "The location of the device.", "properties": { "longitude": { "type": "string", "minLength": 3, "maxLength": 9, "description": "The longitude coordinates of the device.", "example": "-084.0606" }, "latitude": { "type": "string", "minLength": 3, "maxLength": 9, "description": "The latitude coordinates of the device.", "example": "+025.3191" } } } }, "required": [ "deviceId", "ipAddress" ] }, "PaymentCredentialsDeviceRisk": { "type": "object", "description": "Device-level risk signals associated with the request.", "properties": { "deviceId": { "type": "string", "description": "A stable identifier for the device associated with the account." }, "deviceName": { "type": "string", "description": "Recognizable name assigned to the device." }, "deviceType": { "type": "string", "enum": [ "Phone", "Tablet", "Watch", "Wearable", "Other" ], "description": "The category of the device used." }, "ipAddress": { "type": "string", "description": "The IP address observed for the device at the time of the request." }, "deviceRiskScore": { "type": "string", "description": "A risk score provided by the Partner for the device, on a scale of 1-5 (1 = Very Low, 2 = Low, 3 = Medium, 4 = High, 5 = Very High)." }, "deviceTenure": { "type": "number", "description": "The number of weeks since the device was first associated with the account." }, "tlsFingerprint": { "type": "string", "description": "The TLS fingerprint associated with the device connection." }, "location": { "type": "object", "description": "The geographic coordinates of the device at the time of the request.", "properties": { "longitude": { "type": "string", "minLength": 3, "maxLength": 9, "description": "The longitude coordinates of the device.", "example": "-084.0606" }, "latitude": { "type": "string", "minLength": 3, "maxLength": 9, "description": "The latitude coordinates of the device.", "example": "+025.3191" } } } } }, "DeviceRisk": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "A stable identifier for the device associated with the account." }, "devicePlatform": { "type": "string", "enum": [ "IOS", "ANDROID", "OTHER" ], "description": "The operating platform of the device." }, "ipAddress": { "type": "string", "description": "The IP address observed for the device at the time of the request." }, "deviceRiskScore": { "type": "string", "description": "A risk score provided by the Partner for the device, on a scale of 1-5 (1 = Very Low, 2 = Low, 3 = Medium, 4 = High, 5 = Very High)." }, "deviceTenure": { "type": "number", "description": "The number of weeks since the device was first associated with the account." }, "browserUserAgent": { "type": "string", "description": "The user agent string reported by the device or browser." }, "deviceCountry": { "type": "string", "description": "The country associated with the device, in ISO 3166-1 alpha-2 format." }, "tlsFingerprint": { "type": "string", "description": "The TLS fingerprint associated with the device connection." }, "location": { "type": "object", "description": "The geographic coordinates of the device at the time of the request.", "properties": { "longitude": { "type": "string", "minLength": 3, "maxLength": 9, "description": "The longitude coordinates of the device.", "example": "-084.0606" }, "latitude": { "type": "string", "minLength": 3, "maxLength": 9, "description": "The latitude coordinates of the device.", "example": "+025.3191" } } } } }, "IntentsOrderRisk": { "type": "object", "description": "Order-level risk signals associated with the request.", "properties": { "includesGiftCard": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether the purchase includes at least one gift card item." } }, "required": [ "includesGiftCard" ] }, "PaymentCredentialsOrderRisk": { "type": "object", "description": "Order-level risk signals associated with the request.", "properties": { "includesGiftCard": { "type": "string", "enum": [ "YES", "NO" ], "description": "Indicates whether the purchase includes at least one gift card item." } } }, "TermsAndConditions": { "type": "object", "description": "Details of the terms and conditions accepted by the Customer.", "properties": { "version": { "type": "string", "description": "The version identifier of the terms and conditions accepted." }, "acceptanceTs": { "type": "string", "description": "The timestamp indicating when the terms and conditions were accepted, in ISO 8601 format.", "format": "date-time" } } }, "ErrorSystemDownResponse": { "type": "object", "description": "An error response returned when a system failure occurs.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "20001" ] }, "description": { "type": "string", "enum": [ "Internal server error" ] }, "type": { "type": "string", "enum": [ "SYSTEM_EXCEPTION" ] } }, "required": [ "code", "description", "type" ] } }, "required": [ "error" ] }, "SuccessResponseWithNoContent": { "description": "Success response returned without response payload." }, "ErrorUnauthorizedResponse": { "description": "An error response returned when authentication fails." }, "ErrorResourceNotFoundResponse": { "description": "An error response returned when the requested resource is not found." }, "ErrorBusinessExceptionResponse": { "type": "object", "description": "An error response returned when a business rule validation fails.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "An error code returned when a business rule validation fails." }, "description": { "type": "string", "description": "An error description returned when a business rule validation fails." }, "type": { "type": "string", "enum": [ "BUSINESS_EXCEPTION" ] } }, "required": [ "code", "description", "type" ] } }, "required": [ "error" ] }, "ErrorInvalidFieldsResponse": { "type": "object", "description": "An error response that is returned when request validation fails.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "An error code that is returned when request validation fails." }, "description": { "type": "string", "description": "An error description that is returned when request validation fails." }, "type": { "type": "string", "enum": [ "USER_EXCEPTION" ] }, "param": { "type": "string", "description": "The parameter that caused the error, if applicable" } }, "required": [ "code", "description", "type" ] } }, "required": [ "error" ] } } } }