# Source basics

A [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)is associated with the customer's [payment method](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods) that a customer uses to fund a transaction. When generating a charge, Digital River retrieves data from the [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources).

In the Digital River APIs, each [source type](#supported-payment-methods) has [certain characteristics](#characteristics-of-payment-methods) that determine how it's created and how a [charge ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges)is eventually processed.

## Source types <a href="#supported-payment-methods" id="supported-payment-methods"></a>

A [source's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)`type` represents the [payment method](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods) used to create that object.

{% hint style="info" %}
On the [Sources API reference page](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), you can find a complete list of `type` values.
{% endhint %}

A [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)also contains a hash table that corresponds to its `type`. This data object holds detailed information specific to each `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`.

{% tabs %}
{% tab title="Source " %}

```javascript
{
    ...
    "type": "creditCard",
    ...
    "creditCard": {
        "brand": "MasterCard",
        "expirationMonth": 5,
        "expirationYear": 2025,
        "lastFourDigits": "0008"
    },
    ...
}
```

{% endtab %}
{% endtabs %}

## Characteristics of payment sources <a href="#characteristics-of-payment-methods" id="characteristics-of-payment-methods"></a>

A [source's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)characteristics revolve around the [pull or push](#pull-or-push), [synchronous or asynchronous](#synchronous-or-asynchronous), [reusable or single-use](#reusable-or-single-use), [primary or secondary](#primary-or-secondary), and [payment flow](#authentication-flow).

### Pull or push

The difference between a pull and push payment [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)involves how a customer's funds are transferred.

With pull [sources](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), customers provide their information and consent, and the money is drawn from their accounts. No additional customer actions are usually necessary. Credit cards are the most common example.

When using a push payment [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), the customer must explicitly send the funds before a charge can become capturable. These payment sources almost always require additional customer action. For example, if you enable [wire transfers](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/wire-transfer) on your website or app, you'll need to [present your customers with the necessary transfer information](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#handling-pending-payment-orders) to complete payment, and they must then "push" the funds.

### Synchronous or asynchronous

With synchronous payment methods, the [`state`](#source-state) of the resulting [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)is returned immediately as either `chargeable` or `failed`. A credit card is an example of this source [`type`](#supported-payment-methods).

With asynchronous payment methods, the [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)may first return in `state` of `pending_funds`, `pending_redirect`, or `requires_action` before it transitions to `chargeable`. For example, a source with a [`type`](#supported-payment-methods) of `payPal` is asynchronous because the customer is redirected to the [PayPal](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/paypal) site and must take additional action to authorize the transaction.

When integrating asynchronous payment methods, you can [create a webhook](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/webhooks/creating-a-webhook) to listen for the [event ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events)with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of `source.chargeable`. This will allow you to determine when to [attach the source to a checkout](https://docs.digitalriver.com/digital-river-api/payments/using-the-source-identifier#attaching-sources-to-checkouts) or [save the source to a customer's account](https://docs.digitalriver.com/digital-river-api/payments/using-the-source-identifier#attaching-sources-to-customers).

### Reusable or single-use

Some [payment methods](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods) can be used to create reusable [sources](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), meaning they support recurring charge authorizations. In customer-initiated transactions, you can present [stored sources](https://docs.digitalriver.com/digital-river-api/payments/using-the-source-identifier#attaching-sources-to-customers) to customers for convenience. You can also use reusable sources in [merchant-initiated](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge#merchant-initiated) [subscription](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions) renewals.

Other [payment methods](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods) only create single-use [sources](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources).

{% hint style="success" %}
Refer to the [Supported payment methods](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods) page for a list of payment methods that support recurring payments. Additionally, as part of the enablement process, certain payment methods that are typically reusable can be restricted to single-use only.
{% endhint %}

[Sources ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)must have a `reusable` value of `true` before they can be used to make multiple [charges](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics). Reusable sources can't be created using a [public API key](https://docs.digitalriver.com/digital-river-api/administration/dashboard/developers/api-keys#standard-keys). As a result, both [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide) and [DigitalRiver.js with elements](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start) only generate single-use sources. To make them reusable once created (assuming the source's [`type`](#supported-payment-methods) supports reusability), you must [save the source to a customer](https://docs.digitalriver.com/digital-river-api/payments/using-the-source-identifier#attaching-sources-to-customers). This flips `reusable` to `true` and prevents the source's [`state`](#source-state) from becoming `consumed` once it's associated with the [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts).

If a source's underlying payment method doesn't support reusability, we [block the source from being saved to a customer](https://docs.digitalriver.com/digital-river-api/payments/using-the-source-identifier#restrictions-on-saving-sources). As a result, with non-reusable sources, you should only [attach the source to a checkout](https://docs.digitalriver.com/digital-river-api/payments/using-the-source-identifier#attaching-sources-to-checkouts). When you [convert the checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), this will generate a one-time charge authorization.

### Primary or secondary

Refer to [primary and secondary sources](https://docs.digitalriver.com/digital-river-api/payments/using-the-source-identifier#primary-versus-secondary-sources)

### Authentication flow <a href="#authentication-flow" id="authentication-flow"></a>

A [source's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)`flow` represents how your customers experience the payment process and what authentications they must complete. The enumerated `flow` values are `standard`, `redirect`, and `receiver`.

* `standard`: In this flow, which mainly applies to [credit cards](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/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. Customers require no additional action after they submit their information, and a [charge ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics)can be created immediately
* `redirect`: In this flow, you obtain a customer's payment data on your storefront. You then redirect them to the payment provider, asking them to authorize the transaction. Once the authorization is confirmed, a [charge ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics)can be created. We recommend you adhere to [these guidelines](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/guidelines-for-capturing-payment-details#redirect-payment-methods) when using redirect payment methods.
* `receiver`: This flow requires that customers push funds to an account before a [charge ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics)can be created. [Wire transfer](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/wire-transfer) is a common payment method that uses this authentication flow.

## Source state

A [source's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)`state` provides information about what can be done with the object. The source's `state` may be `cancelled`, `chargeable`, `consumed`, `failed`, `requires_action`, `pending_funds`, or `pending_redirect`.

Digital River only creates a charge object when the [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)is `chargeable`. You can listen for `source.chargeable` [events](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) to be notified of when the source transitions to this `state`.

Once charged, the `state` status of [single-use sources](#reusable-or-single-use) switches to `consumed` , and no additional charges can be created from the Source. [Reusable sources](#reusable-or-single-use), however, can maintain a `chargeable` state.

Sources with a [`flow`](#authentication-flow) of `redirect`, such as [PayPal](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/paypal), often are in a `state` of `pending_redirect` because the customer must leave your website to confirm the payment.

For sources with a [`flow`](#authentication-flow) of `receiver`, such as [wire transfers](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/wire-transfer), it may take days before the funds are confirmed by the receiving bank or financial institution, thereby switching the [source's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)`state` from `pending_funds` to `chargeable`.

For different success and error scenarios, you can [create tests](https://docs.digitalriver.com/digital-river-api/payments/testing-scenarios) to determine whether your integration returns the expected `state`.

## Source amount

Once all captures are complete, the customer's payment method is charged the `amount` value contained within the [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), considering any [cancellations you create](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment) or [refunds you issue](https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/refunds/issuing-refunds).

Each time that Digital River returns an updated [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), 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 [update the checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1), the [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)is returned with an updated `amount`.