Forage Payments API

https://docs.joinforage.app/reference
Admin
Forage Payments API is a PCI Level 1 compliant REST API that enables merchants to securely accept...
Tokens:68,031
Snippets:368
Trust Score:5.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start Forage Custom Payment Capture Session

Source: https://docs.joinforage.app/reference

Use this endpoint to start a Forage Custom payment capture session.

```bash
POST /capture_sessions/
```

--------------------------------

### Access Created Data via GET Request

Source: https://docs.joinforage.app/reference

Data created via API or Forage Checkout is accessible through GET requests to the matching resource.

```bash
GET /orders/{ref}/
```

--------------------------------

### API Error Response Examples

Source: https://docs.joinforage.app/reference/cancel-an-order-payment

Examples of different error responses that can be returned by the API.

```APIDOC
## API Error Responses

This section details common error responses encountered when interacting with the API.

### 400 Bad Request

**Description**: The request was malformed or contained invalid parameters.

**Content**: Typically a JSON object with an `errors` array detailing the specific issues.

**Example**:
```json
{
  "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/",
  "errors": [
    {
      "code": "unknown_fields_error",
      "message": "Unknown field(s) provided: {unknown_fields}",
      "source": {
        "resource": "Orders"
      }
    }
  ]
}
```

### 401 Unauthorized

**Description**: Authentication failed, likely due to invalid or missing credentials.

**Content**: A JSON object containing error details, often including an `invalid_token` code.

**Example**:
```json
{
  "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/",
  "errors": [
    {
      "code": "invalid_token",
      "message": "Incorrect authentication credentials.",
      "source": {
        "resource": "Accounts",
        "ref": ""
      }
    }
  ]
}
```

### 403 Forbidden

**Description**: The authenticated user does not have permission to perform the requested action.

**Content**: A JSON object with a `detail` field explaining the lack of permissions.

**Example**:
```json
{
  "detail": "You do not have permission to perform this action."
}
```

### 404 Not Found

**Description**: The requested resource could not be found.

**Content**: A JSON object with an `errors` array, potentially indicating a non-existent order or other resource.

**Example**:
```json
{
  "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/",
  "errors": [
    {
      "code": "resource_not_found",
      "message": "Order with ref {order_ref} does not exist for current Merchant with FNS {fns_number}",
      "source": {
        "resource": "Orders",
        "ref": "{order_ref}"
      }
    }
  ]
}
```

### 409 Conflict

**Description**: The request conflicts with the current state of the resource, often due to concurrent requests or idempotency key issues.

**Content**: A JSON object with an `errors` array detailing the conflict, such as issues with idempotency keys.

**Example**:
```json
{
  "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/",
  "errors": [
    {
      "code": "cannot_change_request",
      "message": "Two requests were submitted with the same idempotency key, but slightly different request bodies. Please use a new idempotency key if you intended to change the request body",
      "source": {
        "resource": "Idempotency_Key"
      }
    }
  ]
}
```

### 429 Too Many Requests

**Description**: The client has sent too many requests in a given amount of time (rate limiting).

**Content**: A JSON object with an `errors` array, indicating that the request was throttled.

**Example**:
```json
{
  "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Request was throttled, please try again later.",
      "source": {
        "resource": "Orders",
        "ref": "{order_ref}"
      }
    }
  ]
}
```
```

--------------------------------

### Invalid Input Data Error

Source: https://docs.joinforage.app/reference/cancel-a-payment

This example shows an error response when invalid input data is provided, such as an unrecognized query parameter.

```json
{
  "path": "/api/payments/{payment_ref}/cancel/",
  "errors": [
    {
      "code": "invalid_input_data",
      "message": "Query parameter unrecognized.",
      "source": {
        "resource": "Payments",
        "ref": "{payment_ref}"
      }
    }
  ]
}
```

--------------------------------

### Error Response: Invalid Input Data

Source: https://docs.joinforage.app/reference/cancel-an-order-payment

This example shows the JSON response when invalid or incomplete query data is provided for canceling an order payment. The 'source' field indicates the resource with the issue.

```json
{
  "path": "/api/orders/{order_ref}/payments/{payment_ref}/cancel/",
  "errors": [
    {
      "code": "invalid_input_data",
      "message": "Query parameter missing or incomplete.",
      "source": {
        "resource": "Orders",
        "ref": "{order_ref}"
      }
    }
  ]
}
```

--------------------------------

### Initialize Forage Checkout Session

Source: https://docs.joinforage.app/reference

Use this endpoint to initialize the Forage Checkout Fully Hosted UI.

```bash
POST /sessions/
```

--------------------------------

### ForageError Object Example

Source: https://docs.joinforage.app/reference/capture-ebt-payment

This is an example of a ForageError object that is returned when an EBT payment capture fails due to insufficient funds.

