# Managing sources Commerce API has two broad categories of payment sources: [primary and secondary](#primary-versus-secondary-sources). After you [create a payment source](#creating-payment-sources) for both categories, you can [attach it to a cart](#attaching-sources-to-a-cart) so we can use it to generate a one-time charge. You can also [detach sources](#detaching-sources-from-cart) from carts. If the [primary source](#primary-payment-sources) supports [reusability](https://docs.digitalriver.com/commerce-api/payments/sources/..#reusable-or-single-use), [save it to a customer's account](#attaching-sources-to-customers). For shoppers with multiple saved payment `sources[]`, we also provide you the ability to [set the default one](#setting-the-default-payment-source). You can [combine primary and secondary sources](#combining-primary-and-secondary-payment-sources), but how you sequence their application depends on whether or not the primary source is [reusable](https://docs.digitalriver.com/commerce-api/payments/sources/..#reusable-or-single-use). When [building your payment flows](https://docs.digitalriver.com/commerce-api/payments/building-your-workflows), the [DigitalRiver object](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object) exposes methods for [authenticating ](#authenticating-sources)and [updating](#updating-sources) sources that can be useful in purchase and account management scenarios. When [building your payment workflows](https://docs.digitalriver.com/commerce-api/payments/building-your-workflows), you should know the differences between [primary ](#primary-payment-sources)and [secondary ](#secondary-payment-sources)payment sources and how they affect the [payment session](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions). ### Primary payment sources Primary payment [sources ](https://www.digitalriver.com/docs/commerce-admin-api/#tag/Source)come from traditional payment methods like [credit cards](https://docs.digitalriver.com/commerce-api/payments/supported-payment-methods/credit-cards), [Google Pay](https://docs.digitalriver.com/commerce-api/payments/supported-payment-methods/google-pay), and [Wire Transfers](https://docs.digitalriver.com/commerce-api/payments/supported-payment-methods/wire-transfer). Most customers use a primary source when purchasing, but a [cart ](https://www.digitalriver.com/docs/commerce-shopper-api/#tag/Apply-Shopper)can only contain one primary source. Primary sources created from [payment methods that support reusability](https://docs.digitalriver.com/commerce-api/payments/supported-payment-methods) may be able to be [associated with a customer](https://docs.digitalriver.com/commerce-api/payments/sources/..#attaching-a-payment-method-to-a-customer-or-payment-option) and then [reused ](https://docs.digitalriver.com/commerce-api/payments/sources/..#reusable-or-single-use)in future transactions. Alternatively, you can [attach a primary source to a cart](https://docs.digitalriver.com/commerce-api/payments/sources/..#attaching-a-payment-method-to-an-order-or-cart), thereby enabling Digital River to submit a charge authorization request after you [submit the cart](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/submitting-a-cart). ### Secondary payment sources Secondary payment [sources](https://app.gitbook.com/s/drE2RCYBuoRpd2TC2sx2/payment-source/source-management#sources-id) are typically used to supplement a [primary source](#primary-payment-sources). {% hint style="info" %} Commerce API currently only supports the[`customerCredit`](https://docs.digitalriver.com/commerce-api/shopper-apis/shopper-basics/common-use-cases/applying-store-credit) type as a supported secondary source. {% endhint %} You can successfully submit an order entirely with secondary sources, but you must ensure the [payment session state](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions#session-state) is valid and the [amount contributed is sufficient](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions#session-state). You cannot edit the `amount` value for a secondary source. To change the `amount` value for the secondary source: 1. [Detach the primary source](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-or-detach-payment-methods#v1-shoppers-me-carts-active-apply-payment-method-1) (or [detach all sources from the cart](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-or-detach-payment-methods#v1-shoppers-me-carts-active-payment)). 2. [Create a new secondary source](#creating-secondary-sources) with the correct amount. 3. [Attach the new secondary source to the cart](#attaching-multiple-payment-sources-to-the-cart). 4. If needed, [attach the primary source to the cart](#attaching-multiple-payment-sources-to-the-cart). {% hint style="info" %} Attach the secondary source to the cart first. The primary source will cover the remaining amount. If you attach the primary source first, the primary source will cover the entire amount, and the secondary source will be ignored when the order is submitted. {% endhint %} Secondary sources do not support [reusability](https://docs.digitalriver.com/commerce-api/payments/sources/..#reusable-or-single-use). Therefore, they [cannot be saved to a customer's account](#restrictions-on-saving-sources). They should only be [attached to a cart](#attaching-sources-to-a-cart) to create a one-time charge when that cart is converted to an order. ## Creating payment sources We provide multiple options for [creating primary sources](#creating-primary-sources) and [creating secondary sources](#creating-secondary-sources). #### Creating primary sources You create [primary sources](#primary-payment-sources) with your [public API](https://app.gitbook.com/s/oUderMtztdH7OKDXmYbI/commerce-api-reference-guide/api-structure/api-keys#public-keys) key using Drop-in payments or [DigitalRiver.js with elements](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js). Once the [source is `chargeable`](https://docs.digitalriver.com/commerce-api/payments/sources/..#source-state), you should either [attach the source to a cart](#attaching-sources-to-a-cart) or [save the source to a customer's account](#attaching-sources-to-customers). #### Creating secondary sources You create [secondary sources](#secondary-payment-sources) through the [Sources API](https://app.gitbook.com/s/drE2RCYBuoRpd2TC2sx2/payment-source/source-management) by sending your [confidential API key](https://app.gitbook.com/s/oUderMtztdH7OKDXmYbI/commerce-api-reference-guide/api-structure/api-keys#confidential-keys) in a `POST/sources` request. When defining the request, you retrieve the [payment session identifier](https://docs.digitalriver.com/commerce-api/shopper-apis/cart/payment-sessions#retrieving-available-payment-methods) from the cart you're building. The `amount` is optional, except when the `type` is `customerCredit`. The `type` is required, and we currently only support `customerCredit`. You must also send an empty hash table whose name matches the `type`. The `owner` hash table is optional and can be used to meet our billing address requirements. When creating a secondary source, you can provide the owner's information, including the address. {% hint style="info" %} We recommend not providing an [owner object](https://docs.digitalriver.com/commerce-api/payments-solutions/digitalriver.js/payment-methods/common-payment-objects#owner-object) with the secondary source. This ensures that the wrong address is not applied to the cart, which will trigger a payment auth failed error. {% endhint %} The `upstreamId` parameter is useful for mapping the source to your credit management system. {% tabs %} {% tab title="POST/sources request" %} ``` curl --location --request POST 'https://api.digitalriver.com/sources' \ --header 'Authorization: Bearer ' \ ... --data-raw '{ "paymentSessionId": "ps_8cecaa32-f692-44cc-b103-4cf24dc93913", "amount": 2, "type": "customerCredit", "customerCredit": {} "upstreamId": "7765374748", }' ``` {% endtab %} {% endtabs %} A `201 OK` response returns a unique [source](https://app.gitbook.com/s/drE2RCYBuoRpd2TC2sx2/payment-source/source-management) in a [`chargeable` state](https://docs.digitalriver.com/commerce-api/payments/sources/..#source-state). You should [attach it to a cart](#attaching-sources-to-a-cart) so that we can use it to generate a one-time charge. {% tabs %} {% tab title="POST/sources response" %} ```javascript { "id": "99fe8ad1-999e-4e13-95d5-248e472aa7c8", "createdTime": "2021-02-24T21:59:05Z", "type": "customerCredit", "currency": "USD", "amount": 2.0, "reusable": false, "state": "chargeable", "clientSecret": "99fe8ad1-999e-4e13-95d5-248e472aa7c8_a8c8bbb4-e9da-4cd7-a3c3-3a00272ced18", "customerCredit": {}, "paymentSessionId": "ps_8cecaa32-f692-44cc-b103-4cf24dc93913", "upstreamId": "7765374748", "liveMode": false } ``` {% endtab %} {% endtabs %} ## Combining primary and secondary payment sources You can associate a [primary payment source](#primary-payment-sources) with only one [secondary payment source](#secondary-payment-sources). In the Cart API, the following payment methods support the use of `customerCredit`: [Credit Cards](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js/payment-methods/credit-cards), [Google Pay](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js/payment-methods/google-pay), [Klarna](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js/payment-methods/klarna), [PayPal Express Checkout](https://docs.digitalriver.com/commerce-api/payments-solutions/digitalriver.js/payment-methods/paypal#paypal-express-checkout-digital-wallet), [PayPal Credit](https://docs.digitalriver.com/commerce-api/payments-solutions/digitalriver.js/payment-methods/paypal#paypal-credit), [PayPal Billing Agreement](https://docs.digitalriver.com/commerce-api/payments-solutions/digitalriver.js/payment-methods/paypal#paypal-billing-agreement), and [Wire Transfer](https://docs.digitalriver.com/commerce-api/payments/supported-payment-methods/wire-transfer). {% hint style="info" %} We currently only support `customerCredit` as a secondary source. {% endhint %} ### Attaching multiple payment sources to the cart You can only associate one primary source with a cart. If there's a primary source in the cart and you try to attach a different primary source, [remove all attached sources](#detaching-sources-from-a-cart) or remove the [attached primary payment source](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-or-detach-payment-methods#v1-shoppers-me-carts-active-apply-payment-method-1) directly from the cart, then attach new sources. {% hint style="danger" %} Always apply the secondary sources first when using multiple sources in a cart. Apply the primary source last. {% endhint %} For a list of payment methods that support reusability, refer to the [Supported payment methods](https://docs.digitalriver.com/commerce-api/payments/supported-payment-methods). Choose one of the best practices below to attach two sources to a cart. #### Best practice 1: Use /apply-payment-method Use the following steps for both authenticated shoppers and anonymous shoppers. 1. Send the [`POST /apply-payment-method`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-or-detach-payment-methods#v1-shoppers-me-carts-active-apply-payment-method) request to attach a secondary source. 2. Send the [`POST /apply-payment-method`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-or-detach-payment-methods#v1-shoppers-me-carts-active-apply-payment-method) request to attach a primary source. #### Best practice 2: Use /apply-payment-method and /apply-shopper Use the following steps only for authenticated shoppers. 1. Send the [`POST /apply-payment-method`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-or-detach-payment-methods#v1-shoppers-me-carts-active-apply-payment-method) request to attach a secondary source. 2. Send the [`POST /apply-shopper`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-a-shopper-to-a-cart#v1-shoppers-me-carts-active-apply-shopper) request to attach the primary source. The default payment option saved to the shopper will be applied to the cart when applying a shopper. Note that the shopper can only save the primary source to their account. ### Address information When you attach a source to the cart using the [`POST /apply-payment-method`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-or-detach-payment-methods#v1-shoppers-me-carts-active-apply-payment-method), the system will not use the address if the cart already has address information. It will use the existing address in the cart. If the cart does not have the address information, the system will copy the address from the `source` to the cart. This behavior applies to both primary and secondary sources. Therefore, we recommend not including the owner's information when you [create a secondary source](#creating-secondary-sources). When you attach a source to a shopper using [`POST /payment-options`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/shoppers/payment-options#v1-shoppers-me-payment-options-1), the system will save the source's payment information and address to the shopper's payment options and associate the address with the payment. When you apply a shopper to a cart using [`POST /apply-shopper`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-a-shopper-to-a-cart#v1-shoppers-me-carts-active-apply-shopper), the system will apply the shopper's default payment method and copy the address associated with the payment method to the card, regardless of whether the cart has an address available. ### Amount contributed from each payment source After applying the payment source to the cart, the amount contributed by the payment source appears in the `amountContributed` field for the `paymentMethod` object in the /cart, /submit-cart, and /order responses. {% code title="Single payment example" %} ```json { "paymentMethod": { "type": "creditCard", "sourceId": "ba462e2a-885e-4436-9c9a-e8a3988daa49", "sourceClientSecret": "ba462e2a-885e-4436-9c9a-e8a3988daa49_bd6910cf-1bae-413e-b4d0-98034efe527c", "creditCard": { "expirationYear": "2525", "lastFourDigits": "1111", "clientSecret": "ba462e2a-885e-4436-9c9a-e8a3988daa49_bd6910cf-1bae-413e-b4d0-98034efe527c", "expirationMonth": "8", "brand": "Visa", "flow": "standard", "reusable": "false" }, "amountContributed": { "currency": "USD", "value": 68.01 } } } ``` {% endcode %} {% code title="Two payment methods example" %} ```json "paymentMethod": { "type": "creditCard", "sourceId": "d86502e8-5252-48e2-bd82-c2fe6de8810b", "sourceClientSecret": "d86502e8-5252-48e2-bd82-c2fe6de8810b_66601535-e527-489a-9b5c-847e9e940aed", "creditCard": { "expirationYear": "2525", "lastFourDigits": "1111", "clientSecret": "d86502e8-5252-48e2-bd82-c2fe6de8810b_66601535-e527-489a-9b5c-847e9e940aed", "expirationMonth": "8", "brand": "Visa", "flow": "standard", "reusable": "false" }, "amountContributed": { "currency": "USD", "value": 68.01 }, "supplementaryPaymentMethods": [ { "type": "customerCredit", "sourceId": "4db130f3-2302-43f2-9f7a-eed3835e1a7e", "sourceClientSecret": "4db130f3-2302-43f2-9f7a-eed3835e1a7e_6b7e2d5a-9037-46a8-8632-4d90b0113ffa", "customerCredit": { "clientSecret": "4db130f3-2302-43f2-9f7a-eed3835e1a7e_6b7e2d5a-9037-46a8-8632-4d90b0113ffa", "flow": "standard", "reusable": "false" }, "amountContributed": { "currency": "USD", "value": 50 } } ] }, ``` {% endcode %} ### Amount contribution of the entire order The `paymentSession` object shows the following information for an entire order: * `amountContributed`: indicates the accumulated contributed amount of the attached payment sources. * `amountRemainingToBeContributed`: indicates the gap amount required to fulfill the order. If the value is not zero, the shopper should pay the remaining cost to cover the order's total amount. {% code title="paymentSession example" %} ```json { "paymentSession": { "id": "3c9bf484-2ec5-46f8-8e88-5f126f026187", "clientSecret": "3c9bf484-2ec5-46f8-8e88-5f126f026187_668c5e4d-0a80-4338-9dce-3825f0831782", "status": "requires_confirmation", "amountContributed": { "currency": "USD", "value": 118.01 }, "amountRemainingToBeContributed": { "currency": "USD", "value": 0 } } } ``` {% endcode %} ### Detaching payment sources from a cart Use one of the following options to remove all attached sources directly from a cart. * [`DELETE v1/shoppers/me/carts/active/apply-payment-method`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-or-detach-payment-methods#v1-shoppers-me-carts-active-apply-payment-method-1) This option removes a payment source from the cart. To remove payment sources individually, include the source ID in the payload. * [`DELETE v1/shoppers/me/carts/active/payment`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-or-detach-payment-methods#v1-shoppers-me-carts-active-payment) removes all attached sources directly from the cart When finished, you can [attach new sources](#attaching-multiple-sources-to-the-cart) to the cart. ### Refunds If a customer requests a refund, the system will first refund the [primary payment source](#primary-payment-sources). Once the system has fully refunded the primary source, it will use the [secondary payment source](#secondary-payment-sources) to refund the remaining value. For example, a customer purchased a line item quantity of 10 for $1000. They used $600 from their primary payment source (a credit card) and $400 from their secondary (store credit) to pay for the order. If the customer requests a refund of $400, the system refunds $400 to their credit card. If the customer requests a refund of $700, the system refunds $600 to their credit card and $100 to their store credit. ## Charging a single-use payment source Your storefront may be configured so that customers are not required to create an account or sign in to purchase. In this case, after you submit the guest customer's payment details, [DigitalRiver.js with elements](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js) will [create a Source](https://docs.digitalriver.com/commerce-api/resources/reference/digitalriver-object#createsource-sourcedata) and return the `sourceId` .You can then use a [`POST /apply-payment-method`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-or-detach-payment-methods#v1-shoppers-me-carts-active-apply-payment-method) request to set the `sourceId` attribute. {% tabs %} {% tab title="cURL" %} ```json curl --location --request POST 'https://<>/v1/shoppers/me/carts/active/apply-payment-method' \ --header 'Content-Type: application/json' \ --header 'authorization: bearer ***\ --data-raw '{ "paymentMethod": { "sourceId": "e7ba0595-059c-460c-bad8-2812123b9313" } }' ``` {% endtab %} {% endtabs %} Since the Source is not attached to a Shopper, this payment method object [cannot be reused](https://docs.digitalriver.com/commerce-api/payments/sources/..#reusable-or-single-use) for future purchases, and once used, its state becomes `consumed`. ## Switching the default payment source Registered customers may have multiple saved payment methods associated with their accounts. These Source objects are stored in the `sources` array of the [Payment options](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/shoppers/payment-options) resource. The first source you attach to a customer becomes its default, sets `isDefault` as `true`, and assigns to the customer's `sourceId` attribute. If you'd like to assign a different default payment source, submit a [`POST /payment-options/{id}`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/shoppers/payment-options#v1-shoppers-me-payment-options-1) request where `{id}` is the new default payment method and set `isDefault` to `true`. {% tabs %} {% tab title="cURL" %} ```json curl --location --request POST 'https://<>/v1/shoppers/me/payment-options/{id}' \ --header 'Content-Type: application/json' \ --header 'authorization: bearer ***\ --data-raw '{ "paymentOption" : { "nickName" : "Credit Card", "isDefault" : "true", "sourceId":"{{sourceId}}" } }' ``` {% endtab %} {% endtabs %}