# Payment sessions

A payment session tracks a transaction's payment. On this page, you'll find information on:

* [The benefits of using payment sessions](#why-use-payment-sessions)
* [When to use payment sessions](#when-to-use-payment-sessions)
* [The payment session object](#the-payment-session-object)
* [How to migrate to payment sessions](#migrating-to-payment-sessions)

## Why use payment sessions?

Payment sessions allow you to [gain access to Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md). This solution lessens your front-end development burden. To take just one example, [Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in.md) automatically retrieve a transaction's applicable [payment methods](/digital-river-api/payments/supported-payment-methods.md) and then present them to customers during the payment collection stage of a checkout.

Additionally, payment sessions simplify [source ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/sources)creation. Without them, you'll need to retrieve numerous data points from the [checkout ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)and ensure they're properly formatted before passing them to [`createSource()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#createsource-element-sourcedata). With payment sessions, however, you simply retrieve the [checkout's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)`payment.session.id` and then pass that value to the appropriate [source creation method](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#creating-payment-sources), thereby minimizing your data transfer requirements

Payment sessions also allow you to comply with [PSD2 and SCA](/digital-river-api/payments/psd2-and-sca.md) regulations. If you reference this object when creating [credit card sources](/digital-river-api/payments/payment-integrations-1/digitalriver.js/payment-methods/credit-cards.md), Digital River, when necessary, automatically collects a customer's authentication data.

## When to use payment sessions

You can use payment sessions to:

* [Configure various elements](#configure-elements)
* [Retrieve available payment methods](#retrieve-available-payment-methods)
* [Create sources](#creating-a-source-with-payment-sessions)
* [Determine when to create orders](#how-to-determine-when-to-create-an-order)
* [Determine the next action to take after order creation](#determine-next-action)

### Configure elements

The following [elements](/digital-river-api/developer-resources/reference/elements.md) all can be configured with a payment session identifier:

* [iDeal](/digital-river-api/developer-resources/reference/elements/ideal-element.md)
* [Tax identifier](/digital-river-api/developer-resources/reference/elements/tax-identifier-element.md)
* [Invoice attribute](/digital-river-api/developer-resources/reference/elements/invoice-attribute-element.md)
* [PayPal](/digital-river-api/developer-resources/reference/elements/paypal-elements.md)

### Retrieve available payment methods

If you're using [DigitalRiver.js with elements](/digital-river-api/payments/payment-integrations-1/digitalriver.js.md) to collect payment, you can call [`retrieveAvailablePaymentMethods()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#retrieving-available-payment-methods) to get a transaction's applicable payment methods and then present them as options during checkouts.

To configure this method, retrieve the [checkout's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)`payment.session.id` and pass it to `sessionId`.

```javascript
digitalriver.retrieveAvailablePaymentMethods({
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f"
}).then(function(result) {
    //do something with the data
});
```

### Create sources <a href="#creating-a-source-with-payment-sessions" id="creating-a-source-with-payment-sessions"></a>

Both of Digital River's [source creation methods](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#creating-payment-sources) can be configured with the [checkout's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)`payment.session.id`. The data our payment service needs to create the [source ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/sources)is retrieved from that referenced object.

{% tabs %}
{% tab title="Drop-in payments" %}

```javascript
let configuration = {
    "sessionId": "172deb0f-de6f-4d2c-9555-53f3894b6318",
    "options": {
        "flow": "checkout",
        "showComplianceSection": true
    }, 
    onSuccess: function(data) {}, 
    onError: function(data) {}, 
    onReady: function(data) {}, 
    onCancel: function(data) {}
}
                                    
let dropin = digitalriverpayments.createDropin(configuration);
dropin.mount("drop-in");
```

{% endtab %}

{% tab title="DigitalRiver.js with elements" %}

```javascript
let payload = {
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
    "type": "payPal",
    "payPal": {
        "returnUrl": "https://mywebsite.com/paymentCallBack.html",
        "cancelUrl": "https://mywebsite.com/paymentCallBack.html"
    }
}

digitalriver.createSource(payload).then(function(result) {
    if(result.state === "chargeable") {
        sendToBackEnd(result);
    } else {
        doErrorScenario();
    }
});
```

{% endtab %}
{% endtabs %}

### Determine when to create orders <a href="#how-to-determine-when-to-create-an-order" id="how-to-determine-when-to-create-an-order"></a>

Before [creating an order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier), a [checkout's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)`payment.session` should be in a [`state`](#session-state) of `requires_confirmation` and its [`amountRemainingToBeContributed`](#amount-contributed-and-amount-remaining-to-be-contributed) should be `0`.

{% code title="Checkout" %}

```javascript
{
    "id": "8f349290-a6ec-438a-8623-ca0c6e6f65fa",
    ...
    "payment": {
        ...
        "session": {
            "id": "1403a59f-37a8-4d9e-8e13-838cf6f2a0cc",
            "amountContributed": 27.01,
            "amountRemainingToBeContributed": 0.0,
            "state": "requires_confirmation",
            "clientSecret": "1403a59f-37a8-4d9e-8e13-838cf6f2a0cc_a2a14087-2aa7-4876-b4f9-d16b5ae6817b"
        }
    }
}
```

{% endcode %}

### Determine next action

If you [create an order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier) and its [`state` ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders/order-basics#state-and-fraud-state)is `pending_payment`, then this indicates that the [charge ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/charges)on the [primary payment `sources[]`](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#primary-versus-secondary-sources) isn't authorized and the goods shouldn't be fulfilled yet.

To handle this `state` change event, check the value of the order's [`payment.session.nextAction.action`](#next-action).

* If it's `redirect`, refer to [Handling redirect payment methods](/digital-river-api/integration-options/checkouts/building-you-workflows/handling-redirect-payment-methods.md).
* If it's `show_payment_instructions`, refer to [Handling delayed payment methods](/digital-river-api/integration-options/checkouts/building-you-workflows/handling-delayed-payment-methods.md).

## The payment session object

{% hint style="warning" %}
The attributes described in this section are only contained in [versions ](https://docs.digitalriver.com/digital-river-api-reference/digital-river-api-reference-guide/versioning)`2021-03-23` and higher.
{% endhint %}

The following section provides information on the payment session object:

* [`state`](#session-state)
* [`amountContributed` and `amountRemainingToBeContributed`](#amount-contributed-and-amount-remaining-to-be-contributed)
* [`nextAction`](#next-action)

### 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_source)
* [`requires_confirmation`](#requires_confirmation)
* [`pending_redirect`](#pending-redirect)
* [`pending_funds`](#pending_funds)
* [`pending`](#pending)
* [`complete`](#complete)

For a complete list of payment session `state` values, refer to the [checkouts](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts), [orders](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders), or [invoices ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices)API reference documentation.

#### `requires_source`

If a [checkout's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)`payment.session.state` is `requires_source`, then this indicates that either:

* No [primary `sources[]`](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#primary-payment-sources) is associated with the checkout or
* The aggregated `amount` of any [secondary `sources[]`](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#secondary-payment-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[]`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/charges/charge-basics) large enough to cover the [checkout's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)`totalAmount`. As a result, the [`amountRemainingToContribute`](#amount-contributed-and-amount-remaining-to-be-contributed) remains greater than `0.0` and any attempt to [create an order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier) is blocked.

#### `requires_confirmation`

When the payment session's `state` is `requires_confirmation`, then one or more [`sources[]`](/digital-river-api/payments/payment-sources.md) have been applied to the [checkout](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts), and the aggregated `amount` is sufficient to fund the transaction.

The [checkout's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)`payment.session.state` must be `requires_confirmation` before you [create the order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier).

For example, if you [attach](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts) a [primary source](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#primary-payment-sources) to a [checkout](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts), then the [`amountRemainingToContribute`](#amount-contributed-and-amount-remaining-to-be-contributed) drops to `0.0` and the payment session's `state` transitions to `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.

This `state` only occurs when customers choose a [payment method](/digital-river-api/payments/supported-payment-methods.md) whose resulting [source](/digital-river-api/payments/payment-sources.md) has a [`redirect` authentication `flow`](/digital-river-api/payments/payment-sources.md#authentication-flow).

If an [order's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders)`payment.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.

This `state` occurs when customers choose a [payment method](/digital-river-api/payments/supported-payment-methods.md) whose resulting [source](/digital-river-api/payments/payment-sources.md) has a [`receiver` authentication `flow`](/digital-river-api/payments/payment-sources.md#authentication-flow).

For example, an [order ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders)with a [`payment.sources[].type`](/digital-river-api/payments/payment-sources.md#supported-payment-methods) of [`konbini`](/digital-river-api/payments/supported-payment-methods/konbini.md) 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](/digital-river-api/payments/psd2-and-sca.md) and redirects) but certain backend payment processes remain incomplete.

#### `complete`

Once all of an [order's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders)payment [`charges[]`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/charges/charge-basics) are [`capturable`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/charges/charge-basics#captures), its `payment.session.state` typically transitions to `complete`.

### Amount contributed and remaining <a href="#amount-contributed-and-amount-remaining-to-be-contributed" id="amount-contributed-and-amount-remaining-to-be-contributed"></a>

Once you associate a [primary payment `sources[]`](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#primary-payment-sources) with a [checkout](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts), 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[]`](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#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](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier), you receive the following error:

{% tabs %}
{% tab title="400 Bad Request" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "order_submit_failed",
            "message": "Payment session status is invalid."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

By comparing values in the [checkout's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)`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 [`state`](#session-state) is [`requires_confirmation`](#requires-confirmation), you can [create the order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier).

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](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). 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](/digital-river-api/payments/supported-payment-methods.md) whose resulting [source ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/sources)has an authentication [`flow`](/digital-river-api/payments/payment-sources.md#authentication-flow) of `redirect` or `receiver`, then, after you [associate the source with the checkout](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#attaching-sources-to-checkouts) and submit the [create order request](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier), the [order](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders), in most cases, will contain `payment.session.nextAction` and this object's nested `action` will be either `redirect` or `show_payment_instructions`.

{% tabs %}
{% tab title="redirect" %}
If `action` is `redirect`, then send customers to the address specified by `data.redirectUrl`. For details, refer to [Handling redirect payment methods](/digital-river-api/integration-options/checkouts/building-you-workflows/handling-redirect-payment-methods.md).

{% code title="Order" %}

```json
{
    "id": "240354510336",
    ...
    "payment": {
        ...
        "session": {
            "id": "1b682138-ce9f-46ec-8b5e-94b710128cd9",
            ...
            "nextAction": {
                "action": "redirect",
                "data": {
                    "redirectUrl": "https://api.digitalriver.com:443/payments/redirects/3fab742c-a7e8-4a90-8951-86d071fa070d?apiKey=pk_test_a45b91ba4f984df7a229b2ab5941ce1c"
                }
            }
        }
    },
    ...
}
```

{% endcode %}
{% endtab %}

{% tab title="show\_payment\_instructions" %}
If `action` is `show_payment_instructions` then use `data.sourceId` and `data.sourceClientSecret` to configure the [delayed payment instructions element](/digital-river-api/developer-resources/reference/elements/delayed-payment-instructions-element.md). For details, refer to [Handling delayed payment methods](/digital-river-api/integration-options/checkouts/building-you-workflows/handling-delayed-payment-methods.md).

{% code title="Order" %}

```json
{
    "id": "239809940336",
    ...
    "payment": {
        ...
        "session": {
            "id": "afaed310-419f-4ced-912c-6830a98c7384",
            ...
            "nextAction": {
                "action": "show_payment_instructions",
                "data": {
                    "sourceId": "9c00d78c-dbad-4303-b366-7e0a49c322e7",
                    "sourceClientSecret": "9c00d78c-dbad-4303-b366-7e0a49c322e7_246ed54a-0dfc-41f0-9e98-14036adf642e"
                }
            }
        }
    },
    ...
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Migrating to payment sessions

The conversion process is fairly straightforward if you collect payment using [DigitalRiver.js with elements](/digital-river-api/payments/payment-integrations-1/digitalriver.js.md) and are not currently using payment sessions but want to migrate to this solution.

{% hint style="success" %}
To collect payment, we generally recommend that you use [Drop-in payments](/digital-river-api/payments/payment-integrations-1/drop-in.md).
{% endhint %}

In the Digital River APIs, payment sessions are automatically enabled. This means that each time you [create a checkout](/digital-river-api/integration-options/checkouts/creating-checkouts.md#creating-and-updating-the-checkout), the response contains a payment session identifier that you use to configure [`createSource()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-sources).

### Update your code

You'll need to update your code to integrate with payment sessions. For each of your enabled [payment methods](/digital-river-api/payments/supported-payment-methods.md), add `sessionId` to the payload that gets passed to [`createSource()`](/digital-river-api/developer-resources/reference/digitalriver-object.md#creating-sources).

You'll also need to remove some parameters. The specific parameters that must be removed depend on the payment method.

The following sections contain instructions and example codes for each payment method: [Credit Card](#credit-card), [PayPal](#paypal), [PayPal Billing](#paypal-billling), [PayPal Credit](#paypal-credit), [SEPA Direct Debit](/digital-river-api/payments/payment-integrations-1/digitalriver.js/payment-methods/direct-debit.md), [Wire Transfer](#wire-transfer), [Cash on Delivery - Japan](#cash-on-delivery-japan), [Payco - Korea Payments](#payco-korea-payments), [Bank Transfer - Korea Payments](#bank-transfer-korea-payments), [Online Banking - IBP](#online-banking-ibp), [bPay](#bpay), [Konbini](#konbini), [Klarna](#klarna), and [Klarna Recurring](#klarna-recurring).

#### Credit Card

For credit cards, you add `sessionId` to the payload, but do not remove any existing parameters.

The following tabs provide code examples of how sources are created without and with payment sessions.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
var payload = {
    "type": "creditCard",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "john.doe@digitalriver.com",
        phoneNumber: "000-000-0000",
        address: {
            line1: "10380 Bren Road West",
            line2: "Suite 123",
            city: "Minnetonka",
            state: "MN",
            postalCode: "55343",
            country: "US"
        }
    }
}

digitalriver.createSource(cardCVV, payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
var payload = {
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
    "type": "creditCard",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "john.doe@digitalriver.com",
        phoneNumber: "000-000-0000",
        address: {
            line1: "10380 Bren Road West",
            line2: "Suite 123",
            city: "Minnetonka",
            state: "MN",
            postalCode: "55343",
            country: "US"
        }
    }
}

digitalriver.createSource(cardCVV, payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}
{% endtabs %}

#### PayPal

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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
var payload = {
    "type": "payPal",
    "amount": 120.99,
    "currency": "USD",
    "payPal": {
        "returnUrl": "http://mypage.com",
        "cancelUrl": "https://mypage.com/cancel",
        "items": [{
                "name": "Cell Phone (Unlocked)",
                "quantity": 1,
                "unitAmount": 100
            },
            {
                "name": "Headphones",
                "quantity": 1,
                "unitAmount": 15
            }
        ],
        "taxAmount": 0.99,
        "shippingAmount": 5,
        "amountsEstimated": true,
        "requestShipping": true,
        "shipping": {
            "recipient": "John Doe",
            "phoneNumber": "952-555-1212",
            "address": {
                "line1": "54321 Fake St.",
                "line2": "Apt. 3C",
                "city": "Minnetonka",
                "state": "MN",
                "country": "US",
                "postalCode": "55341"
            }
        }
    }
}


digitalriver.createSource(payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
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);
    }
});
```

{% endtab %}
{% endtabs %}

#### 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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
var payload = {
    "type": "payPalBilling",
    "amount": 120.99,
    "currency": "USD",
    "payPal": {
        "returnUrl": "http://mypage.com",
        "cancelUrl": "https://mypage.com/cancel",
        "items": [{
                "name": "Cell Phone (Unlocked)",
                "quantity": 1,
                "unitAmount": 100
            },
            {
                "name": "Headphones",
                "quantity": 1,
                "unitAmount": 15
            }
        ],
        "taxAmount": 0.99,
        "shippingAmount": 5,
        "amountsEstimated": true,
        "requestShipping": true,
        "shipping": {
            "recipient": "John Doe",
            "phoneNumber": "952-555-1212",
            "address": {
                "line1": "54321 Fake St.",
                "line2": "Apt. 3C",
                "city": "Minnetonka",
                "state": "MN",
                "country": "US",
                "postalCode": "55341"
            }
        }
    }
}


digitalriver.createSource(payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
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);
    }
});
```

{% endtab %}
{% endtabs %}

#### 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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
var payload = {
    "type": "payPalCredit",
    "amount": 120.99,
    "currency": "USD",
    "payPal": {
        "returnUrl": "http://mypage.com",
        "cancelUrl": "https://mypage.com/cancel",
        "items": [{
                "name": "Cell Phone (Unlocked)",
                "quantity": 1,
                "unitAmount": 100
            },
            {
                "name": "Headphones",
                "quantity": 1,
                "unitAmount": 15
            }
        ],
        "taxAmount": 0.99,
        "shippingAmount": 5,
        "amountsEstimated": true,
        "requestShipping": true,
        "shipping": {
            "recipient": "John Doe",
            "phoneNumber": "952-555-1212",
            "address": {
                "line1": "54321 Fake St.",
                "line2": "Apt. 3C",
                "city": "Minnetonka",
                "state": "MN",
                "country": "US",
                "postalCode": "55341"
            }
        }
    }
}


digitalriver.createSource(payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
var payload = {
    "type": "payPalCredit",
    "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);
    }
});
```

{% endtab %}
{% endtabs %}

#### SEPA Direct Debit

For SEPA Direct Debit, 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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
let payload = {
    "type": "directDebit",
    "amount": 100,
    "currency": "EUR",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "test@digitalriver.com",
        phoneNumber: "000-000-0000",
        address: {
            line1: "123 Main Street",
            line2: "",
            city: "Paris",
            postalCode: "14390",
            country: "FR"
        }
    },
    "directDebit": {
        "returnUrl": "https://mypage.com"
    }
}

digitalriver.createSource(payload).then(function(result) {

    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
var payload = {
    "type": "directDebit",
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "test@digitalriver.com",
        phoneNumber: "000-000-0000",
        address: {
            line1: "123 Main Street",
            line2: "",
            city: "Paris",
            postalCode: "14390",
            country: "FR"
        }
    },
    "directDebit": {
        "returnUrl": "https://mypage.com"
    }
}

digitalriver.createSource(payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}
{% endtabs %}

#### Wire Transfer

For Wire Transfer, 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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
let payload = {
    "type": "wireTransfer",
    "amount": 100,
    "currency": "EUR",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "test@digitalriver.com",
        phoneNumber: "000-000-0000",
        address: {
            line1: "123 Main Street",
            line2: "",
            city: "Paris",
            postalCode: "14390",
            country: "FR"
        }
    },
    "wireTransfer": {
    }
}

digitalriver.createSource(payload).then(function(result) {

    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
var data = {
    "type": "wireTransfer",
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "test@digitalriver.com",
        phoneNumber: "000-000-0000",
        address: {
            line1: "123 Main Street",
            line2: "",
            city: "Paris",
            postalCode: "14390",
            country: "FR"
        }
    },
    "wireTransfer": {
    }
}

digitalriver.createSource(data).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}
{% endtabs %}

#### Cash on Delivery - Japan

For Cash on Delivery - Japan, 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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
let payload = {
    "type": "codJapan",
    "amount": 100,
    "currency": "EUR",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "test@digitalriver.com",
        phoneNumber: "000-000-0000",
        address: {
            line1: "123 Main Street",
            line2: "",
            city: "Paris",
            postalCode: "14390",
            country: "FR"
        }
    },
    "codJapan": {
    }
}

digitalriver.createSource(payload).then(function(result) {

    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
var payload = {
    "type": "codJapan",
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "test@digitalriver.com",
        phoneNumber: "000-000-0000",
        address: {
            line1: "123 Main Street",
            line2: "",
            city: "Paris",
            postalCode: "14390",
            country: "FR"
        }
    },
    "codJapan": {
    }
}

digitalriver.createSource(payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}
{% endtabs %}

#### Payco - Korea Payments

For Payco - Korea Payments, 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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
let payload = {
    "type": "payco",
    "amount": 100,
    "currency": "KRW",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "test@digitalriver.com",
        address: {
            line1: "1234 Fake Street",
            line2: "Yaum-dong",
            city: "Ulsan-si",
            state: "Kyongsangnamdo",
            postalCode: "100-011",
            country: "KR"
        }
    },
    "payco": {
        "returnUrl": "https://yourReturnUrl.com"
    }
}

digitalriver.createSource(payload).then(function(result) {

    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
var payload = {
    "type": "payco",
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "test@digitalriver.com",
        address: {
            line1: "1234 Fake Street",
            line2: "Yaum-dong",
            city: "Ulsan-si",
            state: "Kyongsangnamdo",
            postalCode: "100-011",
            country: "KR"
        }
    },
    "payco": {
        "returnUrl": "https://yourReturnUrl.com"
    }
}

digitalriver.createSource(payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}
{% endtabs %}

#### Bank Transfer - Korea Payments

For Bank Transfer - Korea Payments, 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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
let payload = {
    "type": "bankTransfer",
    "amount": 100,
    "currency": "KRW",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "test@digitalriver.com",
        address: {
            line1: "1234 Fake Street",
            line2: "Yaum-dong",
            city: "Ulsan-si",
            state: "Kyongsangnamdo",
            postalCode: "100-011",
            country: "KR"
        }
    },
    "bankTransfer": {
        "returnUrl": "https://yourReturnUrl.com"
    }
}

digitalriver.createSource(payload).then(function(result) {

    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
var payload = {
    "type": "bankTransfer",
    "sessionId": "ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f",
    "owner": {
        firstName: "John",
        lastName: "Doe",
        email: "test@digitalriver.com",
        address: {
            line1: "1234 Fake Street",
            line2: "Yaum-dong",
            city: "Ulsan-si",
            state: "Kyongsangnamdo",
            postalCode: "100-011",
            country: "KR"
        }
    },
    "bankTransfer": {
        "returnUrl": "https://yourReturnUrl.com"
    }
}

digitalriver.createSource(payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}
{% endtabs %}

#### Online Banking - IBP

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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
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 end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
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 end
        sendToBackend(source);
    }
});
```

{% endtab %}
{% endtabs %}

#### 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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
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 end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
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 end
        sendToBackend(source);
    }
});
```

{% endtab %}
{% endtabs %}

#### 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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
let payload = {
    "type": "klarnaCredit",
    "owner": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "email@email.org",
        "phoneNumber": "9522253720",
        "address": {
            "line1": "line1",
            "line2": "line2",
            "city": "Minnetonka",
            "state": "MN",
            "country": "US",
            "postalCode": "55410"
        }
    },
    "amount": "101.50",
    "currency": "USD",
    "klarnaCredit": {
        "returnUrl": "http://example.com/return",
        "cancelUrl": "http://example.com/cancel",
        "taxAmount": 0,
        "shippingAmount": 5.75,
        "items": [{
            "name": "Happy Ball",
            "quantity": "1",
            "unitAmount": "94.25",
            "subscriptionInfo": {
                "autoRenewal": true,
                "freeTrial": false
            }
        },
        {
            "name": "Happy Ball1",
            "quantity": "2",
            "unitAmount": "0.75"
        }],
        "locale": "en_US",
        "shipping": {
            "recipient": "Guy Incognito",
            "phoneNumber": "9522253720",
            "address": {
                "line1": "line1",
                "line2": "line2",
                "city": "Minnetonka",
                "state": "MN",
                "country": "US",
                "postalCode": "55410"
            },
            "email": "test_email@email.org"
        },
        "accountId": "456789",
        "accountCreatedDate": "2020-11-24T15:20:00.000Z",
        "accountUpdatedDate": "2012-11-25T15:30:00.001Z",
        "hasPaidBefore": false,
        "subscriptionDescription": "Klarna Credit Recurring",
        "subscriptionStartDate": "2019-10-24T15:00:00.030Z",
        "subscriptionEndDate": "2021-10-24T15:00:00.030Z",
        "autoRenewal": "false",
        "affiliateName": "Sample Affiliate"
    }
}

digitalriver.createSource(payload).then(function(result) {

    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
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 end
        sendToBackend(source);
    }
});
```

{% endtab %}
{% endtabs %}

#### 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.

{% tabs %}
{% tab title="Without payment sessions" %}

```javascript
let payload = {
    "type": "klarnaCreditRecurring",
    "owner": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "email@email.org",
        "phoneNumber": "9522253720",
        "address": {
            "line1": "line1",
            "line2": "line2",
            "city": "Minnetonka",
            "state": "MN",
            "country": "US",
            "postalCode": "55410"
        }
    },
    "amount": "101.50",
    "currency": "USD",
    "klarnaCreditRecurring": {
        "returnUrl": "http://example.com/return",
        "cancelUrl": "http://example.com/cancel",
        "taxAmount": 0,
        "shippingAmount": 5.75,
        "items": [{
            "name": "Happy Ball",
            "quantity": "1",
            "unitAmount": "94.25",
            "subscriptionInfo": {
                "autoRenewal": true,
                "freeTrial": false
            }
        },
        {
            "name": "Happy Ball1",
            "quantity": "2",
            "unitAmount": "0.75"
        }],
        "locale": "en_US",
        "shipping": {
            "recipient": "Guy Incognito",
            "phoneNumber": "9522253720",
            "address": {
                "line1": "line1",
                "line2": "line2",
                "city": "Minnetonka",
                "state": "MN",
                "country": "US",
                "postalCode": "55410"
            },
            "email": "test_email@email.org"
        },
        "accountId": "456789",
        "accountCreatedDate": "2020-11-24T15:20:00.000Z",
        "accountUpdatedDate": "2012-11-25T15:30:00.001Z",
        "hasPaidBefore": false,
        "subscriptionDescription": "Klarna Credit Recurring",
        "subscriptionStartDate": "2019-10-24T15:00:00.030Z",
        "subscriptionEndDate": "2021-10-24T15:00:00.030Z",
        "autoRenewal": "false",
        "affiliateName": "Sample Affiliate"
    }
}

digitalriver.createSource(payload).then(function(result) {

    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});
```

{% endtab %}

{% tab title="With payment sessions" %}

```javascript
var payload = {
  "type" : "klarnaCreditRecurring",
  "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",
  "klarnaCreditRecurring" : {
    "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 end
        sendToBackend(source);
    }
});
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.