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 is optional when creating a PaymentMethod.

When omitted, the resulting PaymentMethod can be used to make purchases across multiple merchants, for example, via a platform that supports many storefronts.

When Merchant-Accountis passed, the created PaymentMethod corresponds to a specific merchant. It can only be used to make purchases at that merchant.

📘

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