> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paylinedata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and recover Applications

> Persist one request identity, resolve pricing once and recover safely after uncertainty.

> [!NOTE]
>
> These examples passed the [identified Sandbox run](https://developers.paylinedata.com/index.md#example-verification).
> Use synthetic data and first complete [credential setup](https://developers.paylinedata.com/credentials.md).

## Prepare one logical creation

Generate and persist a UUID v4 `requestId` before the first attempt. Store the
original body securely and reuse it for every retry of that logical creation.
The UUID below is illustrative: replace it once for each new Application. Do not
regenerate it when rerunning the request command after a timeout.

Save this as `create.json` in your private working directory:

```json theme={null}
{
  "requestId": "6de50264-993b-4ac3-9232-1b8ca6d784c1",
  "merchantData": { "business_legal_name": "Sandbox Cedar Shop LLC" },
  "pricing": { "model": "ic_plus" }
}
```

```bash theme={null}
curl --silent --show-error --fail-with-body \
  --request POST "$PAYLINE_API_BASE/applications" \
  --header "Authorization: Bearer $PAYLINE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @create.json \
  --dump-header create-headers.txt --output create-response.json
```

A new durable creation returns `201` and `disposition: created`. An equivalent
retry returns `200` and `disposition: recovered`, with the same `applicationId`
and the **current** status/handoff. Only after a successful response, save the
application ID for later commands:

```bash theme={null}
APPLICATION_ID="$(jq -er '.applicationId | strings | select(length > 0)' create-response.json)" || exit 1
export APPLICATION_ID
```

The response's `handoff.url` is a sensitive merchant credential. Deliver it only
through your approved merchant-facing channel; do not log it. Creation itself
does not send an email or submit to a processor.

## Input rules

Only `business_legal_name` is unconditionally required merchant input. Use the
canonical field IDs and conditional validation in the API reference. Unknown
keys and system-owned fields are rejected. Optional ordinary null/blank answers
mean absent; valid false and zero remain answers. DOB and SSN can be supplied
independently through protected fields.

Bank prefill is optional **all-or-none**: omit all four of `bank_name`,
`bank_account_type`, `bank_routing_number`, `bank_account_number`, or provide all
four valid nonblank strings. Partial, null or blank groups fail before creation.
The merchant may enter an omitted bank group later. Never put real protected
values into the example files or a public ticket.

## Pricing and allocation

Choose `ic_plus`, `flat_rate`, `surcharge` or `cash_discount`. Defaults resolve
once at creation. Omitted numeric overrides retain defaults; explicit null or
blank numeric overrides become decimal string `"0"`. Numeric overrides are
decimal strings, not JSON numbers. Nonnumeric settings have their own rules.

This second illustrative request shows a partial override:

```json theme={null}
{
  "requestId": "09a18e23-e682-4a86-b450-e2aa23125ee3",
  "merchantData": {
    "business_legal_name": "Sandbox Cedar Shop LLC",
    "currently_processing_credit_cards": false
  },
  "pricing": {
    "model": "surcharge",
    "overrides": { "credit_card_per_transaction_fee": "0.1250", "batch_fee": null }
  },
  "ownerUserId": null
}
```

`ownerUserId` and `assigneeUserId` are independent optional work assignments.
Omission or null means Unassigned. They are not merchant ownership or signer
identity. Discover current candidates with the separate directory capability:

```bash theme={null}
curl --silent --show-error --fail-with-body \
  "$PAYLINE_API_BASE/applications/eligible-users?limit=50" \
  --header "Authorization: Bearer $PAYLINE_API_KEY" \
  --output eligible-users.json
```

Pagination uses the returned opaque `nextCursor`; supply it URL-encoded as `cursor`
on the next GET. The maximum page size is 100. Supplied assignment IDs are
revalidated at creation; an earlier directory result is not a lasting grant.

## Recovery is not a new creation

Retry identity is environment + tenant + stable caller + request ID, including
across key replacement. Normalized equivalent original input recovers after
merchant edits or changes to defaults/allocation. Changed intent under the same
identity returns `409 request_conflict`. Do not replace original input with the
merchant's current answers when retrying.

Create bodies are limited to 65,536 UTF-8 bytes; strings to 2,048 characters and
numeric pricing strings to 128. Ordinary retry and GET handoff never renew access.
Expired or revoked access requires a separately authorized, eligible
[explicit reissue](https://developers.paylinedata.com/reissue-access.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.