```javascript
{
  httpStatusCode: 400,
  code: 'ebt_error_51',
  message: 'Insufficient funds - Insufficient Funds. Remaining balances are SNAP: 1.23, EBT Cash: 4.56',
  details: {
    snapBalance: 1.23,
    cashBalance: 4.56
  }
}
```

--------------------------------

### Make a Payment Request with cURL

Source: https://docs.joinforage.app/reference/create-a-payment

Use this cURL command to initiate a payment request. Ensure you replace placeholders like <api_key>, <merchant_id>, and <idempotency-key> with your actual credentials.

```shell
curl --request POST \
    --url https://api.sandbox.joinforage.app/api/payments/ \
    --header 'Authorization: Bearer <api_key>' \
    --header 'Merchant-Account: <merchant-id>' \
    --header 'Idempotency-Key: <idempotency-key>' \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '{
  "amount": 25.99,
  "funding_type": "ebt_snap",
  "payment_method": "ac47392bb1",
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "zipcode": "94106",
    "state": "CA"
  },
  "is_delivery": true,
  "description": "An EBT payment",
  "metadata": {},
  "platform_fee": 0.05,
  "platform_fixed_settlement": 5.11,
  "merchant_fixed_settlement": 5.95,
  "customer_id": "cus_1234567890",
  "external_order_id": "1f2ee410-5b47-4130-aec2-40f5eb2108f5"
}'
```

--------------------------------

### Create Balance Session with cURL

Source: https://docs.joinforage.app/reference/create-custom-balance-check-session

Use this cURL command to create a balance session. Ensure you replace placeholders like <api_key>, <merchant-id>, and <idempotency-key> with your actual credentials. The request body specifies payment method details and redirect URLs.

```shell
curl --request POST \
    --url https://api.sandbox.joinforage.app/api/balance_sessions/ \
    --header 'Authorization: Bearer <api_key>' \
    --header 'Merchant-Account: <merchant-id>' \
    --header 'Idempotency-Key: <idempotency-key>' \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '
{
  "payment_method": "b16673fe21",
  "success_redirect_url": "https://www.your-app.com/status=SUCCEEDED",
  "cancel_redirect_url": "https://www.your-app.com/status=CANCELED"
}
'
```

--------------------------------

### Create Authentication Token (Shell)

Source: https://docs.joinforage.app/reference/create-authentication-token

Use this cURL command to create an authentication token. Ensure you replace placeholder values with your actual Client ID and Client Secret, and adjust the expiration time and scope as needed.

```shell
curl --request POST \
     --url https://api.sandbox.joinforage.app/o/token/ \
     --header 'Authorization: Basic TnVsdzhZeUJnTmlUZzXXUVRMNTd0V0tKVFNqMWpnU2pvMDBLU2lOdTpxdk1NMk1ZVGJqNWlBQ2VvZ1FzaBbhUXVoVDRzQ0R3cm14S1duSUZkVUQ5ZFR3N2taU0toM0JTNnBwdTdieEFzZHgzUmJtM0czZmFucGhwdHVjWWptMzdmNTZPRGg3S1hGeUxtN0lYaTBLNlhab2VIb3J4QVBFYkhPVUlJMWVlbw==' \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data expiration_time=36000 \
     --data grant_type=client_credentials \
     --data scope=hosted_checkout
```

--------------------------------

### EBT Balance Check Failure Response Example

Source: https://docs.joinforage.app/reference/check-the-balance-of-an-ebt-card

This is an example of a ForageError object returned when an EBT balance check fails. It includes HTTP status code, error code, and a descriptive message.

```javascript
{
  httpStatusCode: 400,
  code: 'ebt_error_14',
  message: 'Invalid card number - Re-enter Transaction'
}
```

--------------------------------

### POST /capture_sessions/

Source: https://docs.joinforage.app/reference/create-capture-session

Initiates a Custom Capture Session. Passing `customer_id` is strongly recommended for performance and to ensure continuity of stored payment methods.

