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