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:

• ForageJS: tokenizeCard
• Android: tokenizeEBTCard
• iOS: tokenizeEBTCard

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

✅

The balance property is null when a PaymentMethod is created. Once a balance inquiry has been executed on the PaymentMethod, subsequent GET requests for the PaymentMethod return the balance value.

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. A PaymentMethod can only have a type value of credit or debit 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

✅

The balance object applies to PaymentMethods that represent an EBT Card.

If you’re building a Fully Hosted integration that processes credit or debit payment methods, then the balance value is null for the associated PaymentMethod objects.

card object

card fields forebt payment methods

📘

The below card fields are only relevant to Fully Hosted integrations.

card fields for credit or debit payment methods

card fields for credit or debit payment methods processed by Stripe

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

✅

Pass customer_id in the request body

customer_id helps Forage's servers more quickly identify and associate the correct customer with the Session. While customer_id is not technically a required parameter, if you omit it then requests to create the PaymentMethod could take longer to process.

Each customer should only have one unique customer_id. For example, if you create both a PaymentMethod and a Payment for the same customer, then the customer_id should be the same in both requests.

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.