Payments

✅
Payment objects are only relevant to SDK integrations.
If you’re building with the Fully Hosted or Custom Forage Checkout UI, then use the Order and OrderPayment objects.

With the Forage Payments API, you can:

Create a Payment: POST /payments/
Retrieve a Payment: GET /payments/{payment_ref}/
Update a Payment: POST /payments/{payment_ref}/
Cancel a Payment: POST /payments/{payment_ref}/cancel/
Retrieve all Payments for a given merchant identifier: GET /payments/

You need a ref to a Payment object to complete a transaction. All front-end SDK methods that authorize a payment require the ref as a parameter, for example:

Forage JS: captureEbtPinPayment()
Android: capturePayment()
iOS: capturePayment()

`Payment` object

{
    "ref": "0ddbcda871",
    "merchant": "2222222",
    "funding_type": "ebt_snap",
    "amount": "20.00",
    "description": "An EBT payment",
    "metadata": {
        "psp_customer_id": "cus_1234567890"
    },
    "payment_method": "8ef9edff51",
    "delivery_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "1856 Market St.",
        "line2": null,
        "state": "CA",
        "zipcode": "94106"
    },
    "is_delivery": false,
    "created": "2023-09-18T11:38:29.279185-07:00",
    "updated": "2023-09-18T11:38:29.279209-07:00",
    "status": "requires_confirmation",
    "last_processing_error": null,
    "success_date": null,
    "receipt": null,
    "refunds": [], 
  	"expires_at": "2023-09-18T12:08:29.279209-07:00"
}

✅
When a Payment is initially created, the status value is always requires_confirmation, and the receipt value is always null.

🚧
If a Payment is not captured or canceled within 30 minutes of when it is created, then the Payment expires. Inspect the expires_at field to find a timestamp of the expiration.

Properties

Property	Type	Description
`ref`	string	A unique reference hash for the Forage `Payment` object. You need to pass this value to the front-end SDK method that captures the payment.
`merchant`	string	A string that represents either the merchant’s FNS number, or a unique merchant ID that Forage provides during onboarding.
`funding_type`	string	A string that represents the type of tender. One of: - `ebt_snap` - `ebt_cash` - `credit_tpp` - `benefit`
`amount`	string	A positive decimal number representing how much to charge the `PaymentMethod` in USD. Precision to the penny is supported. The minimum amount that can be charged is `0.01`. To differentiate between a SNAP and an EBT Cash charge on the same EBT card, use the `funding_type` field. If you need to charge both funding types, then create a `Payment` for each charge.
`description`	string	A string that describes the `Payment`.
`metadata`	object	A set of optional, merchant-defined key-value pairs that can be added to an object. For example, some merchants attach their credit card processor’s ID for the customer making the payment. If there’s no additional information that you’d like to add, then pass an empty object as the value.
`payment_method`	string	The unique reference hash for the existing Forage `PaymentMethod` that is to be charged in this transaction.
`delivery_address`	object	The address for delivery or pickup of the order. Per FNS regulations, this value must always be provided. If the order is for pickup, then use the merchant address. Refer to delivery address for details.
`is_delivery`	boolean	Whether the order is for delivery or pickup. This information is required per FNS regulations. Defaults to `false` if not provided.
`created`	ISO 8601 date-time string	A timestamp of when the `Payment` was created.
`updated`	ISO 8601 date-time string	A timestamp of when the `Payment` was last updated.
`status`	string	The status of the `Payment`. One of: - `canceled`: The `Payment` object can't be used. - `failed`: If the error is temporary, then this `Payment` can be resubmitted for capture without modification. Check the `receipt.message` field for a description of the error. - `processing`: The outcome of the `Payment` is pending. - `requires_confirmation`: The `Payment` hasn't been submitted for processing. - `succeeded`: The `Payment` has been successfully processed and will be included in settlement. It can't be changed.
`last_processing_error`	object	The `code` and `message` values corresponding to the most recent Payments API error.
`success_date`	ISO 8601 date-time string	A timestamp of when the `status` of the payment is `succeeded`.
`receipt`	object	The information that you're required to display to the customer after the `Payment` status is `succeeded`, according to FNS regulations. This field is `null` if `receipt` data is not yet available for the `Payment`. Refer to `receipt` for details.
`refunds`	array	An array of the unique reference hashes for any `PaymentRefunds` associated with this `Payment`.
`expires_at`	ISO 8601 date-time string	A timestamp of when the `Payment` will expire if it is not captured or canceled, set to 30 minutes from when the `Payment` is created.

