Digital River payment objects
Learn how to use the Digital River payment objects.
An object is a collection of properties, and a property is an association between a name (or key) and a value. DigitalRiver.js uses objects to collect data.
This object contains the customer's billing address.
Billing address object
{
"name": "John Smith",
"firstName": "John",
"lastName": "Smith",
"phone": "952-555-1111",
"email": "[email protected]",
"address": {
"line1": "10380 Bren Rd W",
"line2": "string",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
}
}
This object contains the customer's shipping address.
Shipping Address object
{
"name": "John Smith",
"firstName": "John",
"lastName": "Smith",
"phone": "952-555-1111",
"email": "[email protected]",
"address": {
"line1": "10380 Bren Rd W",
"line2": "string",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
}
}
This object contains the customer's contact information.
Contact Information object
This object contains the payment request.
Payment Request object
var paymentRequestData = digitalriver.paymentRequest({
country: "US",
currency: "USD",
total: {
label: "Demo Total",
amount: 300
},
displayItems: [{
amount: 100,
label: "Item"
}, {
amount: 200,
label: "Better Item"
}],
shippingOptions: [{
id: "free-shipping",
label: "Free Shipping",
detail: "Arrives in 5 to 7 days",
amount: 0
}, {
id: "overnight-shipping",
label: "Overnight Shipping",
detail: "Arrives in 5 to 7 days",
amount: 1000
}],
requestShipping: true,
style: {
buttonType: "plain",
buttonColor: "light",
buttonLanguage: "en"
}
});
Attribute | Required | Type | Description |
---|---|---|---|
country | Required | String | The country code for the Payment Request session. |
currency | Required | String | The three-digit ISO currency code to supply to the Payment Request session. All amounts contained within the Payment Request will use this currency. |
total | Required | The Payment Request total amount displayed to the customer as part of the Payment Request interface. | |
displayItems | Required | The Payment Request displays items to the customer as part of the Payment RPequest interface. | |
shippingOptions | Optional | The Payment Request interface displays the Shipping Options field to the customer if you set the requestShipping parameter to true. The first item in the array is the default or selected shipping option. | |
requestShipping | Required | Boolean | If true, you must provide an array of shipping options from which the customer can choose. |
style | Optional | This attribute allows you to control the style of the button presented to the customer. |
This object contains the payment request total.
Payment Request Total Item object
{
label: "Order Total",
amount: 100,
isPending: false
}
Field | Required | Description |
---|---|---|
label | Required | The label appears next to the Total Amount of the order on the Payment Sheet. |
amount | Required | The amount of the Order displayed on the Payment Sheet. |
isPending | Optional | If the Shipping Total, Tax Amount, or something similar is still pending, you can change this amount in the future. If you don't provide an updated value, the system treats this amount as Final. |
This object contains the style information for the payment request.
Payment Request Style Option object
{
buttonType: "plain",
buttonColor: "light",
buttonLanguage: "en"
}
Field | Required | Description |
---|---|---|
buttonType | Optional | The type of button. If you don't specify a button type, the system uses the default button type. |
buttonColor | Optional | The color of the button. If you don't specify a button color, the system uses the default color for the button. |
buttonLanguage | Optional | The language for the button's label. If you don't specify a language, the DigitalRiver.js uses English by default. |
This object contains the payment request information for the item.
Payment Request Display Item object
{
buttonType: "plain",
buttonColor: "light",
buttonLanguage: "en"
}
Field | Required | Description |
---|---|---|
label | Required | This label appears next to the Line Item of the order on the Payment Sheet. |
amount | Required | This amount appears on the Payment Sheet for this Line Item. |
isPending | Optional | If the Shipping Total, Tax Amount, or something similar is still pending, you can change this amount in the future. If you do not provide an updated value, the system treats this amount as Final. |
This object contains the shipping option for the payment request.
Payment Request Shipping Option object
{
id: "overnight-shipping",
label: "Overnight Shipping",
amount: 10,
detail: "Will arrive tomorrow morning"
}
Field | Required | Description |
---|---|---|
id | Required | Once a customer selects a shipping option from the Payment Sheet, DigitalRiver.js returns the shipping option ID. This ID should correspond to something within your Order Management platform. |
label | Required | The label appears as part of the Shipping Option on the Payment Sheet. |
amount | Required | The amount that appears on the Payment Sheet for this Shipping Option. |
detail | Required | A long description of the Shipping Option that appears on the Payment Sheet. |
Use this object to respond to a shipping address change or a shipping option change event sent from the Payment request session.
Field | Type | Required | Description |
---|---|---|---|
status | String | Required | Use this field to control the flow and error display within the Payment Request session. The values are as follows:
|
error | Optional | These items will appears as the updated items in the Payment Request interface. | |
total | Optional | The new total amount, if applicable. | |
displayItems | Optional | These items will appears as the updated items in the Payment Request interface. | |
shippingOptions | Optional | The Payment Request interface displays the Shipping Options field to the customer if you set the requestShipping parameter to true. The first item in the array is the default or selected shipping option. |
Successful Payment Request Details Update object
{
status: 'success',
error: {
},
total: {
label: "Order Total",
amount: 100,
isPending: false
},
displayItems: [
{
label: "Line Item Label (Product Name)",
amount: 100,
isPending: false
},
{
label: "Shipping Amount",
amount: 10,
isPending: false
},
],
shippingOptions: [
{
id: "standard-shipping",
label: "Standard Shipping",
amount: 0,
detail: "Will arrive in 7-10 days."
},
{
id: "overnight-shipping",
label: "Overnight Shipping",
amount: 10,
detail: "Will arrive tomorrow morning"
}
]
}
Unsuccessful Payment Request Details Update object
{
status: 'failure',
error: {
message: 'We can only ship to the US, Canada and Mexico.'
}
}
Unsucessful Payment Request Details Update Error object with errors
{
status: 'failure',
error: {
message: 'We can only ship to the US, Canada and Mexico.',
fields: {
addressLine: 'Your address is invalid.',
city: 'Your city is invalid.',
country: 'Your country is invalid',
phone: 'Your phone is invalid.',
postalCode: 'Your postal code is invalid.',
recipient: 'Your recipient value is invalid. Please supply a different one.',
region: 'Your region value is invalid. Please supply a different one.',
}
}
}
Use this object to display a specific error message to the customer as part of a Details Update message to the Payment Request session.
The Payment request details update error object is only available for Apple Pay.
Payment Request Details Update Error object
{
message: "An Error has occurred. Please try again.",
fields: {
addressLine: 'Your address is invalid.',
city: 'Your city is invalid.',
country: 'Your country is invalid',
phone: 'Your phone is invalid.',
postalCode: 'Your postal code is invalid.',
recipient: 'Your recipient value is invalid. Please supply a different one.',
region: 'Your region value is invalid. Please supply a different one.',
}
}
Use this optional string message to display a specific error message to your customer. This allows you to provide a better experience when correcting error scenarios.
Use the following fields to display specific error information to the customer about what is wrong with their address Information.
Field | Payment Request Mapped Field | Required |
---|---|---|
addressLine | addressLine | Optional |
city | city | Optional |
state | region | Optional |
postalCode | postalCode | Optional |
country | country | Optional |
recipient | recipient | Optional |
This object contains the response to the payment request.
Field | Type | Description |
---|---|---|
error | Boolean | |
source | The payment source created using the details provided by the payment session. | |
billingAddress | The billing address provided by the customer. | |
shippingAddress | The shipping address provided by the customer. | |
contactInformation | The contact information provided by the customer. | |
shippingOption | String | The customer's chosen shipping option. |
complete | Function | Call this function once you have processed the returned data. This function receives a string with the following values:
|
This object contains the source object for the payment request.
Payment Request Source object
{
"error": false,
"source": {
"id": "5sdfd42a-1b02-471f-8c20-d9f7bb446d42",
"clientId": "gc",
"channelId": "drdod15",
"type": "creditCard",
"usage": "single",
"owner": {
"firstName": "firstName",
"lastName": "lastName",
"email": "[email protected]",
"referenceId": "testOrderID_payserv1",
"address": {
"line1": "1234 First St.",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": "55410"
}
},
"amount": "100.00",
"currency": "USD",
"status": "chargeable",
"creationIp": "67.216.237.4",
"creationDate": "2018-08-22T19:46:09.725Z",
"flow": "standard",
"creditCard": {
"brand": "Visa",
"expirationMonth": 12,
"expirationYear": 2025,
"lastFourDigits": "1111"
}
},
"billingAddress": {
"name": "John Smith",
"firstName": "John",
"lastName": "Smith",
"phone": "952-111-1111",
"email": "[email protected]"
"address": {
"line1": "10380 Bren Rd W",
"line2": "string",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
}
},
"shippingAddress": {
"name": "John Smith",
"firstName": "John",
"lastName": "Smith",
"phone": "952-111-1111",
"email": "[email protected]"
"address": {
"line1": "10380 Bren Rd W",
"line2": "string",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
}
},
"contactInformation": {
"name": "John Smith",
"phone": "952-111-1111",
"email": "[email protected]"
},
"shippingOption": {
id: "overnight-shipping",
label: "Overnight Shipping",
amount: 10,
detail: "Will arrive tomorrow morning"
},
complete: function() {
}
}
Digital River returns this Error object returns with the change event when Digital River detects an error with an Element. This object contains a type, code, and message.
Change Event Error object
{
"type": "validation_error",
"code": "invalid_card_number",
"message": "Your card number is invalid."
}
Digital River returns this Error object within the
createSource
method if Digital River detects an error with the tokenization request. This object contains a type and an array of messages that explain the error in detail.Create Source Error object
{
"type": "bad_request",
"errors": [{
"code": "invalid_parameter",
"parameter": "owner.firstName",
"message": "'' is not a valid owner.firstname."
},
{
"code": "currency_unsupported",
"parameter": "currency",
"message": "currency 'xyz' is not supported."
}]
}
Last modified 7mo ago