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
- Call the/sessionsendpoint to generate a server to server capture context.
- Define the targetOrigin of the Microform webpage.
- Define the signed fields for theCheckout API.
- Define the unsigned fields of theCheckout API.
- Within the browser:
- Invoke the microform using the capture context.
- Capture the response transient token.
- Invoke theCheckout APIvia HTTP POST.
Requesting a Capture Context
In order to support Microform transient tokens through the Checkout API, we created a
new endpoint:
POST
.
This new endpoint produces a capture context that is compatible with both Microform
and the Checkout API./microform/v2/sessions
This endpoint:
- Replaces the need for a HMAC-SHA256 signature in Checkout API initialization
Microform Integration
0.11 SetupFollow 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.IMPORTANTTo use a transient token with the Checkout API, you must, at a minimum, include thetransient_tokenfield 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"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.compayer_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 withMicroform Integration0.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 byMicroform Integration0.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="posthttps://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>