```APIDOC
## POST /capture_sessions/

### Description
Initiates a Custom Capture Session. This endpoint allows for the creation of a session to capture payment details. Passing `customer_id` is strongly recommended for performance and to ensure continuity of stored payment methods.

### Method
POST

### Endpoint
/capture_sessions/

### Parameters
#### Query Parameters
None

#### Request Body
- **success_redirect_url** (string) - Required - The URL Forage redirects to upon successful order completion.
- **cancel_redirect_url** (string) - Required - The URL Forage redirects to upon order cancellation.
- **delivery_address** (object) - Required - The address for delivery or pickup of the order. Must always be provided per FNS regulations. If the order is for pickup, use the merchant address.
  - **is_delivery** (boolean) - Required - Whether the order is for delivery or pickup. Defaults to `false`.
- **supported_benefits** (array of strings) - Optional - Limits payment method types (e.g., `["snap", "ebt_cash", "non_ebt"]`). Omit to accept all supported types.
- **platform_fee** (number) - Optional - Percentage fee charged by a platform supporting multiple merchants.
- **customer_id** (string) - Optional (Recommended) - A unique identifier for the end customer. Helps Forage identify the customer and reuse stored payment methods. Max length: 64.
- **external_order_id** (string) - Optional - A unique identifier for the order as created by the merchant or platform. Max length: 64. Requires Forage API Version `2023-05-15` or later.
- **external_location_id** (string) - Optional - A unique identifier for the physical fulfillment location of the order.
- **payment_details** (object) - Required - A list of `snap_payment` and/or `ebt_cash_payment` objects. Requires Forage API Version `2024-03-05` or later.

### Request Example
```json
{
  "success_redirect_url": "https://example.com/success",
  "cancel_redirect_url": "https://example.com/cancel",
  "delivery_address": {
    "is_delivery": true,
    "street_address": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip_code": "90210"
  },
  "customer_id": "cust_12345",
  "external_order_id": "order_abcde",
  "payment_details": {
    "snap_payment": {
      "ref": "pm_snap_xyz789"
    }
  }
}
```

### Response
#### Success Response (200)
- **ref** (string) - A unique identifier for the created Capture Session.
- **order_ref** (string) - A unique identifier for the associated Order.
- **payment_refs** (array of strings) - A list of unique identifiers for the payments associated with the Order.

#### Response Example
```json
{
  "ref": "sess_abcdef123456",
  "order_ref": "ord_ghijkl789012",
  "payment_refs": ["pmt_mnopqr345678"]
}
```
```

--------------------------------

### Example Change Event Object

Source: https://docs.joinforage.app/reference/change

This is an example of the event object emitted when an EBT Element's value changes. It includes type, usecase, a boolean 'complete' field indicating valid input, and an error field.

```javascript
{
  type: 'change',
  usecase: 'collect_pin',
  complete: true,
  error: null
}
```

--------------------------------

### POST /api/payments/{payment_ref}/authorize/

Source: https://docs.joinforage.app/reference/authorize-a-payment

Authorizes a previously created payment. This endpoint is used to confirm a transaction after initial setup.

```APIDOC
## POST /api/payments/{payment_ref}/authorize/

### Description
Authorizes a previously created payment. This endpoint is used to confirm a transaction after initial setup.

### Method
POST

### Endpoint
/api/payments/{payment_ref}/authorize/

### Parameters
#### Path Parameters
- **payment_ref** (string) - Required - The reference hash of the payment to authorize.

#### Request Body
- **request_partial_authorization** (boolean) - Optional - If true, partial authorization is attempted when the cardholder balance is insufficient to cover the entire authorization amount. The amount returned represents the “approved” amount that may be less than the original requested amount. If false, authorization will fail if there is insufficient balance.

### Request Example
```json
{
  "request_partial_authorization": true
}
```

### Response
#### Success Response (200)
- **path** (string) - The requested endpoint.
- **errors** (array) - An array with information about the error.
  - **code** (string) - A short string that represents the error.
  - **message** (string) - A developer-facing message with more details about the error, not to be displayed to customers.
  - **source** (object) - The type of the Forage resource involved in the error.
    - **resource** (string) - The type of the Forage resource involved in the error.
    - **ref** (string) - If applicable, the ten character reference hash of the Forage resource that caused the error. An empty string if no specific individual resource was involved.
  - **details** (object) - Additional details about the error, if applicable.

#### Response Example
```json
{
  "path": "/api/payments/{payment_ref}/authorize/",
  "errors": [
    {
      "code": "unknown_server_error",
      "message": "Unknown exception from card network",
      "source": {
        "resource": "Payments"
      }
    }
  ]
}
```

#### Error Response (500)
- **description**: Internal Server Error

#### Error Response (503)
- **description**: Service Unavailable
```

--------------------------------

### Create Payment Reference

Source: https://docs.joinforage.app/reference

Use this endpoint to create a payment reference, which is a required parameter for SDK payment capture functions.

```bash
POST /payments/
```

--------------------------------

### Create Capture Session Request (cURL)

Source: https://docs.joinforage.app/reference/create-capture-session

Use this cURL command to create a capture session. Ensure you replace placeholders like <api_key> and <merchant-id> with your actual credentials. The request body includes redirect URLs, delivery address, and payment details.

```shell
curl --request POST \
    --url https://api.sandbox.joinforage.app/api/capture_sessions/ \
    --header 'Authorization: Bearer <api_key>' \
    --header 'Merchant-Account: <merchant-id>' \
    --header 'Idempotency-Key: <idempotency-key>' \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '{
  "success_redirect_url": "https://www.your-app.com/?status=SUCCEEDED",
  "cancel_redirect_url": "https://www.your-app.com/?status=CANCELED",
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "zipcode": "94106",
    "state": "CA"
  },
  "is_delivery": true,
  "payment_details": {
    "snap_payment": {
      "amount": 20.12,
      "payment_method": "fsdf45345",
      "description": "A SNAP payment",
      "funding_type": "ebt_snap",
      "metadata": {}
    }
  }
}'
```

