The Forage PaymentMethod
object represents a customer's payment instrument.
From a UI perspective, a PaymentMethod
is created when a customer submits their card details to Forage. At the implementation level, the flow varies by integration type:
SDKs
Every SDK includes a method that tokenizes a customer’s EBT Card number and creates a Forage PaymentMethod
:
- ForageJS:
tokenizeCard
- Android:
tokenizeEBTCard
- iOS:
tokenizeEBTCard
SDKs also include a method to perform a balance inquiry on a tokenized EBT Card:
- ForageJS:
checkBalance
- Android:
checkBalance
- iOS:
checkBalance
Custom integrations
- Send a
POST
to/payment_methods/
to create aPaymentMethod
after a customer enters their EBT Card number in the client. For more details on the full Custom integration flow, check out the how it works diagram.
Fully Hosted integrations
- The Fully Hosted Checkout UI automatically creates a
PaymentMethod
under the hood. - To retrieve information about the
PaymentMethod
, save theebt_payment_method
value that Forage returns when the Session is created, so that you can pass it in the path params of a request to retrieve the PaymentMethod. - For more details on the complete Fully Hosted flow, check out the how it works diagram.
PaymentMethod
object
PaymentMethod
object{
"ref": "2aa1583cdb",
"type": "ebt",
"reusable": false,
"card": {
"last_4": "9999",
"created": "2024-02-06T12:59:43.147586-08:00",
"token": "xxx,yyy",
"state": null,
"fingerprint": "470dda97b63f016a962de150cf53ad72a93aaea4c2a59de2541e0994f48e02ef"
},
"balance": null,
"customer_id": "abc123"
}
The
balance
property isnull
when aPaymentMethod
is created. Once a balance inquiry has been executed on thePaymentMethod
, subsequent GET requests for thePaymentMethod
return thebalance
value.
Properties
Property | Type | Description |
---|---|---|
ref | string | A unique reference identifier for the PaymentMethod . The ref is constant for a customer_id if the card is reusable . |
type | string | The type of the customer’s payment instrument. One of: ebt , credit ,debit .⚠️ A PaymentMethod can only have a type value of credit or debit in a Fully Hosted integration. |
reusable | boolean | Whether the PaymentMethod can be reused. If false , then the PaymentMethod can only be used for a single transaction. |
balance | object | Refer to balance object. null until a balance inquiry has been performed. |
card | object | Refer to card object. |
customer_id | string | ⚠️ 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. 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.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 for the same customer, then the customer_id should be the same in both requests. |
balance
object
balance
objectThe
balance
object applies toPaymentMethod
s that represent an EBT Card.If you’re building a Fully Hosted integration that processes
credit
ordebit
payment methods, then thebalance
value isnull
for the associatedPaymentMethod
objects.
Property | Type | Description |
---|---|---|
snap | string | The available SNAP balance on the customer’s EBT Card, represented as a numeric string. |
non_snap | string | The available EBT Cash balance left on the EBT Card, represented as a numeric string. |
updated | ISO 8601 date-time string | A UTC-8 date-time timestamp of when the funds in the account last changed. |
sequence_number | string | A transaction number for this PaymentMethod 's most recent balance check. This value is not returned if the card's balance has never been checked. |
card
object
card
objectcard
fields forebt
payment methods
card
fields forebt
payment methodsProperty | Type | Description |
---|---|---|
last_4 | string | The last four digits of the EBT Card number. |
created | ISO 8601 date-time string | A UTC-8 timestamp that indicates when the EBT PaymentMethod was created, represented as an ISO 8601 date-time string. |
token | string | A token that Forage can use to look up the EBT Card in secure storage. |
state | string | A two-letter abbreviation for the US state that issued the EBT Card (e.g. CA ). |
fingerprint | string | A unique hash based on the card PAN. The fingerprint is constant for a card PAN, no matter the customer_id . Use the fingerprint to track card usage details for fraud prevention. |
The below
card
fields are only relevant to Fully Hosted integrations.
card
fields for credit
or debit
payment methods
card
fields for credit
or debit
payment methodsProperty | Type | Description |
---|---|---|
brand | string | The brand of the card. One of: amex , discover , visa ,mastercard . |
exp_month | number | The month that the card expires, represented as a number between 1 (January) and 12 (December). |
exp_year | number | The year that the card expires, represented as a two-digit number (e.g. 23 ). |
last4 | string | The last four digits of the card number. |
card
fields for credit
or debit
payment methods processed by Stripe
card
fields for credit
or debit
payment methods processed by StripeProperty | Type | Description |
---|---|---|
brand | string | The brand of the card. One of: amex , discover , visa ,mastercard . |
exp_month | number | The month that the card expires, represented as a number between 1 (January) and 12 (December). |
exp_year | number | The year that the card expires, represented as a two-digit number (e.g. 23 ). |
last4 | string | The last four digits of the card number. |
psp_customer_id | string | The Stripe identifier for the customer. |
payment_method_id | string | A unique identifier for a Stripe PaymentMethod that represents a customer's credit/debit payment instrument. |
Examples
Create a PaymentMethod
PaymentMethod
curl --request POST \
--url https://api.sandbox.joinforage.app/api/payment_methods/ \
--header 'API-VERSION: 2023-05-15' \
--header 'Authorization: Bearer <session-token>' \
--header 'Merchant-Account: <merchant-id>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"card": {
"number": "<card-number>"
},
"type": "ebt",
"reusable": true,
"customer_id": "<customer-id>"
}
'
Pass
customer_id
in the request body
customer_id
helps Forage's servers more quickly identify and associate the correct customer with the Session. Whilecustomer_id
is not technically a required parameter, if you omit it then requests to create thePaymentMethod
could take longer to process.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.
Refer to the POST /payment_methods/
docs for complete details.
Retrieve a PaymentMethod
PaymentMethod
curl --request POST \
--url https://api.sandbox.joinforage.app/api/payment_methods/ref/ \
--header 'API-VERSION: 2023-05-15' \
--header 'Authorization: Bearer <session-token>' \
--header 'Merchant-Account: <merchant-id>' \
--header 'accept: application/json' \
Refer to the GET /payment_methods/{ref}
docs for complete details.
Update a PaymentMethod
PaymentMethod
curl --request PATCH \
--url https://api.sandbox.joinforage.app/api/payment_methods/payment_method_ref/ \
--header 'Authorization: Bearer <authentication_token>' \
--header 'Merchant-Account: <merchant-account>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"reusable": true,
"customer_id": "cus_1234567890"
}
'
Refer to the PATCH /payment_methods/{payment_method_ref}/
docs for complete details
PaymentMethods
and Platforms
PaymentMethods
and PlatformsIf you're integrating Forage on behalf of a platform that supports multiple merchants, then note that you can re-use payment method refs
across multiple merchants.