Frontend Integration
Microform and Unified Checkout
The Microform and Unified Checkout methods use the same steps:
- Request the payment instructions from Cortex.
- Load the CyberSource JavaScript library that the instructions name.
- Show the card fields (Microform) or the card form (Unified Checkout), and get a transient token when the shopper submits the card.
- Post the transient token to Cortex to create the payment instrument.
Payment instructions
The requestpaymentinstructionsaction response contains these values for both methods:
{
"communication-instructions": {
"client-library": "<URL of the CyberSource JavaScript library>",
"client-library-integrity": "<integrity hash of the library>"
},
"payload": {
"capture-context": "<capture context JWT>"
}
}
client-library
The URL of the CyberSource JavaScript library for this session. Load the library from this URL and do not hardcode the URL or its integrity hash, because they can be different for each session. For an example, see Loading the library.
client-library-integrity
The Subresource Integrity hash of the library. The browser checks the library against this hash before it runs the script.
capture-context
A JWT that starts the CyberSource session, which you pass to the library. It expires 15 minutes after Cortex returns it, so request new payment instructions if the shopper has not submitted the card by then.
Loading the library
Each time you get the payment instructions, add a script element for the client-library URL to the page. Set the integrity attribute to client-library-integrity and the crossorigin attribute to anonymous. Wait for the script to load before you use the capture context. The Microform and Unified Checkout examples below call this function.
function loadClientLibrary(instructions) {
return new Promise((resolve, reject) => {
const script = document.createElement('script');
script.src = instructions['communication-instructions']['client-library'];
script.integrity = instructions['communication-instructions']['client-library-integrity'];
script.crossOrigin = 'anonymous';
script.onload = resolve;
script.onerror = reject;
document.head.appendChild(script);
});
}
Microform
Requesting the payment instructions
Submit the Cortex requestinstructionsform for the Microform payment method. The shopper's email must already be set, otherwise Cortex returns a NEEDINFO message. No fields need to be populated. The requestinstructionsform shows billing-address fields, but you can leave them empty. The response contains the payment instructions.
Showing the card fields
With Microform, the storefront keeps its own payment form, where CyberSource fields replace only the card number and the security code inputs. The storefront hosts the expiry date fields.
<form id="payment-form">
<label>Card number</label>
<div id="number-container"></div>
<label>Security code</label>
<div id="securityCode-container"></div>
<label for="expiration-month">Expiry month</label>
<input id="expiration-month" type="text" inputmode="numeric" placeholder="MM" autocomplete="cc-exp-month">
<label for="expiration-year">Expiry year</label>
<input id="expiration-year" type="text" inputmode="numeric" placeholder="YYYY" autocomplete="cc-exp-year">
<button type="submit">Save card</button>
</form>
async function startMicroform(instructions) {
await loadClientLibrary(instructions);
const flex = new Flex(instructions.payload['capture-context']);
const microform = flex.microform('card', {
styles: {
input: { 'font-size': '16px', 'font-family': 'sans-serif', color: '#1c2733' },
':focus': { color: '#0b5394' },
valid: { color: '#2f8f4e' },
invalid: { color: '#c0392b' }
}
});
const number = microform.createField('number', { placeholder: 'Card number' });
const securityCode = microform.createField('securityCode', { placeholder: '•••' });
number.load('#number-container');
securityCode.load('#securityCode-container');
document.getElementById('payment-form').addEventListener('submit', (event) => {
event.preventDefault();
const options = {
expirationMonth: document.getElementById('expiration-month').value,
expirationYear: document.getElementById('expiration-year').value
};
microform.createToken(options, (error, transientToken) => {
if (error) {
showError(error.message);
return;
}
createPaymentInstrument(transientToken);
});
});
}
This example is based on the Customer Form Card example in the CyberSource Microform Integration v2 examples. createPaymentInstrument and showError are your own functions. createPaymentInstrument posts the token to Cortex, as described in Creating the payment instrument below. The styles object styles the text inside the CyberSource fields. For the supported properties, see the CyberSource Microform Integration v2 styling reference.
Creating the payment instrument
Post the transient token to the Cortex paymentinstrumentform as transient-token, together with a display-name for the card and the shopper's billing address in billing-address. CyberSource needs the billing address to authorize the card, so if billing-address or one of its fields is missing, Cortex returns NEEDINFO messages and no payment instrument is created.
{
"payment-instrument-identification-form": {
"display-name": "Visa ending 1111",
"transient-token": "<transient token>"
},
"billing-address": {
"name": {
"given-name": "John",
"family-name": "Smith"
},
"address": {
"street-address": "123 Main Street",
"locality": "Vancouver",
"region": "BC",
"country-name": "CA",
"postal-code": "V5V4N1"
}
}
}
The plugin runs a zero dollar authorization on the card. If CyberSource authorizes it, the plugin saves the Token Management Service customer token that CyberSource returns as the payment instrument. If CyberSource returns no customer token, the plugin saves the third-party token instead.
Unified Checkout
Requesting the payment instructions
Submit the Cortex requestinstructionsform for the Unified Checkout payment method. The shopper's email must already be set. Set the shopper's two-letter country code in country, such as US or CA. The plugin sends it to CyberSource as the session country. It also combines it with the shopper's language for the session locale if CyberSource supports that locale, otherwise the session locale is en_US. If the email or the country is missing, Cortex returns NEEDINFO messages. The response contains the payment instructions.
Showing the card form
With Unified Checkout, the storefront shows a card form that CyberSource builds. Add two containers to the page, one for the payment button and one for the card form:
<div id="uc-buttons"></div>
<div id="uc-form"></div>
async function startUnifiedCheckout(instructions) {
await loadClientLibrary(instructions);
let client;
let checkout;
try {
client = await VAS.UnifiedCheckout(instructions.payload['capture-context']);
checkout = await client.createCheckout({ autoProcessing: false });
const transientToken = await checkout.mount({
paymentSelection: '#uc-buttons',
paymentScreen: '#uc-form'
});
await createPaymentInstrument(transientToken);
} catch (error) {
showError(error.message);
} finally {
if (checkout) {
checkout.destroy();
}
if (client) {
client.destroy();
}
}
}
This example is based on the examples in Loading the JavaScript Library in the CyberSource Unified Checkout developer guide. createPaymentInstrument and showError are your own functions. createPaymentInstrument posts the token to Cortex, as described in Creating the payment instrument below. Set autoProcessing to false, so that mount() resolves to the transient token when the shopper submits the card and Unified Checkout does not process a payment. Pass both div selectors to mount() to show the card form inline on the page, or pass only one selector to open it in a sidebar. The card form asks the shopper for the billing address. It also shows the steps set up in the Business Center, such as contact details and a review step. When you are done, call destroy() to remove the card form from the page. For the Business Center setup, see Setting up Unified Checkout.
Creating the payment instrument
Post the transient token to the Cortex paymentinstrumentform as transient-token, together with a display-name for the card.
{
"payment-instrument-identification-form": {
"display-name": "Visa ending 1111",
"transient-token": "<transient token>"
}
}
The plugin runs a zero dollar authorization on the card. If CyberSource authorizes it, the plugin saves the Token Management Service customer token that CyberSource returns as the payment instrument. If CyberSource returns no customer token, the plugin saves the third-party token instead.
Errors and expiry
Declined card. If CyberSource does not authorize the card, Cortex returns HTTP 409 with the
errormessageCybersource did not authorize the card.Itsdata.reasonfield holds the CyberSource reason code. No payment instrument is created, so ask the shopper for another card.Request rejected. If CyberSource rejects the request, for example because a field is missing, Cortex returns HTTP 409 with the
errormessageCybersource could not create a token for the card.Itsdata.reasonfield holds the CyberSource message. No payment instrument is created. For example:{ "messages": [ { "type": "error", "id": "payment.instrument.creation.failed", "debug-message": "Cybersource could not create a token for the card.", "data": { "reason": "Declined - The request is missing one or more fields: orderInformation.billTo.locality, orderInformation.billTo.address1" } } ] }Expired transient token. The transient token expires 15 minutes after the library issues it. After that, Cortex returns a structured error and no payment instrument is created. Request new payment instructions and ask the shopper to enter the card again.
Origin not allowed. If the storefront base URL is not in the configuration's
STOREFRONT_BASE_URLS, the card fields do not load, and CyberSource shows an origin error on the page.Missing email or country. The instructions request returns HTTP 409 with
needinfomessages, such asEmail is required.orCountry is required.Missing billing address (Microform). The payment instrument request returns HTTP 409 with the
needinfomessageBilling address is required.
Content Security Policy
If the storefront sets a Content Security Policy, allow the CyberSource JavaScript library from the client-library URL.
Secure Acceptance (deprecated)
warning
The Direct Post and Hosted Page payment methods use Secure Acceptance, which CyberSource is retiring. See Migrating from Secure Acceptance.
Control Data and Payload Data
When the shopper wants to create the payment instrument, CyberSource provides Cortex the instructions on how to create the payment instrument. The data returned has two sections, control data and payload data. Control data contains the CyberSource endpoint URL. For example, endpoint-href, returns the endpoint URL of https://secureacceptance.cybersource.com/silent/token/create. Payload data has the payment instrument specific information, such as:
transaction_type
The type of transaction, such as authorization, authorization-reversal, capture and credit.
amount
The amount of the purchase.
transaction_uuid
The transaction unique identifier.
signed_date_time
The date and time of the purchase.
reference_number
The unique identifier for the purchase.
currency
The three-character ISO currency code, such as CAD or USD.
payment_method
The way the shopper is paying. This must be in the form of card, echeck or PayPal.
bill_to_email
The shopper’s email address.
bill_to_address_line1
The first line of the shopper’s physical address.
bill_to_address_line2
The second line of the shopper’s physical address.
bill_to_address_city
The city name of the shopper’s physical address.
bill_to_address_state
The province or state of the shopper.
bill_to_address_country
The country the shopper resides in.
bill_to_address_postal_code
The shopper’s postal or zip code.
locale
The ISO language code to use for the storefront.
profile_id
The secured access profile id.
access_key
The secured access key.
unsigned_field_names
The fields where the signer does not have to sign.
signed_field_names
The fields where the signer must sign.
signature
The secure acceptance signature generation.
CyberSource Information Collection
On the payment page, CyberSource must collect the following fields:
- Cardholder first name (
bill_to_forename) - Cardholder last name (
bill_to_surname) - Card type code (
card_type): A three-digit code representing the credit card type. - Card number (
card_number): The credit card number. - Card expiry date (
card_expiry_date): The format must beMM-YYYY CCV/CVN(card_cvn): A three- or four-digit credit card verification number.
The following example is the request body, formed in HTML:
transaction_type=create_payment_token
&amount=0
&transaction_uuid=2225e9d2-1abd-476c-9d70-4118a4238d1e
&signed_date_time=2019-02-27T01%3A44%3A04Z
&reference_number=12345
¤cy=USD
&payment_method=card
&bill_to_forename=Jennifer
&bill_to_surname=Armstrong
&bill_to_email=jarmstrong%40elasticpath.com
&bill_to_phone=
&bill_to_address_line1=100+Ravine+Lane
&bill_to_address_city=Seattle
&bill_to_address_state=WA
&bill_to_address_country=US
&bill_to_address_postal_code=80001
&locale=en-us
&profile_id=elastic
&access_key=2cac14a982fb3d17b01fa196bb678d9c
&unsigned_field_names=card_type%2Ccard_number%2Ccard_expiry_date%2Ccard_cvn%2Cbill_to_forename%2Cbill_to_surname
&signed_field_names=transaction_type%2Camount%2Ctransaction_uuid%2Csigned_date_time%2Creference_number%2Ccurrency%2Cpayment_method%2Cbill_to_email%2Cbill_to_address_line1%2Cbill_to_address_city%2Cbill_to_address_state%2Cbill_to_address_country%2Cbill_to_address_postal_code%2Clocale%2Cprofile_id%2Caccess_key%2Cunsigned_field_names%2Csigned_field_names
&card_type=001
&card_number=4111111111111111
&card_expiry_date=12-2022
&card_cvn=005
&signature=0nw6wgOmB8IKy5ifCsnT9oDSYj8RvFQhw3OecwwNWMI
The following is an example of the response:
<html>
<head>
<title></title>
</head>
<body>
<form id="custom_redirect" action="http://localhost:8666/cybersource/receipt.jsp" accept-charset="UTF-8" method="post">
<input name="utf8" type="hidden" value="✓" />
<input type="hidden" name="req_card_number" id="req_card_number" value="xxxxxxxxxxxx1111" />
<input type="hidden" name="req_locale" id="req_locale" value="en-us" />
<input type="hidden" name="signature" id="signature" value="N+w+puhQ3srciW8avL7ADWxTfdJg/GNC6h29Yeke1Ro=" />
<input type="hidden" name="auth_trans_ref_no" id="auth_trans_ref_no" value="79533025YSEY2WIX" />
<input type="hidden" name="payment_token" id="payment_token" value="9909000238112653" />
<input type="hidden" name="req_bill_to_surname" id="req_bill_to_surname" value="Armstrong" />
<input type="hidden" name="req_bill_to_address_city" id="req_bill_to_address_city" value="Seattle" />
<input type="hidden" name="req_card_expiry_date" id="req_card_expiry_date" value="12-2022" />
<input type="hidden" name="req_bill_to_address_postal_code" id="req_bill_to_address_postal_code" value="80001" />
<input type="hidden" name="reason_code" id="reason_code" value="100" />
<input type="hidden" name="auth_amount" id="auth_amount" value="0.00" />
<input type="hidden" name="auth_response" id="auth_response" value="100" />
<input type="hidden" name="req_bill_to_forename" id="req_bill_to_forename" value="Jennifer" />
<input type="hidden" name="req_payment_method" id="req_payment_method" value="card" />
<input type="hidden" name="request_token" id="request_token" value="Ahj/7wSTKtrbc6uHfjdbESDdy1Zs2DJrZpxbLKvJsKNPwcBtPAVGn4OA2n6QAjYoZLoL3nNmMcgTkyra23Orh343WwAA/Dlj" />
<input type="hidden" name="auth_time" id="auth_time" value="2019-02-27T175326Z" />
<input type="hidden" name="decision_early_return_code" id="decision_early_return_code" value="9999999" />
<input type="hidden" name="req_amount" id="req_amount" value="0" />
<input type="hidden" name="req_bill_to_email" id="req_bill_to_email" value="jarmstrong@elasticpath.com" />
<input type="hidden" name="auth_avs_code_raw" id="auth_avs_code_raw" value="I1" />
<input type="hidden" name="transaction_id" id="transaction_id" value="5512900059666164103003" />
<input type="hidden" name="req_currency" id="req_currency" value="USD" />
<input type="hidden" name="req_card_type" id="req_card_type" value="001" />
<input type="hidden" name="decision" id="decision" value="ACCEPT" />
<input type="hidden" name="message" id="message" value="Request was processed successfully." />
<input type="hidden" name="signed_field_names" id="signed_field_names" value="transaction_id,decision,req_access_key,req_profile_id,req_transaction_uuid,req_transaction_type,req_reference_number,req_amount,req_currency,req_locale,req_payment_method,req_bill_to_forename,req_bill_to_surname,req_bill_to_email,req_bill_to_address_line1,req_bill_to_address_city,req_bill_to_address_state,req_bill_to_address_country,req_bill_to_address_postal_code,req_card_number,req_card_type,req_card_expiry_date,message,reason_code,auth_avs_code,auth_avs_code_raw,auth_response,auth_amount,auth_code,auth_trans_ref_no,auth_time,request_token,decision_early_return_code,decision_early_reason_code,decision_early_rcode,payment_token,signed_field_names,signed_date_time" />
<input type="hidden" name="req_transaction_uuid" id="req_transaction_uuid" value="e56d9383-ab59-454a-a5e3-4cfafde32241" />
<input type="hidden" name="auth_avs_code" id="auth_avs_code" value="X" />
<input type="hidden" name="auth_code" id="auth_code" value="888888" />
<input type="hidden" name="req_bill_to_address_country" id="req_bill_to_address_country" value="US" />
<input type="hidden" name="req_transaction_type" id="req_transaction_type" value="create_payment_token" />
<input type="hidden" name="req_access_key" id="req_access_key" value="2cac14a982fb3d17b01fa196bb678d9c" />
<input type="hidden" name="decision_early_reason_code" id="decision_early_reason_code" value="100" />
<input type="hidden" name="req_profile_id" id="req_profile_id" value="elastic" />
<input type="hidden" name="req_reference_number" id="req_reference_number" value="12345" />
<input type="hidden" name="req_bill_to_address_state" id="req_bill_to_address_state" value="WA" />
<input type="hidden" name="decision_early_rcode" id="decision_early_rcode" value="1" />
<input type="hidden" name="signed_date_time" id="signed_date_time" value="2019-02-27T17:53:26Z" />
<input type="hidden" name="req_bill_to_address_line1" id="req_bill_to_address_line1" value="100 Ravine Lane" />
<noscript>
<p>Your browser does not support JavaScript. Click the button below to continue.</p>
<input type="submit" name="commit" value="Continue" data-disable-with="Continue" />
</noscript>
</form>
<script type="text/javascript">
window.onload = function(){
document.forms['custom_redirect'].submit();
}
</script>
</body>
</html>
The cart must have at least the payment instrument and a cart total greater than zero. With this information present, if there is an error, PaymentInstrumentCreationFailedException is thrown.