Checkouts, payment sources, and orders
Learn more about the standards related to processing checkouts, payment sources, and orders.
The checklist items and standards in this section cover how to process MOR/SOR compliant checkouts, subscriptions, payment sources, and orders.
Click any checklist item to be provided more information on how to meet the checkouts, payment sources, and orders-related integration standard.
The checkout, payment source, and order standards that apply to your integration are dependent on which of the above checklists you're using.
When sending product data in create checkout requests each
items[] must include a SKU identifier or a productDetails object. Each line item in the request must also have a defined price or aggregate price, as well as a quantity.When associating SKU groups with upstream product data in create checkout requests each
items[] must include productDetails and within that object you must specify a skuGroupId.If you're sending
productDetails in create checkout requests, your integration should pass your system's unique product identifier as the object's id.For more information, refer to the sending product data in checkouts section on the Describing line items page.
If you're sending
productDetails in create checkout requests, your integration must reference the product's associated SKU group. You do this by specifying a skuGroupId in the productDetails object.For more information, refer to the sending product data in checkouts section on the Describing line items page.
When building a checkout, use the
taxInclusive flag to indicate whether the price of items in an order should be treated as tax inclusive or exclusive.When building a checkout, provide the IP address of the browser being used by the customer to place the order.
For tracking purposes, specify an upstream identifier during the checkout process that matches the identifier of the corresponding order in your commerce platform.
Each time you create or update a checkout, use the response from the Checkouts API to update price, fee, and tax information in the upstream commerce platform. These updates should be performed for the entire transaction and each line item in the transaction. This ensures that the values in your system stay in sync with those in our system.
Additionally, you should display these response values in your interface so customers can review tax and product totals during the checkout process.
Since the customer actively participates in a subscription acquisition, you should set
chargeType to customer_initiated.During a subscription's autorenewal, the customer is not an active participant. As a result, when building a checkout to process an autorenewal, you should set
chargeType to merchant_initiated.Any transaction that includes a recurring product or service, must provide information that describes that subscription. So, when building a checkout, provide these details in the
subscriptionInfo hash table.For auto-renewing subscriptions, you must display the subscription's terms and acquire the customer's active acceptance of them. So, before converting a checkout to an order, pass these agreed upon terms in the checkout's
terms parameter. This ensures that they are recorded in the billing agreement.During the acquisition process, you can optionally generate a unique subscription identifier and assign it to
subscriptionId.For every recurring product or service, you must use the
autoRenewal parameter to tell us whether the subscription is automatically or manually renewed.During the renewal process, send the the
billingAgreementId generated during the subscription's acquisition.When acquiring or renewing a subscription with the Klarna payment method, you must provide a start and end time.
Drop-in payments is our all-in-one solution for handling payments and ensuring compliance. We recommend you use this solution as a quick and easy way to start accepting payments.
During the checkout experience, you can use the configurable Drop-in object to present available payment methods and then safely and securely capture a customer's payment details. The payment source returned in the
onSuccess event can then be attached to the checkout before the customer arrives on your order review page.During checkout flows, we recommend you provide customers the option to save their payment information for future transactions. When building your payment workflows for both one-off and subscription purchases, you can configure Drop-in payments to present the save payment option to customers.
In the
onSuccess event, if readyForStorage returns true or mandate is populated, then the customer agreed to save that transaction's payment information for future use. In response, your integration should attach the payment source to the customer's record.Whenever Drop-in payments successfully creates a payment source, we send you the
onSuccess event. Once you receive this event, you should redirect the customer to the order review page. Here the customer can perform a final review of the order's details before deciding whether to make the purchase.When a customer is purchasing an auto-renewing subscription, the payment methods that Drop-in payments displays must support recurring transactions. To ensure that Drop-in only displays reusable payment methods, set
autoRenewal to true in a POST/checkouts or POST/checkouts/{id} request. You then use Drop-in's configurable options to set showTermsOfSaleDisclosure to true.When acquiring an auto-renewing subscription, customers must agree to save the transaction's payment source to their account so that it can be applied to renewals. So, you must configure Drop-in payments to display the combined subscription and save payment agreement terms and then acquire the customer's active acceptance..
You do this by first setting
autoRenewal to true in a POST/checkouts or POST/checkouts/{id} request. You then use Drop-in's configurable options to set showTermsOfSaleDisclosure to true.When the
onSuccess event returns a source that is readyForStorage, you should save the source to the customer's account. This operation flips its reusable value to true. As a result, the source can be used in merchant-initiated subscription auto-renewals.After you display the review order page to the customer and the customer actively accepts Digital River's disclosure terms and then submits the order on the storefront, you should convert the checkout to an order.
Digital River creates an Order based on the data in a Checkout. Providing
checkoutId in the payload of POST/orders acts primarily as a call to authorize payment and trigger a fraud review.When a customer uses a synchronous payment method such as a credit card to pay for a transaction, the
POST/orders request almost always immediately returns either an accepted or failed order. When the order succeeds, direct the customer to the "Thank you" page. If the order fails, use the error's message to inform the customer of the issue through the user interface.When the
POST/orders response returns a 201 Created status code, retrieve the order's id from the payload, and use that value to set the corresponding attribute in the upstream commerce platform's order.POST/orders response | Due to... | Ready to fulfill? |
No | ||
No | ||
No | ||
No | ||
Yes |
When the
POST/orders response returns a 201 Created status code, retrieve charges[].state from the payload, and use that value to set the corresponding attribute in the upstream commerce platform's order.For
409 Conflict errors generated by a payment authorization failure, set the commerce platform's order payment status to failed.When the
POST/orders response returns a 201 Created status code, retrieve fraudState from the payload, and use that value to set the corresponding attribute in the upstream commerce platform's order.For
409 Conflict errors generated by a fraud review failure, set the commerce platform's order fraud status to blocked.When Digital River successfully authorizes payment and completes its fraud review, we send the
order.accepted event. This event indicates that the order is ready to fulfill. Upon receipt, retrieve state, fraudState, and charges[].state from the payload, and use these values to update the corresponding attributes in the upstream commerce platform's order.An asynchronous payment authorization failure triggers an
order.charge.failed event. When Digital River asynchronously detects an anomaly during its fraud review, or the customer is determined to be on the Denied Persons List, we send an order.blocked event.Upon receipt of either event, retrieve
state, fraudState, and charges[].state from the payload, and use these values to update the corresponding attributes in the upstream commerce platform's order.For each subscription product or service that you create, store the
billingAgreementId that Digital River generates so that it can be sent in the renewal request.Documentation | Direct API | PHP SDK |
|---|---|---|
| | |
| | |
Events: order.accepted, order.review_opened, order.pending_review, order.pending_payment, order.blocked, order.charge.failed, order.complete | | |
Last modified 10mo ago