--------------------------------

### Retrieve Customer EBT Card Balance

Source: https://docs.joinforage.app/reference/create-custom-balance-check-session

Retrieves the EBT card balance after a customer completes the Forage UI. This is done by sending a GET request to the /api/payment_methods/{payment_method_ref}/ endpoint.

```APIDOC
## GET /api/payment_methods/{payment_method_ref}/

### Description
Retrieves the EBT card balance after a customer has completed the Forage UI. Inspect the `balance` field in the response.

### Method
GET

### Endpoint
`https://{environment}.joinforage.app/api/payment_methods/{payment_method_ref}/`

### Parameters
#### Path Parameters
- **payment_method_ref** (string) - required - The unique reference ID of the `PaymentMethod`.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200 OK)
- **balance** (object) - Contains the EBT card balance information.
  - **amount** (integer) - The balance amount in cents.
  - **currency** (string) - The currency of the balance (e.g., "USD").

#### Response Example
```json
{
  "payment_method_ref": "pm_abc123xyz",
  "type": "ebt",
  "balance": {
    "amount": 5000,
    "currency": "USD"
  }
}
```
```

--------------------------------

### Development Environments

Source: https://docs.joinforage.app/reference

Information on accessing the sandbox and production environments for the Forage API.

```APIDOC
## Development Environments

### Description
Information on the different environments available for interacting with the Forage API.

### Environments
- **sandbox**: Use this environment for development and testing without live data.
  - URL: `https://api.sandbox.joinforage.app/…`
- **production**: Use this environment for live EBT transactions.
  - URL: `https://api.joinforage.app/…`
```

--------------------------------

### Create an Authentication Token

Source: https://docs.joinforage.app/reference/create-authentication-token

Use a POST request to the /o/token/ endpoint to generate a new authentication token. This token is returned as the `access_token` in the response body and is used to authenticate server-side requests to Forage.

```APIDOC
## POST /o/token/

### Description
Creates a new authentication token for server-side requests.

### Method
POST

### Endpoint
`https://{environment}.joinforage.app/o/token/`

### Parameters
#### Request Body
- **grant_type** (string) - Required - The constant string `client_credentials`.
- **expiration_time** (integer) - Optional - The lifespan of the token in seconds. Defaults to `604800` (7 days). Acceptable range: `86400` (1 day) to `2592000` (30 days).
- **scope** (string) - Optional - The token's permissions level. Defaults to `hosted_checkout`. Possible values: `accounts`, `hosted_checkout`, `pinpad_only`, `reporting`. Multiple scopes can be specified separated by a space.

### Headers
- **Authorization** (string) - Required - Base64 encoded `client_id:client_secret` prefixed with `Basic `.
- **accept** (string) - Optional - `application/json`
- **content-type** (string) - Optional - `application/x-www-form-urlencoded`

### Request Example
```curl
curl --request POST \
     --url https://api.sandbox.joinforage.app/o/token/ \
     --header 'Authorization: Basic TnVsdzhZeUJnTmlUZzXXUVRMNTd0V0tKVFNqMWpnU2pvMDBLU2lOdTpxdk1NMk1ZVGJqNWlBQ2VvZ1FzaBbhUXVoVDRzQ0R3cm14S1duSUZkVUQ5ZFR3N2taU0toM0JTNnBwdTdieEFzZHgzUmJtM0czZmFucGhwdHVjWWptMzdmNTZPRGg3S1hGeUxtN0lYaTBLNlhab2VIb3J4QVBFYkhPVUlJMWVlbw==' \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data expiration_time=36000 \
     --data grant_type=client_credentials \
     --data scope=hosted_checkout
```

### Response
#### Success Response (200)
- **access_token** (string) - The generated authentication token.
- **token_type** (string) - The type of token, usually `bearer`.
- **expires_in** (integer) - The token's lifespan in seconds.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 36000
}
```

#### Error Responses
- **400 Bad request**: The request was not accepted because of an error in the request body or path.
- **401 Unauthorized**: Authentication failed.
```

--------------------------------

### Sandbox API URL

Source: https://docs.joinforage.app/reference

Use this URL to develop against the sandbox environment, which does not have live data.

```bash
https://api.sandbox.joinforage.app/…
```

--------------------------------

### POST /api/balance_sessions/

Source: https://docs.joinforage.app/reference/create-custom-balance-check-session

Creates a new balance session. This endpoint is used to initiate a session for a user to complete a transaction.

