POST/fulfillments
request, you're informing our payment services how many items in an order are fulfilled and/or cancelled. We then use that information to capture or cancel the appropriate amount of an order's payment charges.POST/fulfillments
, your integration should also be set up to handle fulfillment-related events.POST/fulfillment
request, you must first receive and handle the necessary events. The specific events you must process depend on the order's fulfillment model:accepted
state.POST/fulfillments
with the quantity
of each shipped line item and then submitting the payment capture request.POST/fulfillments
with the cancelQuantity
of each cancelled line item and then submitting the payment cancel request.accepted
order by creating a fulfillment order. You must then wait to receive a fulfillment_order.shipped
event before handling that by defining a POST/fulfillments
with the quantity
of each shipped line item and then submitting the payment capture request.fulfillment_order.cancelled
event before handling that by defining a POST/fulfillments
with the cancelQuantity
of each cancelled line item and then submitting the payment cancel request.items
array, you specify each line item's unique identifier and the quantity fulfilled and/or cancelled. The request doesn't need to specify both a quantity
and cancelQuantity
, but it must contain one or the other.quantity
, thereby informing our payment services that these items are fulfilled, we attempt to capture the appropriate amount of the payment charge. Conversely, if you specify a cancelQuantity
, we attempt to cancel the relevant charge amount.POST/fulfillments
must include shipment identifiers. Specifically, you're required to provide a single shipmentId
and, for each item in the shipment, a unique shipmentItemId
.fulfillment_order.shipped
event. Each time you receive this shipment notification, retrieve these identifiers and pass them in the POST/fulfillments
.trackingCompany
, the trackingNumber
provided by the shipping carrier, and the trackingUrl
that customers use to monitor the shipment.fulfillment_order.shipped
event.POST/fulfillments
and receive a 201 Created
, the payload contains a fulfillment with a unique identifier. The request also triggers a fulfillment.created
event.POST/fulfillments
that result in every line item's state
transitioning to fulfilled
, then the order's state
also becomes fulfilled
and an order.fulfilled
event is fired.POST/fulfillments
on the order, you receive the following 409 Conflict
:fulfillment.created
event is useful for accessing tracking data. The event provides the name of the shipping company, a unique tracking number, and a url to track the delivery's progress.orderId
, items[].itemId
, trackingCompany
, trackingNumber
, and trackingUrl
. You can use orderId
and items[].itemId
to look up the order and line item(s) in your system and then add the tracking information to the customer's order management page.order.charge.capture.complete
and order.charge.capture.failed
events. The payload of both consists of a charge and contains a fulfillmentId
that identifies the fulfillment which triggered the event.state
remains capturable
because the order is only partially fulfilled.captures[].amount
and captures[].createdTime
provides the data you need to inform customers how much and when they were charged.sourceId
as a path parameter in a GET/sources/{sourceId}
.200 OK
response you'd most likely retrieve creditCard.brand
and creditCard.lastFourDigits
.captures[].fulfillmentId
to retrieve the fulfillment that triggered the capture. From the 200 OK
response, fetch each items[].skuId
and pass the value in a GET/skus/{skuId}
. This allows you to access the SKU's name
, description
, image
, and other product data. Depending on your integration, the fulfillment may also contain shipment tracking data.orderId
to look up the order in your system and provide some or all of this capture, payment, product, and shipping information on the customer's order details page. For example:creditCard.brand
ending in creditCard.lastFourDigits
in the amount of captures[].amount
on captures[].createdTime
. This payment is for the following products:name
| description
| image
order.charge.capture.failed
event.captures[].fulfillmentId
allows you to retrieve the fulfillment, access its shipmentId
and items[].shipmentItemId
and then use these identifiers to cancel the shipment.
Make sure you check with your fulfiller to determine whether they have the ability to cancel a shipment within a certain window of time. If you're using Digital River's fulfillment service, refer to Cancelling physical fulfillments. POST/orders
that authorizes the charge and a POST/fulfillments
that captures payment.failureCode
. We also provide a failureMessage
that may help diagnose the issue. To access this message:id
of the event's capture.200 OK
response, use the saved capture identifier to search captures[]
for the appropriate element and retrieve its failureMessage
.failureCode
is failed-request
and failureMessage
is Failed to operate on charge
. This indicates that Digital River was unable to determine a reason for the capture failure.order.charge.cancel.complete
event typically originates with a customer making a request on your site to cancel an entire order (or a certain quantity of one or more line items in an order).POST/fulfillments
that specifies a cancelQuantity
for each line item that the customer wants to cancel.orderId
, cancels[].createdTime
and cancels[].amount
. To access information about the source, retrieve the event's sourceId
and pass it as a path parameter in a GET/sources/{sourceId}
.creditCard.brand
and creditCard.lastFourDigits
from the response.orderId
to locate the order in your system and display the cancel payment information to customers on their order details page. For example:cancels[].createdTime
we cancelled billing on your creditCard.brand
ending in creditCard.lastFourDigits
in the amount of cancels[].amount
.order.complete
event can also act as a trigger to populate the customer's order details page. The following lists some of the information you may decide to display on this page, along with the field in the event that contains the data. Most likely, you've already used prior API responses and events to store much of this data in your system.id
createdTime
shipTo.address
billTo.address
totalAmount
subtotal
totalFees
totalTax
totalDuty
totalShipping
items[]
payment.sources[].type
payment.charges[].captures[].createdTime
payment.charges[].captures[].amount
payment.charges[].cancels[].createdTime
payment.charges[].cancels[].amount
order.complete
as a trigger to activate a request refund button on the customer's order details page. When handling the button's click event, make sure you use the Refunds API to process the request.