This endpoint is most relevant to Custom integrations.
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 aPaymentMethod
. - To Create a
Payment
, you need to pass theref
as thepayment_method
request body param.
When to use the Merchant-Account
Header
Merchant-Account
HeaderThe 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 aPaymentMethod
customer_id
helps Forage's servers more quickly identify and associate the correct customer with thePaymentMethod
. Whilecustomer_id
is not technically a required parameter, if you omit it then the request to create thePaymentMethod
could take longer to process. It is strongly recommended to passcustomer_id
.Each customer should only have one unique
customer_id
. For example, if you create both aPaymentMethod
and aPayment
for the same customer, then thecustomer_id
should be the same in both requests.
Guides