Managing sources
Learn how to manage sources.
Last updated
Was this helpful?
Learn how to manage sources.
Last updated
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 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 are typically used to supplement a .
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:
(or ).
with the correct amount.
.
If needed, .
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.
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.
Use the following steps for both authenticated shoppers and anonymous shoppers.
Use the following steps only for authenticated shoppers.
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.
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.
Use one of the following options to remove all attached sources directly from a cart.
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.
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
.