On This Page
REST API

Requesting a Capture Context

In order to support Microform transient tokens through the Checkout API, we created a new endpoint:
POST
/microform/v2/sessions
. This new endpoint produces a capture context that is compatible with both Microform and the Checkout API.
This endpoint replaces the need for a HMAC-SHA256 signature in Checkout API initialization.
Microform Integration
 0.11 Setup
Follow the Setting Up the Client Side to initialize and trigger tokenization. (
createToken
).
Also, see this example checkout payment form.

Resource

Send an authenticated POST request to the
/sessions
 API:
  • Test:
    https://apitest.cybersource.com
    /microform/v2/sessions
  • Production:
    https://api.cybersource.com
    /microform/v2/sessions
Authenticate to the API using HTTP Signature or JSON Web Token (JWT) authentication. See the Getting Started with REST API developer guide for more information.

Required Fields

Always include the following fields:
targetOrigins
The merchant origin(s). For example,
https://example.com
.
Required to comply with CORS and CSP standards.
checkoutApiInitialization
This field contains Checkout API request fields.
Please refer to the Checkout API documentation.
Always include the following fields, which the Checkout API requires:
access_key
profile_id
preference_number
transaction_type
transaction_uuid
The following fields are not required, but if you do pass them, pass them inside the capture context:
amount
currency
ignore_avs
ignore_cvn
payment_token
override_custom_receipt_page
unsigned_field_names
If you wish to supply unsigned fields, then you must include this field in the capture context. This field is a comma-separated list of field names.
If you pass a field to the endpoint without listing it in this field, it will not result in an error. Instead, the field is ignored.
IMPORTANT
To use a transient token with the Checkout API, you must, at a minimum, include the
transient_token
 field inside this field.
Signed fields
Signed fields refer to those fields included in the capture context and which are thus signed by the
Microform Integration
 0.11.
Some reasons why fields are signed:
  1. To prevent data tampering.
  2. If they have already been collected.
  3. They do not fall under PCI scope. For example, the field that captures the card number falls under the PCI scope.
If you have an existing integration with the Checkout API, this is similar to how the
signed_field_names
 are used.
Unsigned fields
Unsigned fields refer to those fields not included in the capture context but which are supplied to the Checkout API.
These include fields which have not yet been collected, such as the billing address, the transient token, or may include fields which fall under PCI scope e.g.
card_number
.
Unsigned fields are not signed by the
Microform Integration
 0.11 and so are subject to tampering.

Examples

Include the fields in the request as follows:
{
  "targetOrigins": [
    "
https://www.cybersource-merchant.com"

            
     
             "
  ],
  "clientVersion": "v2.0",
  "checkoutApiInitialization": {
    "field_a": "value_a",
    …
  }
}
An authorization using a transient token with unsigned billing details
{
  "targetOrigins": [
    "https://www.my-merchant-website.com"
  ],
  "clientVersion": "v2.0",
  "checkoutApiInitialization": {
    "profile_id": "12341234-1234-1234-1234-123412341234",
    "access_key": "acce55acce55acce55acce55acce5500",
    "reference_number": "1611305732",
    "transaction_uuid": "1611305732-001",
    "transaction_type": "authorization",
    "currency": "USD",
    "amount": "100.00",
    "locale": "en-us",
    "unsigned_field_names": "transient_token,bill_to_forename,bill_to_surname,bill_to_phone,
     bill_to_email,bill_to_address_line1,bill_to_address_line2,bill_to_address_city,
     bill_to_address_state,bill_to_address_postal_code,bill_to_address_country"
  }
}
An authorization using a transient token with signed billing details
{
    "targetOrigins": [
        "
https://www.cybersource-merchant.com"

            
     
             "
    ],
    "clientVersion": "v2.0",
    "checkoutApiInitialization": {
        "profile_id": "12341234-1234-1234-1234-123412341234",
        "access_key": " acce55acce55acce55acce55acce5500",
        "reference_number": "1611305732",
        "transaction_uuid": "1611305732-001",
        "transaction_type": "authorization",
        "currency": "USD",
        "amount": "100.00",
        "locale": "en-us",
        "bill_to_forename": "Joe",
        "bill_to_surname": "Soap",
        "bill_to_phone": "07788888888",
        "bill_to_email": "
payer_auth_vi_2.1.0_su@cybersource.com
",
        "bill_to_address_line1": "1 My Apartment",
        "bill_to_address_line2": "20 My Street",
        "bill_to_address_city": "San Francisco",
        "bill_to_address_state": "CA",
        "bill_to_address_postal_code": "94043",
        "bill_to_address_country": "US",
        "unsigned_field_names": "transient_token"
    }
}
An authorization using a transient token with a payment token (Secure Storage or TMS)
{
    "targetOrigins": [
        "
https://www.cybersource-merchant.com"

            
     
             "
    ],
    "clientVersion": "v2.0",
    "checkoutApiInitialization": {
        "profile_id": "12341234-1234-1234-1234-123412341234",
        "access_key": " acce55acce55acce55acce55acce5500",
        "reference_number": "1611305732",
        "transaction_uuid": "1611305732-001",
        "transaction_type": "authorization",
        "currency": "USD",
        "amount": "100.00",
        "locale": "en-us",
        "payment_token": "0000000000000000",
        "unsigned_field_names": "transient_token"
    }
}
An authorization using a transient token with unsigned card type and expiry date fields
{
    "targetOrigins": [
        "
https://www.cybersource-merchant.com"

            
     
             "
    ],
    "clientVersion": "v2.0",
    "checkoutApiInitialization": {
        "profile_id": "12341234-1234-1234-1234-123412341234",
        "access_key": " acce55acce55acce55acce55acce5500",
        "reference_number": "1611305732",
        "transaction_uuid": "1611305732-001",
        "transaction_type": "authorization",
        "currency": "USD",
        "amount": "100.00",
        "locale": "en-us",
        "unsigned_field_names": "transient_token,card_type,card_expiry_date"
    }
}