Log In

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 required for merchants creating a PaymentMethod.

Platforms can opt to omit Merchant-Account to create a PaymentMethod that can be used across all the merchants on the platform.

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.