Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Payment Methods

Retrieve a PaymentMethod

A GET request to /payment_methods/{payment_method_ref}/ retrieves the specified 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
  • Retrieve information about a reusable payment method to display in a digital wallet
get/api/payment_methods/{payment_method_ref}/

Headers

Authorizationstring required

An OAuth 2.0 bearer token that validates the request. You can use either a short-lived session token if the request is coming from the front-end, or an authentication token for server-side requests. Pass the token in this header after the word Bearer and a whitespace, for example Bearer <api_key>.

Merchant-Accountstring required

A unique merchant ID that Forage provides during onboarding, as in 123ab45c67. The Merchant ID can be found in the Forage sandbox or production dashboard.

Pass a Merchant-Account header to create a PaymentMethod associated with a specific merchant account for routing and reporting purposes. This header does not restrict PaymentMethods to a single merchant account. PaymentMethods are tenant-scoped and can be used across all merchant accounts within the same tenant.

API-Versionstring

The Forage version, represented as a string with the format of a YYYY-MM-DD date.

If not specified in the request header, then the version defaults to the value set in the Forage dashboard.

Response

OK - Success

refstring

A unique reference identifier for the PaymentMethod. The ref is constant for a customer_id if the card is reusable.

typestring

The card type. One of:

  • credit
  • debit
  • prepaid
  • ebt

⚠️ The type value can only be credit, debit, or prepaid in a Fully Hosted or HSA/FSA integration.

reusableboolean

Whether the PaymentMethod can be reused. If false, then the PaymentMethod can only be used for a single transaction.

customer_idstring

⚠️ If you’re integrating Forage with a POS Terminal, then do not use this param. It is only supported for online transactions.

A unique identifier for the end customer making the payment.

Forage automatically adds the customer_id to the Session's corresponding Order and OrderPayments.

This 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.

If you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload.

Each 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.

Example response

{
  "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"
}