Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Payment Methods

Update a PaymentMethod

A PATCH request to /payment_methods/{payment_method_ref}/ modifies information about an existing PaymentMethod. You can add a customer_id if it was not set when the PaymentMethod was created, or update whether the card is reusable.

Returns a PaymentMethod object if the operation is successful.

patch/api/payment_methods/{payment_method_ref}/

Headers

Authorizationstring required

An OAuth 2.0 authentication token that validates the request. Send a POST to the /o/token/ endpoint to generate an authentication token. Pass the token in this header after the word Bearer and a whitespace, for example Bearer <api_key>.

Merchant-Accountstring required

A unique merchant ID that Forage provides during onboarding, as in 123ab45c67. The Merchant ID can be found in the Forage sandbox or production dashboard.

Pass a Merchant-Account header to create a PaymentMethod associated with a specific merchant account for routing and reporting purposes. This header does not restrict PaymentMethods to a single merchant account. PaymentMethods are tenant-scoped and can be used across all merchant accounts within the same tenant.

Request body

reusableboolean

Whether the PaymentMethod can be reused. If false, then the PaymentMethod can only be used for a single transaction.

customer_idstring

A unique ID for the end customer associated with the payment method. customer_id can only be set once and can't be changed, so this param only applies if the PaymentMethod doesn't yet include a customer_id. If you try to update the customer_id field after it has already been set, then the API throws an error.

You must build with Forage Version 2023-05-15 or later to use customer_id. Either pass 2023-05-15 as the API-Version header on a per request basis, or set the version for all requests in the Forage dashboard.

Response

OK - Success

refstring

A unique reference identifier for the PaymentMethod. The ref is constant for a customer_id if the card is reusable.

typestring

The card type. One of:

  • credit
  • debit
  • prepaid
  • ebt

⚠️ The type value can only be credit, debit, or prepaid in a Fully Hosted or HSA/FSA integration.

reusableboolean

Whether the PaymentMethod can be reused. If false, then the PaymentMethod can only be used for a single transaction.

customer_idstring

⚠️ If you’re integrating Forage with a POS Terminal, then do not use this param. It is only supported for online transactions.

A unique identifier for the end customer making the payment.

Forage automatically adds the customer_id to the Session's corresponding Order and OrderPayments.

This field helps Forage's servers more quickly identify the customer associated with the request. While customer_id is not technically required, if you omit it then requests could take longer to process. It is strongly recommended to pass customer_id.

If you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload.

Each customer should only have one unique customer_id. For example, if you create both a PaymentMethod and a Forage Session (Fully Hosted or Custom) or Payment (SDK) for the same customer, then the customer_id should be the same in both requests to ensure continuity of stored payment methods.

Example response

{
  "ref": "ac47392bb1",
  "type": "ebt",
  "reusable": true,
  "card": {
    "last_4": "3456",
    "created": "2021-06-16T00:11:50.000000Z-07:00",
    "token": "tok_sandbox_12345678901234567890",
    "state": "CA",
    "fingerprint": "470dda97b63f016a962de150cf53ad72a93aaea4c2a59de2541e0994f48e02ef",
    "fingerprint_v2": "a2f1b4e6c7d9380b59fa7c2e98ad0e316be9fcde1e2a4c3d56b17c6e0198a2fb"
  },
  "balance": "100.00",
  "customer_id": "cus_1234567890"
}