Toku Intents de consentimiento API

openapi: 3.2.0
info:
  title: Recursos secundarios Intents de consentimiento API
  version: 1.0.0
  description: 'API server-to-server con la que la organización anuncia cada consentimiento que va a pedir, antes de renderizar su formulario. La llama su backend con la api-key de Toku, y el gateway le entrega al servicio la organización en el header `organization-consumer`; una request sin él responde `403`.


    Es lo que habilita el producto: una organización sin credencial no crea intents, y sin intent no hay consentimiento.'
servers:
- description: Production
  url: https://api.trytoku.com
security:
- ApiKeyAuth: []
tags:
- description: 'API server-to-server con la que la organización anuncia cada consentimiento que va a pedir, antes de renderizar su formulario. La llama su backend con la api-key de Toku, y el gateway le entrega al servicio la organización en el header `organization-consumer`; una request sin él responde `403`.


    Es lo que habilita el producto: una organización sin credencial no crea intents, y sin intent no hay consentimiento.'
  name: Intents de consentimiento
paths:
  /consent/intents:
    post:
      description: 'Registra qué se le va a pedir a quién, y devuelve el token con el que el widget lo registra. La organización llama esto **desde su servidor**, antes de renderizar el paso de su formulario.


        **El titular queda anunciado acá y no viaja en el HTML.** El registro copia de este intent el identificador, el documento de identidad, el correo, el teléfono y el nombre, así que nada de lo que el browser mande puede cambiar quién aceptó.


        El `client_token` **se responde una sola vez** —de acá en adelante sólo existe su hash—, vence a los 30 minutos y **registra un solo consentimiento**: reintentar con él devuelve el registro que ya existe en vez de escribir otro. Un formulario con varios agreements necesita un intent por cada uno.


        **El titular tiene que poder encontrarse después**: además del identificador del comercio, trae un documento de identidad —RUT o pasaporte— o un correo. El correo se guarda sin espacios alrededor y en minúsculas.


        Un titular sin ninguno de los dos, un RUT con dígito verificador inválido, un pasaporte que no cumple el formato o un correo sin forma de correo se rechaza acá, antes de que exista una página.


        **Límite de tasa:** 20 solicitudes por segundo. Al superarlo, la API responde `429`. Ver Límites de tasa.'
      operationId: create_intent
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntentCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntentCreatedResponse'
          description: El consentimiento quedó anunciado. Devuelve el `client_token` que va al HTML, una sola vez, y hasta cuándo sirve.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: 'El titular declarado no se sostiene: no trae ni un documento de identidad ni un correo con el que encontrarlo después, el RUT tiene un dígito verificador que no corresponde, el pasaporte no cumple el formato —hasta nueve letras y dígitos—, el correo no tiene la forma de uno, o el identificador del comercio son sólo espacios. Un cuerpo que no cumple el contrato responde `422`.'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: Faltan las credenciales o son inválidas.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: La request no declara una organización en `organization-consumer`.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: El agreement no existe o no es de la organización que llama.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: El cuerpo de la petición no pasó la validación.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: Se superó el límite de peticiones permitidas.
      summary: Anunciar un consentimiento que se va a pedir
      tags:
      - Intents de consentimiento
