Payment reauthorizations
Gain a better understanding of Digital River's payment reauthorization feature and how you might use it to sell pre-ordered goods
Due to the often-lengthy period of time between payment authorization and capture, you have a higher risk of chargebacks when selling pre-ordered goods or managing other types of delayed fulfillments.
If you'd like to minimize your chargeback risks, your account can be setup so that Digital River never initiates the capture and settlement process without first possessing a valid authorization. There are however potential downsides to selecting this option. For details, refer to Managing chargeback risks.
Although Digital River's payment reauthorization feature has other use cases, this article mainly focuses on strategies you could use to process checkouts and fulfillments that contain pre-ordered goods.
An order whose
state moves to accepted indicates that the issuing bank has given approval for the transaction to proceed. But that authorization remains valid for only a limited amount of time. If it expires before a create fulfillment request is submitted that results in Digital River attempting to fully or partially capture an order's charges[], then the issuing bank may initiate a late presentment chargeback. To manage this scenario, we can configure your account to be chargeback risk tolerant or chargeback risk averse. The option you instruct your Digital River representative to select helps determine the balance between the frequency of chargebacks you receive and the amount of revenue you earn.
If your account is configured to be risk tolerant, then Digital River attempts to capture and settle using the original authorization, even when it has expired and we're unable to create a new one to replace it.
By default, all accounts are set up to be risk tolerant.
In most cases, this option ensures your revenue opportunities are being optimized. It does however carry a slightly higher risk of late presentment chargebacks. But these types of chargebacks typically only occur in a small percentage of all orders.
If your account is configured to be risk averse, then Digital River only attempts to capture a charge when (1) the original payment authorization has yet to expire or (2) we're able to secure a new authorization to replace the expired one. In other words, Digital River never attempts to force settle on an expired authorization.
With this option, you can minimize late presentment chargebacks. However, by setting up your account to be risk averse, you do run the risk of losing out on potential revenue. This is because a high percentage of expired authorization capture attempts are ultimately approved by the issuing bank.
By allowing customers to pre-order goods, you can sell products that are not yet available or those that are out of stock. This can be useful if you want to generate excitement around an upcoming release or forecast demand for a new product.
In this section, you'll find information on how to handle checkouts and process fulfillments that contain pre-ordered goods.
In the Digital River APIs, checkouts that involve pre-ordered goods don't require any unique customizations. This means you're not required to pass any additional data in SKUs, checkouts, or checkout-sessions.
With the pre-orders feature:
- A checkout or checkout-session's
items[]can be physical or digital. Additionally, they can be a mix of pre-ordered and "normal" goods. - In registered checkouts and checkout-sessions, the primary payment source doesn't need to be saved to the customer.
Depending on whether your account is set up to be risk tolerant or risk averse, the following sections outline, at a high-level, some possible approaches to fulfilling pre-ordered goods.
The actual solution you implement is highly dependent on your fulfillment setup. For example, you'll likely need to analyze how your fulfiller and warehouses communicate, the responsiveness of that integration and at what points in the pipeline shipments can be cancelled.
Whichever chargeback risk option you select, the order's
state should be accepted before you initiate fulfillment operations. 
If your account is set up to be risk tolerant, wait until the order's pre-ordered
items[] are ready to be released and then instruct your fulfiller to ship them. Once your fulfiller notifies you that the goods are in transit, send Digital River a POST /fulfillments request that passes along the tracking data they provided, along with the quantity of each items[] that's getting delivered. curl --location --request POST 'https://api.digitalriver.com/fulfillments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Secret API key>' \
...
--data-raw '{
"orderId": "250956650336",
"items": [
{
"itemId": "180179270336",
"quantity": "2"
}
],
"trackingCompany": "Fedex",
"trackingNumber": "Z10100002632653",
"trackingUrl": "http://www.fedex.com/Tracking?tracknumbers=Z10100002632653"
}'
Whether Digital River (1) attempts to capture and settle on the original payment authorization because it has yet to expire, (2) successfully creates a new authorization to replace the expired one or (3) fails to create a new authorization and then force settles on the original, expired one, your request immediately returns a fulfillment and this results in the creation of an event whose
type is order.charge.capture.pending and whose data.object is a charge. Fulfillment
Event
{
"id": "ful_c80eed02-6664-4570-9f96-b0c91bf56f1e",
"createdTime": "2023-01-03T20:17:17Z",
"items": [
{
"quantity": 2,
"cancelQuantity": 0,
"skuId": "bda6f910-1135-4e28-bd7b-fd42b592e5e6",
"itemId": "180179270336"
}
],
"orderId": "250956650336",
"trackingCompany": "Fedex",
"trackingNumber": "Z10100002632653",
"trackingUrl": "http://www.fedex.com/Tracking?tracknumbers=Z10100002632653",
"liveMode": false
}
{
"id": "f1ce58d1-eef2-4d42-8f42-902ae595bc86",
"type": "order.charge.capture.pending",
"data": {
"object": {
"id": "788f5e05-21df-40ef-aa57-dd30f2537b72",
"createdTime": "2023-01-03T20:16:57Z",
"currency": "USD",
"amount": 27.01,
"state": "processing",
"orderId": "250956650336",
"captured": true,
"captures": [
{
"id": "ab7c6657-0f4e-4a7c-ab12-97dab4d3d7aa",
"createdTime": "2023-01-03T20:17:19Z",
"amount": 27.01,
"state": "pending",
"fulfillmentId": "ful_c80eed02-6664-4570-9f96-b0c91bf56f1e"
}
],
"refunded": false,
"sourceId": "b9b0cce6-a170-42da-9e64-cf3e34e22023",
"paymentSessionId": "2d656f29-5ee4-472d-8466-07e5685c60cc",
"type": "customer_initiated",
"liveMode": false
}
},
"liveMode": false,
"createdTime": "2023-01-03T20:17:19.555734Z",
"digitalriverVersion": "2021-12-13"
}
Both of them could be used to trigger a function that updates the status of the payment in your system. Additionally, you might use the failed event's
captures[].fulfillmentId to look up the fulfillment and then send a request to your fulfiller that attempts to cancel shipment of those goods. If your account is set up to be risk averse, wait until the order's pre-ordered
items[] are ready to be released and then send Digital River a POST /fulfillments request that specifies the quantity of each items[] that's scheduled to be shipped. curl --location --request POST 'https://api.digitalriver.com/fulfillments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Secret API key>' \
...
--data-raw '{
"orderId": "250954450336",
"items": [
{
"itemId": "180178140336",
"quantity": "2"
}
],
"trackingCompany": "Fedex",
"trackingNumber": "Z10100002632653",
"trackingUrl": "http://www.fedex.com/Tracking?tracknumbers=Z10100002632653"
}'
If Digital River determines that the original payment authorization has yet to expire or (in the event that it's no longer valid) successfully creates a new authorization, then your
POST/ fulfillments request immediately returns a fulfillment and this results in the creation of an event whose type is order.charge.capture.pending and whose data.object is a charge.Fulfillment
Event
{
"id": "ful_e6e45f1c-7b74-4be2-9940-08c9a04a6559",
"createdTime": "2023-01-03T17:50:57Z",
"items": [
{
"quantity": 2,
"cancelQuantity": 0,
"skuId": "bda6f910-1135-4e28-bd7b-fd42b592e5e6",
"itemId": "180178140336"
}
],
"orderId": "250954450336",
"trackingCompany": "Fedex",
"trackingNumber": "Z10100002632653",
"trackingUrl": "http://www.fedex.com/Tracking?tracknumbers=Z10100002632653",
"liveMode": false
}
{
"id": "a3582549-7727-4a7b-a3e5-9966c1738eab",
"type": "order.charge.capture.pending",
"data": {
"object": {
"id": "5813455e-6b8b-4257-872c-030fd888d4d2",
"createdTime": "2023-01-03T17:49:39Z",
"currency": "USD",
"amount": 27.01,
"state": "processing",
"orderId": "250954450336",
"captured": true,
"captures": [
{
"id": "7f9052d8-053f-4275-b642-985317e48589",
"createdTime": "2023-01-03T17:50:57Z",
"amount": 27.01,
"state": "pending",
"fulfillmentId": "ful_e6e45f1c-7b74-4be2-9940-08c9a04a6559"
}
],
"refunded": false,
"sourceId": "c3afc2a5-ba13-4f07-a99a-295c83114596",
"paymentSessionId": "9a8fe720-ed0f-4b17-8d31-384f179dd899",
"type": "customer_initiated",
"liveMode": false
}
},
"liveMode": false,
"createdTime": "2023-01-03T17:50:58.244814Z",
"digitalriverVersion": "2021-12-13"
}
At this point, you should instruct your fulfiller to ship the goods and, once they notify you that they're in transit, send a
POST/ orders/{id} request that adds to metadata the tracking data your fulfiller provides. Passing this tracking
metadata helps Digital River detect fraud and manage chargeback risks.curl --location --request POST 'https://api.digitalriver.com/orders/248847150336' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Secret API key>' \
...
--data-raw '{
"metadata": {
"trackingCompany": "Fedex",
"trackingNumber": "Z10100002632653",
"trackingUrl": "http://www.fedex.com/Tracking?tracknumbers=Z10100002632653"
}
}'
Both of them could be used to trigger a function that updates the status of the payment in your system. Additionally, you might use the failed event's
captures[].fulfillmentId to look up the fulfillment and then send a request to your fulfiller that attempts to cancel shipment of those goods. If Digital River determines that the original payment authorization has expired and is unable to get the issuing bank to grant a new authorization, then your
POST/ fulfillments request immediately returns an error with a code of payment_authorization_failed and this results in the creation of an event whose type is order.charge.reauth.failed and whose data.object is the order. Error
Event
409 Conflict
{
"errors": [
{
"code": "payment_authorization_failed",
"description": "Fulfillment cannot be processed because the payment authorization has expired",
"parameter": "orderId"
}
]
}
{
"id": "d83b5e90-249f-4050-8103-59de3132f68d",
"type": "order.charge.reauth.failed",
"data": {
"object": {
"id": "1066128630082",
"createdTime": "2022-12-30T18:03:13Z",
"currency": "USD",
"email": "[email protected]",
"billTo": {
"address": {
"line1": "1234 Fake St.",
"city": "Minnetonka",
"postalCode": "55341",
"state": "MN",
"country": "US"
},
"name": "Guy Incognito",
"phone": "123456789",
"email": "[email protected]"
},
"totalAmount": 5.37,
"subtotal": 5.0,
"totalFees": 0.0,
"totalTax": 0.37,
"totalImporterTax": 0.0,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 0.0,
"items": [
{
"id": "53039420082",
"skuId": "sku_3bb13d1d-1904-486b-9975-38f457c1b4c7",
"productDetails": {
"id": "sku_3bb13d1d-1904-486b-9975-38f457c1b4c7",
"name": "productName_test_fulDigital13",
"countryOfOrigin": "US"
},
"amount": 5.0,
"quantity": 1,
"metadata": {
"key11": "value",
"key12": "value"
},
"state": "created",
"stateTransitions": {
"created": "2022-12-30T18:03:13Z"
},
"tax": {
"rate": 0.07375,
"amount": 0.37
},
"importerTax": {
"amount": 0.0
},
"duties": {
"amount": 0.0
},
"availableToRefundAmount": 0.0,
"fees": {
"amount": 0.0,
"taxAmount": 0.0
},
"shipping": {
"amount": 0.0,
"taxAmount": 0.0
}
}
],
"updatedTime": "2022-12-30T18:03:13Z",
"locale": "en_US",
"customerType": "individual",
"sellingEntity": {
"id": "C5_INC-ENTITY",
"name": "DR globalTech Inc."
},
"liveMode": false,
"payment": {
"charges": [
{
"id": "cad13169-727f-4a48-bf0e-a0212475bf18",
"createdTime": "2022-12-30T18:03:16Z",
"currency": "USD",
"amount": 5.37,
"state": "capturable",
"captured": false,
"refunded": false,
"sourceId": "d3832f94-9fcd-458c-8f78-2c9d1f932f6f",
"type": "customer_initiated"
}
],
"sources": [
{
"id": "d3832f94-9fcd-458c-8f78-2c9d1f932f6f",
"type": "creditCard",
"amount": 5.37,
"owner": {
"firstName": "Guy",
"lastName": "Incognito",
"email": "[email protected]",
"address": {
"line1": "1234 Fake St.",
"city": "Minnetonka",
"postalCode": "55341",
"state": "MN",
"country": "US"
}
},
"creditCard": {
"brand": "Visa",
"expirationMonth": 10,
"expirationYear": 2022,
"lastFourDigits": "3676"
}
}
],
"session": {
"id": "ab2ee4bc-7b30-4346-9fef-94e026f8edb6",
"amountContributed": 5.37,
"amountRemainingToBeContributed": 0.0,
"state": "complete",
"clientSecret": "ab2ee4bc-7b30-4346-9fef-94e026f8edb6_b8d8df52-111c-495c-9907-c7aad53e7cde"
}
},
"state": "accepted",
"stateTransitions": {
"accepted": "2022-12-30T18:03:17Z"
},
"fraudState": "passed",
"fraudStateTransitions": {
"passed": "2022-12-30T18:03:17Z"
},
"requestToBeForgotten": false,
"capturedAmount": 0.0,
"cancelledAmount": 0.0,
"availableToRefundAmount": 0.0,
"checkoutId": "7c8c0525-e133-40a6-94d9-f0427266b5e1"
}
},
"liveMode": false,
"createdTime": "2022-12-30T18:03:23.12606Z",
"digitalriverVersion": "2021-12-13"
}
The
payment_authorization_failed error could trigger a request to your fulfiller that instructs them to cancel the order before the goods are shipped. From the event, you could retrieve
items[].productDetails, payment.sources[], and other data and use it to populate a payment failed notification (typically an email) that gets sent to the customer. If it's supported by your business model, you could also attempt to get a new payment method from the customer. If you have a transaction that contains multiple pre-ordered items, but they're not all ready to ship at the same time, and you send a
POST /fulfillments with a partial quantity of these items[] that throws a payment authorization failed exception, then any subsequent capture attempts are also likely to fail. As result, in this particular scenario, we recommend that you cancel all of that transaction's pre-ordered items. Our payments mocker doesn't currently support testing reauthorizations in a non-production environment. However, once feature-specific test credit card numbers become available, we'll add them to the docs.