```APIDOC
## POST /api/balance_sessions/

### Description
Creates a new balance session. This endpoint is used to initiate a session for a user to complete a transaction.

### Method
POST

### Endpoint
https://environment.joinforage.app/api/balance_sessions/

### Parameters
#### Request Body
- **payment_method** (string) - Required - The ID of the payment method to use for the session.
- **success_redirect_url** (string) - Required - The URL to redirect the user to upon successful completion of the session.
- **cancel_redirect_url** (string) - Required - The URL to redirect the user to if they cancel the session.

### Request Example
```json
{
  "payment_method": "b16673fe21",
  "success_redirect_url": "https://www.your-app.com/status=SUCCEEDED",
  "cancel_redirect_url": "https://www.your-app.com/status=CANCELED"
}
```

### Response
#### Success Response (200)
- **session_id** (string) - The unique identifier for the created session.
- **status** (string) - The initial status of the session (e.g., 'pending').
- **expires_at** (string) - The timestamp when the session will expire.

#### Response Example
```json
{
  "session_id": "sess_abc123xyz",
  "status": "pending",
  "expires_at": "2023-10-27T10:00:00Z"
}
```

### Error Handling
- **400 - Cannot Parse Request Body**: The request body could not be parsed.
- **400 - Invalid Input Data**: One or more fields in the request body have invalid data.
- **400 - Invalid Merchant Account**: The provided merchant account ID is invalid.
- **400 - Missing Idempotency Key**: The Idempotency-Key header is missing.
- **400 - Missing Merchant Account**: The Merchant-Account header is missing.
- **400 - Unknown Fields Error**: The request body contains unknown fields.
- **401 - Expired Session Token**: The session token used is expired.
- **401 - Invalid Token**: The provided token is invalid.
- **409 - Cannot Change Request**: The request cannot be processed due to a conflict.
- **423 - Resource Locked**: The resource is currently locked.
- **429 - Too Many Requests**: Rate limit exceeded.
- **500 - Internal Server Error**: An unexpected error occurred on the server.
```

--------------------------------

### Create Payment

Source: https://docs.joinforage.app/reference/authorize-a-payment

This section details the parameters required to create a payment. It covers amount, funding type, payment method, delivery information, and optional fields like metadata and platform fees.

```APIDOC
## POST /payments

### Description
Creates a new payment transaction.

### Method
POST

### Endpoint
/payments

### Parameters
#### Request Body
- **amount** (number) - Required - A positive decimal number that represents how much to charge the [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) in USD. Precision is supported to the penny. The minimum amount that can be charged is `0.01`.
- **funding_type** (string) - Required - The payment instrument type. Use this field to differentiate between a SNAP (`ebt_snap`) and an EBT Cash (`ebt_cash`) charge on the same EBT Card. Use `credit_payfac` for all charges to HSA/FSA cards. `credit_tpp` is the funding type assigned to non-EBT payment objects created via a Fully Hosted Checkout integration. Enum: [`ebt_snap`, `ebt_cash`, `credit_tpp`, `credit_payfac`].
- **payment_method** (string) - Required - The unique reference hash for the existing Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) that is to be charged in this transaction. Exception: POS integrations do not need to provide a `payment_method` when creating a payment.
- **delivery_address** (object) - Optional - The delivery address for the order. See `DeliveryAddressData` schema.
- **is_delivery** (boolean) - Optional - Whether the order is for delivery or pickup. This information is required per FNS regulations. Defaults to `false` if not provided. Exception: If the purchase is made in-store via a POS Terminal, then `is_delivery` is not required.
- **description** (string) - Optional - A description of the payment.
- **metadata** (object) - Optional - Arbitrary metadata associated with the payment. See `MetadataObject` schema.
- **platform_fee** (number) - Optional - An optional field, for use by a platform supporting multiple merchants, that indicates the percentage cut of each payment that the platform charges as a fee.
- **platform_fixed_settlement** (number) - Optional - The fixed amount in USD that a platform takes from EBT Cash payments prior to splitting by the `platform_fee`. Precision is supported to the penny.
- **merchant_fixed_settlement** (number) - Optional - The fixed amount in USD that should be restored to the merchant from EBT Cash payments prior to splitting by the `platform_fee`. Precision is supported to the penny.
- **tpp_lookup_id** (string) - Optional - An identifier for the credit/debit TPP. For Stripe integrations, the client secret for a Stripe `PaymentIntent`.
- **customer_id** (string) - Optional - The unique reference hash for the customer. See `CustomerIDField` schema.
- **external_order_id** (string) - Optional - An identifier for the order in your system. See `ExternalOrderIDField` schema.
- **merchant_destination_account** (string) - Optional - A unique reference hash for the bank account that is to receive funds settlement for this payment. Use this field if you're settling funds across multiple merchant bank accounts. Defaults to the hash for the default merchant bank account if not provided.
- **pos_terminal** (object) - Optional - An object that details information about the POS Terminal that processes the payment. This param is only supported for POS Terminal integrations. Do not use this param for online transactions.
  - **provider_terminal_id** (string) - Required - A unique string that identifies the POS Terminal.
- **external_location_id** (string) - Optional - An identifier for the location in your system. See `ExternalLocationIDField` schema.

### Response
#### Success Response (200)
- **ref** (string) - The unique reference hash for the created Payment.
- Other fields from `PaymentRequest` and `PaymentResponse` schema.

#### Response Example
```json
{
  "ref": "pay_abc123xyz",
  "amount": 10.50,
  "funding_type": "ebt_snap",
  "payment_method": "pm_abc123xyz",
  "is_delivery": true,
  "description": "Monthly grocery order",
  "customer_id": "cust_abc123xyz",
  "external_order_id": "order_12345",
  "merchant_destination_account": "mda_abc123xyz",
  "pos_terminal": {
    "provider_terminal_id": "term_abc123xyz"
  },
  "external_location_id": "loc_abc123xyz"
}
```
```