components:
  schemas:
    IntentCreateRequest:
      properties:
        agreement:
          description: uuid del agreement que el titular va a aceptar, el que la organización ve en el backoffice.
          examples:
          - b3d7c1a2-58f0-4e6d-9c11-7a2e5f0b8d44
          title: Agreement
          type: string
        subject:
          allOf:
          - $ref: '#/components/schemas/ConsentSubjectRequest'
          description: 'Quién va a aceptar, tal como la organización lo conoce. Es lo que queda en el registro: el browser no lo declara y no lo puede cambiar.'
          examples:
          - external_id: cliente-4471
            government_id:
              type: rut
              value: 16.869.976-K
      required:
      - agreement
      - subject
      title: IntentCreateRequest
      type: object
    GovernmentIdRequest:
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/GovernmentIdType'
          description: Tipo del documento de identidad. El titular no siempre tiene RUT, así que el tipo viaja en el registro en vez de adivinarse después mirando el valor.
          examples:
          - rut
        value:
          description: Valor del documento. Un RUT se normaliza —sin puntos, con guion, dígito verificador en mayúscula— y uno con dígito inválido se rechaza; un pasaporte se normaliza en mayúsculas y tiene que ser hasta nueve letras y dígitos, sin puntuación ni espacios.
          examples:
          - 16.869.976-K
          minLength: 1
          title: Value
          type: string
      required:
      - type
      - value
      title: GovernmentIdRequest
      type: object
    ConsentSubjectRequest:
      properties:
        email:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Correo del titular. Se guarda sin espacios alrededor y en minúsculas, y tiene que tener forma de correo: una `@` y ningún espacio. **Hace falta este o el documento de identidad.**'
          examples:
          - javiera.rojas@example.cl
          title: Email
        external_id:
          description: Identificador con el que el comercio ya reconoce al titular en sus propios sistemas.
          examples:
          - cliente-4471
          minLength: 1
          title: External Id
          type: string
        government_id:
          anyOf:
          - $ref: '#/components/schemas/GovernmentIdRequest'
          - type: 'null'
          description: 'Documento de identidad del titular. Sin él, la organización queda sin la recuperación de evidencia por RUT y sus titulares no pueden elegir qué revocan. **Hace falta este o el correo**: un titular sin ninguno de los dos no se podría encontrar después.'
          examples:
          - type: rut
            value: 16.869.976-K
        name:
          anyOf:
          - type: string
          - type: 'null'
          description: Nombre del titular, si el comercio lo capturó.
          examples:
          - Javiera Rojas
          title: Name
        phone:
          anyOf:
          - type: string
          - type: 'null'
          description: Teléfono del titular, si el comercio lo capturó.
          examples:
          - +56 9 8765 4321
          title: Phone
      required:
      - external_id
      title: ConsentSubjectRequest
      type: object
    IntentCreatedResponse:
      properties:
        client_token:
          description: Lo único que va al HTML del comercio. Es opaco para la organización, se responde una sola vez —acá se guarda sólo su hash—, vence a los 30 minutos y registra un solo consentimiento.
          examples:
          - org_dhn3lnrfAjFyWuyEz-8Q3DFaFPnzc9-b.Qm9yZ2VzIGVzIGVsIG1lam9y
          title: Client Token
          type: string
        expires_at:
          description: Momento en que el token deja de servir, en UTC. Después de esto hay que emitir otro.
          examples:
          - '2026-09-09T15:42:00Z'
          format: date-time
          title: Expires At
          type: string
        uuid:
          description: uuid del intent creado, con el que la organización puede reconocerlo después.
          examples:
          - 7c1e9d3a-2b8f-4c6e-9a01-5d3f7b2e8c44
          title: Uuid
          type: string
      required:
      - uuid
      - client_token
      - expires_at
      title: IntentCreatedResponse
      type: object
    ConsentService_ErrorResponse:
      description: Cuerpo de error canónico de la API, con el detalle anidado bajo `error`.
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
      - error
      title: ConsentService_ErrorResponse
      type: object
    ErrorDetail:
      description: 'Detalle de un error de la API: mensaje legible y código interno estable.'
      properties:
        code:
          description: Código de error interno de Toku (formato `TKxxxxx`), estable. El listado completo está en [Códigos de API](/reference/codigos-de-api).
          title: Code
          type: string
        message:
          description: Descripción legible de qué salió mal.
          title: Message
          type: string
      required:
      - message
      - code
      title: ErrorDetail
      type: object
    GovernmentIdType:
      enum:
      - rut
      - passport
      title: GovernmentIdType
      type: string
  securitySchemes:
    ApiKeyAuth:
      description: Toku public API key. Send it in the x-api-key header on every request.
      in: header
      name: x-api-key
      type: apiKey
x-toku-api-version: '2026-10-08'
x-toku-dto-versions:
  DTOAccountPaymentInstrument: DTOAccountPaymentInstrumentV1
  DTOAggregatedPaymentMethod: DTOAggregatedPaymentMethodV2
  DTOAggregatedTransaction: DTOAggregatedTransactionV2
  DTOBankAccountPaymentMethod: DTOBankAccountPaymentMethodV1
  DTOBoletoPaymentInstrument: DTOBoletoPaymentInstrumentV2
  DTOBrPaymentInstrument: DTOBrPaymentInstrumentV2
  DTOCardPaymentInstrument: DTOCardPaymentInstrumentV1
  DTOCardPaymentMethod: DTOCardPaymentMethodV1
  DTOCashClPaymentInstrument: DTOCashClPaymentInstrumentV1
  DTOCashMxPaymentInstrument: DTOCashMxPaymentInstrumentV1
  DTOClPaymentInstrument: DTOClPaymentInstrumentV2
  DTOCustomer: DTOCustomerV2
  DTOInvoice: DTOInvoiceV4
  DTOMxPaymentInstrument: DTOMxPaymentInstrumentV3
  DTOPacManagementPaymentInstrument: DTOPacManagementPaymentInstrumentV1
  DTOPatpassPaymentInstrument: DTOPatpassPaymentInstrumentV1
  DTOPaymentIntent: DTOPaymentIntentV5
  DTOPaymentMethod: DTOPaymentMethodV7
  DTOPixPaymentInstrument: DTOPixPaymentInstrumentV1
  DTOPixPaymentMethod: DTOPixPaymentMethodV1
  DTOReferencedPaymentMXInstrument: DTOReferencedPaymentMXInstrumentV1
  DTOTransaction: DTOTransactionV10
  DTOTransferClPaymentInstrument: DTOTransferClPaymentInstrumentV2
  DTOTransferMxPaymentInstrument: DTOTransferMxPaymentInstrumentV1
  DTOUpdatedFields: DTOUpdatedFieldsV1
  DTOWalletMovement: DTOWalletMovementV1
  DTOWalletPaymentInstrument: DTOWalletPaymentInstrumentV2
