checkout_session_id- Extract from redirect URL (e.g.,fcs_01kbjcmbt5mhsmaggfqc1a4rns)- This ID is required for creating refunds
payment_intent_id- Flex’s internal payment IDlatest_charge- Charge IDstatus- Should becompletefor refunds
Primary refund endpoint
POST /v1/checkout/sessions//refund
This is the main refund endpoint for processing refunds on completed checkout sessions. Base URL:https://api.withflex.com (or your custom domain)
Authentication:
Request format
Option 1: line item-based refund (granular control)
Refund specific products/prices with custom amounts:price instead of product
Option 2: simple amount-based refund
Refund a specific total amount without line item breakdown:Option 3: full refund
Refund the entire checkout session amount:Request parameters
Success response
Status Code:200 OK
refunds[].refund_id- Store this for tracking refund statusrefunds[].status- Current refund status (pending,succeeded,failed)refunds[].reference_id- Acquirer Reference Number (ARN) for bank tracking (populated later)refunds[].reference_status- Status of reference number (pending,available,unavailable)
Error responses
Checkout session not complete (422 unprocessable entity)
complete
Checkout session not found (404 not found)
checkout_session_id or doesn’t belong to your account
Unauthorized (401 unauthorized)
Authorization header
Refund statuses
Typical Timeline:
- Refund status updates to
succeededwithin minutes to hours - Funds appear in customer’s account within 5-10 business days (varies by bank)
Reference numbers for tracking
Flex provides reference numbers that can be used to track refunds with banks and payment networks.Reference types
Reference status
Note: Reference IDs typically become available within hours after the refund is created.
Learn More: Stripe Reference Numbers Guide
Complete workflow examples
Example 1: full refund
Step 1: Customer completes payment You receive redirect after successful payment:Example 2: partial refund by line items
Scenario: Customer returns 1 of 3 items purchased Request:- Refunding only the yoga mat: $35.00
- Including proportional tax: $2.80
- Not refunding shipping (customer kept other items)
- Total refund: $37.80
Example 3: partial refund by amount
Scenario: Price adjustment without item-level detail Request:- Refunding $20.00 difference due to price match
- No line item breakdown needed
- Metadata tracks the reason
Example 4: multiple partial refunds
You can create multiple refunds for the same checkout session until the full amount is refunded. First refund: $50Secondary refund API
Tracking and listing refunds
After creating a refund through the checkout session endpoint, use the secondary refund API to track status:GET /v1/refunds/
GET /v1/refunds (list refunds)
Query Parameters:payment_intent- Filter by payment intent IDcheckout_session- Filter by checkout session IDstatus- Filter by status
PATCH /v1/refunds/ (update refund metadata)
Update refund metadata or reason (does not change amount or status):Implementation details
Automatic handling by Flex
Flex automatically handles:- ✅ Reverse Transfer - Funds are clawed back from the connected account (partner)
- ✅ Application Fee Retention - Flex keeps the platform fee (not refunded)
- ✅ Webhook Processing - Status updates through Stripe webhooks
- ✅ Charge Tracking - Records which charges were refunded in
refund_chargetable - ✅ Reference Number Retrieval - ARN and other tracking numbers populated when available
Partial refund behavior
- Can refund any amount up to the original charge amount
- Multiple partial refunds allowed until full amount refunded
- Track
amount_receivedvs total refunded to calculate remaining refundable amount
Tax, shipping, and discount refunds
When refunding line items, you can specify component amounts:Best practices
1. Store checkout session ID
Always save thecheckout_session_id after payment completion:
2. Verify checkout session status
Before attempting refund, confirm the session is complete:3. Use metadata for tracking
Always include metadata to track refund context:4. Handle refund webhooks
Subscribe to Flex webhooks for automatic refund status updates: Event Types:refund.created- Refund initiatedrefund.succeeded- Refund completed successfullyrefund.failed- Refund failed
5. Track remaining refundable amount
For multiple partial refunds, track the remaining amount:6. Save reference numbers
Store ARNs for customer support inquiries:7. Handle errors gracefully
Testing
Test mode
Use test API keys (starting withsk_test_) to test refunds without affecting real money:
- Refunds complete instantly with
status: "succeeded" - No actual money movement
- Reference IDs still generated for testing
- Full webhook flow works
Test credentials
For testing payments → refunds flow: Email:miguel@homefit.com Password: password
Create test API keys at: http://localhost:3001/partners/dashboard/developers
Troubleshooting
Problem: “checkout session must be complete”
Cause: Trying to refund a checkout session that hasn’t been paid or is in progress Solution:- Check session status:
GET /v1/checkout/sessions/{id} - Ensure
status === "complete" - Wait for payment to finish if still processing
Problem: “checkout session does not exist”
Cause: Invalid checkout session ID or doesn’t belong to your account Solution:- Verify the
checkout_session_idis correct - Ensure you’re using the right API key (test vs. production)
- Check that the session belongs to your partner account
Problem: Refund shows “pending” for too long
Cause: Stripe processing delay or connected account issues Solution:- Wait up to 24 hours for normal processing
- Check Stripe dashboard for errors
- Verify connected account has sufficient balance
- Contact support if still pending after 24 hours
Problem: “Failed to create refund”
Cause: Stripe API error (usually insufficient funds in connected account) Solution:- Check connected account balance in Stripe dashboard
- Ensure partner account has funds to cover refund
- Review Stripe logs for specific error details
- Contact Flex support with
checkout_session_id
Problem: Reference ID not available
Cause: Payment network hasn’t provided ARN yet Solution:- Reference IDs typically appear within hours
- Check
reference_status- ifpending, wait - If
unavailable, payment network doesn’t provide this type - Poll
/v1/refunds/{refund_id}periodically for updates
API endpoint summary
Common use cases
Use case 1: customer service full refund
Use case 2: return processing with line items
Use case 3: price adjustment
Additional resources
- Flex API Documentation: Contact your Flex account manager
- Stripe Refund Guide: https://stripe.com/docs/refunds
- Reference Numbers: https://support.stripe.com/questions/how-to-trace-a-refund-using-reference-numbers
- Webhooks Setup: Contact Flex support for webhook configuration
Support
For issues or questions about refunds:- Check this guide for common solutions
- Review Stripe dashboard for payment details
- Contact Flex support with:
checkout_session_idrefund_id(if refund was created)- Error messages
- Timestamp of the issue