Create a Custom Checkout Payment Flow

This endpoint is only accessible to "PIN Collection Only" integrations. If you are using a Fully Hosted Checkout then see the POST /api/sessions/ endpoint.

Use this endpoint to start a session on Forage's secure frontend to complete the capture of an EBT Payment object you have already POST-ed. The Payment must have a payment_method of type ebt, otherwise you will receive a 400 error. In other words, you cannot capture non-EBT payments through this endpoint.

The total amount to be paid must be broken down into 2 amounts when you create the session,

  1. snap_total - The amount which is SNAP-eligible (e.g. cost of produce in the basket).
  2. ebt_cash_total - The amount which is eligible for EBT cash, but not SNAP-eligible (e.g. cost of paper products).

The remaining_total field should always be 0.0, and you will receive a 400 response if that is not the case. Similarly, the product_list field must always be omitted or set to an empty array or you will receive a 400 response. Because your application handles credit card processing, it is also responsible for collecting the appropriate taxes.

Note that this endpoint will create an Order object on Forage's backend for you. The ref field in the response is a reference to the Order object that was created, and you should be sure to store that in your own record of the transaction.

When your customer is redirected to the redirect_url in the response from this endpoint, they will be presented with a secure PIN-pad.

If their PIN entry is successful, the customer will be redirected to the success_redirect_url you specify in your request. If the customer clicks the cancel button on Forage Checkout, they will be redirected to the cancel_redirect_url you specify in your request.

To view the status of the order after the customer is redirected to success_redirect_url, use the GET /api/orders/{ref}/ endpoint, and check the status field. If the order status is failed, you should iterate over the payments array and call GET /api/orders/{order_ref}/payments/{payment_ref}/ to see the success/failure status of the individual payments.

Click Try It! to start a request and see the response here!