> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Update a payment link > Replaces an active payment link with the body sent. Only an `ACTIVE` link can be edited, and it stays `ACTIVE` — `status` is not accepted in the body: use the activate and deactivate routes. It is a full replace: an optional field left out (`description`, `expirationDate`, `secondaryPaymentMethod`, `numberOfInstallments`) is cleared. Like a new link, it must stay sellable: every product active in your organization's catalog with a price above zero, and `expirationDate` today or later. Checkouts already made are not affected. Any member of the organization, or an admin of the realm, can update one; `updatedBy` is set to the ID of the authenticated caller. ## OpenAPI ````yaml /api-reference/billing.openapi.json put /realms/{realmId}/organizations/{organizationId}/payment-links/{paymentLinkId} openapi: 3.0.3 info: title: Billing version: 1.0.0 description: >- Portão 3 billing API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Full billing surface — contracts, deals, invoices, statements, payment links, checkout and NFSe orchestration. (The product/supplier catalog moved to registry.) Confidence tiers: generated:typed=74 copied:manual=0 unknown=5. servers: - url: https://api.billing.v2.portao3.com.br/ description: production - url: https://api.billing.dev.3pers.com.br/ description: development security: [] tags: - name: Contracts - name: Deals - name: Invoices - name: Invoice Entries - name: Invoice Statements - name: NFSe Configuration - name: Payment Links paths: /realms/{realmId}/organizations/{organizationId}/payment-links/{paymentLinkId}: put: tags: - Payment Links summary: Update a payment link description: Replaces an active payment link with the body sent. operationId: >- putRealmsByRealmIdOrganizationsByOrganizationIdPaymentLinksByPaymentLinkId parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of your organization: the one that sells through the link. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: paymentLinkId in: path required: true description: |- ID of the payment link to update. Format: `UUID` schema: type: string format: uuid example: 5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 2 maxLength: 56 description: >- Name of the link. The checkout page shows it to the payer, and it becomes the description of the deal each checkout creates. example: Plano anual description: description: What the link sells, shown on the checkout page. example: Acesso completo por 12 meses. type: string maxLength: 250 products: minItems: 1 type: array items: type: object properties: product: type: string minLength: 1 description: >- ID of a product of your organization's catalog. It must be active and have a price above zero. example: 8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f quantity: type: integer minimum: 1 description: How many units of the product each checkout sells. example: 1 required: - product - quantity description: >- What the link sells. At least one. The amount charged is the products' current prices times their quantities, read at each checkout. expirationDate: description: >- Last day the link can be paid: an ISO 8601 date (`YYYY-MM-DD`, read as midnight UTC) or a date-time with an offset. Today or later. The link can be paid through that day: the daily expiry run, at 03:01 UTC (00:01 in Brasília) of the following day, turns it `EXPIRED`, which is final. Omitted or `null`: the link never expires. example: '2026-12-31' anyOf: - type: string format: date nullable: true - type: string format: date-time nullable: true type: type: string enum: - RECURRENT - ONE_TIME description: >- `ONE_TIME`: each checkout charges once. `RECURRENT`: each checkout charges `numberOfInstallments` times, monthly. example: ONE_TIME paymentMethod: minItems: 1 type: array items: type: string enum: - BANK_SLIP - PIX_INITIATION - PIX - PIX_AUTOMATIC example: PIX description: >- The ways the payer can choose from at checkout: `BANK_SLIP` (boleto), `PIX` (a PIX charge), `PIX_AUTOMATIC` (PIX Automático: the payer authorizes the recurring payments once) or `PIX_INITIATION` (recurring scheduled PIX, authorized the same way). A `RECURRENT` link with `PIX_AUTOMATIC` needs `numberOfInstallments` above 1 and `firstPaymentDate.pixAutomatic`. --- Example: `["PIX","BANK_SLIP"]` secondaryPaymentMethod: description: >- Other ways each invoice can also be paid, whatever the payer chose — typically `PIX` and/or `BANK_SLIP` alongside `PIX_AUTOMATIC` or `PIX_INITIATION`. --- Example: `["PIX"]` type: array items: type: string enum: - BANK_SLIP - PIX_INITIATION - PIX - PIX_AUTOMATIC example: PIX firstPaymentDate: type: object properties: pix: type: string enum: - SAME_DAY - EXPIRATION_DATE - ONE_DAY - FIVE_DAYS - TEN_DAYS - THIRTY_DAYS - SIXTY_DAYS description: When the first payment is due, for `PIX`. example: SAME_DAY bankSlip: type: string enum: - SAME_DAY - EXPIRATION_DATE - ONE_DAY - FIVE_DAYS - TEN_DAYS - THIRTY_DAYS - SIXTY_DAYS description: When the first payment is due, for `BANK_SLIP`. example: FIVE_DAYS pixAutomatic: type: string enum: - SAME_DAY - EXPIRATION_DATE - ONE_DAY - FIVE_DAYS - TEN_DAYS - THIRTY_DAYS - SIXTY_DAYS description: When the first payment is due, for `PIX_AUTOMATIC`. example: TEN_DAYS description: >- When the first payment of a checkout is due, counted from the checkout day: `SAME_DAY`, `ONE_DAY`, `FIVE_DAYS`, `TEN_DAYS`, `THIRTY_DAYS`, `SIXTY_DAYS`, or `EXPIRATION_DATE` (the link's `expirationDate`; the checkout day when it has none). At least one key. One value applies to every checkout, whatever method the payer picks: `pixAutomatic` when set, otherwise `bankSlip`, otherwise `pix`. numberOfInstallments: description: >- How many monthly payments a checkout of a `RECURRENT` link creates. Above 1 for a `RECURRENT` link with `PIX_AUTOMATIC`. Omitted or `null`: 1. example: 12 type: integer minimum: 1 nullable: true required: - name - products - type - paymentMethod - firstPaymentDate responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: >- ID of the payment link. The checkout page of the link is addressed by it. example: 5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c name: type: string description: Name of the link. example: Plano anual description: type: string description: What the link sells. Absent when it has none. example: Acesso completo por 12 meses. status: type: string enum: - ACTIVE - DEACTIVATED - EXPIRED description: >- `ACTIVE`: payers can check out. `DEACTIVATED`: switched off; it can be activated again. `EXPIRED`: its `expirationDate` passed; final. example: ACTIVE products: type: array items: type: object properties: product: type: string description: ID of the product in your organization's catalog. example: 8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f quantity: type: integer description: How many units of the product each checkout sells. example: 1 required: - product - quantity description: A product the link sells. description: What the link sells. expirationDate: description: >- Last day the link can be paid (midnight UTC of that day), or `null` when it never expires. example: '2026-12-31T00:00:00.000Z' type: string format: date-time nullable: true type: type: string enum: - RECURRENT - ONE_TIME description: >- `ONE_TIME`: each checkout charges once. `RECURRENT`: monthly, `numberOfInstallments` times. example: ONE_TIME paymentMethod: type: array items: type: string enum: - BANK_SLIP - PIX_INITIATION - PIX - PIX_AUTOMATIC example: PIX description: |- The ways the payer can choose from at checkout. --- Example: `["PIX","BANK_SLIP"]` secondaryPaymentMethod: type: array items: type: string enum: - BANK_SLIP - PIX_INITIATION - PIX - PIX_AUTOMATIC example: PIX description: >- Other ways each invoice can also be paid. Empty when there are none. --- Example: `["PIX"]` firstPaymentDate: type: object properties: pix: type: string enum: - SAME_DAY - EXPIRATION_DATE - ONE_DAY - FIVE_DAYS - TEN_DAYS - THIRTY_DAYS - SIXTY_DAYS description: When the first payment is due, for `PIX`. example: SAME_DAY bankSlip: type: string enum: - SAME_DAY - EXPIRATION_DATE - ONE_DAY - FIVE_DAYS - TEN_DAYS - THIRTY_DAYS - SIXTY_DAYS description: When the first payment is due, for `BANK_SLIP`. example: FIVE_DAYS pixAutomatic: type: string enum: - SAME_DAY - EXPIRATION_DATE - ONE_DAY - FIVE_DAYS - TEN_DAYS - THIRTY_DAYS - SIXTY_DAYS description: When the first payment is due, for `PIX_AUTOMATIC`. example: TEN_DAYS description: >- When the first payment of a checkout is due, per payment method. numberOfInstallments: type: integer description: >- How many monthly payments a checkout of a `RECURRENT` link creates, or `null` (1). example: null createdAt: type: string format: date-time description: When the link was created. example: '2026-10-26T14:30:00.000Z' updatedAt: type: string format: date-time description: When the link was last changed. example: '2026-10-26T14:30:00.000Z' required: - id - name - status - products - expirationDate - type - paymentMethod - secondaryPaymentMethod description: A payment link. '404': description: >- `PAYMENT_LINK_NOT_FOUND` — The organization has no payment link with this ID. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - PAYMENT_LINK_NOT_FOUND description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: PAYMENT_LINK_NOT_FOUND origin: BILLING message: Payment link not found '422': description: >- `PAYMENT_LINK_NOT_ACTIVE` — The link is `DEACTIVATED` (activate it first) or `EXPIRED`. `PAYMENT_LINK_INVALID_PRODUCT_STATUS` — A product is not in your organization's catalog, is not active, or has no price above zero. `PAYMENT_LINK_INVALID_EXPIRATION_DATE` — `expirationDate` is before today (UTC). `BAD_REQUEST` — The body is invalid — a missing field, an unknown payment method, no first payment date, a `RECURRENT` PIX Automático link without more than one installment, or a `status` (not accepted: `STATUS_REMOVED`) — or a path parameter is not a valid ID; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - PAYMENT_LINK_NOT_ACTIVE - PAYMENT_LINK_INVALID_PRODUCT_STATUS - PAYMENT_LINK_INVALID_EXPIRATION_DATE - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: PAYMENT_LINK_NOT_ACTIVE origin: BILLING message: Payment link is not active ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.