LogoLogo
System Status
  • Commerce API
    • Test and use cases
    • Roles and permissions
    • Sending API calls
  • Shopper APIs
    • Shopper basics
      • Common use cases
        • Creating a customer
        • Applying store credit
        • Private store workflow
        • Guest checkout
    • OAuth
      • Authentication
      • OAuth 2.0 APIs
      • Token
      • Access tokens
      • Session-aware access tokens
      • Authorizing a shopper
    • Shoppers
      • Managing shoppers
        • User management
        • Single sign-on (SSO)
        • Data validation
        • Bulk user management
        • Bulk user account export
      • Managing a shopper's account
      • Managing a shopper's address
      • Managing payment options
    • Product discovery
      • Categories
      • Products
      • Product variations
      • Pricing
      • Inventory status
      • Financing
      • Offers
        • Understanding offers
        • How to use point of promotions (POPs)
          • Retrieving all point of promotion offers for a specific product
          • Retrieving all offers for a specific point of promotion
        • How to use offers
      • Private stores
        • Managing private stores
        • Submitting an order for a private store
        • Useful APIs
      • Fulfillment
        • Electronic Fulfillment Service (OFI)
        • Digital rights
        • Digital rights revocation
        • Physical fulfillment
          • EDI X12 832 definition data elements
          • EDI X12 846 definition data elements
          • EDI X12 850 definition data elements
          • EDI X12 855 definition data elements
          • EDI X12 856 definition data elements
          • EDI X12 180-1 definition data elements
          • EDI X12 180-2 definition of data elements
          • EDI X12 180-3 definition of data elements
    • Cart
      • Applying a shopper to a cart
      • Getting the current cart
      • Creating or updating a cart
        • Adding a product to a cart
          • Gifting
        • Capturing the customer's IP address
        • Providing address information
        • Managing the shipping or billing address
        • Providing subscription information
        • Managing payment methods
        • Capturing the Terms of Sale (TOS) acceptance
      • Managing offers in a cart
        • Applying an offer
        • Applying a coupon or promo code
        • Getting all applied offers
        • Removing an applied offer
        • Removing eligible offers
        • Reconciling conflicting offers
        • Dynamic offers/personalization
          • Skipping Global Commerce merchandising offer arbitration
          • Triggering a promotional URL offer
          • Overriding a promotional URL offer discount
      • Pricing
        • Landed cost
          • Mixed cart support
          • Tax-included pretty price
      • Redirecting to a Digital River-hosted cart
      • Configuring taxes
        • Managing tax identifiers
      • Managing shipping options
        • Getting shipping options
        • Providing a shipping discount
      • Managing line items
      • Applying a price override
      • Managing payment sessions
      • Managing web checkout
      • Submitting a cart
        • Initiating a charge
        • Authorization declines
      • Resuming cart submission
      • HGOP2
    • Orders
      • Getting orders
      • Selling entities
      • Retrieving addresses from an order
      • Retrieving line items from an order
      • Order lookup
      • Returns
        • Initiate an authenticated session
        • Setting up returns in Global Commerce
        • Managing returns
    • Subscriptions
      • Retrieve the subscription
        • Getting all orders for a subscription
        • Getting a subscription's pending actions
        • Getting all subscriptions for a shopper
        • Getting a subscription by identifier
      • Update subscription at the next renewal
        • Changing the subscription renewal type
        • Changing the subscription renewal quantity
        • Adding or updating a perpetual unit price
        • Changing the subscription's payment option
        • Changing the subscription's payment source
      • Immediately change the subscription
        • Updating the subscription's shipping address
        • Updating a subscription's billing and shipping email address
        • Cancelling a subscription
      • Immediately apply a midterm subscription change
        • Reducing the subscription renewal quantity
  • Admin APIs
    • Admin basics
      • Available Admin API calls
    • Order management
      • Getting the order's details
      • Downloading the invoice
    • Offer management
    • Refund management
      • Authorization
      • Refund reason codes
      • Creating a satisfaction refund
      • Getting the available refunds for a specific order
      • Getting refunds for a specific order
      • Getting refunds available for a shopper's order
      • Getting the JSON schema for an order refund
      • Managing a refund for a delayed payment method
      • Refund error scenarios
    • Subscription management
      • Retrieve the subscription
        • Getting all orders for a subscription
        • Getting a subscription's pending actions
        • Getting all subscriptions for a shopper
        • Getting a subscription by identifier
      • Update the subscription at the next renewal
        • Changing the subscription renewal type
        • Changing the subscription renewal product
        • Changing the subscription renewal price
        • Changing the subscription renewal quantity
        • Adding or updating a perpetual unit price
        • Changing the subscription's payment option
        • Changing the subscription's payment source
      • Immediately change the subscription
        • Activating a subscription
        • Changing the subscription's external reference identifier
        • Updating a subscription's billing and shipping email address
        • Cancelling a subscription
        • Updating the subscription's expiration date
      • Immediately apply a midterm subscription change
        • Applying a midterm change with price override
        • Reducing the subscription renewal quantity
      • Subscription notifications
        • Updating the subscriber's email address
        • Card Account Updater
        • Sending a payment information change notification
        • Sending an expired credit card notification
        • Sending an invalid payment account notification
        • Sending a payment failure notification
        • Sending a subscription renewal reminder notification
        • Setting up subscription renewal reminders
        • Setting up trial subscription renewal reminders
        • Setting up marketing reminders
      • Using the Expired Card Optimizer
    • Customer management
      • Retrieving customer details
      • Requesting PII removal for a customer
    • Site management
      • Configuring authorized shipping and billing countries
      • Getting a site's authorized billing countries
      • Getting a site's authorized shipping countries
    • Product management
      • Getting started
      • Manage products (asynchronous API)
        • Creating or updating a product
        • Adding or updating a product variation
        • Deploying a product
        • Applying live changes
        • Retiring a product
        • Deleting a product variation
        • Deleting a base or individual product's locale
      • Retrieve products (synchronous API)
        • Getting a product by locale
        • Getting a product variation
        • Getting a product variation by locale
      • Get the task status for a product (synchronous API)
        • Getting the latest information on a product task
        • Retrieving the tasks for a specific product
        • Retrieving the tasks for products
      • Bulk operation
        • Asynchronous bulk operations
          • Creating products in bulk
          • Updating products in bulk
          • Deploying products in bulk
          • Deleting product variations in bulk
        • Bulk product upload (BPU)
        • Bulk Product Export (BPE)
          • Line-item level satisfaction refund
          • Order-level satisfaction refund
          • Auto-created line-item level return product
          • Line-item level return product
    • File management
      • Downloading a file
  • Payments
    • Payments solutions
      • Drop-in payments
        • How Drop-in payments work
        • Drop-in payments integration guide
      • DigitalRiver.js with Elements
        • Elements integration guide
        • Configuring payment methods
          • Configuring Afterpay
          • Configuring Alipay+ (cross-border)
          • Configuring Alipay (domestic)
          • Configuring Amazon Pay
          • Configuring Apple Pay
          • Configuring Bancontact
          • Configuring BLIK
          • Configuring Boleto
          • Configuring CCAvenue
          • Configuring Clearpay
          • Configuring Credit Cards
          • Configuring FPX Online Banking
          • Configuring Google Pay
          • Configuring iDEAL
          • Configuring Klarna
          • Configuring Konbini
          • Configuring Online Banking (IBP)
          • Configuring Online Banking (Korea Bank Transfer)
          • Configuring PayCo
          • Configuring PayPal
          • Configuring SEPA Direct Debit
          • Configuring Trustly
          • Configuring Wire Transfer
          • Common payment sources
          • Common payment objects
    • Supported payment methods
      • Afterpay
      • Alipay (domestic)
      • Alipay+ (cross-border)
      • Amazon Pay
      • Apple Pay
      • Bancontact
      • BLIK
      • Boleto
      • CCAvenue
      • Clearpay
      • Credit Cards
      • FPX Online Banking
      • Google Pay
      • iDEAL
      • Klarna
      • Konbini
      • Korea Bank Transfer (Online Banking)
      • Online Banking (IBP)
      • PayCo
      • PayPal
      • PayPal Billing Agreement
      • PayPal Credit
      • PayPal Pay in 3
      • PayPal Pay in 4
      • PayPal RatenZahlung (Installment Payment)
      • SEPA Direct Debit
      • Trustly
      • Wire Transfer
    • Source basics
      • Managing sources
      • Handling credit card sources
      • Retrieving sources
    • Building payment workflows
      • Flows by payment type
      • Handling redirect payment methods
    • PSD2 and SCA
    • Payment testing scenarios
      • Testing standard payment methods
      • Testing redirect payment methods
      • Testing receiver payment methods
      • Testing the CCAvenue payment method
  • Events
    • Events overview
    • Responding to events
    • Event types
      • Delayed payment event types
        • Delayed payment expired event
          • Boleto
          • Konbini
          • Wire Transfer
        • Delayed payment reminder event
          • Boleto
          • Konbini
          • Wire Transfer
      • Subscription event types
        • Subscription created event
        • Subscription updated event
        • Subscription action processed event
        • Subscription cancelled event
        • Subscription credit card expired event
        • Subscription payment information changed event
        • Subscription renewal reminder event
        • Subscription renewed event
        • Subscription trial converted event
        • Subscription trial renewal reminder event
        • Subscription payment failed event
      • Post-order event types
        • Invoice created event
        • Refund credit memo event
      • Inventory event types
        • Inventory out of stock event
        • Inventory source and management
        • Inventory self-managed updated event
        • Inventory fulfiller-managed updated event
      • Post-order Notification Integration Guide
    • Webhooks
      • Commerce API safelist
      • Searching for a webhook
      • Creating a webhook
      • Using webhooks
      • Editing a webhook
      • Turning webhooks on or off
      • Revealing a webhook's secret
      • Rotating a webhook's secret
      • Viewing the webhook details
      • Deleting a webhook
  • Developer Resources
    • Postman collection
    • Commerce API references
    • Shopper APIs reference
    • Admin APIs reference
    • DigitalRiver.js reference
      • Including DigitalRiver.js
      • Initializing DigitalRiver.js
      • DigitalRiver object
      • Elements
        • Amazon Pay element
        • Apple Pay elements
        • Google Pay elements
        • IBAN element
        • iDEAL element
        • Konbini elements
        • Compliance element
        • Offline refund element
        • Online Banking elements
        • Tax Identifier element
        • Delayed payment instructions element
        • PayPal elements
      • Guidelines for capturing payment details
      • Security
      • Digital River payment objects
      • Error types, codes, and objects
  • General resources
    • Global Commerce
    • Global Commerce
      • Company hierarchy
      • Categories
        • Getting a list of categories
      • Products
        • Product scenarios
        • Individual products
          • Creating an individual product
        • Base product with variants
          • Creating a base product with variants
        • Bundle offers
          • Creating a prorated bundle offer with a subscription
        • Product combination
          • Creating a product combination
        • Gifting
        • Inventory status
      • Customer service
        • Log a shopper's request to remove PII
      • Customers
        • Creating a customer
        • Digital River-maintained customer login
        • Client-maintained customer login
      • Transparent Commerce purchase flow
    • eCompass
    • eCompass documentation
    • Release notes
      • 2024
      • 2024 latest
      • 2023
      • 2022
      • 2021
      • 2020
