Payment Methods

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:
  • Custom integrations need to send a POST to /payment_methods/ to create a PaymentMethod after a customer enters their EBT Card number in the client
  • The Fully Hosted Checkout UI automatically creates a PaymentMethod

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 is null when a PaymentMethod is created. Once a balance inquiry has been executed on the PaymentMethod, subsequent GET requests for the PaymentMethod return the balance value.

Properties

PropertyTypeDescription
refstringA unique reference hash for the payment method.
typestringThe type of the customer’s payment instrument. One of: ebt, credit,debit.

:warning: A PaymentMethod can only have a type value of credit or debit in a Fully Hosted integration.
balanceobjectRefer to balance object. null until a balance inquiry has been performed.
cardobjectRefer to card object.
customer_idstringA unique merchant-generated ID for the end customer making the payment.

balance object

✅

The balance object applies to PaymentMethods that represent an EBT Card.

If you’re building a Fully Hosted integration that processes credit or debit payment methods, then the balance value is null for the associated PaymentMethod objects.

PropertyTypeDescription
snapstringThe available SNAP balance on the customer’s EBT Card, represented as a numeric string.
non_snapstringThe available EBT Cash balance left on the EBT Card, represented as a numeric string.
updatedISO 8601 date-time stringThe date-time when the funds in the account last changed.

card object

card fields forebt payment methods

PropertyTypeDescription
last4stringThe last four digits of the EBT Card number.
createdISO 8601 date-time stringThe date-time when the card object was created.
tokenstringA tokenized form of the card number which allows Forage to securely look up the EBT Card.
statestringA 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

PropertyTypeDescription
brandstringThe brand of the card. One of: amex, discover, visa,mastercard.
exp_monthnumberThe month that the card expires, represented as a number between 1 (January) and 12 (December).
exp_yearnumberThe year that the card expires, represented as a two-digit number (e.g. 23).
last4stringThe last four digits of the card number.

card fields for credit or debit payment methods processed by Stripe

PropertyTypeDescription
brandstringThe brand of the card. One of: amex, discover, visa,mastercard.
exp_monthnumberThe month that the card expires, represented as a number between 1 (January) and 12 (December).
exp_yearnumberThe year that the card expires, represented as a two-digit number (e.g. 23).
last4stringThe last four digits of the card number.
psp_customer_idstringThe Stripe customer identifier for orders, expecting balance to be paid using credit/debit card.
payment_method_idstringA unique identifier for a Stripe PaymentMethod that represents a customer's credit/debit payment instrument.

Examples

Create a 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

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

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.