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

📘

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

balance object

card object

card fields forebt payment methods

📘

card Fields For Fully Hosted

The following card fields apply only 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>"
}
'

📘

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.