x-toku-schema-names:
  ApiPaymentMethod_AssociatePaymentMethodResponse: AssociatePaymentMethodResponse
  ApiPaymentMethod_DTOPaymentMethodV7: PaymentMethod
  ApiPaymentTransaction_DTOTransactionV10: Transaction
  ApiPaymentTransaction_TransactionStatus: TransactionStatus
  ApiRenditionFile_BusinessDaysBeforeFilter: BusinessDaysBeforeFilter
  ApiRenditionFile_DaysBeforeFilter: DaysBeforeFilter
  ApiRenditionFile_DueDatesDaysFutureFilter: DueDatesDaysFutureFilter
  ApiRenditionFile_EntityRestrictions: EntityRestrictions
  ApiRenditionFile_NewestNInvoicesFilter: NewestNInvoicesFilter
  ApiRenditionFile_OldestNInvoicesFilter: OldestNInvoicesFilter
  CheckoutApi_AccountDetailsResponse: AccountDetailsResponse
  CheckoutApi_CheckoutSessionResponse: CheckoutSession
  ClientPaymentPortalBackend_CheckoutSessionResponse: CheckoutSessionResponse
  CollectionStrategist_InstitutionId: InstitutionId
  CollectionStrategist_SubTreeConfiguration: SubTreeConfiguration
  DTOAccountPaymentInstrumentV1: AccountPaymentInstrument
  DTOAggregatedTransactionV2: AggregatedTransaction
  DTOAppliedAdjustmentDocumentV1: AppliedAdjustmentDocument
  DTOBoletoPaymentInstrumentV2: BoletoPaymentInstrument
  DTOBrPaymentInstrumentV2: BrPaymentInstrument
  DTOCardPaymentInstrumentV1: CardPaymentInstrument
  DTOCardPaymentMethodV1: CardPaymentMethod
  DTOCashClPaymentInstrumentV1: CashClPaymentInstrument
  DTOCashMxPaymentInstrumentV1: CashMxPaymentInstrument
  DTOClPaymentInstrumentV2: ClPaymentInstrument
  DTOInvoiceV4: Invoice
  DTOMxPaymentInstrumentV3: MxPaymentInstrument
  DTOPacManagementPaymentInstrumentV1: PacManagementPaymentInstrument
  DTOPatpassPaymentInstrumentV1: PatpassPaymentInstrument
  DTOPaymentIntentV5: PaymentIntent
  DTOPixPaymentInstrumentV1: PixPaymentInstrument
  DTOPixPaymentMethodV1: PixPaymentMethod
  DTOReferencedPaymentMXInstrumentV1: ReferencedPaymentMXInstrument
  DTOTransferClPaymentInstrumentV2: TransferClPaymentInstrument
  DTOTransferMxPaymentInstrumentV1: TransferMxPaymentInstrument
  DTOUpdatedFieldsV1: UpdatedFields
  DTOWalletMovementV1: WalletMovement
  DTOWalletPaymentInstrumentV2: WalletPaymentInstrument
  GetCustomerResponse: Customer
  GetSubscriptionResponse: Subscription
  PayoutsBeneficiaryService_ApprovalFlowsStatus: ApprovalFlowsStatus
  PayoutsBeneficiaryService_Beneficiary: Beneficiary
  PayoutsBeneficiaryService_BeneficiaryAccount: BeneficiaryAccount
  PayoutsBeneficiaryService_BeneficiaryAccountVerification: BeneficiaryAccountVerification
  PayoutsBeneficiaryService_IdentityDocument: IdentityDocument
  PayoutsBeneficiaryService_VerificationStatus: VerificationStatus
  PayoutsDataIngestionService_DisbursementType: DisbursementType
  WebhookEndpointResponse: WebhookEndpoint
