--- updatedAt: 2026-05-07T18:17:26.000Z agentTools: projectIndex: https://docs.joinforage.app/llms.txt --- # Cancel an OrderPayment > ⚠️ `OrderPayment`` Updates Must Be Server-Side > > To keep your app secure, requests to cancel an OrderPayment should only be generated on the server-side. A `POST` request to `/orders/{order_ref}/payments/{payment_ref}/cancel/` cancels an existing `OrderPayment`. An `OrderPayment` can only be cancelled if its `status` is `requires_confirmation` or `failed`. Because only payments in these unsuccessful states can be canceled, this endpoint has no financial side effects. On success, the API responds with the original `OrderPayment` object. # OpenAPI definition ```json { "openapi": "3.0.0", "x-readme": { "explorer-enabled": false, "proxy-enabled": false }, "info": { "title": "Forage Payments API", "description": "The Forage Payments API is a REST API for processing Electronic Benefits Transfer (EBT) payments (SNAP and EBT Cash) in your e-commerce or in-store application.\n\nProcessing any EBT payment, or checking an EBT card's balance, requires the cardholder's PIN. Federal regulations require all PIN entry to happen through a PCI-compliant, USDA-approved interface. Forage provides that interface, so EBT PIN collection always happens through a Forage-hosted surface (Forage Checkout or a Forage SDK), never directly in your own form. Some endpoints (for example, capture and balance) are only reachable through that surface because they require PIN data in the request.\n\nEBT rarely covers an entire order: items like delivery fees and non-eligible products can't be paid with SNAP or EBT Cash. You decide how to handle the remaining balance (split tender) and any credit or debit processing alongside the EBT portion.\n\nForage offers four integration options. Pick the one that fits your platform and engineering resources:\n\n1. **Fully Hosted Checkout.** Forage processes EBT and credit/debit through a Forage-hosted Checkout UI. Lowest engineering effort, and Forage absorbs most error handling. See the [Fully Hosted Checkout guide](https://docs.joinforage.app/docs/fully-hosted).\n2. **Custom Checkout.** Forage processes EBT; you handle split tender, taxes, and credit/debit in your own checkout flow. Best when you want minimal changes to your existing UX. See the [Custom Checkout guide](https://docs.joinforage.app/docs/custom).\n3. **Online SDKs.** Client-side SDKs for [web](https://docs.joinforage.app/docs/forage-js), [iOS](https://docs.joinforage.app/docs/ios), and [Android](https://docs.joinforage.app/docs/android) that collect EBT PINs in your app while keeping you out of PCI scope.\n4. **POS Terminal SDK.** Accept in-person EBT payments on an Android POS device. See the [POS Terminal guide](https://docs.joinforage.app/docs/forage-terminal-android).\n\nAs a general principle, any data created by your requests, or by your customers on a Forage-hosted surface, is retrievable through GET requests to the appropriate resource.\n\nHave more questions? Use our [contact form](https://www.joinforage.com/get-in-touch) to reach our sales and engineering support teams.\n", "contact": { "name": "API Support", "email": "engineering@joinforage.com" }, "version": "2025-08-04" }, "externalDocs": { "description": "Forage documentation", "url": "https://docs.joinforage.app/" }, "servers": [ { "url": "https://{environment}.joinforage.app", "variables": { "environment": { "default": "api.sandbox", "enum": [ "api", "api.sandbox" ] } } } ], "security": [], "paths": { "/api/orders/{order_ref}/payments/{payment_ref}/cancel/": { "parameters": [ { "name": "order_ref", "in": "path", "description": "A unique reference hash for the Forage `Order` object, returned when the order’s parent [`Session`](https://docs.joinforage.app/reference/forage-sessions) was created.", "required": true, "schema": { "type": "string" } }, { "name": "payment_ref", "in": "path", "description": "A unique reference hash for the Forage `OrderPayment` object, returned when the [`OrderPayment` was created](https://docs.joinforage.app/reference/create-order-payment).", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AuthenticationBearerTokenHeader" }, { "$ref": "#/components/parameters/MerchantAccountHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "post": { "tags": [ "Order Payments" ], "summary": "Cancel an OrderPayment", "x-readme": { "code-samples": [ { "language": "curl", "code": "curl --request POST \\\n --url https://api.sandbox.joinforage.app/api/orders//payments/cc3175bfea/cancel/ \\\n --header 'Authorization: Bearer ' \\\n --header 'Merchant-Account: ' \\\n --header 'Idempotency-Key: ' \\\n --header 'accept: application/json'\n" } ] }, "description": "> ⚠️ `OrderPayment`` Updates Must Be Server-Side\n>\n> To keep your app secure, requests to cancel an OrderPayment should only be generated on the server-side.\n\nA `POST` request to `/orders/{order_ref}/payments/{payment_ref}/cancel/` cancels an existing `OrderPayment`.\n\nAn `OrderPayment` can only be cancelled if its `status` is `requires_confirmation` or `failed`. Because only payments in these unsuccessful states can be canceled, this endpoint has no financial side effects.\n\nOn success, the API responds with the original `OrderPayment` object.\n", "operationId": "Cancel a payment", "security": [ { "OAuth2": [ "internal", "pinpad_only" ] } ], "responses": { "200": { "description": "__OK__ - Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentResponse" } } } }, "400": { "description": "__Bad request__ - The request was not accepted because of an error in the request body or path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "invalid_input_data": { "summary": "Invalid Input Data", "value": { "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/", "errors": [ { "code": "invalid_input_data", "message": "Query parameter missing or incomplete.", "source": { "resource": "Orders", "ref": "{order_ref}" } } ] } }, "invalid_merchant_account": { "summary": "Invalid Merchant Account", "value": { "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/", "errors": [ { "code": "invalid_merchant_account", "message": "Merchant account Merchant ID not valid.", "source": { "resource": "Merchants" } } ] } }, "missing_idempotency_key": { "summary": "Missing Idempotency Key", "value": { "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/", "errors": [ { "code": "missing_idempotency_key", "message": "You must include a value for the IDEMPOTENCY-KEY header in your requests to this endpoint.", "source": { "resource": "Idempotency_Key" } } ] } }, "missing_merchant_account": { "summary": "Missing Merchant Account", "value": { "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/", "errors": [ { "code": "missing_merchant_account", "message": "No merchant account was provided.", "source": { "resource": "Merchants" } } ] } }, "unknown_fields_error": { "summary": "Unknown Fields Error", "value": { "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/", "errors": [ { "code": "unknown_fields_error", "message": "Unknown field(s) provided: {unknown_fields}", "source": { "resource": "Orders" } } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "invalid_token": { "summary": "Invalid Token", "value": { "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/", "errors": [ { "code": "invalid_token", "message": "Incorrect authentication credentials.", "source": { "resource": "Accounts", "ref": "" } } ] } } } } } }, "403": { "description": "__Forbidden__", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "A string that describes the nature of the error." } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "__Not Found__ - The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "example": { "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/", "errors": [ { "code": "resource_not_found", "message": "Order with ref {order_ref} does not exist for current Merchant with FNS {fns_number}", "source": { "resource": "Orders", "ref": "{order_ref}" } } ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "cannot_change_request": { "summary": "Cannot Change Request", "value": { "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/", "errors": [ { "code": "cannot_change_request", "message": "Two requests were submitted with the same idempotency key, but slightly different request bodies. Please use a new idempotency key if you intended to change the request body", "source": { "resource": "Idempotency_Key" } } ] } } } } } }, "423": { "$ref": "#/components/responses/Error423" }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "too_many_requests": { "summary": "Too Many Requests", "value": { "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/", "errors": [ { "code": "too_many_requests", "message": "Request was throttled, please try again later.", "source": { "resource": "Orders", "ref": "{order_ref}" } } ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "unknown_server_error": { "summary": "Unknown Server Error", "value": { "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/", "errors": [ { "code": "unknown_server_error", "message": "Unknown exception from EBT network", "source": { "resource": "Unknown" } } ] } } } } } } } } } }, "components": { "schemas": { "ErrorsArray": { "type": "array", "description": "An array with information about the error.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short string that represents the error." }, "message": { "type": "string", "description": "A developer-facing message with more details about the error, not to be displayed to customers." }, "source": { "type": "object", "properties": { "resource": { "type": "string", "description": "The type of the Forage resource involved in the error." }, "ref": { "type": "string", "description": "If applicable, the ten character reference hash of the Forage resource that caused the error. An empty string if no specific individual resource was involved." } } }, "details": { "type": "object", "description": "Additional details about the error, if applicable." } } }, "example": [] }, "ErrorResponseObject": { "type": "object", "description": "An object that includes details about the error.", "properties": { "path": { "type": "string", "description": "The requested endpoint." }, "errors": { "$ref": "#/components/schemas/ErrorsArray" } } }, "OrderPaymentRequest": { "type": "object", "description": "This object represents a one-time payment, charged to a single payment method, associated with a specific Forage Order.", "properties": { "funding_type": { "type": "string", "description": "A string that represents the type of tender. One of:\n\n- `benefit`\n- `credit_tpp`\n- `ebt_cash`\n- `ebt_snap`\n", "enum": [ "benefit", "credit_payfac", "credit_tpp", "ebt_cash", "ebt_snap", "wic" ], "default": "ebt_snap" }, "amount": { "type": "string", "format": "decimal", "description": "A positive decimal number that represents how much to charge the `PaymentMethod` in USD. Precision is supported to the penny.\n\nThis value must match the `ebt_cash_total` or `snap_total` value that was passed in the request that [created the Custom Capture Session](https://docs.joinforage.app/reference/create-capture-session), depending on the `funding_type`.\n\nIf you need to charge both funding types, then create an `OrderPayment` for each charge, using the same `order_ref` returned when the order's parent [Payment Capture Session was created](https://docs.joinforage.app/reference/create-capture-session).\n\nThe minimum amount that can be charged is `0.01`.\n", "example": "25.99" }, "description": { "type": "string", "description": "A string that describes the `OrderPayment`.", "default": "An EBT payment" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/MetadataObject" }, { "default": {} } ] }, "payment_method": { "type": "string", "description": "The unique reference hash for the existing Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) that is to be charged in this transaction.", "default": "b16673fe21" }, "customer_id": { "$ref": "#/components/schemas/CustomerIDField" }, "external_order_id": { "$ref": "#/components/schemas/ExternalOrderIDField" }, "merchant_fixed_settlement": { "type": "string", "format": "decimal", "nullable": true, "description": "The fixed amount in USD that should be restored to the merchant from EBT Cash payments prior to splitting by the `platform_fee`. Precision is supported to the penny.\n", "example": "5.11" }, "platform_fixed_settlement": { "type": "string", "format": "decimal", "nullable": true, "description": "The fixed amount in USD that should be restored to the platform from EBT Cash payments prior to splitting by the `platform_fee`. Precision is supported to the penny.\n", "example": "5.11" }, "external_location_id": { "$ref": "#/components/schemas/ExternalLocationIDField" } }, "required": [ "funding_type", "amount", "description", "metadata", "payment_method" ] }, "OrderPaymentResponse": { "allOf": [ { "$ref": "#/components/schemas/OrderPaymentRequest" }, { "type": "object", "properties": { "ref": { "type": "string", "description": "A unique reference hash for the Forage `OrderPayment` object.\n\n_Note:_ `receipt.ref_number` equals `ref`.\n", "example": "cc3175bfea" }, "status": { "type": "string", "description": "The status of the `OrderPayment`. One of:\n\n- `authorized`: The `OrderPayment` has been authorized, but not yet captured. Only applicable to HSA/FSA payments, which use an authorize-then-capture flow.\n- `canceled`: The `OrderPayment` object can't be used.\n- `failed`: If the error is temporary, then this `OrderPayment` can be resubmitted for capture without modification. Check the `receipt.message` field for a description of the error.\n- `processing`: The outcome of the `OrderPayment` is pending.\n- `requires_confirmation`: The `OrderPayment` hasn't been submitted for processing.\n- `succeeded`: The `OrderPayment` has been successfully processed and will be included in settlement. It can't be changed.\n", "enum": [ "authorized", "canceled", "failed", "processing", "requires_confirmation", "succeeded" ], "example": "requires_confirmation" }, "last_processing_error": { "type": "object", "nullable": true, "description": "The code and message values corresponding to the most recent [Payments API error](https://docs.joinforage.app/reference/errors#payments-api-errors).", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "created": { "type": "string", "format": "date-time", "description": "A UTC timestamp, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string, of when the `OrderPayment` was created.", "example": "2021-06-16T00:11:50.000000Z" }, "updated": { "type": "string", "format": "date-time", "description": "A UTC timestamp, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string, of when the `OrderPayment` was last modified.", "example": "2021-06-16T00:11:50.000000Z" }, "success_date": { "type": "string", "format": "date-time", "nullable": true, "description": "A UTC timestamp, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string, of when the `status` of the `OrderPayment` is `succeeded`. This value is always `null` when the `OrderPayment` is first created.", "example": "2021-06-16T00:11:50.000000Z" }, "tpp_lookup_id": { "type": "string", "nullable": true, "description": "This value is always null for `OrderPayments` resulting from Custom Sessions. It’s most relevant to Fully Hosted Sessions, which process credit/debit payments.\n\nA value that merchants can use to associate this payment with a credit/debit payment processed by a third party processor.\n\nFor Stripe integrations, this is the client secret for a [`PaymentIntent`](https://stripe.com/docs/api/payment_intents).\n", "example": "pi_1DpdZq2eZvKYlo2CAYyzTr8j_secret_lxr4crBJP4txbrg7sqit0XQQO" }, "order": { "type": "string", "description": "A unique reference hash for the parent `Order`, as passed in the request to create the `OrderPayment`.", "example": "340129aff3" }, "merchant": { "type": "string", "description": "The FNS (Food and Nutrition Service) number of the merchant associated with this `OrderPayment`." }, "amount": { "type": "string", "format": "decimal", "nullable": true, "description": "The amount charged to the payment method, in USD. Null until the payment is captured." }, "merchant_fixed_settlement": { "type": "string", "format": "decimal", "nullable": true, "description": "The fixed amount in USD restored to the merchant from EBT Cash payments before the `platform_fee` split. Null when not set." }, "platform_fixed_settlement": { "type": "string", "format": "decimal", "nullable": true, "description": "The fixed amount in USD the platform takes from EBT Cash payments before the `platform_fee` split. Null when not set." }, "external_location_id": { "nullable": true, "description": "A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order. Null when not provided." } }, "required": [ "ref", "order", "merchant", "status", "created", "updated" ] } ] }, "CustomerIDField": { "type": "string", "maxLength": 64, "description": "**⚠️ If you’re integrating Forage with a POS Terminal, then do not use this param. It is only supported for online transactions.**\n\nA unique identifier for the end customer making the payment.\n\nForage automatically adds the `customer_id` to the Session's corresponding `Order` and `OrderPayments`.\n\nThis field helps Forage's servers more quickly identify the customer associated with the request. While `customer_id` is not technically required, if you omit it then requests could take longer to process. **It is strongly recommended to pass customer_id.**\n\nIf you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload.\n\nEach customer should only have one unique `customer_id`. For example, if you create both a `PaymentMethod` and a Forage `Session` (Fully Hosted or Custom) or `Payment` (SDK) for the same customer, then the `customer_id` should be the same in both requests to ensure continuity of stored payment methods.\n" }, "ExternalOrderIDField": { "type": "string", "maxLength": 64, "description": "A unique identifier for the order as created by the merchant or platform (not Forage).\n\nWhen a merchant or platform passes this order ID to Forage, it persists in each Forage transaction related to the `Order`. This field enables merchants to map order IDs in their system to corresponding Forage `Order` IDs.\n\n**You must build with Forage Version `2023-05-15` or later to use `external_order_id`.** Either pass `2023-05-15` as the `API-Version` header on a per request basis, or set the version for all requests in the Forage dashboard.\n" }, "ExternalLocationIDField": { "type": "string", "description": "A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order. For example, this field could specify which location of a grocery store chain fulfilled an order.\n", "example": "6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9" }, "MetadataObject": { "type": "object", "description": "A required object containing merchant-defined key-value pairs to provide additional context for the payment.\n\nMerchants should use this field to store **reference information** relevant to the transaction (for example, order details, system identifiers, or tracking data). This helps link the payment to records within their system.\n\nPass an empty object (`{}`) if no additional information is available.\n\n> ⚠️ Personally Identifiable Information\n>\n> **Do not include personally identifiable information (PII)** such as names, emails, or payment details.\n" } }, "responses": { "Error423": { "description": "__Locked__ - The request could not be completed because the target resource is currently locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "resource_locked": { "summary": "Resource Locked", "value": { "path": "/api/example_path/", "errors": [ { "code": "resource_locked", "message": "Request could not be completed because the resource is currently locked. Please try again later.", "source": { "resource": "Idempotency_Key", "ref": "" } } ] } } } } } } }, "parameters": { "AuthenticationBearerTokenHeader": { "name": "Authorization", "in": "header", "description": "An OAuth 2.0 [authentication token](https://docs.joinforage.app/docs/authentication#authentication-tokens) that validates the request. Send a `POST` to the [`/o/token/`](https://docs.joinforage.app/reference/create-authentication-token) endpoint to generate an authentication token. Pass the token in this header after the word `Bearer` and a whitespace, for example `Bearer `.", "schema": { "type": "string" }, "required": true }, "MerchantAccountHeader": { "name": "Merchant-Account", "in": "header", "description": "A unique merchant ID that Forage provides during onboarding, as in `123ab45c67`. The Merchant ID can be found in the Forage [sandbox](https://dashboard.sandbox.joinforage.app/login/) or [production](https://dashboard.joinforage.app/login/) dashboard.", "schema": { "type": "string" }, "required": true }, "IdempotencyKeyHeader": { "name": "Idempotency-Key", "in": "header", "description": "An alphanumeric key that clients can use to identify repeated requests that are dropped in transit. Generate a distinct key for every unique request and only re-use keys for retries.", "schema": { "type": "string" }, "required": true } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "Pass the access token in the 'Authorization' header with the format \"Bearer ${token}\", i.e. the word \"Bearer\" and your access token from the /o/token/ API, separated by whitespace.\n", "flows": { "password": { "tokenUrl": "/o/token/", "scopes": { "hosted_checkout": "Scope for tokens used by merchant applications which allow Forage to manage split tender processing (i.e. EBT + Credit/Debit).\n", "pinpad_only": "Scope for tokens used by merchant applications which manage their own split tender (i.e. Forage Checkout is used only for EBT processing).\n" } }, "clientCredentials": { "tokenUrl": "/o/token/", "scopes": { "internal": "Scope for tokens used by Forage internal applications.\n", "pin-protected": "Scope for tokens which can access secure storage.\n", "disbursement": "Scope for tokens which can disburse money to merchants.\n" } } } } } } } ``` # Sibling pages * [Retrieve all OrderPayments for an Order](https://docs.joinforage.app/reference/get-all-payments.md) * [Retrieve an OrderPayment](https://docs.joinforage.app/reference/get-an-order-payment.md) * [Update an OrderPayment](https://docs.joinforage.app/reference/patch-update-an-order-payment.md)