Integration options
Order management
Payments
Product management
Customer management
Financial reporting
Developer resources
administration
General Resources
Source basics
Learn about the Source object and the payment methods supported in the Digital River API.
A source is associated with a payment method that a customer selects to fund a transaction. Digital River retrieves data from the source when generating a charge.
Each supported payment method in the Digital River APIs has certain features that determine how a source is created and the charge is eventually processed. These features revolve around the concepts of pull or push, synchronous or asynchronous, reusable or single-use, primary or secondary, and payment flow.
Supported payment methods
There are a wide variety of payment methods in the Digital River APIs that can be used to create a source. For a complete list, refer to the Supported payment methods page.
A source's
type represents the payment method used to create that object. On the Sources API reference page, you can find a complete list of these type values.A source also contains a hash table with a name that corresponds to its
type. This data object holds detailed information specific to that type. For example, a source with a type of credit card has a creditCard hash table that lists the card's brand, expirationMonth, expirationYear, and lastFourDigits.Source
1
{
2
...
3
"type": "creditCard",
4
...
5
"creditCard": {
6
"brand": "MasterCard",
7
"expirationMonth": 5,
8
"expirationYear": 2025,
9
"lastFourDigits": "0008"
10
},
11
...
12
}
Copied!
Characteristics of payment methods
The following sections detail the primary characteristics of how a payment method is charged and how a customer experiences the payment process.
Pull or push
The difference between a pull and push payment method has to do with how a customer's funds are transferred.
For a pull payment method, customers provide their information and consent, and the money is drawn from their account. No additional customer actions are usually necessary. Credit cards are the most common example of this payment method type.
When using a push payment method, the customer must explicitly send the funds before a charge can become capturable. These payment methods almost always require additional customer action. For example, if you enable wire transfers on your website or app, you'll present your customers with the necessary transfer information to complete the payment and they must "push" the funds.
Synchronous or asynchronous
With synchronous payment methods, the
state of the source is returned immediately as either chargeable or failed. A credit card is an example of this type of payment method.With asynchronous payment methods, the source may first return with a
state of pending_funds, pending_redirect, or requires_action before it transitions to chargeable. PayPal is an example of an asynchronous payment method because the customer is redirected to the PayPal site and must take additional action to authorize the transaction.When integrating asynchronous payment methods, you'll need to create a webhook to listen for the
source.chargeable event. This will allow you to determine when you should attach the source to a checkout or save the source to a customer's account.Reusable or single-use
Some payment methods can be used to create source objects that are reusable. This means that the customer doesn't need to re-supply the same payment details during every transaction. Other payment methods only create single-use sources.
With certain exceptions, payment methods such as credit cards, Google Pay, direct debit, and PayPal are reusable. Non-card-based payment methods, such as wire transfer, bPay, Konbini, Alipay, online banking, and Payco, are typically single-use only. As part of the enablement process, certain payment methods that are typically reusable can be restricted to single-use.
For a list of payment methods that support reusability, refer to the Supported payment methods page.
Sources must have a
reusable value of true before they can be used to make multiple charges. Reusable sources however can't be created using a public API key. So both Drop-in payments and DigitalRiver.js with elements only generate single-use sources. To make them reusable once they're created (assuming the source type supports re-usability), you must save the source to a customer. This flips reusable to true and prevents the source's state from becoming consumed once it's associated with a transaction.If a source's underlying payment method doesn't support re-usability, we block the source from being saved to a customer. So, with a non-reusable source, you should only attach the source to a checkout. This will generate a one-time charge authorization when you convert the checkout to an order.
Primary or secondary
Payment flow
A source's
flow attribute represents how your customers experience the payment process and what actions they must take to authenticate a payment method. The enumerated values of the attribute are standard, redirect, and receiver.standard: In this flow, which mainly applies to credit cards, you obtain a customer's payment details on your storefront and submit this information to Digital River. The customer is never required to leave your website during the checkout process. No additional action is required by the customer after they submit their information and a charge can be created immediatelyredirect: With this authentication flow type, you obtain a customer's payment data on your storefront. You then redirect them to the website of the payment method where they are asked to authorize the transaction. Once the authorization is confirmed, a charge can be created. We recommend you adhere to these guidelines when using redirect payment methods.receiver: This flow type requires that a customer push funds to an account before a charge can be created. Bank and wire transfers are two common payment methods that use this authentication flow.
Source state
A payment source also has a
state attribute, which provides information about what can be done with it. The state of a source is enumerated by the following values: cancelled, chargeable, consumed, failed, requires_action, pending_funds, and pending_redirect.Digital River only creates a charge object when the source is
chargeable. To be notified of when the source transitions to this state, you can listen for source.chargeable events.Once charged, the status of single-use sources switches to
consumed and no additional charges can be created from the source. Reusable sources however can maintain a chargeable state.Sources with a redirect, such as PayPal, often are in a state of
pending_redirect because the customer must leave your website to confirm the payment.For wire transfers, it may take days before the funds are confirmed by the receiving bank or financial institution, thereby switching the source from
pending_funds to chargeable.For different success and error scenarios, you can create tests to determine whether your integration returns the expected
state value.Source amount
Once all the captures are complete, the customer's payment method is charged the
amount value contained within the source, taking into account any cancellations you create or refunds you issue.Each time that Digital River returns an updated source, the value of
amount can change. For example, if customers add or subtract items from their carts late in the checkout process, and you then submit a new checkout request with the same sourceId, the source is returned with an updated amount.Last modified 1h ago