Powered by GitBook
On this page
  • Primary payment sources
  • Secondary payment sources
  • Creating payment sources
  • Combining primary and secondary payment sources
  • Attaching multiple payment sources to the cart
  • Address information
  • Amount contributed from each payment source
  • Amount contribution of the entire order
  • Detaching payment sources from a cart
  • Refunds
  • Charging a single-use payment source
  • Switching the default payment source

Was this helpful?

  1. Payments
  2. Source basics

Managing sources

Learn how to manage sources.

PreviousSource basicsNextHandling credit card sources

Last updated 4 months ago

Was this helpful?

Commerce API has two broad categories of payment sources: .

After you for both categories, you can so we can use it to generate a one-time charge. You can also from carts.

If the supports , . For shoppers with multiple saved payment sources[], we also provide you the ability to .

You can , but how you sequence their application depends on whether or not the primary source is .

When , the exposes methods for and sources that can be useful in purchase and account management scenarios.

When , you should know the differences between and payment sources and how they affect the .

Primary payment sources

Primary payment come from traditional payment methods like , , and . Most customers use a primary source when purchasing, but a can only contain one primary source.

Primary sources created from may be able to be and then in future transactions.

Alternatively, you can , thereby enabling Digital River to submit a charge authorization request after you .

Secondary payment sources

Secondary payment are typically used to supplement a .

Commerce API currently only supports the type as a supported secondary source.

You can successfully submit an order entirely with secondary sources, but you must ensure the is valid and the .

You cannot edit the amount value for a secondary source. To change the amount value for the secondary source:

  1. (or ).

  2. with the correct amount.

  3. .

  4. If needed, .

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.

Creating payment sources

Creating primary sources

Creating secondary sources

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.

The upstreamId parameter is useful for mapping the source to your credit management system.

curl --location --request POST 'https://api.digitalriver.com/sources' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
    "paymentSessionId": "ps_8cecaa32-f692-44cc-b103-4cf24dc93913",
    "amount": 2,
    "type": "customerCredit",
    "customerCredit": {}
    "upstreamId": "7765374748",
}'
{
    "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
}

Combining primary and secondary payment sources

We currently only support customerCredit as a secondary source.

Attaching multiple payment sources to the cart

Always apply the secondary sources first when using multiple sources in a cart. Apply the primary source last.

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.

Best practice 2: Use /apply-payment-method and /apply-shopper

Use the following steps only for authenticated shoppers.

Address information

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.

Single payment example
{
    "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
        }
    }
}
Two payment methods example
        "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
                    }
                }
            ]
        },

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.

paymentSession example
{
    "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
        }
    }
}

