Configuring components
Gain a better understanding of how to configure components
The configuration object you're required to pass to components()
allows you to:
let components;
...
const configuration = {
checkoutSessionId: await createComponentsCheckoutSession(),
redirectUrl: window.location.protocol + '//' + window.location.hostname + ':' + window.location.port + '/v1/thank-you.html',
onReady: function (data) {},
onChange: function (data) {},
onSuccess: function (data) {}
}
...
components = digitalRiverCheckout.components(configuration);
Identify the checkout-session
In the components()
configuration object, you're required to define checkoutSessionId
.
DigitalRiverCheckout.js needs this identifier so that it can access the checkout-session.
const configuration = {
checkoutSessionId: await createComponentsCheckoutSession(),
...
}
To set this property, call an asynchronous function that creates a checkout-session and returns its unique identifier. For details, refer to Build a configuration object on the Components checkout page.
Redirect after successful checkouts
In the components()
configuration object, the optional redirectUrl
can be assigned a URL. This represents where you'd like Digital River to redirect customers after payment is authorized, and the checkout-session is successfully converted to an order.
const configuration = {
...
redirectUrl: window.location.protocol + '//' + window.location.hostname + ':' + window.location.port + '/v1/thank-you.html',
...
}
You could use redirectUrl
to send your customers to a custom order confirmation page, but if you display the thank you component, then don't define this property.
Callback methods in components
You can use the components()
configuration object to be notified of (1) ready, (2) change, and (3) success events.
Ready event
Define onReady
to be notified when components have successfully initialized.
onReady
onReady
The onReady
property can be assigned a method that accepts data
, and executes when the checkout-session has been successfully created and components are ready to accept input.
const configuration = {
...
onReady: function (data) {},
...
}
The method returns a data
object that contains the requiresShipping
and showTaxIdentifiers
booleans.
{
"requiresShipping": true,
"showTaxIdentifiers": true
}
Change event
Define onChange
to be notified of changes that occur in components.
onChange
onChange
The onChange
property can be assigned a method that accepts data
and executes when customers use a component to submit their information successfully.
const configuration = {
...
onChange: function (data) {},
...
}
The returned data
object, which represents the updated checkout-session, always contains requiresShipping
and showInvoiceAttribute
.
It might also contain optionalTaxIdentifiers[]
or requiredTaxIdentifiers[]
. If the former array exists, your application can optionally display the tax identifier component to users. If the latter exists, you're required to do so.
{
"id": "9d133de3-1095-40bc-934a-19101be6ff0f",
"checkoutId": "b9195f41-1864-42c2-afe6-ad1aa80d66e3",
"createdTime": "2023-01-03T21:48:41Z",
"currency": "EUR",
"customerId": "590881960336",
"email": "[email protected]",
"shipFrom": {
"address": {
"country": "US"
}
},
"billTo": {
"address": {
"country": "DE"
},
"saveForLater": false
},
"totalAmount": 300,
"subtotal": 300,
"totalFees": 0,
"totalTax": 0,
"totalImporterTax": 0,
"totalDuty": 0,
"totalDiscount": 0,
"totalShipping": 0,
"items": [
{
"id": "594f1af2-5a19-4158-90ab-b321a0260fcc",
"sku": {
"id": "30c1a732-61a7-426e-8580-12e7d1552694",
"name": "Puppy shoes",
"eccn": "EAR99",
"taxCode": "5216",
"image": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/6e/Golde33443.jpg/640px-Golde33443.jpg",
"physical": true,
"metadata": {
"customAttribute1": "some value"
}
},
"amount": 300,
"quantity": 1,
"tax": {
"rate": 0,
"amount": 0
},
"importerTax": {
"amount": 0
},
"duties": {
"amount": 0
},
"fees": {
"amount": 0,
"taxAmount": 0
}
}
],
"updatedTime": "2023-01-03T21:48:41Z",
"locale": "en_US",
"customerType": "business",
"sellingEntity": {
"id": "DR_IRELAND-ENTITY",
"name": "Digital River Ireland Ltd."
},
"options": {
"shippingMethods": [
{
"amount": 5,
"description": "Standard Shipping",
"serviceLevel": "SG"
},
{
"amount": 15,
"description": "Next Day Air",
"serviceLevel": "ND"
}
],
"addresses": [
{
"address": {
"line1": "10380 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
},
"name": "John Smith",
"phone": "952-111-1111",
"email": "[email protected]"
},
{
"address": {
"line1": "10-123 1/2 MAIN STREET NW",
"city": "MONTREAL",
"postalCode": "H3Z 2Y7",
"state": "QC",
"country": "CA"
},
"name": "John Jones",
"phone": "9055438570",
"email": "[email protected]"
},
{
"address": {
"line1": "Neuer Wall 10",
"city": "Hamburg",
"postalCode": "20354",
"country": "DE"
},
"name": "Anna Brawner",
"phone": "020143647453",
"email": "[email protected]"
}
],
"sources": [
{
"id": "c7d8c974-4ea5-4549-be0b-49203e88d988",
"createdTime": "2022-09-14T15:02:20Z",
"type": "creditCard",
"currency": "EUR",
"amount": 327.5,
"reusable": true,
"state": "chargeable",
"owner": {
"firstName": "John",
"lastName": "Smith",
"email": "[email protected]",
"address": {
"line1": "10380 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
}
},
"paymentSessionId": "3376ae52-b1e6-4e95-a52c-726b0932285d",
"clientSecret": "c7d8c974-4ea5-4549-be0b-49203e88d988_bdd2e28b-ec88-4902-bdd6-bd26ddb7732e",
"mandate": {
"terms": "Yes, please save this account and payment information for future purchases.",
"signedTime": "2022-09-14T15:02:20.238Z"
},
"creditCard": {
"brand": "MasterCard",
"expirationMonth": 12,
"expirationYear": 2023,
"lastFourDigits": "0008",
"fundingSource": "credit"
}
}
],
"taxIdentifiers": [
{
"id": "c61066b2-5de4-4172-903d-74077c70c0fe",
"state": "verified",
"verifiedName": "---",
"verifiedAddress": "---",
"liveMode": false,
"customerId": "590881960336",
"type": "de",
"value": "DE123456789",
"stateTransitions": {
"verified": "2022-09-14T13:40:31Z"
},
"createdTime": "2022-09-14T13:40:31Z",
"updatedTime": "2022-09-14T13:41:12Z"
}
],
"storeCredits": [
{
"amount": 100,
"name": "Gift Card",
"upstreamId": "7654-2345-0987-123456-1",
"lastFour": "7831",
"iconUrl": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/6e/Golde33443.jpg/640px-Golde33443.jpg"
},
{
"amount": 500,
"name": "Gift Card",
"upstreamId": "7654-2345-0987-123456-2",
"lastFour": "7831"
}
],
"consents": {
"companyName": "Acme Incorporated",
"emailPromotions": {
"url": "https://www.mysite.com/promotions.html"
},
"eula": {
"url": "https://www.mysite.com/EULA.html"
},
"termsOfService": {
"url": "https://www.mysite.com/terms-of-service.html"
}
},
"policies": {
"refund": {
"url": "https://www.mysite.com/refund-policy.html"
},
"return": {
"url": "https://www.mysite.com/return-policy.html"
}
}
},
"payment": {
"session": {
"id": "c1e0fba0-4063-43d4-b751-2590fb4da939",
"amountContributed": 0,
"amountRemainingToBeContributed": 300,
"state": "requires_source",
"clientSecret": "c1e0fba0-4063-43d4-b751-2590fb4da939_d1bf7327-d545-4291-b9a2-8f61d99f2a7f"
}
},
"taxInclusive": false,
"requiresShipping": true,
"optionalTaxIdentifiers": [
"de"
],
"fingerprint": "6f551d35-b60a-46ab-afe8-d8e18e114f6d",
"billingAddressSchema": "{\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"title\":\"Address\",\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\",\"description\":\"purchaser full name\",\"minLength\":0,\"maxLength\":128},\"organization\":{\"type\":\"string\",\"description\":\"purchaser company or organization\",\"minLength\":0,\"maxLength\":128},\"line1\":{\"type\":\"string\",\"description\":\"purchaser residence number and street\",\"minLength\":0,\"maxLength\":128},\"line2\":{\"type\":\"string\",\"description\":\"supplimental address information such as apartment number or suite\",\"minLength\":0,\"maxLength\":128},\"city\":{\"type\":\"string\",\"description\":\"purchaser city of residence\",\"minLength\":0,\"maxLength\":64},\"postalCode\":{\"type\":\"string\",\"description\":\"purchaser postal code\",\"pattern\":\"^\\\\d{5}$\"},\"country\":{\"type\":\"string\",\"description\":\"Address country\",\"enum\":[\"DE\"]}},\"required\":[\"country\",\"postalCode\"]}",
"shippingAddressSchema": "{\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"title\":\"Address\",\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\",\"description\":\"purchaser full name\",\"minLength\":0,\"maxLength\":128},\"organization\":{\"type\":\"string\",\"description\":\"purchaser company or organization\",\"minLength\":0,\"maxLength\":128},\"line1\":{\"type\":\"string\",\"description\":\"purchaser residence number and street\",\"minLength\":0,\"maxLength\":128},\"line2\":{\"type\":\"string\",\"description\":\"supplimental address information such as apartment number or suite\",\"minLength\":0,\"maxLength\":128},\"city\":{\"type\":\"string\",\"description\":\"purchaser city of residence\",\"minLength\":0,\"maxLength\":64},\"postalCode\":{\"type\":\"string\",\"description\":\"purchaser postal code\",\"pattern\":\"^\\\\d{5}$\"},\"country\":{\"type\":\"string\",\"description\":\"Address country\",\"enum\":[\"DE\"]}},\"required\":[\"country\",\"city\",\"postalCode\",\"line1\"]}",
"billingAddressOnlySchema": "{\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"title\":\"Address\",\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\",\"description\":\"purchaser full name\",\"minLength\":0,\"maxLength\":128},\"organization\":{\"type\":\"string\",\"description\":\"purchaser company or organization\",\"minLength\":0,\"maxLength\":128},\"line1\":{\"type\":\"string\",\"description\":\"purchaser residence number and street\",\"minLength\":0,\"maxLength\":128},\"line2\":{\"type\":\"string\",\"description\":\"supplimental address information such as apartment number or suite\",\"minLength\":0,\"maxLength\":128},\"city\":{\"type\":\"string\",\"description\":\"purchaser city of residence\",\"minLength\":0,\"maxLength\":64},\"postalCode\":{\"type\":\"string\",\"description\":\"purchaser postal code\",\"pattern\":\"^\\\\d{5}$\"},\"country\":{\"type\":\"string\",\"description\":\"Address country\",\"enum\":[\"DE\"]}},\"required\":[\"country\",\"postalCode\"]}",
"liveMode": false
}
Success event
Define onSuccess
to be notified of a successfully completed components checkout.
onSuccess
onSuccess
The onSuccess
property can be assigned a method that accepts data
and executes when a customer's payment is authorized, and Digital River successfully converts the checkout-session to an order.
const configuration = {
...
onSuccess: function (data) {}
}
The method returns a data
object, which represents the order.
{
"order": {
"id": "234236860336",
"checkoutId": "07968dbc-7e0e-42a7-bdeb-6a13283ab865",
"checkoutSessionId": "93ca0c41-a3c9-4e62-a955-dfad7931fcf5",
"createdTime": "2022-07-26T20:56:19Z",
"currency": "USD",
"email": "[email protected]",
"shipTo": {
"address": {
"line1": "Neuer Wall 10",
"city": "Hamburg",
"postalCode": "20354",
"country": "DE"
},
"name": "Anna Brawner",
"phone": "020143647453",
"email": "[email protected]",
"saveForLater": false
},
"shipFrom": {
"address": {
"country": "DE"
}
},
"billTo": {
"address": {
"line1": "Neuer Wall 10",
"city": "Hamburg",
"postalCode": "20354",
"country": "DE"
},
"name": "Anna Brawner",
"phone": "020143647453",
"email": "[email protected]",
"saveForLater": false
},
"totalAmount": 362.95,
"subtotal": 305,
"totalFees": 0,
"totalTax": 57.95,
"totalImporterTax": 0,
"totalDuty": 0,
"totalDiscount": 0,
"totalShipping": 5,
"items": [
{
"id": "161531430336",
"sku": {
"id": "sku_1630512988374",
"name": "Thors Hammer",
"eccn": "EAR99",
"taxCode": "4323.310_A",
"image": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQyc7CIax_xuyc5lkppfI8iMZ6t7NpOVTmhhA&usqp=CAU",
"physical": true,
"skuGroupId": "demo-1630512830419",
"metadata": {
"application": "iOS-LLL"
},
"weight": 8125,
"weightUnit": "oz"
},
"amount": 300,
"quantity": 1,
"metadata": {
"shippingAmount": 5
},
"tax": {
"rate": 0.19,
"amount": 57
},
"importerTax": {
"amount": 0
},
"duties": {
"amount": 0
},
"availableToRefundAmount": 0,
"shipFrom": {
"address": {
"line1": "10380 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "DE"
}
},
"fees": {
"amount": 0,
"taxAmount": 0
}
}
],
"shippingChoice": {
"amount": 5,
"description": "Standard Shipping",
"serviceLevel": "SG",
"taxAmount": 0.95
},
"updatedTime": "2022-07-26T20:56:19Z",
"locale": "en_US",
"customerType": "individual",
"sellingEntity": {
"id": "DR_IRELAND-ENTITY",
"name": "Digital River Ireland Ltd."
},
"payment": {
"charges": [
{
"id": "30414f85-a52f-4c94-a3a7-3ce418d51f62",
"createdTime": "2022-07-26T20:56:21Z",
"currency": "USD",
"amount": 362.95,
"state": "capturable",
"captured": false,
"refunded": false,
"sourceId": "d82add35-93e0-4917-8e54-3b595a997dfb",
"type": "customer_initiated"
}
],
"sources": [
{
"id": "d82add35-93e0-4917-8e54-3b595a997dfb",
"type": "creditCard",
"amount": 362.95,
"owner": {
"firstName": "Anna",
"lastName": "Brawner",
"email": "[email protected]",
"address": {
"line1": "Neuer Wall 10",
"city": "Hamburg",
"postalCode": "20354",
"country": "DE"
}
},
"creditCard": {
"brand": "AmericanExpress",
"expirationMonth": 12,
"expirationYear": 2024,
"lastFourDigits": "2341"
}
}
],
"session": {
"id": "522179af-8481-4078-88e3-c305cc55fc77",
"amountContributed": 362.95,
"amountRemainingToBeContributed": 0,
"state": "complete",
"clientSecret": "522179af-8481-4078-88e3-c305cc55fc77_be36a393-8432-4354-bb10-efcb90b40f45"
}
},
"state": "accepted",
"stateTransitions": {
"accepted": "2022-07-26T20:56:22Z"
},
"fraudState": "passed",
"fraudStateTransitions": {
"passed": "2022-07-26T20:56:22Z"
},
"taxInclusive": false,
"liveMode": false
}
}
requiresShipping
requiresShipping
The requiresShipping
boolean indicates whether it's necessary to display the shipping component. If false
, then the checkout-session's items[]
might only contain digital products, or the customer might have used the wallet component. In either case, you won't need to display the shipping component to process the transaction successfully.
showTaxIdentifiers
showTaxIdentifiers
The showTaxIdentifiers
boolean indicates whether it's necessary to display the tax identifier component. It's often true
when the checkout-session's customerType
is business
and (1) the customer selects a non-United States shipping and/or billing country in the address component, or (2) you assign shoppingCountry
a non-US
value.
showInvoiceAttribute
showInvoiceAttribute
The showInvoiceAttribute
boolean indicates whether it's necessary to display the invoice component. If true
this indicates that a Taiwanese-based customer is purchasing as an individual (i.e., a B2C transaction).
Last updated