Source basics

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. 
You can use Dashboard to manage these payment methods.
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.
In the invoicing billing on the Invoicing customers page.
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 
{
    ...
    "type": "creditCard",
    ...
    "creditCard": {
        "brand": "MasterCard",
        "expirationMonth": 5,
        "expirationYear": 2025,
        "lastFourDigits": "0008"
    },
    ...
}
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
Refer to primary and secondary sources​
Payment method's authentication 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 immediately
redirect: 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 authentication payment flow, such as PayPal, often are in a state of pending_redirect because the customer must leave your website to confirm the payment.
For sources with a receiver authentication payment flow, such as 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.

Wire Transfer

Managing sources

Last modified 4mo ago

Copy link

On this page

Supported payment methods

Characteristics of payment methods

Pull or push

Synchronous or asynchronous

Reusable or single-use

Primary or secondary

Payment method's authentication flow

Source state

Source amount