--------------------------------

### Production API URL

Source: https://docs.joinforage.app/reference

Use this URL in production for real live EBT transactions.

```bash
https://api.joinforage.app/…
```

--------------------------------

### Create a Custom Payment Capture Session

Source: https://docs.joinforage.app/reference/create-capture-session

Initiates a Forage Custom Payment Capture UI session. The response contains essential details like the order reference and redirect URL.

```APIDOC
## POST /api/capture_sessions/

### Description
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.

### Method
POST

### Endpoint
https://{environment}.joinforage.app/api/capture_sessions/

### Parameters
#### Request Body
- **amount** (integer) - Required - The amount to capture in cents.
- **currency** (string) - Required - The currency of the amount (e.g., "USD").
- **payment_method_type** (string) - Required - The type of payment method to use (e.g., "EBT").
- **items** (array) - Optional - A list of items associated with the order.
  - **name** (string) - Required - The name of the item.
  - **price** (integer) - Required - The price of the item in cents.
  - **quantity** (integer) - Required - The quantity of the item.
- **description** (string) - Optional - A description of the session.
- **metadata** (object) - Optional - Key-value pairs for additional information.
- **success_redirect_url** (string) - Required - The URL to redirect to upon successful payment.
- **cancel_redirect_url** (string) - Required - The URL to redirect to if the user cancels the payment.

### Request Example
```json
{
  "amount": 1000,
  "currency": "USD",
  "payment_method_type": "EBT",
  "items": [
    {
      "name": "Example Item",
      "price": 500,
      "quantity": 2
    }
  ],
  "description": "Test payment session",
  "metadata": {
    "order_id": "12345"
  },
  "success_redirect_url": "https://example.com/success",
  "cancel_redirect_url": "https://example.com/cancel"
}
```

### Response
#### Success Response (200)
- **ref** (string) - The reference ID for the Order. Store this for future requests.
- **redirect_url** (string) - The URL to launch the Forage customer-facing UI.
- **payment_status** (string) - The status of the payment.
- **created_at** (string) - The timestamp when the session was created.

#### Response Example
```json
{
  "ref": "ord_12345abcde",
  "redirect_url": "https://sandbox.joinforage.app/payment/12345abcde",
  "payment_status": "pending",
  "created_at": "2024-08-30T10:00:00Z"
}
```
```

--------------------------------

### POST /api/payments/

Source: https://docs.joinforage.app/reference/create-a-payment

Creates a Forage Payment object representing a one-time charge. This endpoint should be called from your server-side to maintain security. The response includes a `ref` value needed to authorize and capture the payment via the SDK.

```APIDOC
## POST /api/payments/

### Description
Creates a Forage `Payment` object that represents a one-time charge. This operation must be performed server-side to ensure security. Upon successful creation, the API returns a `Payment` object containing a `ref` value, which is essential for authorizing and capturing the payment using the Forage SDK.

### Method
POST

### Endpoint
`https://{environment}.joinforage.app/api/payments/`

### Parameters
#### Request Body
- **amount** (number) - Required - A positive decimal number representing the charge amount in USD. Minimum value is `0.01`. Supports precision to the penny. Use `funding_type` to differentiate SNAP and EBT Cash charges.
- **funding_type** (string) - Required - Enum: `ebt_snap`, `ebt_cash`, `credit_tpp`, `credit_payfac`. The type of payment instrument. Use `ebt_snap` or `ebt_cash` for EBT cards, `credit_payfac` for HSA/FSA cards, and `credit_tpp` for non-EBT payment objects from a Fully Hosted Checkout integration.
- **payment_method** (string) - Required - The unique reference hash of the Forage `PaymentMethod` to be charged. *Exception: Not required for POS integrations.*
- **delivery_address** (object) - Required - The address for delivery or pickup of the order. Must be provided per FNS regulations. If the order is for pickup, use the merchant address. *Exception: Not required for in-store POS Terminal purchases.*
  - **is_delivery** (boolean) - Required - Indicates if the order is for delivery. Defaults to `false`. *Exception: Not required for in-store POS Terminal purchases.*
