Agentic Commerce Platform Developer Guide

This section describes how to use this guide and where to find further information.

Audience and Purpose: This developer guide is intended for developers who want to add the Agentic Commerce Platform REST API into their payment system.
Conventions: These statements appear in this document:

IMPORTANT

An Important
statement contains information essential to successfully completing a task or learning a concept.
Related Documentation: Visit the Cybersource documentation hub to find additional processor-specific versions of this guide and additional technical documentation.; Visit the Cybersource documentation hub to find additional technical documentation.
Customer Support: For support information about any service, visit the Support Center:

http://support.visaacceptance.com

Recent Revisions to This Document

25.09.01

Pilot release.

Introduction to `Intelligent Commerce`

The Intelligent Commerce on Cybersource enables your AI agents to process purchase intents and complete transactions on behalf of your customers. When integrated into your agentic workflows, Intelligent Commerce enables your customers to submit a purchase intent using your agents. Your agents then display a list of purchase options that best match your customers' intent. When your customers choose a purchase option, your agents retrieve your customers' tokenized payment credentials and complete the transaction using your payment system. To enable fast and secure future purchases, Intelligent Commerce uses the Token Management Service (TMS) to securely tokenize and retrieve your customers' payment credentials for a frictionless checkout experience.

This guide explains how you can use Intelligent Commerce REST API to manage the entire transaction experience, from initial intent to verifying transaction completion.

Benefits

The key benefits of using Intelligent Commerce REST API are:

Connect to multiple card networks with one integration, enabling your customers to use their preferred payment method.

Expand your business to more customers by being able to accept a variety of card types.

Securely process agent-driven transactions using Visa's transaction authentication, TMS, and passkey capabilities.

Intelligent Commerce verifies that your agent is acting in accordance with the customer's purchase intent.

Customer Purchase Intent Examples

When your customers use your agents to begin their purchase intent, they can send messages such as:

Here's a list of back-to-school supplies. Find and purchase all of these supplies. Keep the total purchase amount under $100.

I'm looking for men's black running shoes that are a size 10.5. My purchase limit is $150. Only show me shoes that are rated positively.

Please find me a flight from Austin to Chicago on September 14th in the morning. I have a carry-on and I need to check in a bag. My purchase limit is $350.

Requirements to Support `Intelligent Commerce`

These are the requirements you must complete before you can use Intelligent Commerce REST API:

Have agentic or AI capabilities on your website that your customers can use to find the most relevant products and services.

Create a Cybersource merchant ID (MID) or organization ID. To sign up for a sandbox account, see the Sandbox Account Sign Up page.

Create a REST API shared secret key. To create a key with an existing organization or merchant account, see the Creating and Using Security Keys User Guide
. If you need to sign up for a sandbox account, the sign up process creates a test key.

Set up your system to be REST compliant. For more information, see the Getting Started with REST Guide
. The guide explains how to complete all of the above requirements.

Obtain a token requester ID
and a relationship ID
. To obtain these IDs, contact your Cybersource account manager.

Overview of `Intelligent Commerce` Requests

This diagram illustrates the order in which your AI agent can send Intelligent Commerce requests.

Your AI agent sends an enroll a card
request when a new customer creates an account on your website and enrolls a payment card to tokenize. After the request is sent, the customer must verify their identity to activate tokenized card. For more information, see Enroll a Card.

Your AI agent sends an initiate a purchase intent
when the customer submits a purchase intent using your website's AI capabilities. For more information, see Initiate a Purchase Intent.

(Optional) If the customer submits an updated purchase intent, your AI agent sends an update a purchase intent
request. For more information, see Update a Purchase Intent.

(Optional) If the customer chooses to not
make a purchase after submitting a purchase intent, your AI agent sends a cancel purchase intent
request. For more information, see Cancel a Purchase Intent.

Your AI agent sends a retrieve payment credentials
when the customer chooses a purchase intent option and chooses the tokenized card they want to use. For more information, see Retrieve Payment Credentials.

