A payment session tracks a transaction's payment. On this page, you'll find information on:
Why use payment sessions?
Payment sessions allow you to . This solution lessens your front-end development burden. To take just one example, automatically retrieve a transaction's applicable and then present them to customers during the payment collection stage of a checkout.
Additionally, payment sessions simplify creation. Without them, you'll need to retrieve numerous data points from the and ensure they're properly formatted before passing them to . With payment sessions, however, you simply retrieve the payment.session.id and then pass that value to the appropriate , thereby minimizing your data transfer requirements
Payment sessions also allow you to comply with regulations. If you reference this object when creating , Digital River, when necessary, automatically collects a customer's authentication data.
When to use payment sessions
You can use payment sessions to:
Configure elements
Retrieve available payment methods
digitalriver.retrieveAvailablePaymentMethods({
"sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f"
}).then(function(result) {
//do something with the data
});
The following section provides information on the payment session object:
Session state
A payment session has a defined lifecycle. Each stage of that lifecycle is represented by a state. When building your integration, we recommend you pay close attention to:
requires_source
requires_confirmation
pending_redirect
A payment session in a state of pending_redirect indicates that customers were successfully redirected to the payment provider's portal but have yet to complete the actions necessary to authorize payment.
pending_funds
A payment session state of pending_funds indicates that customers must complete an asynchronous process before payment is authorized.
pending
complete
Amount contributed and remaining
{
"type": "bad_request",
"errors": [
{
"code": "order_submit_failed",
"message": "Payment session status is invalid."
}
]
}
For PayPal, you add sessionId to the payload and remove amount, currency, payPal.items, payPal.taxAmount, payPal.shippingAmount, payPal.amountsEstimated, payPal.requestShipping, and payPal.shipping.
The following tabs provide code examples of how sources are created without and with payment sessions.
var payload = {
"type": "payPal",
"sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
"payPal": {
"returnUrl": "http://mypage.com",
"cancelUrl": "https://mypage.com/cancel"
}
}
digitalriver.createSource(payload).then(function(result) {
if (result.error) {
//handle errors
} else {
var source = result.source;
//send source to back end
sendToBackend(source);
}
});
PayPal Billing
For PayPal Billing, you add sessionId to the payload and remove amount, currency, payPalBilling.items, payPalBilling.taxAmount, payPalBilling.shippingAmount, payPalBilling.amountsEstimated, payPalBilling.requestShipping, and payPalBilling.shipping.
The following tabs provide code examples of how sources are created without and with payment sessions.
var payload = {
"type": "payPalBilling",
"sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
"payPal": {
"returnUrl": "http://mypage.com",
"cancelUrl": "https://mypage.com/cancel"
}
}
digitalriver.createSource(payload).then(function(result) {
if (result.error) {
//handle errors
} else {
var source = result.source;
//send source to back end
sendToBackend(source);
}
});
PayPal Credit
For PayPal Credit, you add sessionId to the payload and remove amount, currency, payPal.items, payPal.taxAmount, payPal.shippingAmount, payPal.amountsEstimated, payPal.requestShipping, and payPal.shipping.
The following tabs provide code examples of how sources are created without and with payment sessions.
For Klarna, you add sessionId to the payload and remove amount, currency, klarnaCredit.items, klarnaCredit.locale, klarnaCredit.discountAmount, klarnaCredit.taxAmount, klarnaCredit.shippingAmount, klarnaCredit.shipping, klarnaCredit.accountId, klarnaCredit.accountCreatedDate, klarnaCredit.accountUpdatedDate, klarnaCredit.hasPaidBefore, klarnaCredit.subscriptionDescription, klarnaCredit.subscriptionStartDate, klarnaCredit.subscriptionEndDate, klarnaCredit.autoRenewal, and klarnaCredit.affiliateName.
The following tabs provide code examples of how sources are created without and with payment sessions.
For Klarna Recurring, you add sessionId to the payload and remove amount, currency, klarnaCreditRecurring.items, klarnaCreditRecurring.locale, klarnaCreditRecurring.discountAmount, klarnaCreditRecurring.taxAmount, klarnaCreditRecurring.shippingAmount, klarnaCreditRecurring.shipping, klarnaCreditRecurring.accountId, klarnaCreditRecurring.accountCreatedDate, klarnaCreditRecurring.accountUpdatedDate, klarnaCreditRecurring.hasPaidBefore, klarnaCreditRecurring.subscriptionDescription, klarnaCreditRecurring.subscriptionStartDate, klarnaCreditRecurring.subscriptionEndDate, klarnaCreditRecurring.autoRenewal, and klarnaCreditRecurring.affiliateName.
The following tabs provide code examples of how sources are created without and with payment sessions.
The following all can be configured with a payment session identifier:
If you're using to collect payment, you can call to get a transaction's applicable payment methods and then present them as options during checkouts.
To configure this method, retrieve the payment.session.id and pass it to sessionId.
Both of Digital River's can be configured with the payment.session.id. The data our payment service needs to create the is retrieved from that referenced object.
Before , a payment.session should be in a of requires_confirmation and its should be 0.
If you and its is pending_payment, then this indicates that the on the isn't authorized and the goods shouldn't be fulfilled yet.
To handle this state change event, check the value of the order's .
If it's redirect, refer to .
If it's show_payment_instructions, refer to .
The attributes described in this section are only contained in 2021-03-23 and higher.
For a complete list of payment session state values, refer to the , , or API reference documentation.
If a payment.session.state is requires_source, then this indicates that either:
No is associated with the checkout or
The aggregated amount of any associated with the checkout is less than the checkout's totalAmount.
In both cases, Digital River won't be able to generate an aggregated amount of large enough to cover the totalAmount. As a result, the remains greater than 0.0 and any attempt to is blocked.
When the payment session's state is requires_confirmation, then one or more have been applied to the , and the aggregated amount is sufficient to fund the transaction.
The payment.session.state must be requires_confirmation before you .
For example, if you a to a , then the drops to 0.0 and the payment session's state transitions to requires_confirmation.
This state only occurs when customers choose a whose resulting has a .
If an payment.session.state persists as pending_redirect, then customers either selected the cancel payment option or clicked their web browser's back button.
This state occurs when customers choose a whose resulting has a .
For example, an with a of and a payment.session.state of pending_funds means that customers have yet to complete payment at the designated convenience store (e.g. 7-11 or FamilyMart).
A pending payment session state means that customers have completed all the necessary actions (such as and redirects) but certain backend payment processes remain incomplete.
Once all of an payment are , its payment.session.state typically transitions to complete.
Once you associate a with a , Digital River uses it to fund the transaction in full and payment.session.amountRemainingToContribute drops to 0.0.
But when checkouts only contain , you need to confirm that sufficient funds exist to cover the checkout's totalAmount. If this isn't the case, and you , you receive the following error:
By comparing values in the payment.session, you can determine how much additional funding, if any, is required. The amountContributed represents the aggregated amount of all the checkout's payment.sources[]. The amountRemainingToBeContributed is how much is needed to fund the transaction.
If amountContributed is equal to the checkout's totalAmount or the amountRemainingToBeContributed is 0.0, then you don't need to request any more payment methods from the customer, and once the payment session's is , you can .
But if amountContributed is less than the checkout's totalAmount or amountRemainingToBeContributed is greater than 0.0, then the customer needs to supply additional payment methods before you . This only happens, however, when you have yet to associate a primary payment source with the checkout. Once that's done, amountRemainingToBeContributed drops to 0.0.
If customers opt to fund a transaction with a whose resulting has an authentication of redirect or receiver, then, after you and submit the , the , in most cases, will contain payment.session.nextAction and this object's nested action will be either redirect or show_payment_instructions.
If action is redirect, then send customers to the address specified by data.redirectUrl. For details, refer to .
If action is show_payment_instructions then use data.sourceId and data.sourceClientSecret to configure the . For details, refer to .
The conversion process is fairly straightforward if you collect payment using and are not currently using payment sessions but want to migrate to this solution.
To collect payment, we generally recommend that you use .
In the Digital River APIs, payment sessions are automatically enabled. This means that each time you , the response contains a payment session identifier that you use to configure .
You'll need to update your code to integrate with payment sessions. For each of your enabled , add sessionId to the payload that gets passed to .
The following sections contain instructions and example codes for each payment method: , , , , , , , , , , , , , and .
