---
title: "Create New Payee"
method: POST
path: "/programs/{programCode}/accounts/{accountIdentifier}/billpayPayees"
tags: ["BillPay"]
---

# Create New Payee

`POST /programs/{programCode}/accounts/{accountIdentifier}/billpayPayees`

Create a new payee for a customer’s account.<br/>
            • A payee can be a merchant or a person.<br/>
            • A Person payee is a custom individual not listed in Green Dot’s vendor payee directory, so the full address information must be provided in order to send the bill payment.<br/>
            • This endpoint allows the creation of a new payee for a customer’s account.<br/>
            • The payee can be used for future bill payments.<br/>
            • The response includes the new payee identifier and status.<br/>
            • The payeeType must be either 'Merchant' or 'Person'.<br/>
            • For merchant payees, merchantId should be provided.<br/>
            • For person payees, full address and contact information must be provided.<br/>
            • The accountIdentifier must be a valid GUID.<br/>
            • The requestId must be provided in the X-GD-RequestId header for idempotency and tracking.<br/>

## Path parameters

- `programCode` string, required
- `accountIdentifier` string, required

## Headers

- `X-GD-RequestId` string, required

## Request body

- CreatePayeeRequest — Create Payee Request – Represents the data required to create a new bill payee for an account. Used to add a merchant or person payee, including all necessary address, contact, and account information.
  - `payeeType` string, nullable — The type of payee. Expected values: "Merchant" or "Person".
  - `name` string, nullable — The name of the payee (merchant or person).
  - `nickName` string, nullable — An optional nickname for the payee.
  - `address1` string, nullable — The first line of the payee's address.
  - `address2` string, nullable — The second line of the payee's address (optional).
  - `city` string, nullable — The city of the payee's address.
  - `state` string, nullable — The state or province of the payee's address.
  - `country` string, nullable — The country of the payee's address (e.g., "US").
  - `zip` string, nullable — The ZIP or postal code of the payee's address.
  - `accountNumber` string, nullable — The account number associated with the payee, if applicable.
  - `phoneNumber` string, nullable — The payee's phone number.
  - `email` string, nullable — The payee's email address.
  - `merchantId` string, nullable — The merchant ID for merchant payees (if applicable).

## Response `201`

Created

- CreatePayeeResponse — Create Payee Response – Contains the result of a payee creation operation. Returns the unique identifier assigned to the new payee and the resulting payee status. Used to confirm successful payee creation and provide the payee identifier for subsequent operations.
  - `payeeIdentifier` string, nullable — The unique identifier assigned to the newly created payee. Use this identifier for future operations involving this payee.
  - `payeeStatus` 'active' | 'inactive', nullable — The status of the payee after creation. Possible values are defined in Gd.Bos.DataTransfer.Response.CreatePayeeResponse.PayeeStatus (e.g., Active, Inactive).
  - `responseDetails` ResponseDetail[], nullable — Required: A list of response details providing status codes, descriptions, and additional information about the result of the operation.
    - `code` integer — The primary status or error code for the response (e.g., 200 for success, 400 for validation error).
    - `subCode` integer, nullable — An optional subcode providing more granular detail about the response or error.
    - `description` string, nullable — A human-readable description of the response, error, or status.
    - `url` string, nullable — A URL linking to documentation or a web page with more information about the response code.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/greendot/apis/baas-apis.md) · [All operations](https://skmtc.net/greendot/apis/baas-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/greendot/baas-apis/revisions/666553766b78/schema)