Initiate a Purchase Intent

Use the information in this section to enable your agents to begin a new purchase intent. When your customer uses your agents to submit a purchase intent, your agents send an initiate a purchase intent
request. This request enables Cybersource to verify that your agent is acting in accordance to the customer's intent.

After initiating a purchase intent, save the instruction ID in the

instructionId

response field in your system. The instruction ID is needed to complete follow-on API requests, such as updating and cancelling the purchase intent.

Endpoints

Send a POST request to one of these endpoints:

Production:

POST https://api.cybersource.com/acp/v1/instructions

Test:

POST https://apitest.cybersource.com/acp/v1/instructions

Required Fields for Initiating a Purchase Intent

assuranceData[].verificationMethod
assuranceData[].verificationResults
assuranceData[].verificationTimestamp
clientCorrelationId
deviceInformation.applicationName
deviceInformation.deviceData.brand
deviceInformation.deviceData.type
deviceInformation.fingerprintSessionId
deviceInformation.ipAddress
mandates[].declineThreshold.amount
mandates[].declineThreshold.currencyCode
mandates[].description
mandates[].effectiveUntilTime
mandates[].mandateId
paymentInformation.customer.id
paymentInformation.instrumentIdentifier.id
paymentInformation.paymentInstrument.id
tokenizedCard.number

Additional Information

For complete descriptions of the request fields, see the Initiate a purchase intent section in the Intelligent Commerce API Hub.

Optional Fields for Initiating a Purchase Intent

assuranceData[].additionalData
assuranceData[].authenticatedIdentities.data
assuranceData[].authenticatedIdentities.id
assuranceData[].authenticatedIdentities.provider
assuranceData[].authenticationContext.action
assuranceData[].verificationEntity
assuranceData[].verificationEvents
assuranceData[].verificationType
buyerInformation.merchantCustomerId
consumerPrompt
deviceInformation.clientDeviceId
deviceInformation.deviceData.manufacturer
deviceInformation.deviceData.model
mandates[].preferredMerchantName
mandates[].quantity
recurringPaymentInformation.occurrence

Example: Initiating a Purchase Intent

Request

{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "paymentInformation": {
    "customer": {
      "id": ""
    },
    "paymentInstrument": {
      "id": ""
    },
    "instrumentIdentifier": {
      "id": "7019989999909760770"
    }
  },
  "deviceInformation": {
    "applicationName": "My Magic App ",
    "fingerprintSessionId": "e48ac10b-58cc-4372-a567-0e02b2c3d489",
    "deviceData": {
      "type": "Mobile",
      "manufacturer": "Apple",
      "brand": "Apple",
      "model": "iPhone 16 Pro Max"
    },
    "ipAddress": "192.168.0.100",
    "clientDeviceId": "c48ac10b-58cc-4372-a567-0e02b2c3d489"
  },
  "tokenizedCard": {
    "number": "15602cf86c70b8b63297134292ec5801"
  },
  "assuranceData": [
    {
      "verificationType": "DEVICE",
      "verificationEntity": "10",
      "verificationEvents": [],
      "verificationMethod": "02",
      "verificationResults": "01",
      "verificationTimestamp": "1735690745",
      "authenticationContext": {
        "action": "AUTHENTICATE"
      },
      "authenticatedIdentities": {
        "data": "authenticatedData",
        "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": null,
      "description": "description"
    }
  ],
  "recurringPaymentInformation": {
    "occurrence": "WEEKLY"
  },
  "buyerInformation": {
    "merchantCustomerId": "example-customer-id"
  },
  "consumerPrompt": "Authorize payment to Best Buy"
}

Response to a Successful Request

{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "instructionId": "1-5C8B7367EC00c229ec8a-c96c-a932-a1f3-1faa8f138b01"
}

Follow-On Requests

After the purchase intent is initiated, your agents can send these follow-on requests using the instruction ID from the response message.

Update a Purchase: Your agent can update the initial purchase intent when the customer changes their purchase inquiry. For more information, see Update a Purchase Intent.
Cancel a Purchase: Your agent can cancel a purchase intent when the customer chooses to not to make the purchase. For more information, see Cancel a Purchase Intent.
Retrieve Payment Credentials: Your agent can retrieve a customer's payment credentials for a fast checkout experience. For more information, see Retrieve Payment Credentials.; A customer's credentials are only retrievable if the customer has already enrolled their payment information and chosen a purchase intent option.
Confirm Transaction Events: Your agent can verify when a purchase is complete to display a payment confirmation to the customer. For more information, see Confirm Transaction Events.