Flows by payment type

Understand the flows by payment type.

Each payment method must follow a specific payment flow to ensure a seamless payment process. The payment flows and corresponding payment methods outlined below follow Digital River's recommended best practices.

Standard payment flow

Use the following flow for standard payments: Apple Pay, credit cards, and Google Pay.

1. Create the shopper token.

2. Apply the shopper and their billing address to a cart.

3. Create a source using DigitalRiver.js. The source state is chargeable.

4. Attach the source to the cart.

5. Submit the cart.

Delayed payment flow

Submit a Konbini payment flow

Use the following flow for delayed payments, such as Konbini.

1. Get the store details.

2. Create a source using DigitalRiver.js. The source state is pending_funds.

3. The customer transfers the funds to the Konbini payment provider.

4. The source state changes to chargeable when the funds are received.

5. Submit the cart.

Submit a Boleto payment flow

To use Boleto as a payment method:

1. Create a cart.
2. Optional. Set the locale and currency. curl --location --request GET 'https://{host}/v1/shoppers/me.json? locale=pt_BR&currency=BRL' --header 'Content-Type: application/json'--header 'authorization: bearer ***\

3. Optional. Set the cart address to the BR address.

4. Attach the tax ID to the cart. The action inserts the tax ID into the payment session.
5. Create a source using DigitalRiver.js with a payment session ID. Note that the tax ID is required when creating the Boleto source. The payment session ID provides the tax ID.
6. Attach the source to the cart.
7. Submit the cart.

Submit a Wire Transfer payment flow

Use the following flow for delayed payments, such as Wire Transfer.

1. Create the shopper token.
2. Apply the shopper and their billing address to a cart.
3. Create a source using DigitalRiver.js. The source state is chargeable.
4. Attach the source to the cart.
5. Submit the cart.
6. The shopper receives the payment details and completes the payment. After the shopper finalizes the payment, the updated order status will appear in Global Commerce.

Redirect then submit (RTS) payment flow

Use the following flow for RTS payment methods, such as PayPal, PayPal Billing Agreement, PayPal Credit, PayPal Pay in 3, PayPal Pay in 4, and PayPal RatenZahlung (Installment Payment)

1. Create the shopper token.
2. Apply the shopper and their billing address to a cart.
3. Create a source using DigitalRiver.js. The source state is pending_redirect.
4. Complete the redirect authorization.
5. Attach the source to the cart. The session state is requires_confirmation.
6. Submit the cart.

Submit then redirect (STR) payment flow

If you're using Drop-in payments and customers opt to fund a transaction with a payment method, such as Bancontact, Klarna, and SEPA Direct Debit, whose resulting source has a flow of redirect must be redirected to the payment provider, where they either approve or cancel the funds transfer.

You should submit the cart before making payment to ensure customers avoid situations where they might send payment, but the Digital River order remains incomplete.

The table in the Supported payment methods section provides a full list of payment methods that require an STR flow.

How to implement an STR flow

In the createDropin() method's configuration object, set the redirect object's disableAutomaticRedirects to true. Assign the returnURL to be your completion step, such as the order confirmation page. cancelURL should return the customer to the cart or store workflow

If customers select a redirect payment method, the data returned by onSuccess contains a source whose state is pending_redirect. When you receive this event, retrieve the source.id from the data.

let digitalRiver = new DigitalRiver("Your public API key", {
    "locale": "en-GB"
});
                        
let configuration = {
    "sessionId": "fe50c56f-88a4-4961-8142-7d4784b87264",
    "options": {
        "flow": "checkout",
        "redirect": {
            "disableAutomaticRedirects": true,
            "returnUrl": "https://mywebsite.com/paymentCallBack.html",
            "cancelUrl": "https://mywebsite.com/paymentCallBack.html"
        },
        ...
    }, 
    onSuccess: function(data) {
       //send sourceId to your backend
       var sourceId = data.source.id;
    }, 
    ...
}
                                    
let dropin = digitalriverpayments.createDropin(configuration);
dropin.mount("drop-in");

Next, pass this identifier in a server-side attach source to an order or cart.

curl --location --request POST 'https://api.digitalriver.com//v1/shoppers/me/carts/active/apply-payment-method' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 'Your access token' \
...
--data-raw '{
  "paymentMethod": {
    "sourceId": "e7ba0595-059c-460c-bad8-2812123b9313"
  }
}

