---
title: "Billpay Webhook"
method: POST
path: "/billpay"
tags: ["Billpay Webhook"]
---

# Billpay Webhook

`POST /billpay`

## Request

- Base URL: `https://client.domain.com`
- URL: `https://client.domain.com/billpay`
- Auth: none declared. Required headers: `X-Request-ID`

Use the Billpay webhook to approve or deny billpay transactions. Use the `response_code`  field in the response to communicate your decision to SoFi Tech Solutions.

## Headers

- `X-Request-ID` string, uuid, required

## Request body

- object
  - `account` object, required
    - `xid` integer, required: Internal system account ID. Example: `5398373`.
    - `prn` string, required: <a href="doc:about-accounts#prn" target="_blank">Payment reference number</a> for the account. Example: `"999200002022"`.
    - `account_status` string, required: Account status code. See the possible values in the <a href="ref:api-reference-account-statuses" target="_blank">Account Statuses</a> enumeration. Example: `"N"`
  - `amounts` object, required
    - `trans_amount` number, float, required: Amount of the billpay transaction. Example: `150.00`
    - `available_funds` number, float, required: Amount of funds available to the account holder for this transaction. Example: `500.00`
    - `currency` string, required: The currency code for `trans_amount` and `fee_amount`. ISO 4217 numeric currency code. 3 digits. Example: `"840"`
    - `fee_amount` number, float, required: Amount of fees for this transaction, if any. Example: `3.00`
  - `timestamp` string, required: Timestamp when this webhook message was sent. Format is `<timestamp><timezone>` where `timestamp` is `YYYYmmdd:HHMMSS` and `timezone` is always `MST`. Example: `"20200315:121504MST"`
  - `billpay_trans_id` integer, required: Unique system-generated billpay transaction ID. Example: `559386`.
  - `biller` object: Biller information. The information sent in this object is configurable (or the `biller` object can be skipped or not sent entirely).
    - `biller_id` integer: Registry ID for the biller. Example: `1024930`
    - `nickname` string, nullable: Account holder's nickname for the biller. Nullable. Example: `"Questar"`.
    - `name` string, nullable: Registry name for the biller. Nullable. Example: `"Questar Gas"`.
    - `type` 'R' | 'Z': Biller type. Possible values: - `R` &mdash; Electronic - `Z` &mdash; Paper
    - `address_1` string, nullable: Biller address line 1. Nullable. Example: `"123 Las Vegas Blvd."`
    - `address_2` string, nullable: Biller address line 2. Nullable. Example: `"Suite 300"`
    - `city` string, nullable: Biller city. Nullable. Example: `"Las Vegas"`
    - `state_province` string, nullable: Biller state or province. Nullable. Example: `"NV"`
    - `postal_code` string, nullable: Biller postal code. Nullable. Example: `"88901"`
    - `phone` string, nullable: Biller phone number. Nullable. Example: `"7021231234"`
  - `version` '1.0', required: The version of this API. Hard-coded to `"1.0"`.
  - `jwt` string: The JSON web token (JWT) that authenticates the HTTP request from SoFi Tech Solutions. See the <a href="ref:api-reference-external-trans-api-about-external-trans-api-security" target="_blank">security overview</a> for more information and an example.

## Response `200`

Your decision and instructions for SoFi Tech Solutions.

- object
  - `response_code` string, required: Response code indicating how to process the billpay transaction. Possible response codes: * `00` &mdash; Approve * `01` &mdash; Reject; Insufficient funds * `98` &mdash; System Error; Reject and do not retry * `99` &mdash; System Error; Retry later You can use `99` to tell SoFi Tech Solutions to retry later if your product is configured for retries.

---

[API](https://skmtc.dev/galileo-ft/apis/external-trans-api.md) - [All operations](https://skmtc.dev/galileo-ft/apis/external-trans-api/llms.txt) - [OpenAPI document](https://skmtc.dev/galileo-ft/apis/external-trans-api/revisions/03b2e38d6647?raw)