After your AI agent uses your payment system to process the transaction, your AI agent sends a confirm transaction events
request to verify that the purchase is complete. For more information, see Confirm Transaction Events.

Complete a Purchase Workflow

This diagram illustrates the required steps to complete a purchase using Intelligent Commerce.

The new customer signs up for an account on your website and enrolls their card credentials.

Your AI agent sends an enroll a card API request to Cybersource.

Cybersource tokenizes the customer's card and responds with a

PENDING

status. For more information, see Enroll a Card.

The customer verifies their identity to activate their tokenized card.

The customer logs in to their account and uses the agent to submit a purchase inquiry.

The customer verifies their identity to authenticate the purchase intent.

Your agent sends an initiate a purchase intent request to Cybersource.

Cybersource responds with an instruction ID. For more information, see Initiate a Purchase Intent.

Your agent displays list of best products or services based on the customer's purchase intent.

The customer chooses a product or service.

Your agent displays the customer's tokenized cards.

The customer chooses their preferred card to pay with.

Your agent sends a retrieve payment credentials to Cybersource and includes the instruction ID. For more information, see Retrieve Payment Credentials.

Cybersource retrieves the customer's tokenized card.

Your agent uses the customer's tokenized card and your payment system to complete the transaction.

Your agent sends a confirm transaction events request to Cybersource. For more information, see Confirm Transaction Events.

Cybersource responds with a

COMPLETED

status.

Your agent confirms payment and checkout completion to customer.

Endpoints

The Intelligent Commerce REST API uses these endpoints to complete purchases:

Enroll a Card: Production:

POST https://api.cybersource.com/acp/v1/tokens
Test:

POST https://apitest.cybersource.com/acp/v1/tokens
Initiate a Purchase Intent: Production:

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

POST https://apitest.cybersource.com/acp/v1/instructions
Update a Purchase Intent: Production:

PUT https://api.cybersource.com/acp/v1/instructions/{instructionID}
Test:

PUT https://apitest.cybersource.com/acp/v1/instructions/{instructionID}
Cancel a Purchase Intent: Production:

PUT https://api.cybersource.com/acp/v1/instructions/{instructionID}
/cancel
Test:

PUT https://apitest.cybersource.com/acp/v1/instructions/{instructionID}
/cancel
Retrieve Payment Credentials: Production:

POST https://api.cybersource.com/acp/v1/instructions/{instructionID}
/credentials
Test:

POST https://apitest.cybersource.com/acp/v1/instructions/{instructionID}
/credentials
Confirm Transaction Events: Production:

POST https://api.cybersource.com/acp/v1/instructions/{instructionID}
/confirmations
Test:

POST https://apitest.cybersource.com/acp/v1/instructions/{instructionID}
/confirmations

Enroll a Card

Use the information in this section to securely tokenize a customer's payment credentials for future purchases. Your agents can enroll a customer's card for tokenization during the customer's account registration or when the customer begins a new purchase intent. Each customer must have at least one card enrolled in Intelligent Commerce to complete a purchase. Enrolling a card includes also tokenizing the customer's billing information, such as their name and address.

Intelligent Commerce uses the Token Management Service (TMS) to tokenize the customer's payment credentials. Your agents can tokenize any card type supported by TMS.

A successful response includes the

PENDING

status in the

status

field. After sending the request, the customer is immediately prompted to verify their identity in order to activate the enrolled card.

Endpoints

Send a POST request to one of these endpoints.

Production:

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

Test:

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

Required Fields for Enrolling a Card

billTo.country
billTo.countryCallingCode
billTo.phoneNumber
clientCorrelationId
consumerIdentity.identityType
consumerIdentity.identityValue
deviceInformation.applicationName
deviceInformation.deviceData.brand
deviceInformation.deviceData.type
deviceInformation.fingerprintSessionId
deviceInformation.ipAddress
paymentInformation.customer.id
paymentInformation.instrumentIdentifier.id
paymentInformation.paymentInstrument.id

Additional Information

