Create a PaymentMethod

A POST request to /payment_methods/ creates a new representation of a customer’s payment instrument in Forage’s database.

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 ref as the path param in a request to Retrieve a PaymentMethod.
• To Create a Payment, you need to pass the ref as the payment_method request body param.

When to use the Merchant-Account Header

The Merchant-Account Header requirements vary by payment method type:

• For EBT payment methods: The Merchant-Account header is optional
• For HSA/FSA payment methods: The Merchant-Account header is required
• For credit/debit payment methods: The Merchant-Account header 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

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

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.

See these guides for more information:

• How Custom integrations work
• Custom Quickstart