Managing sources
Learn how to manage sources.
For both categories, after you create a payment source, you can always attach it to a cart so that we can use it to generate a one-time charge. You can also detach sources from carts.
Once you create a primary source that supports reusability, you can save it to a customer's account. For customers who have multiple saved payment sources, we also provide you the ability to set the default one.
And when building your payment flows, the DigitalRiver.js library contains methods for authenticating and updating sources that can be useful in purchase and account management scenarios.
When building your payment workflows, you should be aware of the differences between primary and secondary payment sources and how they affect the payment session.
Primary payment sources are created from traditional payment methods such as credit cards, Google Pay, PayPal, and wire transfers. Nearly all transactions are conducted with a primary source, but each order can only contain one. Once you create them and then attach them to a customer, primary sources can be re-used in future transactions (assuming the underlying payment method supports reusability). You can also attach them to a cart so we can use them to create a one-time charge.
Each time that Digital River returns an updated Source, the value of
amount
can change. For example, if a customer adds or subtracts items from their cart late in the checkout process, and you then submit a new Cart request with the same sourceId
, the Source is returned with an updated amount
.Once they are successfully associated with a transaction, primary sources move the payment session into the necessary state and fully fund the transaction.
You can successfully submit an order entirely with secondary sources, but you need to ensure the payment session state is valid and the amount contributed is sufficient.
You cannot edit the
amount
value for a secondary source. To change the amount
value for the secondary source:- 1.
- 2.
- 4.
Always 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.
Secondary sources do not support reusability. Therefore, they cannot be saved to a customer's account. They should only be attached to a cart to create a one-time charge when that cart is converted to an order.
You create primary sources with your public API key using Drop-in Payments or DigitalRiver.js with elements. Once the source is
chargeable
, you should either attach the source to a cart or save the source to a customer's account.You create secondary sources through the Sources API by sending your confidential API key in a
POST/sources
request.When defining the request, you retrieve the payment session identifier 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. You can provide the owner information, including the address when creating a secondary source. We recommend that you do not provide an 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.
The
upstreamId
parameter is useful for mapping the source to your credit management system.POST/sources request
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",
}'
A
201 OK
response returns a unique source in a chargeable
state. You should attach it to a cart so that we can use it to generate a one-time charge.POST/sources response
{
"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
}
In the Cart API, the following payment methods support the use of
customerCredit
: Credit Cards, Google Pay, Klarna, PayPal Express Checkout, PayPal Credit, PayPal Billing Agreement, and Wire Transfer.We currently only support
customerCredit
as a secondary source.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 or remove the attached primary payment source directly from the cart, then attach new sources to the cart.
When using multiple sources in a cart, always apply the secondary sources first. Apply the primary source last.
To attach two sources to a cart, choose one of the following best practices.
Use the following steps for both authenticated shoppers and anonymous shoppers.
- 1.
- 2.
Use the following steps only for authenticated shoppers.
- 1.
- 2.Send the
POST /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.
When you attach a source to the cart using the
POST /apply-payment-method
and the cart already has address information, the system will not use the source
address. 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. This is why we recommend that you don't include the owner information when you create a secondary source.
When you attach a source to a shopper using
POST /payment-options
, 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
, 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 or not.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
}
}
]
},
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 that means the shopper should apply an additional payment to the cart to cover the order 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
}
}
}
Use one of the following options to remove all attached sources directly from a cart.
DELETE v1/shoppers/me/carts/active/apply-payment-method
removes a payment source from the cart. Use this option and include the source ID in the payload to remove payment sources one by one.DELETE v1/shoppers/me/carts/active/payment
removes all attached sources directly from the cart
If a customer requests a refund, the system will refund the primary payment source first. Once the system fully refunds the primary source, the system will use the secondary payment source to refund the remaining value.
For example, a customer purchased a line item quantity of 10 for a total of $1000. They used $600 from their primary payment source (for example, a credit card) and $400 from their secondary payment source (for example, 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.
Your storefront may be configured so that customers are not required to create an account or sign-in to make a purchase. In this case, after you submit the guest customer's payment details, DigitalRiver.js with elements will create a Source and return the
sourceId
. You can then use a POST /apply-payment-method
request to set the sourceId
attribute. cURL
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"
}
}'
Since the Source is not attached to a Shopper, this payment method object cannot be re-used for future purchases, and once used, its state becomes
consumed
.Registered customers may have multiple saved payment methods associated with their account. These Source objects are stored in the
sources
array of the Payment Options resource. The first Source attached to a Customer becomes the default payment method where
isDefault
is set to true
and its identifier is assigned to the sourceId
attribute. If you'd like to assign a different payment method as the default, simply submit a POST /payment-options/{id}
request where {id}
is the new default payment method and set isDefault
to true
. cURL
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}}"
}
}'
Last modified 3mo ago