x-provenance:
  method: searched
  source: https://docs.trytoku.com/reference
  harvested: '2026-10-29'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.trytoku.com/reference/associate_subscription.md
  - https://docs.trytoku.com/reference/associate_subscription_bulk.md
  - https://docs.trytoku.com/reference/bulk_inscriptions_public.md
  - https://docs.trytoku.com/reference/cancel_billing_document.md
  - https://docs.trytoku.com/reference/cancel_preauth_endpoint.md
  - https://docs.trytoku.com/reference/capture_preauth_endpoint.md
  - https://docs.trytoku.com/reference/change_subscription_status.md
  - https://docs.trytoku.com/reference/create_adjustment_document.md
  - https://docs.trytoku.com/reference/create_beneficiaries.md
  - https://docs.trytoku.com/reference/create_bulk_automatic_debit_payment_methods.md
  - https://docs.trytoku.com/reference/create_credit_note.md
  - https://docs.trytoku.com/reference/create_customer.md
  - https://docs.trytoku.com/reference/create_customer_billing_data.md
  - https://docs.trytoku.com/reference/create_customer_billing_data_bulk.md
  - https://docs.trytoku.com/reference/create_document.md
  - https://docs.trytoku.com/reference/create_external_transaction.md
  - https://docs.trytoku.com/reference/create_external_transactions.md
  - https://docs.trytoku.com/reference/create_handler.md
  - https://docs.trytoku.com/reference/create_intent.md
  - https://docs.trytoku.com/reference/create_invoice_billing_data.md
  - https://docs.trytoku.com/reference/create_m2m_access_token.md
  - https://docs.trytoku.com/reference/create_or_update_invoice.md
  - https://docs.trytoku.com/reference/create_or_update_subscription.md
  - https://docs.trytoku.com/reference/create_pacs.md
  - https://docs.trytoku.com/reference/create_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/create_ppd_billing_document.md
  - https://docs.trytoku.com/reference/create_ppd_complement_billing_document.md
  - https://docs.trytoku.com/reference/create_ppd_complement_from_wallet_movement_billing_document.md
  - https://docs.trytoku.com/reference/create_public_validator_execution.md
  - https://docs.trytoku.com/reference/create_pue_billing_document.md
  - https://docs.trytoku.com/reference/create_receipt.md
  - https://docs.trytoku.com/reference/create_referenced_payment_mx_reference_endpoint.md
  - https://docs.trytoku.com/reference/create_terminal.md
  - https://docs.trytoku.com/reference/create_transfer_clabe_account.md
  - https://docs.trytoku.com/reference/create_webhook_endpoint.md
  - https://docs.trytoku.com/reference/delete_customer.md
  - https://docs.trytoku.com/reference/delete_customer_collection_account_endpoint.md
  - https://docs.trytoku.com/reference/delete_external_transaction.md
  - https://docs.trytoku.com/reference/delete_external_transactions.md
  - https://docs.trytoku.com/reference/delete_invoice.md
  - https://docs.trytoku.com/reference/delete_pacs.md
  - https://docs.trytoku.com/reference/delete_payment_method.md
  - https://docs.trytoku.com/reference/delete_subscription.md
  - https://docs.trytoku.com/reference/delete_terminal.md
  - https://docs.trytoku.com/reference/download_pdf_for_transaction.md
  - https://docs.trytoku.com/reference/edit_customer.md
  - https://docs.trytoku.com/reference/edit_invoice.md
  - https://docs.trytoku.com/reference/edit_invoice_billing_data.md
  - https://docs.trytoku.com/reference/edit_subscription.md
  - https://docs.trytoku.com/reference/edit_webhook_endpoint.md
  - https://docs.trytoku.com/reference/enroll_carteira_boleto.md
  - https://docs.trytoku.com/reference/expire_checkout_session_endpoint.md
  - https://docs.trytoku.com/reference/expire_handler.md
  - https://docs.trytoku.com/reference/expire_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/external_boleto_initialize.md
  - https://docs.trytoku.com/reference/external_onetime_initialize.md
  - https://docs.trytoku.com/reference/generate_report.md
  - https://docs.trytoku.com/reference/get_account_verifications_by_batch.md
  - https://docs.trytoku.com/reference/get_adjustment_document.md
  - https://docs.trytoku.com/reference/get_bank_account_verification_by_id.md
  - https://docs.trytoku.com/reference/get_bank_account_verifications.md
  - https://docs.trytoku.com/reference/get_beneficiary_accounts.md
  - https://docs.trytoku.com/reference/get_billing_document.md
  - https://docs.trytoku.com/reference/get_checkout_session_endpoint_v2.md
  - https://docs.trytoku.com/reference/get_customer.md
  - https://docs.trytoku.com/reference/get_customer_billing_data.md
  - https://docs.trytoku.com/reference/get_customer_collection_account_endpoint.md
  - https://docs.trytoku.com/reference/get_customers.md
  - https://docs.trytoku.com/reference/get_handler.md
  - https://docs.trytoku.com/reference/get_invoice.md
  - https://docs.trytoku.com/reference/get_invoice_billing_data.md
  - https://docs.trytoku.com/reference/get_paginated_chargeable_invoices.md
  - https://docs.trytoku.com/reference/get_payment_method.md
  - https://docs.trytoku.com/reference/get_payment_method_by_id.md
  - https://docs.trytoku.com/reference/get_payment_methods.md
  - https://docs.trytoku.com/reference/get_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/get_public_transactions.md
  - https://docs.trytoku.com/reference/get_receipt.md
  - https://docs.trytoku.com/reference/get_report_columns.md
  - https://docs.trytoku.com/reference/get_signed_document_url.md
  - https://docs.trytoku.com/reference/get_subscription.md
  - https://docs.trytoku.com/reference/get_subscriptions.md
  - https://docs.trytoku.com/reference/get_terminal.md
  - https://docs.trytoku.com/reference/get_transaction.md
  - https://docs.trytoku.com/reference/get_transaction_data_for_refund.md
  - https://docs.trytoku.com/reference/get_transaction_fees_public.md
  - https://docs.trytoku.com/reference/get_transfer_clabe_account.md
  - https://docs.trytoku.com/reference/get_webhook_endpoint.md
  - https://docs.trytoku.com/reference/get_webhook_endpoints.md
  - https://docs.trytoku.com/reference/get_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/ingest_payout_request_input.md
  - https://docs.trytoku.com/reference/initialize_enrollment_pix.md
  - https://docs.trytoku.com/reference/initialize_push_notification_enrollment.md
  - https://docs.trytoku.com/reference/list_adjustment_documents.md
  - https://docs.trytoku.com/reference/list_customer_invoices.md
  - https://docs.trytoku.com/reference/list_invoices.md
  - https://docs.trytoku.com/reference/list_invoices_by_customer.md
  - https://docs.trytoku.com/reference/list_payout_request_items.md
  - https://docs.trytoku.com/reference/list_payouts.md
  - https://docs.trytoku.com/reference/list_subject_consents.md
  - https://docs.trytoku.com/reference/list_terminals.md
  - https://docs.trytoku.com/reference/lookup_customer.md
  - https://docs.trytoku.com/reference/lookup_invoice.md
  - https://docs.trytoku.com/reference/lookup_subscription.md
  - https://docs.trytoku.com/reference/open_checkout_session_endpoint.md
  - https://docs.trytoku.com/reference/patch_beneficiary_account_data.md
  - https://docs.trytoku.com/reference/patch_beneficiary_account_external_id.md
  - https://docs.trytoku.com/reference/patch_beneficiary_metadata.md
  - https://docs.trytoku.com/reference/patch_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/pos_charge_endpoint.md
  - https://docs.trytoku.com/reference/post_customer_collection_account_endpoint.md
  - https://docs.trytoku.com/reference/post_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/public_available_institutions.md
  - https://docs.trytoku.com/reference/public_start_create_cash_mx_reference.md
  - https://docs.trytoku.com/reference/public_update_checkout_session_endpoint.md
  - https://docs.trytoku.com/reference/refund_invoice_public.md
  - https://docs.trytoku.com/reference/refund_transaction_public.md
  - https://docs.trytoku.com/reference/soft_delete_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/subscriptions_by_customer.md
  - https://docs.trytoku.com/reference/undo_debt_reconciliation_by_invoice_endpoint.md
  - https://docs.trytoku.com/reference/update_adjustment_document.md
  - https://docs.trytoku.com/reference/update_customer_billing_data.md
  - https://docs.trytoku.com/reference/update_external_transaction.md
  - https://docs.trytoku.com/reference/update_external_transactions.md
  - https://docs.trytoku.com/reference/update_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/update_terminal.md
  - https://docs.trytoku.com/reference/upload_external_pdf.md
  - https://docs.trytoku.com/reference/validate_handler.md
  - https://docs.trytoku.com/reference/verify_bank_account.md
  - https://docs.trytoku.com/reference/verify_public_bulk_bank_accounts.md
  - https://docs.trytoku.com/reference/void_invoice.md
  merge:
    pages: 131
    deduped: 757
    conflicts_kept_first: 0