A POST request to /payment_methods/ creates a new representation of a customer's payment instrument in Forage's database.
Tokenization vs. Network Validation
Tokenization (this endpoint): Forage validates card format, BIN support, and merchant configuration. The EBT network is NOT contacted during tokenization. Card validity can only be confirmed after attempting a balance check or payment with the processor.
Network validation: Occurs later during balance checks or payments when the EBT network validates the card, PIN, and account status.
| Stage | Who validates | When it happens | Example errors |
|---|---|---|---|
| Tokenization | Forage | POST /payment_methods | invalid PAN, unsupported BIN/state, throttling |
| Processing | EBT network | balance check or payment | card closed, insufficient funds, wrong PIN |
BIN Blocking Scope
Forage blocks known BINs from restricted states (Guam, Virgin Islands) where online EBT is not supported. However, Forage does not block unregistered BINs. An unregistered BIN may pass tokenization but will fail during processing when the EBT network rejects the card.
On success, the API responds with a Forage PaymentMethod object. You need to retrieve and store the ref value for future requests. For example:
- To get the outcome of a balance inquiry, you need to pass the
refas the path param in a request to Retrieve aPaymentMethod. - To Create a
Payment, you need to pass therefas thepayment_methodrequest body param.
When to use the Merchant-Account Header
Merchant-Account HeaderThe Merchant-Account Header requirements vary by payment method type:
- For EBT payment methods: The
Merchant-Accountheader is optional - For HSA/FSA payment methods: The
Merchant-Accountheader is required - For credit/debit payment methods: The
Merchant-Accountheader is required
The Merchant-Account header is required for all payment methods except EBT due to technical requirements for routing and payout processing.
EBT PaymentMethods are tenant-scoped. An EBT PaymentMethod created under one merchant account can be used by other merchant accounts within the same tenant. The Merchant-Account header does not restrict EBT PaymentMethod usability across merchant accounts within the same tenant.
When Merchant-Account is passed, the created PaymentMethod is associated with that specific merchant account for routing and reporting purposes. For EBT payment methods, the PaymentMethod remains usable across all merchant accounts within the same tenant.
SDK Behavior
Forage JS automatically includes the Merchant-Account header from initialization when creating PaymentMethods. There is currently no option to omit this header during PaymentMethod creation.
Use customer_id When Creating PaymentMethods
customer_id When Creating PaymentMethodsPass customer_id in the request to Create a PaymentMethod. customer_id helps Forage's servers more quickly identify and associate the correct customer with the PaymentMethod. While customer_id is not technically a required parameter, if you omit it then the request to create the PaymentMethod could take longer to process. It is strongly recommended to pass customer_id.
Additionally, passing customer_id enables Forage to throttle card additions per customer, helping prevent abuse and fraud.
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 to ensure continuity of stored payment methods.
State Validation
To check which states and BINs Forage supports, use the Retrieve state card details endpoint. This is useful for customers concerned with state waivers or validating card eligibility before tokenization.
See these guides for more information: