--- updatedAt: 2026-05-07T18:17:26.000Z agentTools: projectIndex: https://docs.joinforage.app/llms.txt --- # Retrieve a PaymentMethod A `GET` request to `/payment_methods/{payment_method_ref}/` retrieves the specified [`PaymentMethod` object](ref:payment-methods#paymentmethod-object). You can use this endpoint to, for example: - Retrieve the `balance` of an EBT Card after a customer completes a [Custom Balance Check Session](ref:create-custom-balance-check-session) - Retrieve information about a reusable payment method to display in a digital wallet # 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/payment_methods/{payment_method_ref}/": { "parameters": [ { "name": "payment_method_ref", "in": "path", "description": "A unique reference hash for the Forage `PaymentMethod`, returned when the [`PaymentMethod` was created](https://docs.joinforage.app/reference/create-payment-method).", "required": true, "schema": { "type": "string" } } ], "get": { "parameters": [ { "$ref": "#/components/parameters/BearerTokenHeader" }, { "$ref": "#/components/parameters/MerchantAccountHeaderPaymentMethod" }, { "$ref": "#/components/parameters/APIVersionHeader" } ], "tags": [ "Payment Methods" ], "summary": "Retrieve a PaymentMethod", "x-readme": { "code-samples": [ { "language": "curl", "code": "curl --request GET \\\n --url https://api.sandbox.joinforage.app/api/payment_methods/ac47392bb1/ \\\n --header 'Authorization: Bearer ' \\\n --header 'Merchant-Account: ' \\\n --header 'accept: application/json'\n" } ] }, "description": "A `GET` request to `/payment_methods/{payment_method_ref}/` retrieves the specified [`PaymentMethod` object](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object).\n\nYou can use this endpoint to, for example:\n- Retrieve the `balance` of an EBT Card after a customer completes a [Custom Balance Check Session](https://docs.joinforage.app/reference/create-custom-balance-check-session)\n- Retrieve information about a reusable payment method to display in a digital wallet\n", "operationId": "Get payment method", "security": [ { "OAuth2": [ "pinpad_only", "hosted_checkout", "internal" ] } ], "responses": { "200": { "$ref": "#/components/responses/PaymentMethod200" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "invalid_input_data": { "summary": "Invalid Input Data", "value": { "path": "/api/payment_methods/{payment_method_ref}/", "errors": [ { "code": "invalid_input_data", "message": "Query parameter missing or incomplete.", "source": { "resource": "Payment_Methods" } } ] } }, "invalid_merchant_account": { "summary": "Invalid Merchant Account", "value": { "path": "/api/payment_methods/{payment_method_ref}/", "errors": [ { "code": "invalid_merchant_account", "message": "Merchant account Merchant ID not valid.", "source": { "resource": "Merchants" } } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "expired_session_token": { "summary": "Expired Session Token", "value": { "path": "/api/payment_methods/{payment_method_ref}/", "errors": [ { "code": "expired_session_token", "message": "This token has expired", "source": { "resource": "Session_Token" } } ] } }, "invalid_token": { "summary": "Invalid Token", "value": { "path": "/api/payment_methods/{payment_method_ref}/", "errors": [ { "code": "invalid_token", "message": "Incorrect authentication credentials.", "source": { "resource": "OAuth_Access_Tokens" } } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "path": "/api/payment_methods/{payment_method_ref}/", "errors": [ { "code": "resource_not_found", "message": "Payment method with id {payment_method_ref} does not exist for Tenant {tenant.name}", "source": { "resource": "Payment_Methods" } } ] } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "too_many_requests": { "summary": "Too Many Requests", "value": { "path": "/api/payment_methods/{payment_method_ref}/", "errors": [ { "code": "too_many_requests", "message": "Request was throttled, please try again later.", "source": { "resource": "Payment_Methods" } } ] } } } } } } } } } }, "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" } } }, "BalanceResponse": { "type": "object", "description": "An object that represents an EBT cardholder's account balance.", "properties": { "id": { "type": "integer", "description": "The unique identifier for the balance record.", "example": 12345 }, "snap": { "type": "string", "format": "currency", "description": "The available SNAP balance in USD on the customer’s EBT Card, represented as a numeric string." }, "non_snap": { "type": "string", "format": "currency", "description": "The available EBT Cash balance in USD on the customer's EBT Card, represented as a numeric string." }, "updated": { "type": "string", "format": "date-time", "description": "A UTC timestamp that indicates when the funds in the account last changed, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string." }, "sequence_number": { "type": "string", "description": "A transaction number for this `PaymentMethod`'s most recent balance check. Returned only for POS Terminal transactions; omitted from online merchant balance checks." } } }, "EBTCardResponse": { "type": "object", "description": "An object that details information about the EBT Card.", "properties": { "last_4": { "type": "string", "description": "The last four digits of the EBT Card number." }, "created": { "type": "string", "format": "date-time", "description": "A UTC timestamp that indicates when the EBT `PaymentMethod` was created, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string." }, "token": { "type": "string", "description": "A token that Forage can use to look up the EBT Card in secure storage." }, "state": { "type": "string", "description": "The two-letter abbreviation for the US state that issued the EBT Card (e.g. `CA`)." }, "fingerprint": { "type": "string", "description": "⚠️ Deprecated. Please use `fingerprint_v2` instead. A unique hash based on the card PAN. The `fingerprint` is constant for a card PAN, no matter the `customer_id`. Use the `fingerprint` to track card usage for fraud prevention.\n" }, "fingerprint_v2": { "type": "string", "description": "A unique hash based on the card PAN. The `fingerprint_v2` is constant for a card PAN, no matter the `customer_id`. Use the `fingerprint_v2` to track card usage for fraud prevention." } } }, "NonEBTCard": { "type": "object", "description": "If a [credit/debit PSP](https://docs.joinforage.app/docs/ebt-online-101#creditdebit-payment-service-provider-psp) other than Stripe processes the payment, then this object details information about the non-EBT Card.", "properties": { "brand": { "type": "string", "description": "The card brand. One of:\n- `amex`\n- `discover`\n- `mastercard`\n- `visa`\n", "enum": [ "amex", "discover", "mastercard", "visa" ], "example": "visa" }, "exp_month": { "type": "number", "description": "The expiration month as listed on the card, without any preceding `0` (e.g. `4` instead of `04`).", "example": 3 }, "exp_year": { "type": "number", "description": "The two-digit expiration year listed on the card (e.g. `21`).", "example": 21 }, "last_4": { "type": "string", "description": "The last four digits of the card number.", "example": "6008" } }, "required": [ "brand", "cvc", "last_4", "exp_month", "exp_year" ] }, "StripeCard": { "allOf": [ { "$ref": "#/components/schemas/NonEBTCard" }, { "type": "object", "description": "If Stripe is the credit/debit [PSP](https://docs.joinforage.app/docs/ebt-online-101#creditdebit-payment-service-provider-psp), then this object details information about the non-EBT Card.", "properties": { "payment_method_id": { "type": "string", "description": "The unique identifier for the Stripe PaymentMethod that represents the customer's payment instrument.", "example": "pm_123456789012345" }, "psp_customer_id": { "type": "string", "description": "The unique Stripe identifier for the cardholder.", "example": "cus_123456789012345" }, "is_hsa_fsa": { "type": "boolean", "description": "Indicates whether the card is an HSA/FSA card." }, "bin": { "type": "string", "description": "The BIN portion of the card number.", "example": "400005" }, "issuer": { "type": "string", "description": "The name of the card issuer.", "example": "Lewis & Clark Bank" }, "address_postal_code_check": { "type": "string", "description": "The result of any check done on the delivery address zip code. One of:\n- `pass`: The provided information is correct and matches the data on file with the card issuer.\n- `fail`: The provided information is incorrect and does not match the data on file.\n- `unavailable`: The card issuer will not perform the check.\n- `unchecked`: The information was provided but has not yet been checked by the card issuer.\n", "enum": [ "pass", "fail", "unavailable", "unchecked" ], "example": "pass" }, "cvc_check": { "type": "string", "description": "The result of any check done on the CVC. One of:\n- `pass`: The provided information is correct and matches the data on file with the card issuer.\n- `fail`: The provided information is incorrect and does not match the data on file.\n- `unavailable`: The card issuer will not perform the check.\n- `unchecked`: The information was provided but has not yet been checked by the card issuer.\n", "enum": [ "pass", "fail", "unavailable", "unchecked" ], "example": "pass" } }, "required": [ "payment_method_id", "psp_customer_id" ] } ] }, "TokenizedPaymentMethod": { "description": "This object represents a customer's payment instrument. It has been tokenized by the server. It does not include all details about the payment method.\n\nIf the `PaymentMethod` has a type of `ebt`, then the `balance` field will be `null` until the `/api/payment_methods/{ref}/` endpoint is called. The `balance` field will always be `null` for non-EBT payment methods.\n", "allOf": [ { "type": "object", "properties": { "ref": { "type": "string", "description": "A unique reference identifier for the `PaymentMethod`. The `ref` is constant for a `customer_id` if the card is `reusable`." }, "type": { "type": "string", "description": "The card type. One of:\n\n- `credit`\n- `debit`\n- `prepaid`\n- `ebt`\n\n⚠️ The `type` value can only be `credit`, `debit`, or `prepaid` in a [Fully Hosted](https://docs.joinforage.app/docs/fully-hosted) or [HSA/FSA](https://docs.joinforage.app/docs/enable-hsa-fsa-payments) integration.\n" }, "reusable": { "type": "boolean", "description": "Whether the `PaymentMethod` can be reused. If `false`, then the `PaymentMethod` can only be used for a single transaction." }, "card": { "oneOf": [ { "$ref": "#/components/schemas/EBTCardResponse" }, { "$ref": "#/components/schemas/NonEBTCard" }, { "$ref": "#/components/schemas/StripeCard" } ] }, "balance": { "$ref": "#/components/schemas/BalanceResponse" }, "customer_id": { "$ref": "#/components/schemas/CustomerIDField" } } } ], "example": { "ref": "ac47392bb1", "type": "ebt", "reusable": true, "card": { "last_4": "3456", "created": "2021-06-16T00:11:50.000000Z-07:00", "token": "tok_sandbox_12345678901234567890", "state": "CA", "fingerprint": "470dda97b63f016a962de150cf53ad72a93aaea4c2a59de2541e0994f48e02ef", "fingerprint_v2": "a2f1b4e6c7d9380b59fa7c2e98ad0e316be9fcde1e2a4c3d56b17c6e0198a2fb" }, "balance": "100.00", "customer_id": "cus_1234567890" } }, "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" } }, "responses": { "PaymentMethod200": { "description": "__OK__ - Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenizedPaymentMethod" } } } } }, "parameters": { "BearerTokenHeader": { "name": "Authorization", "in": "header", "description": "An OAuth 2.0 bearer token that validates the request. You can use either a short-lived [session token](https://docs.joinforage.app/docs/authentication#session-tokens) if the request is coming from the front-end, or an [authentication token](https://docs.joinforage.app/docs/authentication#authentication-tokens) for server-side requests. Pass the token in this header after the word `Bearer` and a whitespace, for example `Bearer `.", "schema": { "type": "string" }, "required": true }, "MerchantAccountHeaderPaymentMethod": { "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.\n\nPass a `Merchant-Account` header to create a `PaymentMethod` associated with a specific merchant account for routing and reporting purposes. **This header does not restrict `PaymentMethod`s to a single merchant account. `PaymentMethod`s are tenant-scoped and can be used across all merchant accounts within the same tenant.**\n", "schema": { "type": "string" }, "required": true }, "APIVersionHeader": { "name": "API-Version", "in": "header", "description": "The [Forage version](https://docs.joinforage.app/reference/version-history), represented as a string with the format of a `YYYY-MM-DD` date.\n\nIf not specified in the request header, then the version defaults to the value set in the Forage dashboard.\n", "schema": { "type": "string" }, "required": false } }, "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 * [Create a PaymentMethod](https://docs.joinforage.app/reference/create-payment-method.md) * [Update a PaymentMethod](https://docs.joinforage.app/reference/update-payment-method.md) * [Delete a PaymentMethod](https://docs.joinforage.app/reference/delete-payment-method.md)