swagger: '2.0' info: description: All CyberSource API specs merged together. These are available at https://developer.cybersource.com/api/reference/api-reference.html version: 0.0.1 title: CyberSource Merged Spec bankAccountValidation Instructions API host: apitest.cybersource.com basePath: / schemes: - https consumes: - application/json;charset=utf-8 produces: - application/hal+json;charset=utf-8 tags: - name: Instructions description: Purchase intent lifecycle management for agentic payments. Use these APIs to create, update, and cancel purchase intents (instructions) that define what a consumer wants to buy, including mandates, order details, merchant information, and shipping. An instruction must exist before payment credentials can be retrieved. paths: /acp/v1/instructions: post: tags: - Instructions summary: Initiate a purchase intent description: Create a new purchase intent (instruction) for an agentic transaction. The agent calls this endpoint after a card has been enrolled to define what the consumer wants to buy. The request includes payment instrument references, device and assurance data, mandates (spending limits, merchant preferences, and product descriptions), and optional buyer information. Return an instructionId (HTTP 200) if the intent is created immediately, or PENDING (HTTP 202) with pendingEvents if cardholder authentication is required. The instructionId returned is used in all subsequent operations - update, cancel, retrieve credentials, and confirm transaction. operationId: initiatePurchaseIntent x-devcenter-metaData: categoryTag: Intelligent_Commerce_Connect developerGuides: https://developer.cybersource.com/docs/cybs/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-purchase-initiate-intro.html mleForRequest: mandatory mleForResponse: mandatory disableProcessorDropDown: true disableDefaultMerchantCreds: false authorizationType: - Json Web Token overrideMerchantCredential: agentic_mid_091225001 parameters: - in: body name: agenticCreatePurchaseIntentRequest required: true schema: required: - assuranceData - clientCorrelationId - deviceInformation - mandates - paymentInformation type: object properties: clientCorrelationId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Client Correlation Id used during the tokenization or during FIDO assertion. paymentInformation: required: - instrumentIdentifier type: object description: Payment Information data. References the tokenized payment card to use for this transaction. At least one of customer, paymentInstrument, or instrumentIdentifier must be provided. The instrumentIdentifier is the most commonly used reference. If you have a TMS instrument identifier, provide it in instrumentIdentifier.id. properties: customer: type: object description: Customer data. properties: id: type: string description: Unique identifier for the Customer token used in the transaction. minLength: 1 maxLength: 32 paymentInstrument: type: object description: Payment Instrument data. properties: id: type: string description: Unique identifier for the Payment Instrument token used in the transaction. minLength: 1 maxLength: 32 instrumentIdentifier: required: - id type: object description: Instrument Identifier data. properties: id: type: string description: Unique identifier for the Instrument Identifier token used in the transaction. minLength: 12 maxLength: 32 deviceInformation: type: object description: Device and Application instance data. Identifies the device and application from which the consumer is making the payment request. required: - applicationName - deviceData - ipAddress - fingerprintSessionId properties: userAgent: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 2048 description: "Base64 Encoded userAgent string of the connecting client application, with no padding. \nUser agent string of the connecting client application. \nConditionality: \n- Required for browsers\n- Optional for non-browsers\n" applicationName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Name of the connecting client application. fingerprintSessionId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Device Fingerprinting Session identifier. country: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 2 maxLength: 2 format: ISO 3166-1-alpha2 description: ISO 3166-1 alpha-2 country code. The country where the Consumer is accessing the service from. deviceData: type: object description: Device data. required: - type - brand properties: type: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: "Type of device being used. \nExample values are: \n- Mobile Phone\n- Tablet\n- Tablet\n- Laptop\n- Personal Assistant\n- Connected Auto\n- Home Appliance\n- Wearable\n- Stationary Computer\n- E-Reader\n- Handheld Gaming Devices\n- Other\n" manufacturer: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Manufacturer of the device. brand: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Brand name of the device. model: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Specific model of the device. ipAddress: type: string pattern: ^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(?:[^0-9]*(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))*$ minLength: 0 maxLength: 255 description: IP address of the consumer's device. clientDeviceId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Unique identifier of the consumer's device. assuranceData: type: array description: Assurance data. items: required: - verificationMethod - verificationResults - verificationTimestamp type: object description: Assurance data. Contains identity verification details that prove the consumer or device has been authenticated before the payment operation. properties: verificationType: type: string description: "Optional. Type of the verification data. \nPossible values:\n - `CARDHOLDER` (Default)\n - `DEVICE`\n" verificationEntity: type: string description: "Optional. Entity performing the verification. \nPossible value: \n - `10` - VISA (Default)\n" verificationEvents: type: array items: type: string description: "Optional. Event where the verification occurred. \nPossible values: \n - `01` - Payment transaction\n - `02` - Add card/Card enrollment\n - `03` - Profile access\n - `04` - Account verification\n" verificationMethod: type: string description: "Required. Method of the verification. \nPossible values: \n - `02` - App-based authentication\n - `04` - One-time passcode\n - `21` - Visa Token Service step-up: Device binding\n - `22` - Visa Token Service step-up: Cardholder verification\n - `23` - FIDO2\n" verificationResults: type: string description: "Required. Result of the verification. \nPossible values: \n - `01` - Verified\n - `02` - Not Verified\n - `03` - Not performed\n - `04` - Not required\n - `21` - Not allowed\n" verificationTimestamp: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: Required. Date and time the verification occurred. UTC time in Unix epoch format. authenticationContext: type: object description: Authentication Context data. Describes the authentication action performed. properties: action: type: string description: Authentication Context action. authenticatedIdentities: required: - id type: object description: Authenticated Identities data. Contains the identity assertion from the authentication provider. properties: data: type: string description: Data related to the authenticated identity. provider: type: string description: Provider of the authenticated identity. id: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 50 description: "This is a distinctive and non-transparent identifier provided by VISA for correlation purposes in the previous, related API. \nField Mapping when authenticationMethodType is 'FIDO2': \n - On Success: FidoResponse.identifier\n - On Error: AuthContext.identifier\n" additionalData: type: string description: Additional data related to assurance. mandates: type: array description: Mandate data. items: required: - declineThreshold - description - effectiveUntilTime - mandateId type: object description: Mandate data. Defines the consumer's spending authorization for a purchase intent, including merchant preferences, amount limits, and product details. properties: mandateId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: "Unique identifier with in the context of a purchase-intent for the mandate. \nAssigned by Partner. Id shall not be reused when a mandate is updated/deleted.\n" preferredMerchantName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: User merchant preference. example: Best Buy merchantCategory: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Merchant category Description. merchantCategoryCode: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Merchant category Code. Once it is checked, it has to be valid merchant category code. Ex:" 5311" declineThreshold: type: object description: Decline Threshold data. Defines the maximum transaction amount the consumer is willing to authorize under this mandate. properties: amount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: Transaction Decline Threshold amount. currencyCode: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 3 maxLength: 3 description: ISO 4217 currency code. Currency in which the Transaction Decline Threshold amount is expressed. recurringPaymentInformation: type: object description: 'Frequency of the transaction. Specifies how often the transaction occurs. If the mandate contains a recurring instruction, a recurring frequency must be provided and the request.isRecurring flag should be set to true. ' properties: occurrence: type: string description: "Frequency of the transaction. \nPossible values: \n - `WEEKLY`\n - `MONTHLY`\n - `YEARLY`\n" effectiveUntilTime: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 12 description: UTC time in Unix epoch format. quantity: type: string minLength: 0 maxLength: 10 description: Quantity of the product. example: '10' description: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Description of the product. example: 50 Blue Balloons buyerInformation: type: object description: Buyer Information data. Contains consumer identification and preference details. properties: merchantCustomerId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Reference identifier of the Consumer. personalIdentification: type: array items: type: object properties: type: type: string description: The type of the identification id: type: string description: The value of the identification type issueBy: type: string description: 'The government agency that issued the driver''s license or passport. If `**type** = DRIVER_LICENSE`, this is the State or province where the customer''s driver''s license was issued. If `**type** = PASSPORT`, this is the Issuing country for the cardholder''s passport. ' language: type: string description: (Required) Consumer-provided language choice. ISO 639-1 Code isRecurring: type: boolean description: Indicates whether the transaction is recurring. Default value is false. consumerPrompt: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Recap - A summary or condensed version of user prompts that leads to the purchase. example: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 paymentInformation: customer: id: '' paymentInstrument: id: '' instrumentIdentifier: id: 458CC7D865E5024FE063AF598E0AA950 deviceInformation: userAgent: SampleUserAgent applicationName: 'My Magic App ' fingerprintSessionId: e48ac10b-58cc-4372-a567-0e02b2c3d489 country: US deviceData: type: Mobile manufacturer: Apple brand: Apple model: iPhone 16 Pro Max ipAddress: 192.168.0.100 clientDeviceId: c48ac10b-58cc-4372-a567-0e02b2c3d489 assuranceData: - verificationType: DEVICE verificationEntity: '10' verificationEvents: [] verificationMethod: '02' verificationResults: '01' verificationTimestamp: '1735690745' authenticationContext: action: AUTHENTICATE authenticatedIdentities: data: ezAwMX06AAM1NkHcRqXxoy3kt-vNTLdJ7Zg8PVKSr_7bwd1EfMs4MWlmLeFGIhSONwer8hF1yWPs7b7-g1lYrOeNwUuCg9dsCrnKI0-A9BvrwMemw6K05reS2kUVkfu7KbwtLSzcF9BLUcGsrbtE-alrZ4MzRCGSMvJP6PVo-H_dKowL5DfNvt9ZElB9cWpaPkHo8Cvu4WvLaz42XSFK2fBfuKpCiCTIokEEuqjZrSANKeJGFzp3uqzDGn-X-_a8Gq0DcA-d7-p_9nyi5VMRv9TLjzVh5BFXfLJ_3Jz8N2CwpphgZXd9kfuQO5vhqOKKqnyXP6-qEVb1JM48-YNvOKhIDGKkdpYEv6UxHaOUVCfw6H5mnh5Cry_YU62-EWVvwqdc6YKCMWr6QOPMMxo0-SFG0zK3SVNnY5uE7tKiuP-J2n2i_8Wlj1-qFgjMlY1qaRe8LWLvKsQMu-CKov0BGiqtH681rTjnZijj75xTYJ1xyhJv7uYf8r2O2KO9lHD-JHZYBxSY5XCgS0IYW7y8h52ehO9lShwJZ9nVVrEvaK0mek49jFXXAdjgOHHmdbnLh7PJUsTU4RepHB-SaRBS1iclx4WaXcVzjsU6AtET3NCwSysEMvEKHkuHgEOcAHxSiztIsPA_lScSLajFPxjJIGsVONnX9612hT8HC2XvTXcIciEaBqdRMwSeoibsUznduV4QoDRXJQceRUa3oAbyv7c3EzYGjnKPbsJQb2SL5GOZISmTAg8luE6IQpfeFYMjCO72I68S8lmFrTgKqdcOmwGzzTuZTSe_DhQU7xqhAbkL19_wShGsWBktOhOX75V8mpz3EqM15TBBcuHyUDeEmSd7aTLrB2E84rFD7PebluV9GEoUL2I1LMV58HXRhtFpnFcm2NWy6sGnNFLN7fzUzqJbQrobEGB3b6T8xHLUfkl3luOw1xpg5ewyWUaVFl5yiNVnYsskitv6gcQhLaw4b2u44A2iO-4L_18WDoZgMURt-vDoYw provider: provider id: f48ac10b-58cc-4372-a567-0e02b2c3d489 additionalData: '' mandates: - mandateId: d48ac10b-58cc-4372-a567-0e02b2c3d489 preferredMerchantName: '' declineThreshold: amount: '10000.00' currencyCode: USD effectiveUntilTime: '1784841600' quantity: '10' description: description recurringPaymentInformation: occurrence: WEEKLY buyerInformation: merchantCustomerId: 3e1b7943-6567-4965-a32b-5aa93d057d35 consumerPrompt: Authorize payment to Best Buy responses: '200': description: OK schema: title: agenticCreatePurchaseIntentResponse200 type: object required: - clientCorrelationId - instructionId properties: clientCorrelationId: type: string description: Client Correlation Id used during the tokenization or during FIDO assertion. status: type: string description: Purchase status. instructionId: type: string description: Unique instruction identifier. examples: application/json: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 instructionId: 1-5C8B7367EC00c229ec8a-c96c-a932-a1f3-1faa8f138b01 '202': description: Pending schema: title: agenticPendingPurchaseIntentResponse202 type: object required: - clientCorrelationId properties: clientCorrelationId: type: string description: Client Correlation Id used during the tokenization or during FIDO assertion. instructionId: type: string description: Unique instruction identifier. status: type: string description: Purchase status. pendingEvents: type: array description: List of pending events. items: type: string propertyName: type: string description: Name of the property related to the pending event. examples: application/json: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 instructionId: 1-5C8B7367EC00114ddb4b-f06a-0bff-7430-18d285223901 status: PENDING pendingEvents: - PENDING_CARDHOLDER_AUTHENTICATION propertyName: '' '400': description: Bad Request schema: title: agenticCreatePurchaseIntentBadRequestResponse400 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '400' reason: INVALID_ARGUMENT message: Requested CVM method is not available at this time. detail: reason: '' message: '' '401': description: Unauthorized schema: title: agenticCreatePurchaseIntentUnauthorizedResponse401 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '401' reason: UNAUTHENTICATED message: Requested CVM method is not available at this time. detail: reason: '' message: '' '403': description: Forbidden schema: title: agenticCreatePurchaseIntentForbiddenResponse403 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '403' reason: FORBIDDEN message: Requested CVM method is not available at this time. detail: reason: '' message: '' '404': description: Not Found schema: title: agenticCreatePurchaseIntentNotFoundResponse404 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '404' reason: NOT_FOUND message: Requested CVM method is not available at this time. detail: reason: '' message: '' '409': description: Conflict schema: title: agenticCreatePurchaseIntentConflictResponse409 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '409' reason: UNAVAILABLE message: Requested CVM method is not available at this time. detail: reason: '' message: '' '500': description: Internal Server Error schema: title: agenticCreatePurchaseIntentInternalServerErrorResponse500 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '500' reason: INTERNAL_SERVER_ERROR message: Requested CVM method is not available at this time. detail: reason: '' message: '' /acp/v1/instructions/{instructionId}: put: tags: - Instructions summary: Update a purchase intent description: Update an existing purchase intent (instruction) identified by its instructionId. The agent calls this endpoint when the consumer modifies their order — for example, changing the quantity, updating mandates, switching payment instruments, or changing shipping details. The request body has the same structure as the initiate request. Returns the same instructionId (HTTP 200) on success, or PENDING (HTTP 202) with pendingEvents if additional cardholder authentication is required for the updated intent. operationId: updatePurchaseIntent x-devcenter-metaData: categoryTag: Intelligent_Commerce_Connect developerGuides: https://developer.cybersource.com/docs/cybs/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-purchase-update-intro.html mleForRequest: mandatory mleForResponse: mandatory disableProcessorDropDown: true disableDefaultMerchantCreds: false authorizationType: - Json Web Token overrideMerchantCredential: agentic_mid_091225001 parameters: - name: instructionId in: path required: true type: string maxLength: 50 minLength: 36 description: Unique identifier for the purchase intent instruction. - name: agenticUpdatePurchaseIntentRequest in: body required: true schema: required: - assuranceData - clientCorrelationId - deviceInformation - mandates - paymentInformation type: object properties: clientCorrelationId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Client Correlation Id used during the tokenization or during FIDO assertion. paymentInformation: required: - instrumentIdentifier type: object description: Payment Information data. References the tokenized payment card to use for this transaction. At least one of customer, paymentInstrument, or instrumentIdentifier must be provided. The instrumentIdentifier is the most commonly used reference. If you have a TMS instrument identifier, provide it in instrumentIdentifier.id. properties: customer: type: object description: Customer data. properties: id: type: string description: Unique identifier for the Customer token used in the transaction. minLength: 1 maxLength: 32 paymentInstrument: type: object description: Payment Instrument data. properties: id: type: string description: Unique identifier for the Payment Instrument token used in the transaction. minLength: 1 maxLength: 32 instrumentIdentifier: required: - id type: object description: Instrument Identifier data. properties: id: type: string description: Unique identifier for the Instrument Identifier token used in the transaction. minLength: 12 maxLength: 32 deviceInformation: type: object description: Device and Application instance data. Identifies the device and application from which the consumer is making the payment request. required: - applicationName - deviceData - ipAddress - fingerprintSessionId properties: userAgent: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 2048 description: "Base64 Encoded userAgent string of the connecting client application, with no padding. \nUser agent string of the connecting client application. \nConditionality: \n- Required for browsers\n- Optional for non-browsers\n" applicationName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Name of the connecting client application. fingerprintSessionId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Device Fingerprinting Session identifier. country: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 2 maxLength: 2 format: ISO 3166-1-alpha2 description: ISO 3166-1 alpha-2 country code. The country where the Consumer is accessing the service from. deviceData: type: object description: Device data. required: - type - brand properties: type: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: "Type of device being used. \nExample values are: \n- Mobile Phone\n- Tablet\n- Tablet\n- Laptop\n- Personal Assistant\n- Connected Auto\n- Home Appliance\n- Wearable\n- Stationary Computer\n- E-Reader\n- Handheld Gaming Devices\n- Other\n" manufacturer: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Manufacturer of the device. brand: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Brand name of the device. model: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Specific model of the device. ipAddress: type: string pattern: ^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(?:[^0-9]*(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))*$ minLength: 0 maxLength: 255 description: IP address of the consumer's device. clientDeviceId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Unique identifier of the consumer's device. assuranceData: type: array description: Assurance data. items: required: - verificationMethod - verificationResults - verificationTimestamp type: object description: Assurance data. Contains identity verification details that prove the consumer or device has been authenticated before the payment operation. properties: verificationType: type: string description: "Optional. Type of the verification data. \nPossible values:\n - `CARDHOLDER` (Default)\n - `DEVICE`\n" verificationEntity: type: string description: "Optional. Entity performing the verification. \nPossible value: \n - `10` - VISA (Default)\n" verificationEvents: type: array items: type: string description: "Optional. Event where the verification occurred. \nPossible values: \n - `01` - Payment transaction\n - `02` - Add card/Card enrollment\n - `03` - Profile access\n - `04` - Account verification\n" verificationMethod: type: string description: "Required. Method of the verification. \nPossible values: \n - `02` - App-based authentication\n - `04` - One-time passcode\n - `21` - Visa Token Service step-up: Device binding\n - `22` - Visa Token Service step-up: Cardholder verification\n - `23` - FIDO2\n" verificationResults: type: string description: "Required. Result of the verification. \nPossible values: \n - `01` - Verified\n - `02` - Not Verified\n - `03` - Not performed\n - `04` - Not required\n - `21` - Not allowed\n" verificationTimestamp: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: Required. Date and time the verification occurred. UTC time in Unix epoch format. authenticationContext: type: object description: Authentication Context data. Describes the authentication action performed. properties: action: type: string description: Authentication Context action. authenticatedIdentities: required: - id type: object description: Authenticated Identities data. Contains the identity assertion from the authentication provider. properties: data: type: string description: Data related to the authenticated identity. provider: type: string description: Provider of the authenticated identity. id: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 50 description: "This is a distinctive and non-transparent identifier provided by VISA for correlation purposes in the previous, related API. \nField Mapping when authenticationMethodType is 'FIDO2': \n - On Success: FidoResponse.identifier\n - On Error: AuthContext.identifier\n" additionalData: type: string description: Additional data related to assurance. mandates: type: array items: required: - declineThreshold - description - effectiveUntilTime - mandateId type: object description: Mandate data. Defines the consumer's spending authorization for a purchase intent, including merchant preferences, amount limits, and product details. properties: mandateId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: "Unique identifier with in the context of a purchase-intent for the mandate. \nAssigned by Partner. Id shall not be reused when a mandate is updated/deleted.\n" preferredMerchantName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: User merchant preference. example: Best Buy merchantCategory: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Merchant category Description. merchantCategoryCode: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Merchant category Code. Once it is checked, it has to be valid merchant category code. Ex:" 5311" declineThreshold: type: object description: Decline Threshold data. Defines the maximum transaction amount the consumer is willing to authorize under this mandate. properties: amount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: Transaction Decline Threshold amount. currencyCode: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 3 maxLength: 3 description: ISO 4217 currency code. Currency in which the Transaction Decline Threshold amount is expressed. recurringPaymentInformation: type: object description: 'Frequency of the transaction. Specifies how often the transaction occurs. If the mandate contains a recurring instruction, a recurring frequency must be provided and the request.isRecurring flag should be set to true. ' properties: occurrence: type: string description: "Frequency of the transaction. \nPossible values: \n - `WEEKLY`\n - `MONTHLY`\n - `YEARLY`\n" effectiveUntilTime: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 12 description: UTC time in Unix epoch format. quantity: type: string minLength: 0 maxLength: 10 description: Quantity of the product. example: '10' description: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Description of the product. example: 50 Blue Balloons buyerInformation: type: object description: Buyer Information data. Contains consumer identification and preference details. properties: merchantCustomerId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Reference identifier of the Consumer. personalIdentification: type: array items: type: object properties: type: type: string description: The type of the identification id: type: string description: The value of the identification type issueBy: type: string description: 'The government agency that issued the driver''s license or passport. If `**type** = DRIVER_LICENSE`, this is the State or province where the customer''s driver''s license was issued. If `**type** = PASSPORT`, this is the Issuing country for the cardholder''s passport. ' language: type: string description: (Required) Consumer-provided language choice. ISO 639-1 Code consumerPrompt: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Recap - A summary or condensed version of user prompts that leads to the purchase. example: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 paymentInformation: customer: id: '' paymentInstrument: id: '' instrumentIdentifier: id: 458CC7D865E5024FE063AF598E0AA950 deviceInformation: userAgent: SampleUserAgent applicationName: 'My Magic App ' fingerprintSessionId: e48ac10b-58cc-4372-a567-0e02b2c3d489 country: US deviceData: type: Mobile manufacturer: Apple brand: Apple model: iPhone 16 Pro Max ipAddress: 192.168.1.1 clientDeviceId: c48ac10b-58cc-4372-a567-0e02b2c3d489 assuranceData: - verificationType: DEVICE verificationEntity: '10' verificationEvents: [] verificationMethod: '02' verificationResults: '01' verificationTimestamp: '1745690745' authenticationContext: action: AUTHENTICATE authenticatedIdentities: data: ezAwMX06AAM1NkHcRqXxoy3kt-vNTLdJ7Zg8PVKSr_7bwd1EfMs4MWlmLeFGIhSONwer8hF1yWPs7b7-g1lYrOeNwUuCg9dsCrnKI0-A9BvrwMemw6K05reS2kUVkfu7KbwtLSzcF9BLUcGsrbtE-alrZ4MzRCGSMvJP6PVo-H_dKowL5DfNvt9ZElB9cWpaPkHo8Cvu4WvLaz42XSFK2fBfuKpCiCTIokEEuqjZrSANKeJGFzp3uqzDGn-X-_a8Gq0DcA-d7-p_9nyi5VMRv9TLjzVh5BFXfLJ_3Jz8N2CwpphgZXd9kfuQO5vhqOKKqnyXP6-qEVb1JM48-YNvOKhIDGKkdpYEv6UxHaOUVCfw6H5mnh5Cry_YU62-EWVvwqdc6YKCMWr6QOPMMxo0-SFG0zK3SVNnY5uE7tKiuP-J2n2i_8Wlj1-qFgjMlY1qaRe8LWLvKsQMu-CKov0BGiqtH681rTjnZijj75xTYJ1xyhJv7uYf8r2O2KO9lHD-JHZYBxSY5XCgS0IYW7y8h52ehO9lShwJZ9nVVrEvaK0mek49jFXXAdjgOHHmdbnLh7PJUsTU4RepHB-SaRBS1iclx4WaXcVzjsU6AtET3NCwSysEMvEKHkuHgEOcAHxSiztIsPA_lScSLajFPxjJIGsVONnX9612hT8HC2XvTXcIciEaBqdRMwSeoibsUznduV4QoDRXJQceRUa3oAbyv7c3EzYGjnKPbsJQb2SL5GOZISmTAg8luE6IQpfeFYMjCO72I68S8lmFrTgKqdcOmwGzzTuZTSe_DhQU7xqhAbkL19_wShGsWBktOhOX75V8mpz3EqM15TBBcuHyUDeEmSd7aTLrB2E84rFD7PebluV9GEoUL2I1LMV58HXRhtFpnFcm2NWy6sGnNFLN7fzUzqJbQrobEGB3b6T8xHLUfkl3luOw1xpg5ewyWUaVFl5yiNVnYsskitv6gcQhLaw4b2u44A2iO-4L_18WDoZgMURt-vDoYw provider: provider id: f48ac10b-58cc-4372-a567-0e02b2c3d489 additionalData: '' mandates: - mandateId: d48ac10b-58cc-4372-a567-0e02b2c3d489 declineThreshold: amount: '100.00' currencyCode: USD effectiveUntilTime: '1795690745' quantity: '10' description: Description of the product recurringPaymentInformation: occurrence: WEEKLY buyerInformation: merchantCustomerId: 3e1b7943-6567-4965-a32b-5aa93d057d35 consumerPrompt: Authorize payment to Best Buy responses: '200': description: OK schema: title: agenticUpdatePurchaseIntentResponse200 type: object required: - clientCorrelationId - instructionId properties: clientCorrelationId: type: string description: Client Correlation Id used during the tokenization or during FIDO assertion. status: type: string description: Purchase status. instructionId: type: string description: Unique instruction identifier. examples: application/json: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 instructionId: 1-5C8B7367EC00c229ec8a-c96c-a932-a1f3-1faa8f138b01 '202': description: Pending schema: title: agenticPendingUpdatePurchaseIntentResponse202 type: object required: - clientCorrelationId properties: clientCorrelationId: type: string description: Client Correlation Id used during the tokenization or during FIDO assertion. instructionId: type: string description: Unique instruction identifier. status: type: string description: Purchase status. pendingEvents: type: array description: List of pending events. items: type: string propertyName: type: string description: Name of the property related to the pending event. examples: application/json: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 instructionId: 1-5C8B7367EC00114ddb4b-f06a-0bff-7430-18d285223901 status: PENDING pendingEvents: - PENDING_CARDHOLDER_AUTHENTICATION propertyName: '' '400': description: Bad Request schema: title: agenticUpdatePurchaseIntentBadRequestResponse400 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '400' reason: INVALID_ARGUMENT message: Requested CVM method is not available at this time. detail: reason: '' message: '' '401': description: Unauthorized schema: title: agenticUpdatePurchaseIntentUnauthorizedResponse401 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '401' reason: UNAUTHENTICATED message: Requested CVM method is not available at this time. detail: reason: '' message: '' '403': description: Forbidden schema: title: agenticUpdatePurchaseIntentForbiddenResponse403 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '403' reason: FORBIDDEN message: Requested CVM method is not available at this time. detail: reason: '' message: '' '404': description: Not Found schema: title: agenticUpdatePurchaseIntentNotFoundResponse404 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '404' reason: NOT_FOUND message: Requested CVM method is not available at this time. detail: reason: '' message: '' '409': description: Conflict schema: title: agenticUpdatePurchaseIntentConflictResponse409 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '409' reason: UNAVAILABLE message: Requested CVM method is not available at this time. detail: reason: '' message: '' '500': description: Internal Server Error schema: title: agenticUpdatePurchaseIntentInternalServerErrorResponse500 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '500' reason: INTERNAL_SERVER_ERROR message: Requested CVM method is not available at this time. detail: reason: '' message: '' /acp/v1/instructions/{instructionId}/cancel: put: tags: - Instructions summary: Cancel a purchase intent description: Cancel an existing purchase intent (instruction) identified by its instructionId. The agent calls this endpoint when the consumer decides to abandon the purchase before payment credentials have been used. Requires device information and assurance data for identity verification. Returns status CANCELLED (HTTP 200) on success, or PENDING (HTTP 202) with pendingEvents if cardholder authentication is required before cancellation can proceed. operationId: cancelPurchaseIntent x-devcenter-metaData: categoryTag: Intelligent_Commerce_Connect developerGuides: https://developer.cybersource.com/docs/cybs/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-purchase-cancel-intro.html mleForRequest: mandatory mleForResponse: mandatory disableProcessorDropDown: true disableDefaultMerchantCreds: false authorizationType: - Json Web Token overrideMerchantCredential: agentic_mid_091225001 parameters: - name: instructionId in: path required: true type: string maxLength: 50 minLength: 36 - name: agenticCancelPurchaseIntentRequest in: body required: true description: Unique identifier for the purchase intent instruction. schema: required: - assuranceData - clientCorrelationId - deviceInformation type: object properties: clientCorrelationId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Client Correlation Id used during the tokenization or during FIDO assertion. paymentInformation: required: - instrumentIdentifier type: object description: Payment Information data. References the tokenized payment card to use for this transaction. At least one of customer, paymentInstrument, or instrumentIdentifier must be provided. The instrumentIdentifier is the most commonly used reference. If you have a TMS instrument identifier, provide it in instrumentIdentifier.id. properties: customer: type: object description: Customer data. properties: id: type: string description: Unique identifier for the Customer token used in the transaction. minLength: 1 maxLength: 32 paymentInstrument: type: object description: Payment Instrument data. properties: id: type: string description: Unique identifier for the Payment Instrument token used in the transaction. minLength: 1 maxLength: 32 instrumentIdentifier: required: - id type: object description: Instrument Identifier data. properties: id: type: string description: Unique identifier for the Instrument Identifier token used in the transaction. minLength: 12 maxLength: 32 deviceInformation: type: object description: Device and Application instance data. Identifies the device and application from which the consumer is making the payment request. required: - applicationName - deviceData - ipAddress - fingerprintSessionId properties: userAgent: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 2048 description: "Base64 Encoded userAgent string of the connecting client application, with no padding. \nUser agent string of the connecting client application. \nConditionality: \n- Required for browsers\n- Optional for non-browsers\n" applicationName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Name of the connecting client application. fingerprintSessionId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Device Fingerprinting Session identifier. country: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 2 maxLength: 2 format: ISO 3166-1-alpha2 description: ISO 3166-1 alpha-2 country code. The country where the Consumer is accessing the service from. deviceData: type: object description: Device data. required: - type - brand properties: type: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: "Type of device being used. \nExample values are: \n- Mobile Phone\n- Tablet\n- Tablet\n- Laptop\n- Personal Assistant\n- Connected Auto\n- Home Appliance\n- Wearable\n- Stationary Computer\n- E-Reader\n- Handheld Gaming Devices\n- Other\n" manufacturer: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Manufacturer of the device. brand: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Brand name of the device. model: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Specific model of the device. ipAddress: type: string pattern: ^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(?:[^0-9]*(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))*$ minLength: 0 maxLength: 255 description: IP address of the consumer's device. clientDeviceId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Unique identifier of the consumer's device. assuranceData: type: array description: Assurance data. items: required: - verificationMethod - verificationResults - verificationTimestamp type: object description: Assurance data. Contains identity verification details that prove the consumer or device has been authenticated before the payment operation. properties: verificationType: type: string description: "Optional. Type of the verification data. \nPossible values:\n - `CARDHOLDER` (Default)\n - `DEVICE`\n" verificationEntity: type: string description: "Optional. Entity performing the verification. \nPossible value: \n - `10` - VISA (Default)\n" verificationEvents: type: array items: type: string description: "Optional. Event where the verification occurred. \nPossible values: \n - `01` - Payment transaction\n - `02` - Add card/Card enrollment\n - `03` - Profile access\n - `04` - Account verification\n" verificationMethod: type: string description: "Required. Method of the verification. \nPossible values: \n - `02` - App-based authentication\n - `04` - One-time passcode\n - `21` - Visa Token Service step-up: Device binding\n - `22` - Visa Token Service step-up: Cardholder verification\n - `23` - FIDO2\n" verificationResults: type: string description: "Required. Result of the verification. \nPossible values: \n - `01` - Verified\n - `02` - Not Verified\n - `03` - Not performed\n - `04` - Not required\n - `21` - Not allowed\n" verificationTimestamp: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: Required. Date and time the verification occurred. UTC time in Unix epoch format. authenticationContext: type: object description: Authentication Context data. Describes the authentication action performed. properties: action: type: string description: Authentication Context action. authenticatedIdentities: required: - id type: object description: Authenticated Identities data. Contains the identity assertion from the authentication provider. properties: data: type: string description: Data related to the authenticated identity. provider: type: string description: Provider of the authenticated identity. id: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 50 description: "This is a distinctive and non-transparent identifier provided by VISA for correlation purposes in the previous, related API. \nField Mapping when authenticationMethodType is 'FIDO2': \n - On Success: FidoResponse.identifier\n - On Error: AuthContext.identifier\n" additionalData: type: string description: Additional data related to assurance. example: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 paymentInformation: customer: id: '' paymentInstrument: id: '' instrumentIdentifier: id: 458CC7D865E5024FE063AF598E0AA950 deviceInformation: userAgent: SampleUserAgent applicationName: My Magic App fingerprintSessionId: finSessionId country: US deviceData: type: Mobile manufacturer: Apple brand: Apple model: iPhone 16 Pro Max ipAddress: 192.168.1.1 clientDeviceId: 000b2767814e4416999f4ee2b099491d2087 assuranceData: - verificationType: CARDHOLDER verificationEntity: '10' verificationEvents: - '01' verificationMethod: '02' verificationResults: '02' verificationTimestamp: '1753165632' AuthenticationContext: action: AUTHENTICATE authenticatedIdentities: data: ezAwMX06AAM1NkHcRqXxoy3kt-vNTLdJ7Zg8PVKSr_7bwd1EfMs4MWlmLeFGIhSONwer8hF1yWPs7b7-g1lYrOeNwUuCg9dsCrnKI0-A9BvrwMemw6K05reS2kUVkfu7KbwtLSzcF9BLUcGsrbtE-alrZ4MzRCGSMvJP6PVo-H_dKowL5DfNvt9ZElB9cWpaPkHo8Cvu4WvLaz42XSFK2fBfuKpCiCTIokEEuqjZrSANKeJGFzp3uqzDGn-X-_a8Gq0DcA-d7-p_9nyi5VMRv9TLjzVh5BFXfLJ_3Jz8N2CwpphgZXd9kfuQO5vhqOKKqnyXP6-qEVb1JM48-YNvOKhIDGKkdpYEv6UxHaOUVCfw6H5mnh5Cry_YU62-EWVvwqdc6YKCMWr6QOPMMxo0-SFG0zK3SVNnY5uE7tKiuP-J2n2i_8Wlj1-qFgjMlY1qaRe8LWLvKsQMu-CKov0BGiqtH681rTjnZijj75xTYJ1xyhJv7uYf8r2O2KO9lHD-JHZYBxSY5XCgS0IYW7y8h52ehO9lShwJZ9nVVrEvaK0mek49jFXXAdjgOHHmdbnLh7PJUsTU4RepHB-SaRBS1iclx4WaXcVzjsU6AtET3NCwSysEMvEKHkuHgEOcAHxSiztIsPA_lScSLajFPxjJIGsVONnX9612hT8HC2XvTXcIciEaBqdRMwSeoibsUznduV4QoDRXJQceRUa3oAbyv7c3EzYGjnKPbsJQb2SL5GOZISmTAg8luE6IQpfeFYMjCO72I68S8lmFrTgKqdcOmwGzzTuZTSe_DhQU7xqhAbkL19_wShGsWBktOhOX75V8mpz3EqM15TBBcuHyUDeEmSd7aTLrB2E84rFD7PebluV9GEoUL2I1LMV58HXRhtFpnFcm2NWy6sGnNFLN7fzUzqJbQrobEGB3b6T8xHLUfkl3luOw1xpg5ewyWUaVFl5yiNVnYsskitv6gcQhLaw4b2u44A2iO-4L_18WDoZgMURt-vDoYw provider: VISA_PAYMENT_PASSKEY id: f48ac10b-58cc-4372-a567-0e02b2c3d489 additionalData: '' responses: '200': description: OK schema: title: agenticCancelPurchaseIntentResponse200 type: object required: - clientCorrelationId - instructionId properties: clientCorrelationId: type: string description: Client Correlation Id used during the tokenization or during FIDO assertion. status: type: string description: Purchase status. instructionId: type: string description: Unique instruction identifier. examples: application/json: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 instructionId: 1-5C8B7367EC00c229ec8a-c96c-a932-a1f3-1faa8f138b01 '202': description: Pending schema: title: agenticPendingCancelPurchaseIntentResponse202 type: object required: - clientCorrelationId properties: clientCorrelationId: type: string description: Client Correlation Id used during the tokenization or during FIDO assertion. instructionId: type: string description: Unique instruction identifier. status: type: string description: Purchase status. pendingEvents: type: array description: List of pending events. items: type: string propertyName: type: string description: Name of the property related to the pending event. examples: application/json: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 instructionId: 1-5C8B7367EC00114ddb4b-f06a-0bff-7430-18d285223901 status: PENDING pendingEvents: - PENDING_CARDHOLDER_AUTHENTICATION propertyName: '' '400': description: Bad Request schema: title: agenticCancelPurchaseIntentBadRequestResponse400 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '400' reason: INVALID_ARGUMENT message: Requested CVM method is not available at this time. detail: reason: '' message: '' '401': description: Unauthorized schema: title: agenticCancelPurchaseIntentUnauthorizedResponse401 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '401' reason: UNAUTHENTICATED message: Requested CVM method is not available at this time. detail: reason: '' message: '' '403': description: Forbidden schema: title: agenticCancelPurchaseIntentForbiddenResponse403 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '403' reason: FORBIDDEN message: Requested CVM method is not available at this time. detail: reason: '' message: '' '404': description: Not Found schema: title: agenticCancelPurchaseIntentNotFoundResponse404 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '404' reason: NOT_FOUND message: Requested CVM method is not available at this time. detail: reason: '' message: '' '409': description: Conflict schema: title: agenticCancelPurchaseIntentConflictResponse409 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '409' reason: UNAVAILABLE message: Requested CVM method is not available at this time. detail: reason: '' message: '' '500': description: Internal Server Error schema: title: agenticCancelPurchaseIntentInternalServerErrorResponse500 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '500' reason: INTERNAL_SERVER_ERROR message: Requested CVM method is not available at this time. detail: reason: '' message: '' /acp/v1/instructions/{instructionId}/credentials: post: tags: - Instructions summary: Retrieve payment credentials description: Retrieve tokenized payment credentials for a purchase intent to complete the transaction at a merchant. The agent calls this endpoint after a purchase intent has been created and approved, providing transaction-level details including order information, merchant details, payment options, and production information. Returns COMPLETED (HTTP 200) with a signed payload containing encrypted payment credentials (authorization token and JWS-signed payload), or PENDING (HTTP 202) with pendingEvents if additional cardholder authentication is required. The signed payload is used by the merchant's payment processor to complete the transaction. operationId: retrievePaymentCredentials x-devcenter-metaData: categoryTag: Intelligent_Commerce_Connect developerGuides: https://developer.cybersource.com/docs/cybs/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-retrieve-credentials-intro.html mleForRequest: mandatory mleForResponse: mandatory disableProcessorDropDown: true disableDefaultMerchantCreds: false authorizationType: - Json Web Token overrideMerchantCredential: agentic_mid_091225001 parameters: - name: instructionId in: path required: true type: string maxLength: 50 minLength: 36 description: Unique identifier for the purchase intent instruction. - name: agenticRetrievePaymentCredentialsRequest in: body required: true schema: required: - clientCorrelationId - paymentInformation - transactionData type: object properties: clientCorrelationId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Client Correlation Id used during the tokenization or during FIDO assertion. paymentInformation: required: - instrumentIdentifier type: object description: Payment Information data. References the tokenized payment card to use for this transaction. At least one of customer, paymentInstrument, or instrumentIdentifier must be provided. The instrumentIdentifier is the most commonly used reference. If you have a TMS instrument identifier, provide it in instrumentIdentifier.id. properties: customer: type: object description: Customer data. properties: id: type: string description: Unique identifier for the Customer token used in the transaction. minLength: 1 maxLength: 32 paymentInstrument: type: object description: Payment Instrument data. properties: id: type: string description: Unique identifier for the Payment Instrument token used in the transaction. minLength: 1 maxLength: 32 instrumentIdentifier: required: - id type: object description: Instrument Identifier data. properties: id: type: string description: Unique identifier for the Instrument Identifier token used in the transaction. minLength: 12 maxLength: 32 transactionData: type: array description: List of transaction data. items: type: object required: - clientReferenceInformation - merchantInformation - orderInformation properties: clientReferenceInformation: required: - code type: object description: Client reference information. properties: code: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: "A distinct identifier for this order/line item. This ID will act as a reference to connect this line item with payment details, \npayment transactions, and confirmation events.\n" mandateReferenceData: type: array description: Mandate Reference Data. items: type: object properties: mandateId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: (Conditional) Unique Mandate identifier associated with the Transaction. type: type: string description: "(Conditional) Type of the transaction. This field is used to determine the type of transaction and the associated processing rules. \nPossible values: \n - `PURCHASE` (Default)\n - `BILL_PAYMENT`\n - `MONEY_TRANSFER`\n - `DISBURSEMENT`\n - `P2P`\n" orderInformation: required: - amountDetail type: object description: Order information. properties: amountDetail: required: - currency - totalAmount type: object description: Amount Detail data. Breaks down the total transaction amount into components. properties: totalAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The final amount that the customer needs to pay or paid. currency: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 3 maxLength: 3 description: '(Conditional) ISO 4217 currency code. Currency in which the transactionAmount, subTotal, tax, Shipping& handling or discount amount is expressed. Conditionality - Required when either transactionAmount, subTotal, tax, Shipping& handling or discount amount is present. ' subTotalAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The total transaction amount before any taxes or discounts are applied. discountAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The total discount amount applied to the transaction. shippingAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: The total shipping and handling cost(amount) applied to the transaction. handlingAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: The total shipping and handling cost(amount) applied to the transaction. shipTo: required: - country - countryCallingCode - phoneNumber type: object description: Shipping information. properties: addressId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 36 maxLength: 36 description: '(Conditional) Reference identifier of the address Conditionality - Required when address is already registered with VACP System. Optional for requests when address fields are provided. ' district: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 100 description: "Name of the business; Name of the community; c/o Name etc. Notes - Shipping Address - The final recipient's name will be captured \nin deliveryContacts field. Billing Address - The Card Holder or Consumer Name will be recorded as part of Card or Order Information.\n" address1: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 75 description: '(Conditional) Address line 1 Conditionality - Required when used with the DPA Registration operation in the Management Service APIs Required when address is used as shipping/delivery Address. ' address2: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 75 description: Address line 2. address3: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 75 description: Address line 3. locality: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: "(Conditional) Address city Conditionality - When used with the DPA Registration operation in the Management \nService APIs at least one of the following is required \n- both city and state\n- zip Required if this is a shipping address in a valid format for the country\n" administrativeArea: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 30 description: "(Conditional) Address state Recommendation to support ISO 3166-2 format i.e. made up of ISO 3166-1 alpha 2 country code, \nfollowed by an alphanumeric string of 3 characters representing the state or sub-division Conditionality - \nWhen used with the DPA Registration operation in the Management Service APIs at least one of the following is required \n- both city and state\n- zip Required if this is a shipping address in a valid format for the country.\n" country: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 2 maxLength: 2 description: Address country code ISO 3166-1 alpha-2 country code. postalCode: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 16 description: "Address zip/postal code Conditionality - When used with the DPA Registration operation in th Management Service APIs \nat least one of the following is required. \n- both city and state \n- zip Required if this is a shipping address in a valid format for the country and has a postal code or zip code\n" createTime: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 12 description: Date and time the address was created. UTC time in Unix epoch format. lastUsedTime: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 12 description: Date and time the address was last used. UTC time in Unix epoch format. firstName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 60 description: First name of the recipient. middleName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 60 description: Middle name of the recipient. lastName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 60 description: Last name of the recipient. email: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Consumer-provided email address. countryCallingCode: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 4 description: Phone number country code as defined by the International Telecommunication Union. phoneNumber: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 4 maxLength: 14 description: Phone number without country code. numberIsVoiceOnly: type: boolean description: Indicates that the phone number provided is not capable of receiving text messages. instructions: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 1024 description: Consumer-provided delivery instructions. lineItems: type: array items: type: object description: Item details. properties: items: type: object properties: productSku: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: Unique identifier for the product. productName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 10 description: Name of the product. quantity: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 10 description: (Conditional) Quantity of the product. unitPrice: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The price of a single unit. unitPriceCurrency: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 3 maxLength: 3 description: ISO 4217 currency code. Currency in which the unit price is expressed. amountDetail: required: - currency - totalAmount type: object description: Amount Detail data. Breaks down the total transaction amount into components. properties: totalAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The final amount that the customer needs to pay or paid. currency: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 3 maxLength: 3 description: '(Conditional) ISO 4217 currency code. Currency in which the transactionAmount, subTotal, tax, Shipping& handling or discount amount is expressed. Conditionality - Required when either transactionAmount, subTotal, tax, Shipping& handling or discount amount is present. ' subTotalAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The total transaction amount before any taxes or discounts are applied. discountAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The total discount amount applied to the transaction. shippingAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: The total shipping and handling cost(amount) applied to the transaction. handlingAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: The total shipping and handling cost(amount) applied to the transaction. productUrl: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: URL of the product. policies: type: object description: Policies related to the item. properties: termsAndConditions: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the sale, payment, use of the product. cancellationPolicy: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the cancellation of the order. refundPolicy: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the refund. disputePolicy: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the dispute. shippingPolicy: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the shipping. discountAndPromotions: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the discount. propertyName: type: object additionalInfo: type: array items: type: object properties: key: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Key for the additional information. value: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Value for the additional information. deliveryMethod: type: string description: "(Conditional) An indication of the manner in which the purchased goods are to be delivered \nPossible values: \n - `NO_DELIVERY`\n - `ADDRESS_BILLING`\n - `ADDRESS_ON_FILE`\n - `ADDRESS_OTHER`\n - `PICKUP`\n - `ELECTRONIC`\n" paymentServiceProviderUrl: type: string pattern: (?!^[*.,'#_/-]+$)^.*$ minLength: 0 maxLength: 255 description: (Conditional) URL of the payment service provider. paymentServiceProviderName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: (Conditional) Name of the payment service provider. merchantOrderId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: (Conditional) Digital Payment Application generated order/invoice number corresponding to a Consumer purchase. merchantInformation: required: - merchantDescriptor - merchantName type: object description: Merchant Information data. properties: merchantId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 0 maxLength: 255 description: (Conditional) Identifier of the DPA generated by VISA based on the previously provided during the Merchant Registration Process when known. merchantName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 0 maxLength: 40 description: Merchant name. Required for the Network's system to facilitate authentication. categoryCode: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 0 maxLength: 4 description: (Conditional) Code associated with Merchant Category. Describes the merchant's type of business, product or service. If it is checked, it has to be valid value. Ex, "5311" merchantDescriptor: required: - country - url type: object description: Merchant Descriptor data. properties: country: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code. url: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 0 maxLength: 255 description: Merchant URL. domainName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 0 maxLength: 255 description: (Conditional) Merchant URL. language: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 5 maxLength: 5 description: Merchant's preferred locale. For example:["en_US","fr_CA"] ISO language country pair. [ISO 639-1 Code] [ISO 3166-1 alpha-2 country code] paymentOptions: type: object description: Payment Options data. properties: dpaDynamicDataTtlMinutes: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 10 description: Requested "Time to Live" (expiry period) of the Dynamic Data, specified in minutes. dynamicDataType: type: string description: "Type of Dynamic Data required in the payload \nPossible values: \n - `TAVV`\n - `DAVV`\n - `NONE`\n" attachments: type: array items: type: object description: Attachment data. properties: name: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: Type/Name of the image. For example - product, payment confirmation, cart etc. contentType: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 30 description: Content Type of the image. For example - image/jpeg, image/png, application/pdf etc. content: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Image(Binary) in Base64 encoded with no padding. example: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 paymentInformation: customer: id: '' paymentInstrument: id: '' instrumentIdentifier: id: 458CC7D865E5024FE063AF598E0AA950 transactionData: - clientReferenceInformation: code: a151052b-b701-4562-a52f-86ee8de9bc53ac mandateReferenceData: - mandateId: d48ac10b-58cc-4372-a567-0e02b2c3d489 - mandateId: a12bc34d-56ef-7890-b123-4cd56ef78901 type: PURCHASE orderInformation: amountDetail: totalAmount: '100' currency: USD subTotalAmount: '100' discountAmount: '100' shippingAmount: '13' handlingAmount: '25' shipTo: addressId: 8d7962f5-b9c7-4e5b-bf53-9f357dc90957 district: Financial District address1: 123 Main St address2: Apt 1 address3: Suite 200 locality: San Francisco administrativeArea: CA country: US postalCode: '94105' createTime: '1735690745' lastUsedTime: '1735690745' firstName: John middleName: '' lastName: Doe email: john.doe@example.com countryCallingCode: '1' phoneNumber: '4155551234' numberIsVoiceOnly: false instructions: Leave it at the front door lineItems: - items: productSku: SKU-1234 productName: Balloons quantity: '10' unitPrice: '100.00' unitPriceCurrency: USD amountDetail: totalAmount: '100.00' currency: USD subTotalAmount: '10.00' discountAmount: '6.00' shippingAmount: '6.00' handlingAmount: '0.00' productUrl: https://example.com/product/1234 policies: termsAndConditions: Standard terms and conditions apply cancellationPolicy: Cancel within 24 hours for full refund refundPolicy: 30-day money back guarantee disputePolicy: Contact customer service for disputes shippingPolicy: Ships within 2-3 business days discountAndPromotions: 10% off first purchase propertyName: '' additionalInfo: - key: color value: red deliveryMethod: ADDRESS_ON_FILE paymentServiceProviderUrl: https://psp.example.com paymentServiceProviderName: Example PSP merchantOrderId: d48ac10b-58cc-4372-a567-0e02b2c3d489 merchantInformation: merchantId: '27416273' merchantName: John Doe categoryCode: '5311' merchantDescriptor: country: US url: www.merchant.com domainName: merchantDomain language: en_US paymentOptions: dpaDynamicDataTtlMinutes: '10080' dynamicDataType: TAVV attachments: - name: product-image contentType: image/jpeg content: /9j/4AAQSkZJRgABAQAAAQABAAD responses: '200': description: OK schema: title: agenticRetrievePaymentCredentialsResponse200 type: object description: 'The response maybe in one of two formats: - TransactionResponseComplete - TransactionResponsePendingEvents Only one of the response will be populated in the response ' properties: TransactionResponseComplete: type: object required: - clientCorrelationId - instructionId properties: clientCorrelationId: type: string description: Client Correlation Id used during the tokenization or during FIDO assertion. instructionId: type: string description: Instruction identifier. status: type: string description: Status of the Retrieve Payment Credentials request. authorization: type: string description: First Party Authorization Token/code. signedPayload: type: string description: Signed payload containing the payment credentials. TransactionResponseWithPendingEvents: type: object required: - clientCorrelationId - instructionId properties: clientCorrelationId: type: string description: Client Correlation Id used during the tokenization or during FIDO assertion. instructionId: type: string description: Transaction identifier. status: type: string description: Status of the Retrieve Payment Credentials request. pendingEvents: type: array description: Set of pending events. items: type: string examples: application/json: transactionResponseComplete: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 instructionId: 1-5C8B7367EC00114ddb4b-f06a-0bff-7430-18d285223901 status: COMPLETED authorization: '' signedPayload: jws-signed-payload transactionResponseWithPendingEvents: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 instructionId: 1-5C8B7367EC00114ddb4b-f06a-0bff-7430-18d285223901 status: PENDING pendingEvents: PENDING_CARDHOLDER_AUTHENTICATION '400': description: Bad Request schema: title: agenticRetrievePaymentCredentialsBadRequestResponse400 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '400' reason: INVALID_ARGUMENT message: Requested CVM method is not available at this time. detail: reason: '' message: '' '401': description: Unauthorized schema: title: agenticRetrievePaymentCredentialsUnauthorizedResponse401 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '401' reason: UNAUTHENTICATED message: Requested CVM method is not available at this time. detail: reason: '' message: '' '403': description: Forbidden schema: title: agenticRetrievePaymentCredentialsForbiddenResponse403 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '403' reason: FORBIDDEN message: Requested CVM method is not available at this time. detail: reason: '' message: '' '404': description: Not Found schema: title: agenticRetrievePaymentCredentialsNotFoundResponse404 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '404' reason: NOT_FOUND message: Requested CVM method is not available at this time. detail: reason: '' message: '' '409': description: Conflict schema: title: agenticRetrievePaymentCredentialsConflictResponse409 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '409' reason: UNAVAILABLE message: Requested CVM method is not available at this time. detail: reason: '' message: '' '500': description: Internal Server Error schema: title: agenticRetrievePaymentCredentialsInternalServerErrorResponse500 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '500' reason: INTERNAL_SERVER_ERROR message: Requested CVM method is not available at this time. detail: reason: '' message: '' x-example: example0: summary: Retrieve payment credentials value: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 paymentInformation: customer: id: '' paymentInstrument: id: '' instrumentIdentifier: id: 458CC7D865E5024FE063AF598E0AA950 transactionData: - clientReferenceInformation: code: a151052b-b701-4562-a52f-86ee8de9bc53ac mandateReferenceData: - mandateId: d48ac10b-58cc-4372-a567-0e02b2c3d489 - mandateId: a12bc34d-56ef-7890-b123-4cd56ef78901 type: PURCHASE orderInformation: amountDetail: totalAmount: '100' currency: USD subTotalAmount: '100' discountAmount: '100' shippingAmount: '13' handlingAmount: '25' shipTo: addressId: 8d7962f5-b9c7-4e5b-bf53-9f357dc90957 district: Financial District address1: 123 Main St address2: Apt 1 address3: Suite 200 locality: San Francisco administrativeArea: CA country: US postalCode: '94105' createTime: '1735690745' lastUsedTime: '1735690745' firstName: John middleName: '' lastName: Doe email: john.doe@example.com countryCallingCode: '1' phoneNumber: '4155551234' numberIsVoiceOnly: false instructions: Leave it at the front door lineItems: - items: productSku: SKU-1234 productName: Balloons quantity: '10' unitPrice: '100.00' unitPriceCurrency: USD amountDetail: totalAmount: '100.00' currency: USD subTotalAmount: '10.00' discountAmount: '6.00' shippingAmount: '6.00' handlingAmount: '0.00' productUrl: https://example.com/product/1234 policies: termsAndConditions: Standard terms and conditions apply cancellationPolicy: Cancel within 24 hours for full refund refundPolicy: 30-day money back guarantee disputePolicy: Contact customer service for disputes shippingPolicy: Ships within 2-3 business days discountAndPromotions: 10% off first purchase propertyName: '' additionalInfo: - key: color value: red deliveryMethod: ADDRESS_ON_FILE paymentServiceProviderUrl: https://psp.example.com paymentServiceProviderName: Example PSP merchantOrderId: d48ac10b-58cc-4372-a567-0e02b2c3d489 merchantInformation: merchantId: '27416273' merchantName: John Doe categoryCode: '5311' merchantDescriptor: country: US url: www.merchant.com domainName: merchantDomain language: en_US paymentOptions: dpaDynamicDataTtlMinutes: '10080' dynamicDataType: TAVV attachments: - name: product-image contentType: image/jpeg content: /9j/4AAQSkZJRgABAQAAAQABAAD /acp/v1/instructions/{instructionId}/confirmations: post: tags: - Instructions summary: Confirm transaction events description: Confirm transaction events for a completed purchase. The agent calls this endpoint after the payment has been submitted to notify the Intelligent Commerce Connect of the transaction outcome. The request includes processor information (transaction type, status, approval codes), order details (shipping, tracking, product information), and merchant information. Returns HTTP 202 acknowledging receipt of the confirmation. operationId: confirmTransactionEvents x-devcenter-metaData: categoryTag: Intelligent_Commerce_Connect developerGuides: https://developer.cybersource.com/docs/cybs/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-confirm-trxn-intro.html mleForRequest: mandatory mleForResponse: mandatory disableProcessorDropDown: true disableDefaultMerchantCreds: false authorizationType: - Json Web Token overrideMerchantCredential: agentic_mid_091225001 parameters: - name: instructionId in: path required: true type: string maxLength: 50 minLength: 36 description: Unique identifier for the purchase intent instruction. - name: agenticConfirmTransactionEventsRequest in: body required: true schema: required: - clientCorrelationId - paymentInformation - confirmationData type: object properties: clientCorrelationId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Client Correlation Id used during the tokenization or during FIDO assertion. paymentInformation: required: - instrumentIdentifier type: object description: Payment Information data. References the tokenized payment card to use for this transaction. At least one of customer, paymentInstrument, or instrumentIdentifier must be provided. The instrumentIdentifier is the most commonly used reference. If you have a TMS instrument identifier, provide it in instrumentIdentifier.id. properties: customer: type: object description: Customer data. properties: id: type: string description: Unique identifier for the Customer token used in the transaction. minLength: 1 maxLength: 32 paymentInstrument: type: object description: Payment Instrument data. properties: id: type: string description: Unique identifier for the Payment Instrument token used in the transaction. minLength: 1 maxLength: 32 instrumentIdentifier: required: - id type: object description: Instrument Identifier data. properties: id: type: string description: Unique identifier for the Instrument Identifier token used in the transaction. minLength: 12 maxLength: 32 confirmationData: type: array description: (Required) Contains Transaction, Order and Payment Confirmation Events. items: required: - clientReferenceInformation - processorInformation type: object properties: clientReferenceInformation: required: - code type: object description: Client reference information. properties: code: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: "A distinct identifier for this order/line item. This ID will act as a reference to connect this line item with payment details, \npayment transactions, and confirmation events.\n" orderInformation: type: object properties: orderId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 100 description: Unique identifier for the order orderStatus: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: Status of the order orderDate: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 12 description: Order date (UTC time in Epoch format) expectedDeliveryDate: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 12 description: Expected delivery date for the order (UTC time in Epoch format) amountDetail: required: - currency - totalAmount type: object description: Amount Detail data. Breaks down the total transaction amount into components. properties: totalAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The final amount that the customer needs to pay or paid. currency: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 3 maxLength: 3 description: '(Conditional) ISO 4217 currency code. Currency in which the transactionAmount, subTotal, tax, Shipping& handling or discount amount is expressed. Conditionality - Required when either transactionAmount, subTotal, tax, Shipping& handling or discount amount is present. ' subTotalAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The total transaction amount before any taxes or discounts are applied. discountAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The total discount amount applied to the transaction. shippingAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: The total shipping and handling cost(amount) applied to the transaction. handlingAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: The total shipping and handling cost(amount) applied to the transaction. shipTo: required: - country - countryCallingCode - phoneNumber type: object description: Shipping information. properties: addressId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 36 maxLength: 36 description: '(Conditional) Reference identifier of the address Conditionality - Required when address is already registered with VACP System. Optional for requests when address fields are provided. ' district: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 100 description: "Name of the business; Name of the community; c/o Name etc. Notes - Shipping Address - The final recipient's name will be captured \nin deliveryContacts field. Billing Address - The Card Holder or Consumer Name will be recorded as part of Card or Order Information.\n" address1: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 75 description: '(Conditional) Address line 1 Conditionality - Required when used with the DPA Registration operation in the Management Service APIs Required when address is used as shipping/delivery Address. ' address2: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 75 description: Address line 2. address3: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 75 description: Address line 3. locality: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: "(Conditional) Address city Conditionality - When used with the DPA Registration operation in the Management \nService APIs at least one of the following is required \n- both city and state\n- zip Required if this is a shipping address in a valid format for the country\n" administrativeArea: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 30 description: "(Conditional) Address state Recommendation to support ISO 3166-2 format i.e. made up of ISO 3166-1 alpha 2 country code, \nfollowed by an alphanumeric string of 3 characters representing the state or sub-division Conditionality - \nWhen used with the DPA Registration operation in the Management Service APIs at least one of the following is required \n- both city and state\n- zip Required if this is a shipping address in a valid format for the country.\n" country: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 2 maxLength: 2 description: Address country code ISO 3166-1 alpha-2 country code. postalCode: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 16 description: "Address zip/postal code Conditionality - When used with the DPA Registration operation in th Management Service APIs \nat least one of the following is required. \n- both city and state \n- zip Required if this is a shipping address in a valid format for the country and has a postal code or zip code\n" createTime: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 12 description: Date and time the address was created. UTC time in Unix epoch format. lastUsedTime: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 12 description: Date and time the address was last used. UTC time in Unix epoch format. firstName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 60 description: First name of the recipient. middleName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 60 description: Middle name of the recipient. lastName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 60 description: Last name of the recipient. email: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Consumer-provided email address. countryCallingCode: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 4 description: Phone number country code as defined by the International Telecommunication Union. phoneNumber: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 4 maxLength: 14 description: Phone number without country code. numberIsVoiceOnly: type: boolean description: Indicates that the phone number provided is not capable of receiving text messages. instructions: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 1024 description: Consumer-provided delivery instructions. shippingDetails: type: object description: Shipping Details data. properties: shippingMethod: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 128 description: Method of shipping (e.g., Standard, Express) trackingId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Tracking ID for the shipment carrier: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Shipping carrier or provider lineItems: type: array items: type: object description: Item details. properties: items: type: object properties: productSku: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: Unique identifier for the product. productName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 10 description: Name of the product. quantity: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 10 description: (Conditional) Quantity of the product. unitPrice: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The price of a single unit. unitPriceCurrency: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 3 maxLength: 3 description: ISO 4217 currency code. Currency in which the unit price is expressed. amountDetail: required: - currency - totalAmount type: object description: Amount Detail data. Breaks down the total transaction amount into components. properties: totalAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The final amount that the customer needs to pay or paid. currency: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 3 maxLength: 3 description: '(Conditional) ISO 4217 currency code. Currency in which the transactionAmount, subTotal, tax, Shipping& handling or discount amount is expressed. Conditionality - Required when either transactionAmount, subTotal, tax, Shipping& handling or discount amount is present. ' subTotalAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The total transaction amount before any taxes or discounts are applied. discountAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The total discount amount applied to the transaction. shippingAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: The total shipping and handling cost(amount) applied to the transaction. handlingAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: The total shipping and handling cost(amount) applied to the transaction. productUrl: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: URL of the product. policies: type: object description: Policies related to the item. properties: termsAndConditions: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the sale, payment, use of the product. cancellationPolicy: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the cancellation of the order. refundPolicy: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the refund. disputePolicy: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the dispute. shippingPolicy: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the shipping. discountAndPromotions: type: string pattern: (?s)(?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 4098 description: Any specific terms and conditions related to the discount. propertyName: type: object additionalInfo: type: array items: type: object properties: key: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Key for the additional information. value: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 255 description: Value for the additional information. merchantInformation: type: object description: Merchant Information data properties: merchantId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 0 maxLength: 255 description: Reference identifier of the Merchant merchantName: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 0 maxLength: 255 description: Merchant name categoryCode: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 0 maxLength: 4 description: Merchant Category Code (MCC). Describes the merchant's type of business, product or service processorInformation: required: - transactionType - transactionStatus type: object description: Payment/Transaction Confirmation Data provided by the payment processor/acquirer. properties: dynamicDataId: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 0 maxLength: 50 description: A unique reference ID that represents the dynamic data associated with a transaction transactionType: type: string description: "Type of payment transaction\nPossible values:\n - 'PURCHASE'\n - 'AUTHORIZATION'\n - 'CAPTURE'\n - 'REFUND'\n - 'REVERSAL'\n - 'VERIFICATION'\n - 'CHARGEBACK'\n - 'FRAUD'\n" transactionStatus: type: string description: "Status of payment transaction\nPossible values:\n - 'APPROVED'\n - 'DECLINED'\n - 'PENDING'\n - 'ERROR'\n - 'CANCELLED'\n" responseCode: type: string minLength: 0 maxLength: 2 pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ description: 2 Digit Response code sent directly from the payment processor transactionTimestamp: type: string minLength: 1 maxLength: 12 pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ description: Date and time of the transaction (UTC time in Epoch format) approvalCode: type: string minLength: 0 maxLength: 128 pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ description: Authorization code. Returned when the processor returns this value retrievalReferenceNumber: type: string minLength: 0 maxLength: 64 pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ description: Unique number to identify the transaction. It is used with other data elements to identify and track all messages related to a transaction systemTraceAuditNumber: type: string minLength: 0 maxLength: 64 pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ description: System Trace Audit Number. Audit number assigned by the payment network acquirerReferenceNumber: type: string minLength: 0 maxLength: 64 pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ description: Acquirer Reference Number. Reference number assigned by the acquirer amountDetail: required: - currency - totalAmount type: object description: Amount Detail data. Breaks down the total transaction amount into components. properties: totalAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The final amount that the customer needs to pay or paid. currency: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 3 maxLength: 3 description: '(Conditional) ISO 4217 currency code. Currency in which the transactionAmount, subTotal, tax, Shipping& handling or discount amount is expressed. Conditionality - Required when either transactionAmount, subTotal, tax, Shipping& handling or discount amount is present. ' subTotalAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The total transaction amount before any taxes or discounts are applied. discountAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.*$ minLength: 1 maxLength: 12 description: The total discount amount applied to the transaction. shippingAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: The total shipping and handling cost(amount) applied to the transaction. handlingAmount: type: string pattern: (?!^[*.,'#_/-]+$)(?!.*\./.*)^.+$ minLength: 1 maxLength: 12 description: The total shipping and handling cost(amount) applied to the transaction. entryMode: type: string description: "Method of entering payment card information\nPossible values: \n - 'EMV'\n - 'CONTACTLESS'\n - 'MANUAL'\n - 'ECOMMERCE'\n - 'WALLET'\n" paymentInstrument: type: object description: Details of the PAN associated with the enrolled card. Contains processor verification results. properties: verificationResults: type: object properties: cvv2VerificationCode: type: string minLength: 0 maxLength: 2 description: Cvv2 verification result addressVerificationCode: type: string minLength: 0 maxLength: 2 description: Address verification result example: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 paymentInformation: customer: id: '' paymentInstrument: id: '' instrumentIdentifier: id: 458CC7D865E5024FE063AF598E0AA950 confirmationData: - clientReferenceInformation: code: a151052b-b701-4562-a52f-86ee8de9bc53ac orderInformation: orderId: ORD-98765 orderStatus: COMPLETED orderDate: '1735690745' expectedDeliveryDate: '1784841600' amountDetail: totalAmount: '42.5' currency: USD subTotalAmount: '40.00' discountAmount: '2.50' shippingAmount: '5.00' handlingAmount: '2.00' shipTo: addressId: 8d7962f5-b9c7-4e5b-bf53-9f357dc90957 district: Financial District address1: 123 Main St address2: Apt 4B address3: Building C locality: San Francisco administrativeArea: CA country: US postalCode: '94105' createTime: '1735690745' lastUsedTime: '1735690745' firstName: John middleName: A lastName: Doe email: john.doe@example.com countryCallingCode: '1' phoneNumber: '4155551234' numberIsVoiceOnly: 'false' instructions: Leave at front door shippingDetails: shippingMethod: STANDARD trackingId: TRACK-123456 carrier: UPS lineItems: - items: productSku: PROD-001 productName: Sample Product quantity: '1' unitPrice: '40.00' unitPriceCurrency: USD amountDetail: totalAmount: '42.50' currency: USD subTotalAmount: '40.00' discountAmount: '2.50' shippingAmount: '5.00' handlingAmount: '2.00' productUrl: https://example.com/product/001 policies: termsAndConditions: Standard terms and conditions apply cancellationPolicy: Cancel within 24 hours for full refund refundPolicy: 30-day money back guarantee disputePolicy: Contact customer service for disputes shippingPolicy: Ships within 2-3 business days discountAndPromotions: 10% off first purchase additionalProperties: warranty: 1 year origin: USA additionalInfo: - key: color value: blue - key: material value: cotton merchantInformation: merchantId: MERCH-12345 merchantName: Example Merchant categoryCode: '5411' processorInformation: dynamicDataId: DDID-123456 transactionType: PURCHASE transactionStatus: APPROVED responseCode: '00' transactionTimestamp: '1762053600' approvalCode: AUTH-789012 retrievalReferenceNumber: RRN-456789 systemTraceAuditNumber: STAN-123456 acquirerReferenceNumber: ARN-987654 amountDetail: totalAmount: '42.50' currency: USD subTotalAmount: '40.00' discountAmount: '2.50' shippingAmount: '5.00' handlingAmount: '2.00' entryMode: MANUAL paymentInstrument: verificationResults: addressVerificationCode: Y cvv2VerificationCode: M responses: '202': description: OK schema: title: agenticConfirmTransactionEventsResponse202 type: object required: - clientCorrelationId properties: clientCorrelationId: type: string description: Client Correlation Id provided by the Agent. examples: application/json: clientCorrelationId: 3e1b7943-6567-4965-a32b-5aa93d057d35 '400': description: Bad Request schema: title: agenticConfirmTransactionEventsBadRequestResponse400 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '400' reason: INVALID_ARGUMENT message: Requested CVM method is not available at this time. detail: reason: '' message: '' '401': description: Unauthorized schema: title: agenticConfirmTransactionEventsUnauthorizedResponse401 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '401' reason: UNAUTHENTICATED message: Requested CVM method is not available at this time. detail: reason: '' message: '' '403': description: Forbidden schema: title: agenticConfirmTransactionEventsForbiddenResponse403 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '403' reason: FORBIDDEN message: Requested CVM method is not available at this time. detail: reason: '' message: '' '404': description: Not Found schema: title: agenticConfirmTransactionEventsNotFoundResponse404 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '404' reason: NOT FOUND message: Requested CVM method is not available at this time. detail: reason: '' message: '' '409': description: Conflict schema: title: agenticConfirmTransactionEventsConflictResponse409 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '409' reason: UNAVAILABLE message: Requested CVM method is not available at this time. detail: reason: '' message: '' '500': description: Internal Server Error schema: title: agenticConfirmTransactionEventsInternalServerErrorResponse500 type: object properties: error: type: object description: Error response object. required: - status - reason - message properties: status: type: string description: HTTP status code to categorize the errors. reason: type: string description: Error reason as associated with the HTTP status code message: type: string description: Error message as associated with the HTTP status code. detail: type: object description: Additional details about the error. properties: reason: type: string description: Detailed reason for the error. source: type: string description: Source for the error sourceType: type: string description: Detail about source for the error message: type: string description: Detailed message for the error examples: application/json: error: status: '500' reason: INTERNAL_SERVER_ERROR message: Requested CVM method is not available at this time. detail: reason: '' message: '' x-devcenter-metaData: categoryTagArray: - name: Payments description: For more information about Payments transactions, see the [Payments Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/payments/developer/ctv/rest/payments/payments-intro.html). - name: Transaction_Batches description: For more information about Transaction Batches, see the [Transaction Batches Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-transaction-batch-api/txn_batch_api_intro.html). - name: eCheck_AVS description: For more information about eCheck Account Validation, see the [Account Validation Developer Guides Page](https://...). - name: Token_Management description: For more information about the Token Management Service (TMS) see the [Token Management Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/all/rest/tms/tms-overview.html) - name: Flex_Microform description: Microform Integration is a lightweight acceptance solution designed to safely and securely accept payment information within your web page. Microform is designed to a be embedded seamlessly within your existing webpage experience, blending in with your existing acceptance form. This solution allows for the replacement of sensitive payment date with a transient token (a short lived reference to the sensitive payment data). For more information about Flex Microform transactions, see the [Flex Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-flex/SAFlexibleToken.html). For examples on how to integrate Flex Microform within your webpage please see our [GitHub Flex Samples](https://github.com/CyberSource?q=flex&type=&language=) - name: Flex_API description: For more information about Flex API, please see [Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/digital-accept-flex/developer/all/rest/digital-accept-flex/da-flex-api-intro.html). - name: Risk_Management - name: Payouts description: 'For more information about Payouts, see the [Payouts Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-payouts/Introduction.html). ' - name: Installments description: For more information about Installment contact Cybersource Support. For Visa installments contact VISthroughCYBS@visa.com - name: Recurring_Billing_Subscriptions description: For more information about Recurring Billing, see the [Recurring Billing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-developer/recur-bill-services-intro.html). - name: BIN_Lookup description: 'The BIN Lookup Service is a versatile business tool that provides card network agnostic solution designed to ensure frictionless transaction experience by utilizing up-to-date Bank Identification Number (BIN) attributes sourced from multiple global and regional data sources. This service helps to improve authorization rates by helping to route transactions to the best-suited card network, minimizes fraud through card detail verification and aids in regulatory compliance by identifying card properties. The service is flexible and provides businesses with a flexible choice of inputs such as primary account number (PAN), network token from major networks (such as Visa, American Express, Discover and regional networks) which includes device PAN (DPAN), and all types of tokens generated via CyberSource Token Management Service (TMS). Currently, the range of available credentials is contingent on the networks enabled for the business entity. Therefore, the network information specified in this documentation is illustrative and subject to personalized offerings for each reseller or merchant. ' - name: Transaction_Details description: For more information about Transaction Details, see the [Transaction Details Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-txn-search-details-rest-api-dev-guide-102718/txn_details_api.html). - name: Transaction_Search description: For more information about Transaction Search, see the [Transaction Search Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-txn-search-details-rest-api-dev-guide-102718/txn_search_api.html). - name: Reporting description: 'For more information about Reporting, see the [Reporting Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-reporting-rest-api-dev-guide-102718/reporting_api.html). ' - name: Secure_File_Share description: For more information about Secure File Share, see the [Secure File Share Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-secure-file-share-api-102718/secure_file_share_api_intro.html). - name: Invoices description: For more information about Invoicing, see the [Invoicing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/Introduction.html). - name: Pay_By_Link description: For more information about PayByLink, see the [PBL Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/boarding/user/all/rest/boarding/templates-matrix-intro/templates-matrix-pay-by-link.html). - name: User_Management description: For more information about User Management, see the [User Managment Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-user-management-api-102718/user_management_api_intro.html). - name: Value_Added_Service - name: Fee Service - name: Merchant_Boarding description: For more information about Merchant Boarding, please see [Developer Guides Page](https://developer.cybersource.com/api/developer-guides/Merchant-Boarding-API_ditamap/Merchant-Boarding-API.html). - name: Webhooks description: For more information about Webhooks, please see [Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro.html). - name: Unified_Checkout description: For more information about Unified Checkout, see the [Unified Checkout Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-intro.html). - name: Unified_Checkoutv1 description: For more information about Unified Checkout, see the [Unified Checkout Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-about-guide.html). - name: Account_Updater description: For more information about Account Updater, see the [Account Updater Developer Guides Page:](https://developer.cybersource.com/library/documentation/dev_guides/Account_Updater_UG/html/index.html). - name: Visa_Bank_Account_Validation description: 'The Visa Bank Account Validation Service is a new standalone product designed to validate customer''s routing and bank account number combination for ACH transactions. Merchant''s can use this standalone product to validate their customer''s account prior to processing an ACH transaction against the customer''s account to comply with Nacha''s account validation mandate for Web-debit transactions. ' - name: Currency Conversion description: 'Empower global transactions with transparency and choice. Our Dynamic Currency Conversion API lets merchants offer customers the option to pay in their home currency at checkout, delivering real-time exchange rates and clear cost disclosure. **Key Benefits:** - **Enhanced Customer Experience:** Provide clarity and convenience for international shoppers. - **Real-Time Rates:** Accurate currency conversion with all the data required for acquirers and their merchants to maintain compliance with card network rules. - **Seamless Integration:** Flexible API endpoints for rate lookup, authorization, and capture. - **Regulatory Compliance:** Provides the data required for acquirers and merchants to meet and maintain card scheme requirements for disclosure and consent. Ideal for merchants and payment partners seeking to boost trust and conversion in cross-border commerce. **Key Features:** - **Rate Lookup:** Retrieves the most up-to-date exchange rate for eligible cards before authorization. - **Currency Choice:** Enables the merchant to offer customers the option to select between the merchant''s local currency and their card''s billing currency. - **Compliance:** Ensures merchants have the data required to adhere to card network regulations; exchange rates, markups, etc. **Supported Scenarios:** - Dynamic Currency Conversion when cardholder''s billing currency differs from merchant''s pricing currency. - Merchant and acquirer must support the cardholder''s billing currency. **Core API Endpoints:** **Currency Conversion API** Returns eligibility and exchange rate details, including: - exchangeRate - marginRate - reconciliationId and Id (for subsequent payment requests) **Payment Authorization with DCC*** POST /pts/v2/payments Required fields include: - orderInformation.amountDetails.currency - orderInformation.amountDetails.originalCurrency - orderInformation.amountDetails.originalAmount - orderInformation.amountDetails.exchangeRate - currencyConversion.indicator (e.g., 1 = Converted, 2 = Nonconvertible, 3 = Declined) **Capture with DCC*** POST /pts/v2/payments/{id}/captures Maps from original authorization and includes original and converted amounts. **Refund with DCC*** POST /pts/v2/captures/{id}/refunds Maps from original authorization and includes original and converted amounts. *Note: DCC is only supported on select processors. Contact your acquirer or account manager for more information. **Compliance & Disclosure:** Merchants must: - Adhere to card network rules for Dynamic Currency Conversion (DCC) transactions. - Display the converted amount, exchange rate, and markup percentage and other required disclosures. - Obtain explicit cardholder consent before applying DCC. - Work with your acquirer to obtain full set of compliance requirements. For more information, see the [Currency Conversion Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/currency-conversion/developer/all/rest/currency-conversion/cc-intro.html). ' - name: Intelligent_Commerce_Connect description: For more information about Intelligent Commerce Cross Network Service API, please see [Developer Guides](https://developer.cybersource.com/docs/cybs/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-about-guide.html).