Create and recover Applications

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

These examples passed the identified Sandbox run. Use synthetic data and first complete credential setup.

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:

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

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:

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:

{
  "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:

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.