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/v1/sessions

. This new endpoint produces a capture context that is compatible with both Microform and the Checkout API.

This endpoint:

Replaces

POST /flex/v1/keys?format=JWT

for Microform.

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/v1/sessions

Production:

https://api.cybersource.com/microform/v1/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.

See the Checkout API documentation.

Always include these fields, which the Checkout API requires:

access_key
profile_id
preference_number
transaction_type
transaction_uuid

These 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:

To prevent data tampering.

If they have already been collected.

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"
            
     
             "
  ],
  "checkoutApiInitialization": {
    "field_a": "value_a",
    …
  }
}

An authorization using a transient token with unsigned billing details

{
  "targetOrigins": [
    "https://www.my-merchant-website.com"
  ],
  "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"
            
     
             "
    ],
    "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"
            
     
             "
    ],
    "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"
            
     
             "
    ],
    "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"
    }
}