For complete descriptions of the request fields, see the Enroll a card section in the Intelligent Commerce API Hub.

Optional Fields for Enrolling a Card

assuranceData[].additionalData
assuranceData[].authenticatedIdentities.data
assuranceData[].authenticatedIdentities.id
assuranceData[].authenticatedIdentities.provider
assuranceData[].authenticationContext.action
assuranceData[].verificationEntity
assuranceData[].verificationEvents
assuranceData[].verificationMethod
assuranceData[].verificationResults
assuranceData[].verificationTimestamp
assuranceData[].verificationType
billTo.email
billTo.firstName
billTo.fullName
billTo.lastName
billTo.numberIsVoiceOnly
buyerInformation.language
buyerInformation.merchantCustomerId
buyerInformation.personalIdentification[].id
buyerInformation.personalIdentification[].issuedBy
buyerInformation.personalIdentification[].type
consentData[].acceptedTime
consentData[].effectiveUntil
consentData[].id
consentData[].source
consentData[].type
consumerIdentity.identityProvider
consumerIdentity.identityProviderUrl
deviceInformation.clientDeviceId
deviceInformation.country
deviceInformation.deviceData.manufacturer
deviceInformation.deviceData.model
deviceInformation.userAgent
enrollmentReferenceData.enrollmentReferenceProvider
enrollmentReferenceData.enrollmentReferenceType
tokenizedCard.tokenReferenceId

Example: Enrolling a Card

Request

{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "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.0.100",
    "clientDeviceId": "000b2767814e4416999f4ee2b099491d2087"
  },
  "buyerInformation": {
    "merchantCustomerId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
    "personalIdentification": [
      {
        "type": "The identification type",
        "id": "1",
        "issuedBy": "The government agency that issued the driver's license or passport"
      }
    ],
    "language": "en"
  },
  "billTo": {
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Michael Doe",
    "email": "[email protected]",
    "countryCallingCode": "1",
    "phoneNumber": "5551234567",
    "numberIsVoiceOnly": false,
    "country": "US"
  },
  "consumerIdentity": {
    "identityType": "EMAIL_ADDRESS",
    "identityValue": "[email protected]",
    "identityProvider": "PARTNER",
    "identityProviderUrl": "https://identity.partner.com"
  },
  "paymentInformation": {
    "customer": {
      "id": ""
    },
    "paymentInstrument": {
      "id": ""
    },
    "instrumentIdentifier": {
      "id": "3C189A435506B99AE0634136CF0AEB92"
    }
  },
  "tokenizedCard": {
    "tokenReferenceId": "15602cf86c70b8b63297134292ec5801"
  },
  "enrollmentReferenceData": {
    "enrollmentReferenceType": "TOKEN_REFERENCE_ID",
    "enrollmentReferenceProvider": "VTS"
  },
  "assuranceData": [
    {
      "verificationType": "DEVICE",
      "verificationEntity": "10",
      "verificationEvents": [
        "01"
      ],
      "verificationMethod": "02",
      "verificationResults": "01",
      "verificationTimestamp": "1735690745",
      "authenticationContext": {
        "action": "AUTHENTICATE"
      },
      "authenticatedIdentities": {
        "data": "authenticatedIdentities.data",
        "provider": "VISA_PAYMENT_PASSKEY",
        "id": "authenticatedIdentities.id"
      },
      "additionalData": "assuranceData.additionalData"
    }
  ],
  "consentData": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "PERSONALIZATION",
      "source": "CLIENT",
      "acceptedTime": "1719169800",
      "effectiveUntil": "1750705800"
    }
  ]
}

Response to a Successful Request

{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "status": "PENDING",
  "pendingEvents": [
    "PENDING_CARDHOLDER_AUTHENTICATION"
  ]
}

Response to a Successful Request

{
"clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
"status": "ACTIVE"
}

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.

Update a Purchase Intent

Use the information in this section to enable your agents to update a purchase intent. This can occur when a customer wants to modify their initial purchase intent, such as changing the spending limit or to retrieve new purchase options.