Detaching payment sources from a cart

Use one of the following options to remove all attached sources directly from a cart.

Refunds

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

curl --location --request POST 'https://<<host>>/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"
  }
}'

Switching the default payment source

curl --location --request POST 'https://<<host>>/v1/shoppers/me/payment-options/{id}' \
--header 'Content-Type:  application/json' \
--header 'authorization: bearer ***\
--data-raw '{
  "paymentOption" : {
    "nickName" : "Credit Card",
    "isDefault" : "true",
    "sourceId":"{{sourceId}}"
  }
}'

Secondary sources do not support . Therefore, they . They should only be to create a one-time charge when that cart is converted to an order.

We provide multiple options for and .

You create with your key using Drop-in payments or . Once the , you should either or .

You create through the by sending your in a POST/sources request.

When defining the request, you retrieve the 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.

We recommend not providing an with the secondary source. This ensures that the wrong address is not applied to the cart, which will trigger a payment auth failed error.

A 201 OK response returns a unique in a . You should so that we can use it to generate a one-time charge.

You can associate a with only one .

In the Cart API, the following payment methods support the use of customerCredit: , , , , , , and .

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, or remove the directly from the cart, then attach new sources.

For a list of payment methods that support reusability, refer to the .

Send the request to attach a secondary source.

Send the request to attach a primary source.

Send the request to attach a secondary source.

Send the 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.

When you attach a source to the cart using the , 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 .

When you attach a source to a shopper using , 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 , 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.

This option removes a payment source from the cart. To remove payment sources individually, include the source ID in the payload.

removes all attached sources directly from the cart

When finished, you can to the cart.

If a customer requests a refund, the system will first refund the . Once the system has fully refunded the primary source, it will use the to refund the remaining value.

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, will and return the sourceId .You can then use a request to set the sourceId attribute.

Since the Source is not attached to a Shopper, this payment method object for future purchases, and once used, its state becomes consumed.

Registered customers may have multiple saved payment methods associated with their accounts. These Source objects are stored in the sources array of the 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 request where {id} is the new default payment method and set isDefault to true.

Supported payment methods
creating primary sources
creating secondary sources
primary payment source
secondary payment source
create a secondary source
attach new sources
primary payment source
secondary payment source
cannot be saved to a customer's account
attached to a cart
reusability
cannot be reused
payment session identifier
building your payment flows
DigitalRiver object
building your payment workflows
payment session
sources
credit cards
Google Pay
Wire Transfers
cart
payment methods that support reusability
submit the cart
customerCredit
primary and secondary
create a payment source
attach it to a cart
detach sources
primary source
save it to a customer's account
set the default one
combine primary and secondary sources
authenticating
updating
primary
secondary
primary source
Create a new secondary source
Attach the new secondary source to the cart
attach the primary source to the cart
reusability
reusable
associated with a customer
reused
attach a primary source to a cart
payment session state
amount contributed is sufficient
DigitalRiver.js with elements
primary sources
attach the source to a cart
save the source to a customer's account
source is chargeable
Credit Cards
Google Pay
Klarna
Wire Transfer
DigitalRiver.js with elements
secondary sources
attach it to a cart
chargeable state
remove all attached sources
attached primary payment source
POST /apply-payment-method
POST /apply-payment-method
POST /apply-payment-method
POST /apply-shopper
POST /apply-payment-method
POST /payment-options
POST /apply-shopper
DELETE v1/shoppers/me/carts/active/apply-payment-method
DELETE v1/shoppers/me/carts/active/payment
create a Source
POST /apply-payment-method
Payment options
POST /payment-options/{id}
PayPal Express Checkout
PayPal Credit
PayPal Billing Agreement
Detach the primary source
detach all sources from the cart
sources
source
public API
Sources API
confidential API key
owner object