Payment source basics
Learn about the Source object and the payment methods supported in the Digital River API.
The source object represents a customer's payment method and is used by Digital River to generate a charge.
Each payment method supported in the Digital River APIs has certain features that determine how a source is created and a 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

A payment method contains the necessary details to create a source object. The supported payment methods are listed in our payment integrations section. For instructions on how to enable the various types of payment methods, contact your Digital River account manager
The type attribute represents the payment method used to create the source. On the Sources API reference page, you can find a complete list of available source types. In the Checkouts API, you can use any of these source types to fund a transaction. The Invoices API, however, only supports credit cards and store credit.
The source object also contains a hash table with a name that corresponds to the type value. For example, a source with a type of credit card will contain a creditCard hash table.
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 section on the Drop-in 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 and DigitalRiver.js 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

The 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, 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 1mo ago