CyberSource Unified Checkout Capture Context API
The Unified Checkout Capture Context API from CyberSource — 1 operation(s) for unified checkout capture context.
OpenAPI Specification
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 Unified Checkout Capture Context API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Unified Checkout Capture Context
externalDocs:
description: Find out more
url: https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-intro.html
paths:
/up/v1/capture-contexts:
post:
tags:
- Unified Checkout Capture Context
summary: Generate Unified Checkout Capture Context
description: 'Unified Checkout is a powerful product within the Digital Acceptance Suite. Unified Checkout is designed to assist merchants with the adoption and inclusion of digital payments within their payment acceptance page. With Unified Checkout Integration you can add digital payment methods to create familiar, convenient and seamless payment experiences that are designed to reduce checkout friction and increase conversions.
Click to Pay Drop-in UI is built on the Unified Checkout platform.
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). For examples on how to integrate Unified Checkout within your webpage please see our [GitHub Unified Checkout Samples](https://github.com/CyberSource/cybersource-unified-checkout-sample-java).
Generate Unified Checkout Capture Context
Generate a one-time use capture context used for the invocation of Unified Checkout. The Request wil contain all of the parameters for how Unified Checkout will operate within a client webpage. The resulting payload will be a JWT signed object that can be used to initiate Unified Checkout or Click to Pay Drop-in UI within a web page'
operationId: generateUnifiedCheckoutCaptureContext
x-devcenter-metaData:
firstLevelApiLifeCycle: new
secondLevelApiLifeCycle: hidden
apiLifeCycle: hidden
categoryTag: Unified_Checkout
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-intro.html
disableProcessorDropDown: true
produces:
- application/jwt
parameters:
- in: body
name: generateUnifiedCheckoutCaptureContextRequest
required: true
schema:
type: object
properties:
clientVersion:
type: string
example: '0.34'
maxLength: 60
description: Specify the version of Unified Checkout that you want to use.
targetOrigins:
type: array
items:
type: string
example: https://yourCheckoutPage.com
description: "The [target origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) of the website on which you will be launching Unified Checkout is defined by the scheme (protocol), hostname (domain) and port number (if used). \n\nYou must use https://hostname (unless you use http://localhost)\nWildcards are NOT supported. Ensure that subdomains are included.\nAny valid top-level domain is supported (e.g. .com, .co.uk, .gov.br etc)\n\nExamples:\n - https://example.com\n - https://subdomain.example.com\n - https://example.com:8080<br><br>\n\nIf you are embedding within multiple nested iframes you need to specify the origins of all the browser contexts used, for example:\n\n targetOrigins: [\n \"https://example.com\",\n \"https://basket.example.com\",\n \"https://ecom.example.com\"\n ]\n"
allowedCardNetworks:
type: array
items:
type: string
maxLength: 30
example:
- VISA
- MASTERCARD
description: "The list of card networks you want to use for this Unified Checkout transaction.\n\nUnified Checkout currently supports the following card networks:\n - VISA\n - MASTERCARD\n - AMEX\n - CARNET\n - CARTESBANCAIRES\n - CUP\n - DINERSCLUB\n - DISCOVER\n - EFTPOS\n - ELO\n - JAYWAN\n - JCB\n - JCREW\n - KCP\n - MADA\n - MAESTRO\n - MEEZA\n - PAYPAK\n - UATP\n"
allowedPaymentTypes:
type: array
items:
type: string
description: "The payment types that are allowed for the merchant. \n\nPossible values when launching Unified Checkout:\n - APPLEPAY\n - CHECK\n - CLICKTOPAY\n - GOOGLEPAY\n - PANENTRY \n - PAZE <br><br>\n\nUnified Checkout supports the following Buy Now, Pay Later (BNPL) payment methods:\n - AFTERPAY<br><br>\n\nUnified Checkout supports the following Online Bank Transfer payment methods:\n - Bancontact (BE)\n - DragonPay (PH)\n - iDEAL (NL)\n - Multibanco (PT)\n - MyBank (IT, BE, PT, ES)\n - Przelewy24|P24 (PL)\n - Tink Pay By Bank (GB)<br><br>\n\n Unified Checkout supports the following Post-Pay Reference payment methods:\n - Konbini (JP)<br><br>\n\nPossible values when launching Click To Pay Drop-In UI:\n- CLICKTOPAY <br><br>\n\n**Important:** \n - CLICKTOPAY only available for Visa, Mastercard and AMEX for saved cards.\n - Visa and Mastercard will look to tokenize using network tokenization for all Click to Pay requests. Click to Pay uses Click to Pay token requester IDs and not the merchant's existing token requester.\n - Apple Pay, Google Pay, Check, and Paze can be used independently without requiring PAN entry in the allowedPaymentTypes field.<br><br>\n\n**Managing Google Pay Authentication Types**\nWhen you enable Google Pay on Unified Checkout you can specify optional parameters that define the types of card authentication you receive from Google Pay.<br><br>\n\n**Managing Google Pay Authentication Types**\nWhere Click to Pay is the payment type selected by the customer and the customer manually enters their card, the option to enroll their card in Click to Pay will be auto-checked if this field is set to \"true\". \n\nThis is only available where the merchant and cardholder are based in the following countries and the billing type is set to \"FULL\" or \"PARTIAL\".\n - UAE\n - Argentina\n - Brazil\n - Chile\n - Colombia\n - Kuwait\n - Mexico\n - Peru\n - Qatar\n - Saudi Arabia\n - Ukraine\n - South Africa<br><br>\n\nIf false, this is not present or not supported in the market. Enrollment in Click to Pay is not checked for the customer when completing manual card entry.\n"
country:
type: string
example: US
maxLength: 2
description: "Country the purchase is originating from (e.g. country of the merchant). \nUse the two-character ISO Standard\n"
locale:
type: string
example: en_US
description: 'Localization of the User experience conforming to the ISO 639-1 language standards and two-character ISO Standard Country Code.
Please refer to list of [supported locales through Unified Checkout](https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-appendix-languages.html)
'
buttonType:
type: string
example: null
description: 'Changes the label on the payment button within Unified Checkout .<br><br>
Possible values:
- ADD_CARD
- CARD_PAYMENT
- CHECKOUT
- CHECKOUT_AND_CONTINUE
- DEBIT_CREDIT
- DONATE
- PAY
- PAY_WITH_CARD
- SAVE_CARD
- SUBSCRIBE_WITH_CARD<br><br>
This is an optional field,
'
captureMandate:
type: object
properties:
billingType:
type: string
example: FULL
maxLength: 25
description: 'Configure Unified Checkout to capture billing address information.
Possible values:
- FULL: Capture complete billing address information.
- PARTIAL: Capture first name, last name, country and postal/zip code only.
- NONE: Capture only first name and last name.
'
requestEmail:
type: boolean
description: "Configure Unified Checkout to capture customer email address.\n\nPossible values:\n - True\n - False\n"
requestPhone:
type: boolean
description: 'Configure Unified Checkout to capture customer phone number.
Possible values:
- True
- False
'
requestShipping:
type: boolean
description: 'Configure Unified Checkout to capture customer shipping details.
Possible values:
- True
- False
'
shipToCountries:
type: array
description: "List of countries available to ship to. \nUse the two-character ISO Standard Country Codes.\n"
items:
type: string
example: US
maxLength: 2
showAcceptedNetworkIcons:
type: boolean
description: 'Configure Unified Checkout to display the list of accepted card networks beneath the payment button
Possible values:
- True
- False
'
showConfirmationStep:
type: boolean
description: 'Configure Unified Checkout to display the final confirmation screen when using Click to Pay.<br>
Where ''BillingType''= NONE and ''requestShipping''= FALSE and the customer is using an existing Click to Pay card as their chosen payment method, a final confirmation screen can be removed allowing the customer to check out as soon as they have selected their payment method from within their Click to Pay card tray.
Possible values:
- True
- False
'
requestSaveCard:
type: boolean
description: "Configure Unified Checkout to display the \"Save card for future use\" checkbox.<br>\n\nConfigurable check box that will show in a Manual card entry flow to allow a Cardholder to give consent to store their manually entered credential with the Merchant that they are paying.<br> \nApplicable when manually entering the details and not enrolling in Click to Pay.\n\nPossible values:\n - True \n - False<br><br>\n\n**Use Cases:**\n\n**Offer consumers option to save their card in Unified Checkout:** \n- Include the captureMandate.requestSaveCard field in the capture context request and set it to true.\n- When set to true, this will show a checkbox with the message 'Save card for future use' in Unified Checkout.\n- When selected this provides a response in both the Transient Token and Get Credentials API response.<br><br>\n\n**Do not offer consumers the option to save their card in Unified Checkout:** \n- Include the captureMandate.requestSaveCard field in the capture context request and set it to false OR omit the field from the capture context request.\n- When set to false, the save card option is not shown to consumers when manually entering card details.\n"
comboCard:
type: boolean
description: "Configure Unified Checkout to display combo card at checkout.<br>\n\nA combo debit/credit card is a single card that functions both as a Debit/Credit card. \nUnified Checkout / Click to Pay Drop-in UI allows the Cardholder to choose whether they would like the transaction to be paid for using either debit or credit card.\n**Important:** This is applicable to Visa cards only.\n\nPossible values:\n- True \n- False<br><br>\n\n**Use Cases:**\n\n**Offer Combo Card at Checkout:** \n- Include the captureMandate.comboCard field in the capture context request and set it to true.\n- When set to true, Combo Card selection is shown at checkout <br><br>\n\n**Do not offer Combo Card at Checkout:** \n- Include the captureMandate.comboCard field in the capture context request and set it to false OR omit the field from the capture context request.\n- The Combo Card selection is not shown at checkout.\n"
CPF:
type: object
properties:
required:
type: boolean
description: "Configure Unified Checkout to display and capture the CPF number (Cadastro de Pessoas Físicas). The CPF number is a unique 11-digit identifier issued to Brazilian citizens and residents for tax purposes.\n\nPossible values:\n- True\n- False<br><br>\n\nThis field is optional. \nIf set to true the field is required.\nIf set to false the field is optional.\nIf the field is not included in the capture context then it is not captured.<br><br>\n\n**Important:**\n - If PANENTRY is specified in the allowedPaymentTypes field, the CPF number will be displayed in Unified Checkout regardless of what card number is entered.\n - If CLICKTOPAY is specified in the allowedPaymentTypes field, the CPF number will be displayed in Unified Checkout only when a Visa Click To Pay card is entered.\n"
completeMandate:
type: object
description: "The completeMandate object is designed to provide instructions for orchestrating payment services. Unified Checkout is capable of orchestrating a number of services on your behalf.<br><br> \nBy providing this field in the capture context Unified Checkout will initiate services on your behalf from the browser, simplifying your integration.\n"
properties:
type:
type: string
example: AUTH
maxLength: 25
description: "This field is used to indicate how a payment should be processed.\n\nPossible values:\n- AUTH: Use this value when you want to authorize a payment within Unified Checkout without capturing it immediately. Payment types that initiate an immediate transfer of funds are NOT allowed. If a capture context request includes a payment type incompatible with this mode, a 400 error will be returned. A merchant would need to perform their own capture via API where applicable.<br><br> \n- CAPTURE: Use this value when you want to perform a sale within Unified Checkout and capture the payment immediately during the transaction. Note: Some payment types may return a PENDING status, requiring an additional status check call to determine the final outcome of the payment.<br><br>\n- PREFER_AUTH: Use this value to offer multiple alternative payment options during the Unified Checkout experience. This option authorizes the payment without immediate capture, where available. It will perform a \"CAPTURE\" where an \"AUTH\" is not allowed by the payment type. Transactions can be AUTHORIZED, CAPTURED, or PENDING. If an \"AUTH\" is performed, a merchant would need to perform their own capture via API where applicable.\n"
tms:
type: object
description: 'Configure Unified Checkout to create a TMS token at the end of the payment journey
'
properties:
tokenCreate:
type: boolean
example: true
description: "Use this when you want to create a token from the card/bank data in your payment request. \n\nPossible values:\n - True\n - False<br><br>\n"
tokenTypes:
type: array
items:
type: string
maxLength: 30
example:
- CUSTOMER
description: 'Cybersource tokens types you are performing a create on.
If not supplied the default token type for the merchants token vault will be used.
Possible values:
- Customer
- paymentInstrument
- instrumentIdentifier
- shippingAddress
'
decisionManager:
type: boolean
description: "Configure Unified Checkout to determine whether Decision Manager is invoked during service orchestration.\n\nPossible values:\n - True\n - False<br><br>\n\nSetting this value to True indicates that device fingerprinting will be executed to add additional information for risk service\nSetting this value to False (or not provided) indicates that you do not wish to run device fingerprinting and skip decision manager services.\n"
consumerAuthentication:
type: boolean
description: "Configure Unified Checkout to determine whether Consumer Authentication is invoked during service orchestration.\n\nPossible values:\n - True\n - False<br><br>\n\nSetting this value to True will attempt to perform authentication using the Payer Authentication Service.\nSetting this value to False (or not provided) indicates that you do not wish to perform authentication using the Payer Authentication Service.\n"
transientTokenResponseOptions:
type: object
properties:
includeCardPrefix:
type: boolean
description: "Use the transientTokenResponseOptions.includeCardPrefix field to choose your preferred card number prefix length: 6-digit, 8-digit, or no card number prefix.\n\nPossible values:\n- True\n- False<br><br>\n\nTo select the type of card number prefix:\n- No field included: A 6-digit prefix is returned (default)\n- True: An 8-digit prefix is returned\n- False: No prefix is returned<br><br>\n\nThe following conditions apply:\n- 8-digit card number prefixes only apply to Discover, JCB, Mastercard, UnionPay, and Visa brands with 16-digit card numbers or more.\n- Any card with less than 16-digit numbers will return a 6-digit prefix even when the transientTokenResponseOptions.includeCardPrefix field is set to true.\n- Any card brand other than Discover, JCB, Mastercard, UnionPay, or Visa will return a 6-digit prefix even when the transientTokenResponseOptions.includeCardPrefix field is set to true.\n- If any card brand is co-branded with Discover, JCB, Mastercard, UnionPay, or Visa, an 8-digit prefix will be returned if the transientTokenResponseOptions.includeCardPrefix field is set to true.<br><br>\n\n**Important:** \nIf your application does NOT require a card number prefix for routing or identification purposes, set the transientTokenResponseOptions.includeCardPrefix field to False. This will minimize your personal data exposure.\n"
data:
type: object
properties:
orderInformation:
type: object
properties:
amountDetails:
type: object
properties:
totalAmount:
type: string
example: 21
description: 'This field defines the total order amount.
'
currency:
type: string
example: USD
description: 'This field defines the currency applicable to the order.
'
surcharge:
type: object
properties:
amount:
type: string
example: 2.5
description: 'This field defines the surcharge amount applicable to the order.
'
discountAmount:
type: string
example: 2
description: 'This field defines the discount amount applicable to the order.
'
subTotalAmount:
type: string
example: 5
description: 'This field defines the sub total amount applicable to the order.
'
serviceFeeAmount:
type: string
example: 5
description: 'This field defines the service fee amount applicable to the order.
'
taxAmount:
type: string
example: 10
description: 'This field defines the tax amount applicable to the order.
'
taxDetails:
type: object
properties:
taxId:
type: string
example: 1234
maxLength: 20
description: 'This field defines the tax identifier/registration number
'
type:
type: string
example: N
maxLength: 1
description: 'This field defines the Tax type code (N=National, S=State, L=Local etc)
'
billTo:
type: object
properties:
address1:
type: string
example: 277 Park Avenue
maxLength: 60
description: 'Payment card billing street address as it appears on the credit card issuer''s records.
'
address2:
type: string
example: 50th Floor
maxLength: 60
description: 'Used for additional address information. For example: _Attention: Accounts Payable_
Optional field.
'
address3:
type: string
example: Desk NY-50110
maxLength: 60
description: Additional address information (third line of the billing address)
address4:
type: string
example: address4
maxLength: 60
description: 'Additional address information (fourth line of the billing address)
'
administrativeArea:
type: string
example: NY
maxLength: 20
description: 'State or province of the billing address. Use the [State, Province, and Territory Codes for the United States and Canada](https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf).
'
buildingNumber:
type: string
example: buildingNumber
maxLength: 256
description: 'Building number in the street address.
'
country:
type: string
example: US
maxLength: 2
description: 'Payment card billing country. Use the two-character [ISO Standard Country Codes](http://apps.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf).
'
district:
type: string
example: district
maxLength: 50
description: 'Customer''s neighborhood, community, or region (a barrio in Brazil) within the city or municipality
'
locality:
type: string
example: New York
maxLength: 50
description: 'Payment card billing city.
'
postalCode:
type: string
example: 10172
maxLength: 10
description: 'Postal code for the billing address. The postal code must consist of 5 to 9 digits.
'
company:
type: object
properties:
name:
type: string
example: Visa Inc
maxLength: 60
description: Name of the customer's company.
address1:
type: string
example: 277 Park Avenue
maxLength: 60
description: 'Payment card billing street address as it appears on the credit card issuer''s records.
'
address2:
type: string
example: 50th Floor
maxLength: 60
description: 'Used for additional address information. For example: _Attention: Accounts Payable_
Optional field.
'
address3:
type: string
example: Desk NY-50110
maxLength: 60
description: 'Additional address information (third line of the billing address)
Optional field.
'
address4:
type: string
example: address4
maxLength: 60
description: 'Additional address information (fourth line of the billing address)
Optional field
'
administrativeArea:
type: string
example: NY
maxLength: 20
description: 'State or province of the billing address. Use the [State, Province, and Territory Codes for the United States and Canada](https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf).
'
country:
type: string
example: US
maxLength: 2
description: 'Payment card billing country. Use the two-character [ISO Standard Country Codes](http://apps.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf).
'
buildingNumber:
type: string
example: buildingNumber
maxLength: 256
description: 'Building number in the street address.
'
district:
type: string
example: district
maxLength: 50
description: 'Customer''s neighborhood, community, or region (a barrio in Brazil) within the city or municipality
'
locality:
type: string
example: New York
maxLength: 50
description: 'Payment card billing city.
'
postalCode:
type: string
example: 10172
maxLength: 10
description: 'Postal code for the billing address. The postal code must consist of 5 to 9 digits.
'
email:
type: string
example: john.doe@visa.com
maxLength: 255
description: 'Customer''s email address, including the full domain name.
'
firstName:
type: string
example: John
maxLength: 60
description: Customer's first name. This name must be the same as the name on the card
lastName:
type: string
example: Doe
maxLength: 60
description: 'Customer''s last name. This name must be the same as the name on the card.
'
middleName:
type: string
example: F
maxLength: 60
description: 'Customer''s middle name.
'
nameSuffix:
type: string
example: Jr
maxLength: 60
description: 'Customer''s name suffix.
'
title:
type: string
example: Mr
maxLength: 60
description: 'Title.
'
phoneNumber:
type: string
example: 1234567890
description: 'Customer''s phone number.
'
phoneType:
type: string
example: day
description: 'Customer''s phone number type.
#### For Payouts:
This field may be sent only for FDC Compass.
Possible Values:
* day
* home
* night
* work
'
shipTo:
type: object
properties:
address1:
type: string
example: CyberSource
maxLength: 60
description: 'First line of the shipping address.
'
address2:
type: string
example: Victoria House
maxLength: 60
# --- truncated at 32 KB (122 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-unified-checkout-capture-context-api-openapi.yml