//#region src/generate-pix-payload/generate-pix-payload.d.ts
/** The parameters `generatePixPayload` takes to build a Pix BR Code. */
export type GeneratePixPayloadParams = {
  /** The Pix key of the receiver, in any accepted form. Required unless `url` is given. */
  key?: string;
  /**
   * The PSP location of a dynamic payload (Bacen field 26-25), without a URL scheme, e.g.
   * `"pix.example.com/qr/v2/1234"`. When given, the payload is generated as dynamic
   * (`pointOfInitiation` `"12"`) and carries this URL instead of a key. Required unless `key`
   * is given; giving both `key` and `url` is invalid, just like giving neither.
   */
  url?: string;
  /** Name of the receiver, folded to ASCII and truncated to 25 characters. */
  merchantName: string;
  /** City of the receiver, folded to ASCII and truncated to 15 characters. */
  merchantCity: string;
  /** Amount in BRL, with at most two decimal places. Omit it to let the payer type it. Not allowed together with `url`: a dynamic BR Code takes its amount from the PSP location. */
  amount?: number;
  /** Transaction ID, 1 to 25 characters of `[A-Za-z0-9]` (default: the absent marker `***`). Not allowed together with `url`. */
  txid?: string;
  /** Free text shown to the payer, folded to ASCII and truncated to what the template holds. */
  description?: string;
};
/**
 * Generates the payload of a Pix BR Code, the string behind a Pix QR Code and behind "Pix
 * copia e cola".
 *
 * Exactly one of `params.key` or `params.url` must be given: `null` is returned when both are
 * given and when neither is given, since only one of them can occupy the "Merchant Account
 * Information" template at a time.
 *
 * When `params.key` is given, it is normalized to its DICT canonical form by `getPixKeyInfo` and
 * the payload is static: the "Point of Initiation Method" object is left out, so the payload
 * may be paid more than once, as in the example of the Bacen manual.
 *
 * When `params.url` is given instead, the payload is dynamic per the Manual de Padrões para
 * Iniciação do Pix: the URL takes the key's place in the "Merchant Account Information"
 * template (sub-object `25` instead of `01`) and the "Point of Initiation Method" object (`01`)
 * is set to `"12"`. `params.url` must be at most 77 characters, the length that keeps the
 * template within its 99 character limit together with the `br.gov.bcb.pix` GUI. `getPixPayloadInfo`
 * already parses both shapes, so `getPixPayloadInfo(generatePixPayload({ url, ... }))` round-trips.
 *
 * Object `01` is optional in the Manual do BR Code (`Uso: O`), so writing it only for a dynamic
 * payload is one of the shapes the manual allows and follows its own examples; `getPixPayloadInfo`
 * accepts the others too. The Pix Saque BR Code, which announces the ISPB of the "facilitador de
 * serviço de saque" in sub-object 26-03 (`fss`), is not generated here, only parsed.
 *
 * Unreserved Templates (IDs 80 to 99) are never written: the location always goes in the
 * "Merchant Account Information" template, so the "QR Code composto" of Pix Automático (Pix
 * recorrente), which puts its recurrence location in one of them, is out of scope here.
 * `getPixPayloadInfo` does read a composto, but only as an ordinary dynamic payload.
 *
 * The merchant name, the merchant city and the description are folded to printable ASCII
 * (accents are dropped) and truncated to the lengths the BR Code allows, the description to
 * whatever is left of the 99 characters the "Merchant Account Information" template holds.
 *
 * `params.amount` is written with the two decimal places the BR Code takes, so an amount that
 * does not survive that round trip (`0.005`, `123.456`) is refused rather than rounded into a
 * payload that asks the payer for a different sum.
 *
 * @param {GeneratePixPayloadParams} params - The parameters of the payload.
 * @param {string} [params.key] - The Pix key of the receiver. Required unless `url` is given.
 * @param {string} [params.url] - The PSP location of a dynamic payload. Required unless `key`
 * is given.
 * @param {string} params.merchantName - The name of the receiver.
 * @param {string} params.merchantCity - The city of the receiver.
 * @param {number} [params.amount] - The amount in BRL, with at most two decimal places. Omit it
 * to let the payer type it.
 * @param {string} [params.txid] - The transaction ID, 1 to 25 characters of `[A-Za-z0-9]`.
 * @param {string} [params.description] - The free text shown to the payer.
 * @returns {string|null} The BR Code payload, or `null` when the parameters are invalid.
 *
 * @example
 * ```typescript
 * generatePixPayload({
 *   key: "123.456.789-09",
 *   merchantName: "Fulano de Tal",
 *   merchantCity: "Brasília",
 *   amount: 123.45,
 * });
 * // "00020126330014br.gov.bcb.pix0111123456789095204000053039865406123.455802BR..."
 *
 * generatePixPayload({
 *   url: "pix.example.com/qr/v2/1234",
 *   merchantName: "Fulano de Tal",
 *   merchantCity: "Brasília",
 * });
 * // "00020101021226480014br.gov.bcb.pix2526pix.example.com/qr/v2/12345204000053039865802BR5913Fulano de Tal6008Brasilia62070503***6304FC66"
 *
 * generatePixPayload({ merchantName: "Fulano", merchantCity: "Brasília" }); // null (neither key nor url)
 * generatePixPayload({ key: "123.456.789-09", url: "pix.example.com/qr/v2/1234", merchantName: "Fulano", merchantCity: "Brasília" }); // null (both key and url)
 * ```
 *
 * @see Official: https://www.bcb.gov.br/content/estabilidadefinanceira/spb_docs/ManualBRCode.pdf
 * @see Official: https://www.bcb.gov.br/content/estabilidadefinanceira/pix/Regulamento_Pix/II_ManualdePadroesparaIniciacaodoPix.pdf
 * @see Official: https://github.com/bacen/pix-api
 * Pix (SPI) OpenAPI spec.
 * @see Official: https://www.bcb.gov.br/content/estabilidadefinanceira/pix/API-DICT.html
 * DICT (Diretório de Identificadores de Contas Transacionais) API specification.
 */
export declare const generatePixPayload: (params: GeneratePixPayloadParams) => string | null;
//#endregion