- **description** (string) - Required - A description of the payment.
- **metadata** (object) - Required - An object containing merchant-defined key-value pairs for additional context. Pass an empty object (`{}`) if no additional information is available.

### Request Example
```json
{
  "amount": 10.50,
  "funding_type": "ebt_snap",
  "payment_method": "pm_12345abcde",
  "delivery_address": {
    "street_address": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip_code": "90210"
  },
  "is_delivery": true,
  "description": "Order #98765",
  "metadata": {
    "order_id": "98765",
    "customer_id": "cust_abcde12345"
  }
}
```

### Response
#### Success Response (200)
- **ref** (string) - The reference hash for the created Payment, used to capture the payment via the SDK.
- **amount** (number) - The amount charged.
- **currency** (string) - The currency of the charge (e.g., "USD").
- **funding_type** (string) - The funding type used for the payment.
- **payment_method** (string) - The reference hash of the payment method.
- **status** (string) - The current status of the payment (e.g., "pending", "succeeded", "failed").
- **created_at** (string) - Timestamp of when the payment was created.

#### Response Example
```json
{
  "ref": "pay_abcdef12345",
  "amount": 10.50,
  "currency": "USD",
  "funding_type": "ebt_snap",
  "payment_method": "pm_12345abcde",
  "status": "pending",
  "created_at": "2024-08-30T10:00:00Z"
}
```
```

--------------------------------

### POST /api/payment_methods/

Source: https://docs.joinforage.app/reference/create-payment-method

This endpoint is used to create a PaymentMethod. It allows checking which states and BINs Forage supports, which is useful for customers concerned with state waivers or validating card eligibility before tokenization.

```APIDOC
## POST /api/payment_methods/

### Description
To check which states and BINs Forage supports, use the Retrieve state card details endpoint. This is useful for customers concerned with state waivers or validating card eligibility before tokenization.

### Method
POST

### Endpoint
https://environment.joinforage.app/api/payment_methods/

### Headers
- **Authorization** (string) - Required - An OAuth 2.0 bearer token that validates the request. You can use either a short-lived session token if the request is coming from the front-end, or an authentication token for server-side requests. Pass the token in this header after the word `Bearer` and a whitespace, for example `Bearer <api_key>`.
- **Merchant-Account** (string) - Required - A unique merchant ID that Forage provides during onboarding, as in `123ab45c67`. The Merchant ID can be found in the Forage sandbox or production dashboard. Pass a `Merchant-Account` header to create a `PaymentMethod` associated with a specific merchant account for routing and reporting purposes. **This header does not restrict `PaymentMethod`s to a single merchant account. `PaymentMethod`s are tenant-scoped and can be used across all merchant accounts within the same tenant.**
- **API-Version** (string) - Optional - The Forage version, represented as a string with the format of a `YYYY-MM-DD` date. If not specified in the request header, then the version defaults to the value set in the Forage dashboard.

### Request Body
- **type** (string) - Required - The card type. One of: `credit`, `debit`, `prepaid`, `ebt`. Note: The `type` value can only be `credit`, `debit`, or `prepaid` in a Fully Hosted or HSA/FSA integration.
- **reusable** (boolean) - Required - Whether the `PaymentMethod` can be reused. If `false`, then the `PaymentMethod` can only be used for a single transaction.
- **customer_id** (string) - Optional - A unique identifier for the end customer making the payment. Forage automatically adds the `customer_id` to the Session's corresponding `Order` and `OrderPayments`. This field helps Forage's servers more quickly identify the customer associated with the request. While `customer_id` is not technically required, if you omit it then requests could take longer to process. **It is strongly recommended to pass customer_id.** If you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload. Each customer should only have one unique `customer_id`. For example, if you create both a `PaymentMethod` and a Forage `Session` (Fully Hosted or Custom) or `Payment` (SDK) for the same customer, then the `customer_id` should be the same in both requests to ensure continuity of stored payment methods. **If you’re integrating Forage with a POS Terminal, then do not use this param. It is only supported for online transactions.**
- **card** (object) - Required - Represents the card details. This can be an `EBTCard` object or other card types.
  - **number** (string) - Required - The card number.

### Request Example
```json
{
  "type": "ebt",
  "reusable": true,
  "card": {
    "number": "1234567890123456"
  },
  "customer_id": "cus_1234567890"
}
```

