Use the
Digital Accept
Checkout API
in conjunction with Microform technologies to provide a cohesive PCI SAQ A embedded payment application within your merchant e-commerce page. The
Digital Accept
Checkout API
provides access to payment processing and additional value-added services directly from the browser.
This approach lets the integrator manage the entire consumer experience with the exception of two Microform fields which are embedded within the page to capture the PAN and/or CVV data in a secure fashion. Microform technology embeds invisible iFrames within a merchant’s payment page for the secure capture of sensitive payment information.
Basic Flow
  1. Call the
    /sessions
    endpoint to generate a server to server capture context.
    1. Define the targetOrigin of the Microform webpage.
    2. Define the signed fields for the
      Checkout API
      .
    3. Define the unsigned fields of the
      Checkout API
      .
  2. Within the browser:
    1. Invoke the microform using the capture context.
    2. Capture the response transient token.
    3. Invoke the
      Checkout API
      via HTTP POST.

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 one of the following methods:

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"
https://www.smartpayfuse-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"
https://www.smartpayfuse-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
payer_auth_vi_2.1.0_su@nab.com.au
", "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"
https://www.smartpayfuse-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"
https://www.smartpayfuse-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" } }

Invoking the Checkout API

Once you have the transient token provided, the next step is to pass it to the Checkout API.
Checkout API.
Make the request to the Checkout API from the customer's browser, using a standard form post (
application/x-www-form-urlencoded
) request.
If you are using the Checkout API inside an iframe, to avoid issues with third-party cookies not being supported, ensure that you use an iframe endpoint
iframe endpoint
.

New Checkout API Request Fields

capture_context
The same capture context used with
Microform Integration
0.11.
This field is not supported with Hosted Checkout.
Capture contexts are valid for 15 minutes only. The Checkout API will not accept expired capture contexts.
Format: String
Required if you want to supply a transient token.
transient_token
The transient token JWT provided by
Microform Integration
0.11. If you pass this field, you must also pass the corresponding capture context (
capture
_context) must also be supplied.
You do not need to validate the transient token signature. The Checkout API will do this for you.

Example

The following example shows a request that calls the Secure Acceptance Checkout API and creates a token.
<form id="sa-form" action="
https://secureacceptance.cybersource.com/silent/pay" method="post
https://secureacceptance.smartpayfuse-merchant.com/silent/pay" method="post
"> <input type="hidden" id="capture_context" name="capture_context" value="eyJraWQiOi...HHWuACdnLQ" /> <input type="hidden" id="transient_token" name="transient_token" value="" /> <-- Optional unsigned fields --> <input type="text" name="bill_to_forename value="" /> <input type="text" name="bill_to_surname value="" /> <input type="text" name="bill_to_phone value="" /> <input type="text" name="bill_to_email value="" /> <input type="text" name="bill_to_address_line1 value="" /> <input type="text" name="bill_to_address_line2 value="" /> <input type="text" name="bill_to_address_city value="" /> <input type="text" name="bill_to_address_state value="" /> <input type="text" name="bill_to_address_postal_code value="" /> <input type="text" name="bill_to_address_country" value="" /> </form> <script type="text/javascript"> var captureContext = document.getElementById('capture_context').value; var flex = new Flex(captureContext); // Initialize Flex Microform ... payButton.addEventListener('click', function() { // Compiling MM & YY into optional parameters var options = { expirationMonth: document.querySelector('#expMonth').value, expirationYear: document.querySelector('#expYear').value }; microform.createToken(options, function(err, token) { if (err) { // handle error console.error(err); errorsOutput.textContent = err.message; } else { document.getElementById('transient_token').value = token; // No need to verify JWS document.getElementById('sa-form').submit(); } }); }); </script>