This operation moves the source into "pending redirect" state, the order state to "Source pending redirect", and provides you with the redirectUrl to present to the customer:

POST /shoppers/me/carts/active/apply-payment-method

{
    "clientId": "gc",
    "channelId": "drdod15",
    "liveMode": false,
    "id": "5ce08114-143b-4bf6-ae0e-6fc501ee0c24",
    "clientSecret": "5ce08114-143b-4bf6-ae0e-6fc501ee0c24_a468b08e-2c47-4531-82af-d48d80ff6dcc",
    "type": "alipayCn",
    "reusable": false,
    "owner": {
        "firstName": "Donglei",
        "lastName": "Ye",
        "email": "[e-mail]",
        "phoneNumber": "13063725095",
        "address": {
            "line1": "Wei Bai Chang",
            "city": "ShunDe District)",
            "state": "Guangdong",
            "country": "CN",
            "postalCode": "528322"    
        }
    },
    "amount": "10.00",
    "currency": "CNY",
    "state": "pending_redirect",
    "creationIp": "10.81.3.92",
    "createdTime": "2020-02-26T02:48:11.508Z",
    "updatedTime": "2020-02-26T02:48:11.508Z",
    "flow": "redirect",
    "redirect": {
        "redirectUrl": "https://api.digitalriverws.com:443/payments/redirects/51314834-9bf9-483f-b3a7-4b36a14d3f5c?apiKey=pk_hc_e03ee62c0d964bb3ac75595b1203d13c",
        "returnUrl": "returnUrl.com"
    },
    "alipayCn+": {}
}

At this point, retrieve the cart data you need—such as currency, orderTotal, subTotal, tax, billingAddress, shippingAddress,payment.sources[], and relevant lineItems —to build a review page.

If customers click your submit order button after reviewing the transaction's details, send a submit cart request.

POST /shoppers/me/carts/active/sumbit-cart

{
    "cart": {
    "termsOfSalesAcceptance": "true"
    }
}

If you get a 201 Created response, then redirect the customer to the redirectUrl, where they can either approve or cancel payment. Once the customer completes either of these actions, they're redirected to the URL you assigned to cancelUrl or returnUrl.

When the returnUrl loads, call a function that initiates a server-side request, and send the resume cart call. You do not need to perform this call if the customer goes to your cancelUrl.

curl --location -g --request POST ' https://api.digitalriver.com/v1/shoppers/me/carts/active/resume-cart' \
--header 'Authorization: Basic {{access_token}}' \
...

If you get a 200 OK repsonse, verify the order's state is Submitted and paymentSession status is complete. You can render the order confirmation page to the customer.

Order

{
    "resumeCart": {
        "order": {
            ...
            "orderState": "Submitted",
     ...
        "paymentSession": {
            "id": "6a92bfac-072b-4e2c-8066-9bd2e4ab4fa0",
            "clientSecret": "6a92bfac-072b-4e2c-8066-9bd2e4ab4fa0_21ed1510-c504-47ae-a345-f7d5d17a1944",
            "status": "complete"
        }
    }
}

If you receive a 409 response with the error "Requisition is not present or not in Source Pending Redirect state", this indicates something went wrong. You must recreate the cart and return customers to the payment collection stage.

STR payment flow

Use the STR payment flow for Afterpay, Alipay (domestic), Alipay+ (cross-border), Amazon Pay Express Checkout, Bancontact, BLIK, CCAvenue, Clearpay, iDEAL, Klarna Financing, Klarna Pay in 3, Klarna Pay in 4, Klarna Pay in 30 days, Online Banking (FPX), Online Banking (IBP), Online Banking (Korea Bank Transfer), PayCo, SEPA Direct Debit, and Trustly.

1. Create the shopper token.
2. Apply the shopper and their billing address to a cart.
3. Create a source using DigitalRiver.js with a session identifier (paymentSessionId). The source state is pending_redirect.
4. Attach the source to the cart. The session state is requires_confirmation.
5. Submit the cart. The session state is pending_redirect.
6. Resume cart to complete post-order processing.

STR sequence diagram

The Submit then Redirect (STR) sequence diagram illustrates the interactions between the client, server, and external payment provider during the STR payment flow. It includes key steps such as applying the shopper to a cart, handling session states, and completing the redirect authorization, ultimately leading to successful payment processing. The scope of the following diagram is limited to the operations in this flow.

282KB

Submit then Redirect for Commerce API.png

image