/orders/{id}
GET /orders/{id} to retrieve the status on a specific order.
This endpoint focuses on a specific order identified by its unique ID (represented by {id}). When you access this endpoint, it typically returns detailed information about a single order, such as the customer's name, order details, payment status, and shipment tracking.
Use this API in your Advanced CIT integration, your Standard MIT integration, your SFTP implementation.
If /evaluate returned a 'CHALLENGE', 'CAPTUREREQUIRED' or 'SUBMITTED' order status, you will retrieve FlexFactor decision for that transaction with GET /orders.
Request
Required key
id | The FlexFactor order id returned by the /evaluate response. |
bearer token | The auth token returned by /oauth2/token |
Try it right now:
- Check out the /orders/{id} Reference.
Response
| Field Name | Field Type | Field Explanation |
|---|---|---|
| id | String | Unique identifier for the order |
| correlationId | String | Identifier used to correlate this transaction with other related transactions |
| referenceNumber | String | Reference number unique to this request |
| status | String | The order status, as a lowercase string: draft, onhold, cancelled, problem, processing, capturerequired, returned, completed, or disputed. See Order status. Note: onhold can appear on GET responses and as a filter, but no webhook is emitted for it. |
| state | String | A coarser view of the order lifecycle: Processing, Cancelled, CaptureRequired, or Completed. |
| statusName | String | Deprecated. Use state. Textual representation of the order's status. |
| orderPlacedDate | String | Date and time when the order was placed, in ISO 8601 format |
| expiryDate | String | Expiry date of the order, can be null |
| billingAddress | Object | Object containing billing address details like country, city, and postal code |
| shippingAddress | Object | Object containing shipping address details, can be null |
| firstName | String | First name of the customer |
| lastName | String | Last name of the customer |
| String | Email address of the customer | |
| phone | String | Phone number of the customer |
| secondaryEmail | String | Secondary email of the customer, can be empty |
| currency | String | ISO 4217 currency code for the transaction, for example USD |
| currencyCode | Integer | ISO 4217 numeric currency code, for example 840 for USD |
| currencySymbol | String | Symbol representing the currency used, for example $ |
| amount | Float | Total amount of the order |
| formattedAmount | String | Formatted total amount of the order with currency symbol |
| orderItems | Array | List of items included in the order, each item is an object with details like name, price, and quantity |
| activityItems | Array | List of payment-related activities for the order, such as authorization and capture transactions, as well as dispute and refund. Each entry also carries bin and last4 of the card used, discountAmount, and isExternal (true when the activity was recorded from outside FlexFactor's own processing). |
| totalBalancePaid | Integer | Total amount paid towards the order |
| totalBalancePaidFormatted | String | Formatted total amount paid towards the order |
| balanceToBePaid | Float | Remaining balance to be paid |
| balanceToBePaidFormatted | String | Formatted remaining balance to be paid |
| refundsAmount | Decimal | Total amount refunded, in dollars |
| paymentInstrumentToken | String | Token representing the payment method used for the transaction |
| paymentMethod | Object | The payment method used: token and last4 |
| merchantName | String | Name of the merchant/store where the order was placed |
| merchantId | String | Merchant identifier specific to the store |
| siteId | String | Identifier of the FlexFactor site the order was assigned to |
Order status
| Order status | Description | Returned by |
|---|---|---|
| Challenge | Conditional status: the transaction rescue requires an action from the customer. This action can be performed via the UI Widget. If the UI Widget is not embedded, treat as a decline. | /evaluate response; challenge.* webhooks |
| Capture required | Pending status: the transaction rescue requires a /capture. | /evaluate response (CIT authorize); GET /orders status capturerequired; order.capturerequired webhook |
| Submitted | Pending status: the transaction was received for asynchronous processing. Track the outcome via GET /orders or webhooks. | /evaluate response only |
| Draft | Pending status: MIT order was picked up by the system, but is not yet being processed. | GET /orders status draft |
| Onhold | Pending status: the order is temporarily on hold. | GET /orders status onhold |
| Processing | Pending status: the order is being processed. | GET /orders status processing |
| Problem | Fail status: a processing problem occurred. | GET /orders status problem |
| Completed | Success status: the transaction was rescued and captured. A refunded order stays completed; read refundsAmount. | GET /orders status completed; order.completed webhook |
| Returned | Returned status: defined in the status enum. A refund does not move an order here. | GET /orders status returned |
| Disputed | Dispute status: the order has an open dispute. | GET /orders status disputed |
| Approved | Success status: the transaction was rescued. | /evaluate and /capture responses |
| Declined | Fail status: the transaction could not be rescued. | /evaluate and /capture responses |
| Cancelled | Fail status: the order was cancelled, voided, or expired without a rescue. | GET /orders status cancelled; order.cancelled or order.expired webhook |
The mapping between the synchronous response, the GET /orders status, and webhooks is consolidated in Workflows §3.5.
Expired orders are returned as cancelled — there is no separate "expired" status in the API. The expiry is signalled by theorder.expiredwebhook.
HTTP status codes
| Situation | HTTP | Body |
|---|---|---|
| The order was found | 200 | Order record (fields above) |
| Invalid or expired bearer token | 401 | — |
No order matches {id}, or it belongs to another merchant | 404 | Problem details |
| An internal error occurred | 500 | — |
Payload examples
Request
curl --request GET \
--url https://api-sandbox.flexfactor.io/v1/orders/{Flex unique order id} \
--header 'Authorization: Bearer {the token returned by /oauth2}' \
--header 'accept: application/json'Response
{
"id": "8ee05b5f-652a-471b-bbec-dc0887e1f08f",
"correlationId": "00000000-0000-0000-0000-000000000000",
"referenceNumber": "b46cbb4a-90ba-4f5d-b9c3-9d5dcbef8912",
"state": "Completed",
"status": "completed",
"statusName": "completed",
"orderPlacedDate": "2024-02-29T15:13:57.787092Z",
"expiryDate": null,
"billingAddress": {
"country": "US",
"countryCode": "US",
"line1": "378 EAST ST",
"line2": "",
"city": "BLOOMSBURG",
"zipCode": "178151847",
"state": "PATTT"
},
"shippingAddress": null,
"firstName": "CURE1",
"lastName": "TESTER",
"email": "[email protected]",
"phone": "+1 234567890",
"secondaryEmail": "",
"currency": "USD",
"currencyCode": 840,
"currencySymbol": "$",
"amount": 45.65,
"formattedAmount": "$45.65",
"orderItems": [
{
"id": "2424de18-26ec-4d47-96c3-b2debdaddc77",
"name": "Green FlexFactor Fleece Zip Hoodie",
"referenceId": "0",
"unitPrice": 45.65,
"discount": 0,
"tax": 0,
"quantity": 1,
"amount": 45.65
}
],
"activityItems": [
{
"orderId": "8ee05b5f-652a-471b-bbec-dc0887e1f08f",
"paymentTransactionId": "5dfc23c7-35fa-4370-b055-eecfd8239ed5",
"relatedTransactionId": null,
"type": "authorization",
"description": "Authorization with card that ends with 1111",
"totalAmountFormatted": null,
"totalAmount": 4565,
"discountAmount": 0,
"requestDate": "0001-01-01T00:00:00",
"paymentDate": "2024-02-29T15:13:55.397356Z",
"createDateTime": null,
"bin": "411111",
"last4": "1111",
"isExternal": false
},
{
"orderId": "8ee05b5f-652a-471b-bbec-dc0887e1f08f",
"paymentTransactionId": "bc12b943-4d6f-4cfa-85da-06ab02818842",
"relatedTransactionId": "5dfc23c7-35fa-4370-b055-eecfd8239ed5",
"type": "capture",
"description": "Captured trx ref: bc12b943-4d6f-4cfa-85da-06ab02818842",
"totalAmountFormatted": null,
"totalAmount": 4565,
"discountAmount": 0,
"requestDate": "0001-01-01T00:00:00",
"paymentDate": "2024-02-29T15:13:57.60449Z",
"createDateTime": null,
"bin": "411111",
"last4": "1111",
"isExternal": false
},
{
"orderId": "8ee05b5f-652a-471b-bbec-dc0887e1f08f",
"paymentTransactionId": "3095a2bd-adf2-4f4d-b88c-caeefb19bc72",
"relatedTransactionId": null,
"type": "chargeback",
"description": "Transaction Ref: 3095a2bd-adf2-4f4d-b88c-caeefb19bc72 was disputed",
"totalAmountFormatted": null,
"totalAmount": 4565,
"discountAmount": 0,
"requestDate": "0001-01-01T00:00:00",
"paymentDate": "2024-02-29T23:07:17.365108Z",
"createDateTime": null,
"bin": "411111",
"last4": "1111",
"isExternal": false
}
],
"totalBalancePaid": 0,
"totalBalancePaidFormatted": "$0",
"balanceToBePaid": -4519.35,
"balanceToBePaidFormatted": "$-4519.35",
"refundsAmount": 45.65,
"paymentInstrumentToken": "88e877a7-9900-4b4c-b344-019cc2a61316",
"paymentMethod": {
"token": "88e877a7-9900-4b4c-b344-019cc2a61316",
"last4": "1111"
},
"merchantName": "YOUR STORE",
"merchantId": "{your MID}",
"siteId": "{your siteId}"
}
Note: top-levelamount/balancefields andrefundsAmountare returned in major units (dollars);activityItems[].totalAmountis in cents.
Updated 4 days ago
Did this page help you?