Process EBT SNAP refunds
Learn how to implement EBT SNAP compliant refunds with the Forage API
A refund is a repayment to a customer after they return item(s) in an order. This guide details the specifics of refunding EBT SNAP benefits. The guide is divided into the following sections:
Refund Receipt Details
For details on refund receipts, see the Forage receipts guide.
Refund scenarios
Item substitutions
An item substitution is when a lower-cost alternative replaces an item in the original order. A customer might initiate the substitution, or a retailer or delivery shopper might make the swap when they discover a price discrepancy, an inventory error, or that the item is out of stock. Weighted items can also result in item substitutions. If the fulfilled weight is lower than the ordered weight, then the difference may result in a refund.
Item removals
An item removal is when an item is removed from the order. A customer might remove it while the order is being fulfilled, or a retailer or delivery shopper might opt to remove an item if it’s out of stock and there’s no adequate substitute, or if the retailer doesn’t support substitutions.
Item returns
A customer might initiate a return if an item is expired or otherwise unsatisfactory.
Promotions And Refunds
Refunds may affect eligibility for promotions like free shipping. To maintain a good customer experience, consider honoring the original offer.
FNS requirements
Deadlines
- Customer-requested refunds must be processed within two business days after the item is returned.
- Refunds due to merchant error, like overestimated weighted products, out of stock items, or substitutions must be processed on the same day that the original order was fulfilled.
- Merchants must send customers a refund notification, whether via email, confirmation screen, or a customer’s account portal, within 24 hours of when the refund is completed.
Refund Receipt Requirements
For details and examples of refund notifications, see the Forage receipts guide.
Payment instruments
FNS Refund Requirements Summary
Refunds must match original payment methods:
- SNAP-ineligible items can’t be refunded to SNAP.
- EBT Cash–ineligible items can’t be refunded to EBT Cash.
- Never refund more than was originally charged.
SNAP
Only SNAP eligible purchases can be refunded to a customer's SNAP balance. To protect against fraud, no other payment instrument can receive the SNAP refund. Refunds from SNAP to credit/debit, EBT Cash, or store gift cards are prohibited.
Refunding non-SNAP items, like alcohol, should never result in a SNAP refund.
EBT Cash
Only EBT Cash eligible purchases can be refunded to a customer's EBT Cash balance. To protect against fraud, no other payment instrument can receive the EBT Cash refund. Refunds from EBT Cash to credit/debit, SNAP, or store gift cards are prohibited.
Refunding non-EBT Cash items, like alcohol, should never result in an EBT Cash refund.
SNAP purchases can only be refunded to SNAP. EBT Cash purchases can only be refunded to EBT Cash.
Refund entry
Every retailer must have a secure method for authorized employees, using password protected user IDs, to manually enter refund requests. There must be functionality for an employee to either issue refunds by item or to directly enter a specific amount to be refunded.
Refund notification
Refer to the EBT SNAP refunds section of the receipts guide for a comprehensive list of information that must be shared with customers after a refund is completed.
How to process online EBT SNAP refunds
Forage recommends splitting refund feature development into two parts:
- Design the refunds flow
- Query the API to issue refunds
Example API Requests
Jump to the example API requests.
Design the refunds flow
Either restore the original tender amount or maximize credit/debit return
When an entire order is refunded, the merchant returns the total amount paid to the customer. However, if a refund involves only some of the items purchased, then a merchant returns just the cost of those items.
If you map the exact tender amount paid per item in your database, then the fastest-to-build refunds flow is to issue a refund based on the original payment split.
To maximize the credit/debit return instead, you can redistribute the payment split. Calculate the refund based on whether or not the restored EBT SNAP balance can be applied to other eligible items in the cart. This is not required, but it’s the preferred customer experience.
To illustrate the different options, consider the following example receipt. "SP" indicates that an item is SNAP eligible. "EBT" indicates EBT Cash eligible:
The receipt illustrates an order involving multiple payment instruments.
Pretend that the customer returns Item A, a $10 SNAP eligible item. The refunds flow that restores the original tender amount refunds $10 to the customer’s SNAP balance. The flow that maximizes the credit/debit refund results in a $10.10 credit card refund. Read on for details.
Refunds flow that restores the original tender amount
In this example scenario, the return of Item A restores $10 to the customer’s SNAP balance.
If the customer decides to also return Item B, then $10 is refunded to the credit card balance. Returning Item D results in a $5.05 refund to the customer’s EBT Cash account.
Refunds flow that maximizes the credit/debit return
Optional For FNS, Helpful For CX
This step isn’t required by FNS but improves the customer experience.
If a customer pays for EBT SNAP eligible items via a mix of payment methods, then during a refund it’s possible to redistribute the payment split. The final refund amount is determined based on whether or not the restored EBT SNAP balance can be applied to other eligible items in the cart.
Items with higher tax rates can be refunded to SNAP first to minimize a customer’s taxes and maximize their credit/debit refund, as outlined in the steps below.
Step 1: Calculate the updated order total
Subtract the cost of the returned item from the original order total.
In the scenario, you’d deduct the $10.00 value of Item A from the $60.00 order total. This results in an updated order total of $50.00.
Step 2: Sort any remaining SNAP eligible items by highest tax rate
If SNAP-paid items are returned, then the SNAP credit can be redistributed among any remaining SNAP eligible order items. To maximize a customer’s potential credit/debit card return, apply the SNAP credit to the highest-taxed items first.
In the scenario, after removing Item A, two SNAP eligible items are in the cart:
- Item C: $10.00, Tax rate 1%
- Item B: $10.00, Tax rate 0%
Item C has a higher tax rate, so it’s sorted above Item B.
Step 3: Apply SNAP credit to SNAP eligible items
Apply all of the returned SNAP credit to the remaining SNAP eligible items in the cart, starting with the highest-taxed items. If the credit exceeds the value of the remaining SNAP eligible items, then return the excess SNAP amount to the customer’s SNAP balance.
In the scenario, the return of Item A restores $10.00 in SNAP credit. That $10.00 is applied in full to Item C, because its tax rate is higher than Item B’s.
Step 4: Distribute the original EBT Cash charge
The original EBT Cash payment can be applied to any remaining SNAP eligible and EBT Cash eligible items. The order of the items doesn’t matter: unlike SNAP purchases, EBT Cash purchases are taxed. If the original EBT Cash payment is greater than the cost of the remaining eligible items, then refund the difference to the customer’s EBT Cash account balance.
In the scenario, the customer paid $5.05 in EBT Cash. That $5.05 is applied in full to the original Item D.
Step 5: Apply the original credit/debit card payment to outstanding items and fees
Apply the original credit/debit card payment to any outstanding items and fees. If the credit/debit card payment exceeds the cost of the outstanding items, then refund the difference to the customer’s credit/debit card account balance. If the cost of the outstanding items exceeds the original credit/debit card payment, then create a new order and charge the customer the difference.
In the scenario, the following items remain in the cart:
- Item B: $10.00, Tax rate 0%
- Item E: $25.00
- Plus 1% Tax rate: $25.25
The original $45.35 credit/debit card payment is applied to the outstanding $35.25 total. The remaining $10.10 is refunded to the credit/debit card.
Query the Forage API
The endpoints that you need to call to issue refunds differ depending on whether you’ve built with an SDK or the Forage Checkout UI. SDK integrations create PaymentRefunds, while Fully Hosted and Custom integrations create OrderRefunds.
How to handle a failed refund
No matter your integration type, if a refund attempt fails, then retry the request with the same payload and same idempotency key.
SDK
SDK integrations call the Payment Refunds endpoints.
To refund a payment, send a POST to /payments/{payment_ref}/refunds/, passing the ref for the relevant Payment to be refunded as the path param. In the request body specify the amount to be refunded, along with a reason , as in the following example.
Request
curl --request POST \
--url https://api.sandbox.joinforage.app/api/payments/{payment_ref}/refunds/ \
--header 'Authorization: Bearer <authentication-token>' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'Merchant-Account: <merchant-account>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"amount": 25.99,
"reason": "Order could not be delivered"
}
'
Response
{
"ref": "0ddbcda871",
"payment_ref": "b873fe62dc",
"merchant": "9000055",
"funding_type": "ebt_snap",
"amount": "25.99",
"reason": "Order could not be delivered.",
"created": "2023-09-18T11:38:29.279185-07:00",
"updated": "2023-09-18T11:38:29.279209-07:00",
"status": "requires_confirmation",
"last_processing_error": null,
"receipt": null
}
For more information, see these API reference docs:
Forage Checkout (Fully Hosted and Custom)
Forage Checkout integrations, for both Fully Hosted and Custom, call the Order Refunds endpoints.
Call different endpoints for refunding an entire Order or refunding part of an Order.
Refund an entire Order
To refund an entire Order, send a POST to /orders/{order_ref}/refunds/, passing the ref for the relevant Order to be refunded as the path param. In the request body specify the reason for the refund and a metadata object, as in the following example.
Request
curl --request POST \
--url https://api.sandbox.joinforage.app/api/orders/{order_ref}/refund_all/ \
--header 'Authorization: Bearer <authentication-token>' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'Merchant-Account: <fns-number>' \
--header 'accept: application/json' \
--header 'content-type: application/json'
--data '
{
"reason": "Order could not be delivered",
"metadata": {}
}
'
Response
{
"ref": "e0f7607d5f",
"snap_total": "10.00",
"ebt_cash_total": "9.00",
"remaining_total": "0.00",
"product_list": [],
"status": "draft",
"delivery_address": {
"city": "San Francisco",
"country": "US",
"line1": "1856 Market St.",
"line2": "Apt. 3",
"state": "CA",
"zipcode": "94105,"
},
"is_delivery": false,
"success_redirect_url": "",
"cancel_redirect_url": "",
"supported_benefits": [
"snap",
"ebt_cash",
"non_ebt"
],
"success_date": null,
"receipt": null,
"customer_id": null,
"is_commercial_shipping": null,
"expires_at": "2023-09-29T18:33:28.315051Z",
"psp_customer_id": null,
"external_order_id": null,
"payments": [],
"refunds": []
}
For more information, see these API reference docs:
Refund part of an Order
To refund part of an Order, specifically part or all of a single OrderPayment associated with an Order, send a POST to /orders/{order_ref}/refunds/, passing the ref for the relevant Order to be refunded as the path param. In the request body set the amount to be refunded, the ref for the relevant OrderPayment, the reason for the refund, and a metadata object, as in the following example.
Request
curl --request POST \
--url https://api.sandbox.joinforage.app/api/orders/{order_ref}/refunds/ \
--header 'Authorization: Bearer <authentication-token>' \
--header 'Idempotency-Key: 123e4567e8' \
--header 'Merchant-Account: <fns-number>' \
--header 'accept: application/json' \
--header 'content-type: application/json'
--data '
{
"amount": 25.99,
"payment": <payment-ref>,
"reason": "Order could not be delivered",
"metadata": {}
}
'
Response
{
"ref": "1ccabfg754",
"order": "e0f7607d5f",
"payment": "f587edf124",
"merchant": "9000055",
"funding_type": "ebt_snap",
"amount": "20.00",
"merchant_fixed_settlement": 5.95,
"platform_fixed_settlement": 5.11,
"reason": "Order could not be delivered.",
"metadata": {},
"created": "2023-09-18T11:38:29.279185-07:00",
"updated": "2023-09-18T11:38:29.279209-07:00",
"status": "requires_confirmation",
"last_processing_error": null,
"receipt": null,
"tpp_lookup_id": "re_3JemUSGfBYJeLEva0af6My64",
"refund_errors": []
}
For more information, see these API reference docs:
Updated 22 days ago