Endpoints

Send a PUT request to one of these endpoints. The

{instructionID}

is the instruction ID from the initial create a purchase response.

Production:

PUT https://api.cybersource.com/acp/v1/instructions/{instructionID}

Test:

PUT https://apitest.cybersource.com/acp/v1/instructions/{instructionID}

Required Fields for Updating 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.instrumentIdentifier.id
tokenizedCard.number

Additional Information

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

Optional Fields for Updating a Purchase Intent

assuranceData[].additionalData
assuranceData[].authenticatedIdentities.data
assuranceData[].authenticatedIdentities.id
assuranceData[].authenticatedIdentities.provider
assuranceData[].authenticationContext.action
assuranceData[].verificationEntity
assuranceData[].verificationEvents
assuranceData[].verificationType
mandates[].quantity

Example: Updating a Purchase Intent

Request

{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "paymentInformation": {
    "instrumentIdentifier": {
      "id": "7019989999909760770"
    }
  },
  "deviceInformation": {
    "applicationName": "My Magic App ",
    "fingerprintSessionId": "e48ac10b-58cc-4372-a567-0e02b2c3d489",
    "deviceData": {
      "type": "Mobile",
      "brand": "appInstance.brand"
    },
    "ipAddress": "192.168.1.1"
  },
  "tokenizedCard": {
    "number": "15602cf86c70b8b63297134292ec5801"
  },
  "assuranceData": [
    {
      "verificationType": "DEVICE",
      "verificationEntity": "10",
      "verificationEvents": [],
      "verificationMethod": "02",
      "verificationResults": "01",
      "verificationTimestamp": "1745690745",
      "authenticationContext": {
        "action": "AUTHENTICATE, REGISTER"
      },
      "authenticatedIdentities": {
        "data": "authenticatedData",
        "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": {},
  "buyerInformation": {}
}

Response to a Successful Request

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

Cancel a Purchase Intent

Use the information in this section to cancel a purchase intent when a customer does not want to make a purchase.

Endpoints

Send a PUT request to one of these endpoints. The

{instructionID}

is the instruction ID from the create a purchase response.

Production:

PUT https://api.cybersource.com/acp/v1/instructions/{instructionID}
/cancel

Test:

PUT https://apitest.cybersource.com/acp/v1/instructions/{instructionID}
/cancel

Required Fields for Cancelling a Purchase Intent

assuranceData[].authenticatedIdentities.id
assuranceData[].verificationMethod
assuranceData[].verificationResults
assuranceData[].verificationTimestamp
clientCorrelationId
deviceInformation.applicationName
deviceInformation.deviceData.brand
deviceInformation.deviceData.type
deviceInformation.fingerprintSessionId
deviceInformation.ipAddress

Additional Information

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

Optional Fields for Cancelling a Purchase Intent

assuranceData[].AuthenticationContext.action
assuranceData[].additionalData
assuranceData[].authenticatedIdentities.data
assuranceData[].authenticatedIdentities.provider
assuranceData[].verificationEntity
assuranceData[].verificationEvents
assuranceData[].verificationType
deviceInformation.clientDeviceId
deviceInformation.country
deviceInformation.deviceData.manufacturer
deviceInformation.deviceData.model
deviceInformation.userAgent

Example: Cancelling a Purchase Intent

Request

{
  "clientCorrelationId": "cancelIntentRequest",
  "deviceInformation": {
    "userAgent": "appInstance.userAgent",
    "applicationName": "appInstance.applicationName",
    "fingerprintSessionId": "assuranceData.methodResults.dfpSessionId",
    "country": "US",
    "deviceData": {
      "type": "appInstance.type",
      "manufacturer": "appInstance.manufacturer",
      "brand": "appInstance.brand",
      "model": "appInstance.model"
    },
    "ipAddress": "192.168.1.1",
    "clientDeviceId": "appInstance.clientDeviceId"
  },
  "assuranceData": [
    {
      "verificationType": "CARDHOLDER",
      "verificationEntity": "10",
      "verificationEvents": [
        "01"
      ],
      "verificationMethod": "02",
      "verificationResults": "02",
      "verificationTimestamp": "1753165632",
      "AuthenticationContext": {
        "action": "AUTHENTICATE, REGISTER"
      },
      "authenticatedIdentities": {
        "data": "fidoResponse.fidoBlob",
        "provider": "VISA_PAYMENT_PASSKEY",
        "id": "fidoResponse.identifier"
      },
      "additionalData": ""
    }
  ]
}

Response to a Successful Request

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

Retrieve Payment Credentials

Use the information in this section to retrieve a customer's tokenized payment credentials. During checkout, your agents display a list of the customer's tokenized cards. When the customer chooses which listed card they want to pay with, your agents send a retrieve payment credentials
request. After retrieving the customer's tokenized card, your agent can use your payment system to complete the transaction.

Endpoints

Send a POST request to one of these endpoints. The

{instructionID}

is the instruction ID from the create a purchase request.

Production:

POST https://api.cybersource.com/acp/v1/instructions/{instructionID}
/credentials

Test:

POST https://apitest.cybersource.com/acp/v1/instructions/{instructionID}
/credentials

Required Fields for Retrieving Payment Credentials

clientCorrelationId
paymentInformation.instrumentIdentifier.id
tokenizedCard.number
transactionData[].clientReferenceInformation.code
transactionData[].merchantInformation.merchantDescriptor.country
transactionData[].merchantInformation.merchantDescriptor.url
transactionData[].merchantInformation.merchantName
transactionData[].orderInformation.amountDetail.currency
transactionData[].orderInformation.amountDetail.totalAmount

Additional Information

For complete descriptions of the request fields, see the Retrieve payment credentials section in the Intelligent Commerce API Hub.

Optional Fields for Retrieving Payment Credentials

transactionData[].acquirerInformation.merchantId¹
transactionData[].agreementInformation[].id
transactionData[].deliveryMethod
transactionData[].merchantInformation.domainName
transactionData[].merchantInformation.language
transactionData[].merchantLocale
transactionData[].merchantOrderId
transactionData[].orderInformation.amountDetail. discountAmount
transactionData[].orderInformation.amountDetail.order. handlingAmount
transactionData[].orderInformation.amountDetail.order. shippingAmount
transactionData[].orderInformation.amountDetail. settlementAmount
transactionData[].orderInformation.amountDetail. settlementcurrency
transactionData[].orderInformation.amountDetail. subTotalAmount
transactionData[].orderInformation.amountDetail. taxAmount
transactionData[].paymentOptions.dpaDynamicDataTtlMinutes
transactionData[].paymentOptions.dynamicDataType
transactionData[].paymentServiceproviderName
transactionData[].products[].additionalInfo[].key
transactionData[].products[].additionalInfo[].value
transactionData[].products[].policies.cancellationPolicy
transactionData[].products[].policies.discountAndPromotions
transactionData[].products[].policies.disputePolicy
transactionData[].products[].policies.propertyName
transactionData[].products[].policies.refundPolicy
transactionData[].products[].policies.shippingPolicy
transactionData[].products[].policies.termsAndConditions
transactionData[].products[].productId
transactionData[].products[].productName
transactionData[].products[].productUrl
transactionData[].products[].quantity
transactionData[].products[].transactionAmount.discount
transactionData[].products[].transactionAmount.shippingAndHandling
transactionData[].products[].transactionAmount.subTotal
transactionData[].products[].transactionAmount.tax
transactionData[].products[].transactionAmount.transactionAmount
transactionData[].products[].transactionAmount.transactionCurrencyCode
transactionData[].products[].unitPrice.amount
transactionData[].products[].unitPrice.currency
transactionData[].shippingAddress.addressId¹
transactionData[].shippingAddress.city¹
transactionData[].shippingAddress.countryCode
transactionData[].shippingAddress.createTime
transactionData[].shippingAddress. deliveryContactDetails. contactEmailAddress
transactionData[].shippingAddress. deliveryContactDetails. contactFullName
transactionData[].shippingAddress.deliveryContactDetails.contactPhoneNumber.countryCode
transactionData[].shippingAddress. deliveryContactDetails. contactPhoneNumber. numberIsVoiceOnly
transactionData[].shippingAddress. deliveryContactDetails. contactPhoneNumber. phoneNumber
transactionData[].shippingAddress. deliveryContactDetails. instructions
transactionData[].shippingAddress.lastUsedTime
transactionData[].shippingAddress.line1¹
transactionData[].shippingAddress.line2
transactionData[].shippingAddress.line3
transactionData[].shippingAddress.name
transactionData[].shippingAddress.state¹
transactionData[].shippingAddress.zip¹
transactionData[].transactionType

Example: Retrieving Payment Credentials

Request

{
  "clientCorrelationId": "retrievePaymentCredentialsRequest",
  "paymentInformation": {
    "instrumentIdentifier": {
      "id": "7019989999909760770"
    }
  },
  "tokenizedCard": {
    "number": "15602cf86c70b8b63297134292ec5801"
  },
  "transactionData": [
    {
      "clientReferenceInformation": {
        "code": "transactionDatatransactionReferenceId"
      },
      "agreementInformation": [
        {
          "id": "d48ac10b-58cc-4372-a567-0e02b2c3d489"
        }
      ],
      "acquirerInformation": {
        "merchantId¹": "transactionDatamerchantId"
      },
      "transactionType": "PURCHASE",
      "orderInformation": {
        "amountDetail": {
          "totalAmount": "100",
          "currency": "USD",
          "settlementAmount": "transactionDatatransactionAmounttransactionAmount",
          "settlementcurrency": "USD",
          "subTotalAmount": "100",
          "taxAmount": "100",
          "discountAmount": "100",
          "order": {
            "shippingAmount": "13",
            "handlingAmount": "transactionDatatransactionAmountshippingAndHandling"
          }
        }
      },
      "paymentServiceproviderName": "",
      "merchantOrderId": "d48ac10b-58cc-4372-a567-0e02b2c3d489",
      "shippingAddress": {
        "addressId¹": "",
        "name": "",
        "line1¹": "123 Main St",
        "line2": "Apt 1",
        "line3": "",
        "city¹": "San Francisco",
        "state¹": "CA",
        "countryCode": "US",
        "zip¹": "94105",
        "createTime": "1735690745",
        "lastUsedTime": "1735690745",
        "deliveryContactDetails": {
          "contactFullName": "",
          "contactEmailAddress": "",
          "contactPhoneNumber": {
            "countryCode": "",
            "phoneNumber": "",
            "numberIsVoiceOnly": "true"
          },
          "instructions": ""
        }
      },
      "merchantInformation": {
        "merchantName": "John Doe",
        "merchantDescriptor": {
          "country": "US",
          "url": "transactionDatashippingAddressmerchantUrl"
        },
        "domainName": "transactionDatamerchantDomain",
        "language": "en_US"
      },
      "deliveryMethod": "ADDRESS_ON_FILE",
      "paymentOptions": {
        "dpaDynamicDataTtlMinutes": "10080",
        "dynamicDataType": "TAVV"
      },
      "merchantLocale": "en_US",
      "products": [
        {
          "productId": "1234",
          "productName": "Balloons",
          "quantity": "10",
          "unitPrice": {
            "currency": "USD",
            "amount": "100.00"
          },
          "transactionAmount": {
            "transactionAmount": "100.00",
            "transactionCurrencyCode": "USD",
            "subTotal": "10.00",
            "tax": "1.10",
            "shippingAndHandling": "6.00",
            "discount": "6.00"
          },
          "productUrl": "",
          "policies": {
            "termsAndConditions": "",
            "cancellationPolicy": "",
            "refundPolicy": "",
            "disputePolicy": "",
            "shippingPolicy": "",
            "discountAndPromotions": "",
            "propertyName": ""
          },
          "additionalInfo": [
            {
              "key": "color",
              "value": "red"
            }
          ]
        }
      ]
    }
  ]
}

Response to a Successful Request

{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "transactionId": "1-5C8B7367EC00114ddb4b-f06a-0bff-7430-18d285223901",
  "status": "COMPLETED"
}

Confirm Transaction Events

Use the information in this section to verify when a transaction is complete. After your agents use your customer's tokenized card and your payment system to process a transaction, your agents can send the confirm transaction events
request to know when a payment is done processing.

A successful payment is indicated by the

COMPLETED

status in the

status

response field. After verifying the transaction is complete, you can confirm the purchase with the customer.

Endpoints

Send a POST request to one of these endpoints. The

{instructionID}

is the instruction ID from the create a purchase request.

Production:

POST https://api.cybersource.com/acp/v1/instructions/{instructionID}
/confirmations

Test:

POST https://apitest.cybersource.com/acp/v1/instructions/{instructionID}
/confirmations

Required Fields for Confirming Transaction Events

clientCorrelationId
transactionData[].clientReferenceInformation.code
transactionData[].merchantInformation.merchantDescriptor.country
transactionData[].merchantInformation.merchantDescriptor.url
transactionData[].merchantInformation.merchantName
transactionData[].orderInformation.amountDetail.currency
transactionData[].orderInformation.amountDetail.totalAmount

Additional Information

For complete descriptions of the request fields, see the Confirm transaction events section in the Intelligent Commerce API Hub.

Optional Field for Confirming Transaction Events

transactionData[].type

Example: Confirming Transaction Events

Request

{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "transactionData": [
    {
      "clientReferenceInformation": {
        "code": "transactionDatatransactionReferenceId"
      },
      "acquirerInformation": {},
      "type": "PURCHASE",
      "orderInformation": {
        "amountDetail": {
          "totalAmount": "100.00",
          "currency": "USD"
        }
      },
      "merchantInformation": {
        "merchantName": "Test Merchant",
        "merchantDescriptor": {
          "country": "US",
          "url": "https://example.com"
        }
      }
    }
  ]
}

Response to a Successful Request

{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "transactionId": " ",
  "status": "COMPLETED",
  "signedPayload": "jws-signed-payload"
}

Agentic Commerce Platform Developer Guide

Recent Revisions to This Document

25.09.01

Introduction to Intelligent Commerce

Benefits

Customer Purchase Intent Examples

Requirements to Support Intelligent Commerce

Overview of Intelligent Commerce Requests

Figure:

Complete a Purchase Workflow

Figure:

Endpoints

Enroll a Card

Endpoints

Required Fields for Enrolling a Card

Additional Information

Optional Fields for Enrolling a Card

Example: Enrolling a Card

Initiate a Purchase Intent

Endpoints

Required Fields for Initiating a Purchase Intent

Additional Information

Optional Fields for Initiating a Purchase Intent

Example: Initiating a Purchase Intent

Follow-On Requests

Update a Purchase Intent

Endpoints

Required Fields for Updating a Purchase Intent

Additional Information

Optional Fields for Updating a Purchase Intent

Example: Updating a Purchase Intent

Cancel a Purchase Intent

Endpoints

Required Fields for Cancelling a Purchase Intent

Additional Information

Optional Fields for Cancelling a Purchase Intent

Example: Cancelling a Purchase Intent

Retrieve Payment Credentials

Endpoints

Required Fields for Retrieving Payment Credentials

Additional Information

Optional Fields for Retrieving Payment Credentials

Example: Retrieving Payment Credentials

Confirm Transaction Events

Endpoints

Required Fields for Confirming Transaction Events

Additional Information

Optional Field for Confirming Transaction Events

Example: Confirming Transaction Events

Introduction to `Intelligent Commerce`

Requirements to Support `Intelligent Commerce`

Overview of `Intelligent Commerce` Requests