Create a Custom Payment Capture Session

A POST request to /capture_sessions/ initiates a Session of the Forage Custom Payment Capture UI.

The response payload represents the Custom Payment Capture Session. The ref and redirect_url fields are the most important:

• ref represents the Order
  • Store this ref so that you can pass it in a future request to Create an Order Payment, or to check the status of the Order via a GET to /orders/{order_ref}/
• redirect_url is the URL that launches the front-end, customer-facing Forage UI
  • Point customers to this URL to enter their PIN to complete checkout

If PIN entry is successful, then Forage points the customer to the success_redirect_url specified in the request body. Forage directs the customer to the cancel_redirect_url if they cancel the balance inquiry from the Forage UI.

To check the status of an Order after the customer completes the Forage UI, send a GET to /orders/{order_ref}/.

📘

Use customer_id For Better Performance

Pass customer_id in the request to Create a Capture Session.

Forage automatically adds the customer_id to the Session's corresponding Order and OrderPayments.

customer_id helps Forage's servers more quickly identify and associate the correct customer with the Session. While customer_id is not technically a required parameter, if you omit it then the request to create the Session could take longer to process. It is strongly recommended to pass customer_id.

When the same customer_id is provided for a returning customer, Forage will retrieve and reuse their stored payment method, if available. Alternatively, passing the same ebt_payment_method can also pre-fill the stored payment method in the checkout session.

Each customer should only have one unique customer_id. For example, if you create both a Capture Session and a PaymentMethod for the same customer, then the customer_id should be the same in both requests to ensure continuity of stored payment methods.