### Response
#### Success Response (200)
- **id** (string) - A unique identifier for the created PaymentMethod.
- **type** (string) - The type of the card.
- **reusable** (boolean) - Indicates if the PaymentMethod is reusable.
- **last_4** (string) - The last 4 digits of the card number.
- **exp_month** (integer) - The expiration month of the card.
- **exp_year** (integer) - The expiration year of the card.
- **fingerprint** (string) - A unique identifier for the card, used for matching.
- **created_at** (string) - Timestamp when the PaymentMethod was created.
- **updated_at** (string) - Timestamp when the PaymentMethod was last updated.
- **customer_id** (string) - The ID of the customer associated with this PaymentMethod.

#### Response Example
```json
{
  "id": "pm_123abc456def",
  "type": "ebt",
  "reusable": true,
  "last_4": "3456",
  "exp_month": 12,
  "exp_year": 2025,
  "fingerprint": "abc123def456",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z",
  "customer_id": "cus_1234567890"
}
```

#### Error Responses
- **400 Bad Request**: Various reasons including missing fields, invalid input data, invalid merchant account, unsupported BIN, incorrect card number format, etc.
- **401 Unauthorized**: Invalid or expired token.
- **429 Too Many Requests**: Rate limit exceeded.
```

--------------------------------

### POST /api/payments/

Source: https://docs.joinforage.app/reference/create-a-payment

Initiates a payment transaction. This endpoint is used to create a new payment request with all necessary details.

```APIDOC
## POST /api/payments/

### Description
Initiates a payment transaction. This endpoint is used to create a new payment request with all necessary details.

### Method
POST

### Endpoint
https://environment.joinforage.app/api/payments/

### Parameters
#### Request Body
- **external_location_id** (string) - Required - An identifier for the external location.
- **amount** (number) - Required - The payment amount.
- **funding_type** (string) - Required - The type of funding (e.g., 'ebt_snap').
- **payment_method** (string) - Required - The payment method identifier.
- **delivery_address** (object) - Optional - The delivery address details.
  - **city** (string) - Required - The city of the delivery address.
  - **country** (string) - Required - The country of the delivery address (e.g., 'US').
  - **line1** (string) - Required - The first line of the street address.
  - **zipcode** (string) - Required - The postal code.
  - **state** (string) - Required - The state or province.
- **is_delivery** (boolean) - Required - Indicates if the transaction is for delivery.
- **description** (string) - Optional - A description for the payment.
- **metadata** (object) - Optional - Additional key-value pairs for metadata.
- **platform_fee** (number) - Optional - The platform fee for the transaction.
- **platform_fixed_settlement** (number) - Optional - The fixed settlement amount for the platform.
- **merchant_fixed_settlement** (number) - Optional - The fixed settlement amount for the merchant.
- **customer_id** (string) - Optional - The identifier for the customer.
- **external_order_id** (string) - Optional - An external identifier for the order.

### Request Example
```json
{
  "external_location_id": "6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9",
  "amount": 25.99,
  "funding_type": "ebt_snap",
  "payment_method": "ac47392bb1",
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "zipcode": "94106",
    "state": "CA"
  },
  "is_delivery": true,
  "description": "An EBT payment",
  "metadata": {},
  "platform_fee": 0.05,
  "platform_fixed_settlement": 5.11,
  "merchant_fixed_settlement": 5.95,
  "customer_id": "cus_1234567890",
  "external_order_id": "1f2ee410-5b47-4130-aec2-40f5eb2108f5"
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the payment.
- **payment_id** (string) - The unique identifier for the payment.

#### Response Example
```json
{
  "status": "succeeded",
  "payment_id": "pay_a1b2c3d4e5f6"
}
```

#### Error Responses
- **400 - Cannot parse request body**: The request body could not be parsed.
- **400 - Amount mismatch**: The provided amount is inconsistent.
- **400 - Inconsistent funding and payment method**: The funding type and payment method are incompatible.
- **400 - Invalid input data**: One or more input fields are invalid.
- **400 - Card not reusable**: The payment card cannot be reused for this transaction.
- **400 - Different EBT Card**: An attempt to use a different EBT card than expected.
- **400 - Duplicate funding type**: The funding type has already been used in this request.
- **400 - Invalid merchant account**: The provided merchant account is invalid.
- **400 - Missing Idempotency Key**: The Idempotency-Key header is missing.
- **400 - Missing Merchant Account**: The Merchant-Account header is missing.
- **400 - Settlement Greater Than Amount**: The settlement amount exceeds the payment amount.
- **401 - Invalid token**: The provided authentication token is invalid.
- **409 - Cannot Change Request**: The payment request cannot be modified.
- **423 - Resource Locked**: The resource is currently locked.
- **429 - Too Many Requests**: Rate limit exceeded.
- **500 - Unknown Server Error**: An unexpected server error occurred.
- **503 - EBT processor timeout**: The EBT processor timed out.
```
Tokens:
Raw