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:
- Every SDK includes a method that tokenizes a customer’s EBT Card number and creates a Forage
PaymentMethod
:- ForageJS:
tokenizeEBTCardNumber
- Android:
tokenizeEBTCard
- iOS:
tokenizeEBTCard
- ForageJS:
- Custom integrations need to send a
POST
to/payment_methods/
to create aPaymentMethod
after a customer enters their EBT Card number in the client - The Fully Hosted Checkout UI automatically creates a
PaymentMethod
PaymentMethod
object
PaymentMethod
object{
"ref": "fde3b91329",
"type": "ebt",
"balance": null,
"card": {
"last_4": "5455",
"created": "2023-07-10T17:21:23.346019-07:00",
"token": "tok_sandbox_xfy3yzShLFyagv477GKpm1,",
"state": "CA"
},
"customer_id": "5b53e4786e73d3da67d04f1bfe5269f72684085a23034f6b55e6887dcdb76417"
}
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 hash for the payment method. |
type | string | The type of the customer’s payment instrument. One of: ebt , credit ,debit .![]() PaymentMethod can only have a type value of credit or debit in a Fully Hosted integration. |
balance | object | Refer to balance object. null until a balance inquiry has been performed. |
card | object | Refer to card object. |
customer_id | string | A unique merchant-generated ID for the end customer making the payment. |
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 | The date-time when the funds in the account last changed. |
card
object
card
objectcard
fields forebt
payment methods
card
fields forebt
payment methodsProperty | Type | Description |
---|---|---|
last4 | string | The last four digits of the EBT Card number. |
created | ISO 8601 date-time string | The date-time when the card object was created. |
token | string | A tokenized form of the card number which allows Forage to securely look up the EBT Card. |
state | string | A two-letter abbreviation for a US state. |
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 customer identifier for orders, expecting balance to be paid using credit/debit card. |
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>"
}
'
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 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' \
--header 'content-type: application/json' \
--data '
{
"reusable": false,
"customer_id": "<customer-id>"
}
'
Refer to the POST /payment_methods/{ref}/
docs for complete details.