Payment sessions allow you to gain access to Drop-in payments. This solution lessens your front-end development burden. To take just one example, Drop-in payments automatically retrieves a transaction's applicable payment methods and then presents them to customers during the payment collection stage of a checkout.
Additionally, payment sessions simplify source creation. Without them, you'll need to retrieve numerous data points from the checkout and ensure they're properly formatted before passing them to createSource(). With payment sessions however you simply retrieve the checkout'spayment.session.id and then pass that value to the appropriate source creation method, thereby minimizing your data transfer requirements
Payment sessions also allow you to comply with PSD2 and SCA regulations. If you reference this object when creating credit card sources, Digital River, when necessary, automatically collects a customer's authentication data.
To configure this method, retrieve the checkout'spayment.session.id and pass it to sessionId.
digitalriver.retrieveAvailablePaymentMethods({"sessionId":"ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f"}).then(function(result) {//do something with the data});
Create sources
Both of Digital River's source creation methods can be configured with the checkout'spayment.session.id. The data our payment service needs to create the source is then retrieved from that referenced object.
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:
The aggregated amount of any secondary sources[] 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 charges[] large enough to cover the checkout'stotalAmount. As a result, the amountRemainingToContribute remains greater than 0.0 and any attempt to create an order is blocked.
requires_confirmation
When the payment session's state is requires_confirmation, then one or more sources[] have been applied to the checkout, and their aggregated amount is sufficient to fund the transaction.
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.
If an order'spayment.session.state persists as pending_redirect, then customers either selected the cancel payment option or clicked their web browser's back button.
pending_funds
A payment session state of pending_funds indicates that customers must complete an asynchronous process before payment is authorized.
For example, an order with a payment.sources[].type of konbini 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).
pending
A pending payment session state means that customers have completed all the necessary actions (such as SCA and redirects) but certain back-end payment processes remain incomplete.
complete
Once all of an order's payment charges[] are capturable, its payment.session.state typically transitions to complete.
Amount contributed and remaining
Once you associate a primary payment sources[] with a checkout, Digital River uses it to fund the transaction in full and payment.session.amountRemainingToContribute drops to 0.0.
But when checkouts only contain secondary payment sources[], you need to confirm that sufficient funds exist to cover the checkout's totalAmount. If this isn't the case, and you convert the checkout to an order, you receive the following error:
{"type": "bad_request","errors": [ {"code":"order_submit_failed","message":"Payment session status is invalid." } ]}
By comparing values in the checkout'spayment.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 state is requires_confirmation, you can create the order.
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 create the order. 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.
Next action
If customers opt to fund a transaction with a payment method whose resulting source has an authentication flow of redirect or receiver, then, after you associate the source with the checkout and submit the create order request, the order, 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 Handling redirect payment methods.
If you collect payment using DigitalRiver.js with elements and are not currently using payment sessions but want to migrate to this solution, the conversion process is fairly straightforward.
To collect payment, we generally recommend that you use Drop-in payments.
In the Digital River APIs, payment sessions are automatically enabled. This means that each time you create a checkout, the response contains a payment session identifier that you use to configure createSource().
Update your code
You'll need to update your code to integrate with payment sessions. For each of your enabled payment methods, add sessionId to the payload that gets passed to createSource().
You'll also need to remove some parameters. The specific parameters that must be removed depend on the payment method.
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 endsendToBackend(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 endsendToBackend(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 Online Banking - IBP, you add sessionId to the payload and remove amount and currency.
The following tabs provide code examples of how sources are created without and with payment sessions.
let payload = {"type":"onlineBanking","amount":100,"currency":"EUR","owner": {"firstName":"John","lastName":"Doe","email":"john.doe@digitalriver.com","phoneNumber":"000-000-0000","address": {"line1":"52-58 Neue Mainzer Straße","line2":"","city":"Frankfurt am Main","state":"HE","postalCode":"60311","country":"DE" } },"onlineBanking": {"returnUrl":"https://myurl.com/success","cancelUrl":"https://myurl.com/cancel","bankCode":"82" }}digitalriver.createSource(payload).then(function(result) {if (result.error) {//handle errors } else {var source =result.source;//send source to back endsendToBackend(source); }});
var payload = {"type":"onlineBanking","sessionId":"ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f","owner": {"firstName":"John","lastName":"Doe","email":"john.doe@digitalriver.com","phoneNumber":"000-000-0000","address": {"line1":"52-58 Neue Mainzer Straße","line2":"","city":"Frankfurt am Main","state":"HE","postalCode":"60311","country":"DE" } },"onlineBanking": {"returnUrl":"https://myurl.com/success","cancelUrl":"https://myurl.com/cancel","bankCode":"82" }}digitalriver.createSource(payload).then(function(result) {if (result.error) {//handle errors } else {var source =result.source;//send source to back endsendToBackend(source); }});
Konbini
For Konbini, you add sessionId to the payload and remove amount and currency.
The following tabs provide code examples of how sources are created without and with payment sessions.
let payload = {"type":"konbini","amount":120.99,"currency":"JPY","owner": {"firstName":"John","lastName":"Doe","email":"john.doe@digitalriver.com","phoneNumber":"000-000-0000","address": {"line1":"6 Chome-10-1 Roppongi, Minato","state":"Tokyo","postalCode":"106-0032","country":"JP" } },"konbini": {"storeId":"010" }}digitalriver.createSource(payload).then(function(result) {if (result.error) {//handle errors } else {var source =result.source;//send source to back endsendToBackend(source); }});
var payload = {"type":"konbini","sessionId":"ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f","owner": {"firstName":"John","lastName":"Doe","email":"john.doe@digitalriver.com","phoneNumber":"000-000-0000","address": {"line1":"6 Chome-10-1 Roppongi, Minato","state":"Tokyo","postalCode":"106-0032","country":"JP" } },"konbini": {"storeId":"010" }}digitalriver.createSource(payload).then(function(result) {if (result.error) {//handle errors } else {var source =result.source;//send source to back endsendToBackend(source); }});
Klarna
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.
var payload = {"type":"klarnaCredit","owner": {"firstName":"firstName","lastName":"lastName","email":"email@email.org","phoneNumber":"9522253720","address": {"line1":"line1","line2":"line2","city":"Minnetonka","state":"MN","country":"US","postalCode":"55410" } },"sessionId":"3aa75613-9596-438a-9604-67e20016aa96","klarnaCredit": {"returnUrl":"http://example.org/return","cancelUrl":"http://example.org/cancel" }}digitalriver.createSource(payload).then(function(result) {if (result.error) {//handle errors } else {var source =result.source;//send source to back endsendToBackend(source); }});
Klarna Recurring
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.