From a UI perspective, a PaymentMethod is created when a customer submits their card details to Forage. At the implementation level, the flow varies by integration type:

SDKs

Every SDK includes a method that tokenizes a customer's EBT Card number and creates a Forage PaymentMethod:

SDKs also include a method to perform a balance inquiry on a tokenized EBT Card:

ForageJS: checkBalance
Android: checkBalance
iOS: checkBalance

Custom integrations

Send a POST to /payment_methods/ to create a PaymentMethod after a customer enters their EBT Card number in the client. For more details on the full Custom integration flow, check out the how it works diagram.

Fully Hosted integrations

The Fully Hosted Checkout UI automatically creates a PaymentMethod under the hood.
To retrieve information about the PaymentMethod, save the ebt_payment_method value that Forage returns when the Session is created, so that you can pass it in the path params of a request to retrieve the PaymentMethod.
For more details on the complete Fully Hosted flow, check out the how it works diagram.

`PaymentMethod` object

{
  "ref": "2aa1583cdb",
  "type": "ebt",
  "reusable": false,
  "card": {
    "last_4": "9999",
    "created": "2024-02-06T12:59:43.147586-08:00",
    "token": "xxx,yyy",
    "state": null,
    "fingerprint": "470dda97b63f016a962de150cf53ad72a93aaea4c2a59de2541e0994f48e02ef"
  },
  "balance": null,
  "customer_id": "abc123"
}

📘
When balance Becomes Available
The balance field is null when a PaymentMethod is first created. After a balance inquiry, future GET requests will return the balance.

Properties

Property	Type	Description
`ref`	string	A unique reference identifier for the `PaymentMethod`. The `ref` is constant for a `customer_id` if the card is `reusable`.
`type`	string	The type of the customer's payment instrument. One of: `ebt`, `credit`, `debit`, `prepaid`. ⚠️ A `PaymentMethod` can only have a `type` value of `credit`, `debit`, or `prepaid` in a Fully Hosted integration.
`reusable`	boolean	Whether the `PaymentMethod` can be reused. If `false`, then the `PaymentMethod` can only be used for a single transaction.
`balance`	object	Refer to `balance` object. `null` until a balance inquiry has been performed.
`card`	object	Refer to `card` object.
`customer_id`	string	⚠️ 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. 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. 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 for the same customer, then the `customer_id` should be the same in both requests.

`balance` object

Property	Type	Description
`snap`	string	The available SNAP balance on the customer's EBT Card, represented as a numeric string.
`non_snap`	string	The available EBT Cash balance left on the EBT Card, represented as a numeric string.
`updated`	ISO 8601 date-time string	A UTC-8 date-time timestamp of when the funds in the account last changed.
`sequence_number`	string	A transaction number for this `PaymentMethod`'s most recent balance check. This value is not returned if the card's balance has never been checked.

`card` object

`card` fields for`ebt` payment methods

Property	Type	Description
`last_4`	string	The last four digits of the EBT Card number.
`created`	ISO 8601 date-time string	A UTC-8 timestamp that indicates when the EBT `PaymentMethod` was created, represented as an ISO 8601 date-time string.
`token`	string	A token that Forage can use to look up the EBT Card in secure storage.
`state`	string	A two-letter abbreviation for the US state that issued the EBT Card (e.g. `CA`). This field can be `null` if the card's BIN is unregistered or cannot be mapped to a specific state.
`fingerprint`	string	Deprecated. 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`. Note: `fingerprint` and `fingerprint_v2` use different hashing algorithms, so the same card will have different values for each field.
`fingerprint_v2`	string	A unique hash based on the card PAN. The `fingerprint_v2` is constant for a card PAN, no matter the `customer_id`. Use `fingerprint_v2` to track card usage for fraud prevention. This is the current field to use; `fingerprint` is deprecated. Cards with the same last 4 digits may have different `fingerprint_v2` values if they have different full PANs.

📘
card Fields For Fully Hosted
The following card fields apply only to Fully Hosted integrations.

`card` fields for `credit`, `debit`, or `prepaid` payment methods

Property	Type	Description
`brand`	string	The brand of the card. One of: `amex`, `discover`, `visa`,`mastercard`.
`exp_month`	number	The month that the card expires, represented as a number between `1` (January) and `12` (December).
`exp_year`	number	The year that the card expires, represented as a two-digit number (e.g. `23`).
`last4`	string	The last four digits of the card number.

`card` fields for `credit`, `debit`, or `prepaid` payment methods processed by Stripe

Property	Type	Description
`brand`	string	The brand of the card. One of: `amex`, `discover`, `visa`,`mastercard`.
`exp_month`	number	The month that the card expires, represented as a number between `1` (January) and `12` (December).
`exp_year`	number	The year that the card expires, represented as a two-digit number (e.g. `23`).
`last4`	string	The last four digits of the card number.
`psp_customer_id`	string	The Stripe identifier for the customer.
`payment_method_id`	string	A unique identifier for a Stripe PaymentMethod that represents a customer's credit, debit, or prepaid payment instrument.

Examples

Create a `PaymentMethod`

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/payment_methods/ \
     --header 'API-VERSION: 2023-05-15' \
     --header 'Authorization: Bearer <session-token>' \
     --header 'Merchant-Account: <merchant-id>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "card": {
    "number": "<card-number>"
  },
  "type": "ebt",
  "reusable": true,
  "customer_id": "<customer-id>"
}
'

📘
Use Consistent customer_id
Pass customer_id to help Forage associate the Session with the correct customer. It's not required, but omitting it may slow down requests.
Use the same customer_id across all related resources for the same customer.
Refer to the POST /payment_methods/ docs for complete details.

Retrieve a `PaymentMethod`

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/payment_methods/ref/ \
     --header 'API-VERSION: 2023-05-15' \
     --header 'Authorization: Bearer <session-token>' \
     --header 'Merchant-Account: <merchant-id>' \
     --header 'accept: application/json' \

Refer to the GET /payment_methods/\{ref\} docs for complete details.

Update a `PaymentMethod`

curl --request PATCH \
     --url https://api.sandbox.joinforage.app/api/payment_methods/payment_method_ref/ \
     --header 'Authorization: Bearer <authentication_token>' \
     --header 'Merchant-Account: <merchant-account>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "reusable": true,
  "customer_id": "cus_1234567890"
}
'

Refer to the PATCH /payment_methods/{payment_method_ref}/ docs for complete details

`PaymentMethods` and Platforms

If you're integrating Forage on behalf of a platform that supports multiple merchants, then note that you can re-use payment method refs across multiple merchants.