`delivery_address`

Property	Type	Description
`city`	string	The name of the city.
`country`	string	The constant string `US`.
`line1`	string	The first line of the street address.
`line2`	string	The second line of the street address.
`state`	string	A two-letter abbreviation for the US state.
`zipcode`	string	A zip or postal code.

`receipt`

🚧
The receipt value is null when the Payment is first created and until receipt data is available. Pass the ref returned in the response to create the Payment in periodic GET requests to /payments/{payment_ref}/ until the status of the Payment is succeeded. At that point, the receipt data, including the balance, is up-to-date.

Property	Type	Description
`ref_number`	string	The unique reference hash of the Forage `Payment`.
`is_voided`	boolean	Whether the `Payment` has been voided. If `false`, then the `Payment` amount has been charged as expected. In the rare case of `true`, the charge has been refunded.
`snap_amount`	string	The USD amount charged/refunded to the SNAP balance of the EBT Card, represented as a numeric string.
`ebt_cash_amount`	string	The USD amount charged/refunded to the EBT Cash balance of the EBT Card, represented as a numeric string.
`other_amount`	string	The USD amount charged/refunded to any payment method that is not an EBT Card, represented as a numeric string.
`sales_tax_applied`	string	The USD amount of taxes charged to the customer’s non-EBT payment instrument, represented as a numeric string.
`balance`	object	Refer to balance for details.
`last_4`	string	The last four digits of the EBT Card number.
`message`	string	A message from the EBT payment network that must be displayed to the customer.
`transaction_type`	string	A constant string that is used to identify the transaction associated with the receipt. Always `Payment` in the case of payments.
`created`	ISO 8601 date-time string	A timestamp of when the `Payment` was created.

`balance`

Property	Type	Description
`snap`	string	The available SNAP balance in USD on the customer’s EBT Card, represented as a numeric string.
`non_snap`	string	The available EBT Cash balance in USD on the EBT Card, represented as a numeric string.
`updated`	ISO 8601 date-time string	A timestamp of when the funds in the account last changed.

Examples

Create a `Payment`

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/payments/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Idempotency-Key: 123e4567e8' \
     --header 'Merchant-Account: 9000055' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "line2": "Unit 3",
    "zipcode": "94106",
    "state": "CA"
  },
  "is_delivery": false,
  "amount": 20.00,
  "funding_typel": "ebt_snap",
  "description": "An EBT payment"
  "metadata": {}, 
  "payment_method": "<payment-method-ref>"
}
'

📘
POST /payments/ documentation

Retrieve a `Payment`

curl --request GET \
     --url https://api.sandbox.joinforage.app/api/payments/{payment_ref}/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Merchant-Account: 9000055' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

📘
GET /payments/{payment_ref}/ documentation

Update a `Payment`

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/payments/{payment_ref}/ \
     --header 'Authorization: Bearer <authentication-token>' \
		 --header 'Idempotency-Key: 123e4567e8' \
     --header 'Merchant-Account: 9000055' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'\
     --data '
{
  "is_delivery": true,
}
'

📘
POST /payments/{payment_ref}/ documentation

Cancel a `Payment`

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/payments/{payment_ref}/cancel/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Merchant-Account: 9000055' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

📘
POST /payments/{payment_ref}/cancel/ documentation

Retrieve all `Payment`s for a given merchant identifier

curl --request GET \
     --url https://api.sandbox.joinforage.app/api/payments/?external_order_id={external_order_id}} \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Merchant-Account: 9000055' \
     --header 'accept: application/json' \

📘
GET /payments/?external_order_id=<external-order-id>/ documentation

Payment object

Properties

delivery_address

receipt

balance

Examples

Create a Payment

Retrieve a Payment

Update a Payment

Cancel a Payment

Retrieve all Payments for a given merchant identifier

`Payment` object

`delivery_address`

`receipt`

`balance`

Create a `Payment`

Retrieve a `Payment`

Update a `Payment`

Cancel a `Payment`

Retrieve all `Payment`s for a given merchant identifier