A Payment
object represents a one-time charge to an existing PaymentMethod
.
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
andOrderPayment
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:
Payment
object
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, thestatus
value is alwaysrequires_confirmation
, and thereceipt
value is alwaysnull
.
If a
Payment
is not captured or canceled within 30 minutes of when it is created, then thePayment
expires. Inspect theexpires_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
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
receipt
The
receipt
value is null when thePayment
is first created and until receipt data is available. Pass theref
returned in the response to create thePayment
in periodic GET requests to/payments/{payment_ref}/
until thestatus
of thePayment
issucceeded
. 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
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
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>"
}
'
Retrieve a Payment
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'
Update a Payment
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,
}
'
Cancel a Payment
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'
Retrieve all Payment
s for a given merchant identifier
Payment
s for a given merchant identifiercurl --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