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.
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:
# --- truncated at 32 KB (204 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-instructions-api-openapi.yml