Payment settings

Download the full API pública projection: openapi.json.

Charge and reconcile payments explains this resource in prose, with runnable examples.

GET /payment-settingsCopy Anchor Link

How this business charges, and its Mercado Pago connection

charging.reservation (refundable reservations: booking deposits, vehicle reservation deposits) and charging.final (balances, budgets, packs, services), each with the effective mode, whether it is the workspace's choice or the vertical default (source), and the default_mode. Defaults: healthcare mp_first for both; automotive transfer_first for reservations (a Mercado Pago refund does not return the commission) and mp_first for final payments; any other vertical mp_first. provider is which connected provider payment links go through (preferred: the business's choice or null; active: what a new link would use now or null when none is connected; connected: every connected provider, which the buyer chooses among on the link page when there are two or more); webpay is the Webpay Plus connection status and fintoc, flow, khipu and bancame the Fintoc, Flow, Khipu and banca.me («cuotas sin tarjeta») ones. mercadopago is the connection status plus configured (the environment can connect at all). installments.min_clp: from which amount a final-charge link offers cuotas (null = off). budgets.accept_charge: what a presupuesto's «aceptar y pagar» charges (full | first_installment). Requires tenant_bank_accounts:read (or clinic_money:read).

curl https://api.vitrinadev.com/api/v1/payment-settings \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "charging": {
      "reservation": {
        "mode": "transfer_first",
        "source": "default",
        "default_mode": "transfer_first"
      },
      "final": {
        "mode": "mp_first",
        "source": "tenant",
        "default_mode": "mp_first"
      }
    },
    "provider": {
      "preferred": "webpay",
      "active": "webpay",
      "connected": [
        "mercadopago",
        "webpay",
        "fintoc",
        "flow",
        "khipu",
        "bancame"
      ]
    },
    "webpay": {
      "connected": true,
      "environment": "integration",
      "commerce_code": "597055555532",
      "api_key_preview": "579B••••1C",
      "connected_at": "2026-10-20T14:00:00.000Z"
    },
    "fintoc": {
      "connected": true,
      "mode": "test",
      "secret_key_preview": "••••Ab12",
      "connected_at": "2026-10-20T14:00:00.000Z"
    },
    "flow": {
      "connected": true,
      "environment": "sandbox",
      "api_key": "flow-api-key-example",
      "secret_key_preview": "4c1a••••9e",
      "connected_at": "2026-10-20T14:00:00.000Z"
    },
    "khipu": {
      "connected": true,
      "api_key_preview": "9d2f••••a7",
      "connected_at": "2026-10-20T14:00:00.000Z"
    },
    "bancame": {
      "connected": true,
      "environment": "automation",
      "merchant_entity": "ex-46df3310759e9000",
      "public_key": "pk_bancame_example",
      "private_key_preview": "eyJh••••c5",
      "connected_at": "2026-11-02T14:00:00.000Z"
    },
    "installments": {
      "min_clp": null
    },
    "budgets": {
      "accept_charge": "full"
    },
    "mercadopago": {
      "connected": true,
      "mp_user_id": "1234567890",
      "mp_nickname": "AUTOMOTORAEJEMPLO",
      "environment": "production",
      "connected_at": "2026-10-08T14:00:00.000Z",
      "last_sync_at": "2026-10-08T15:00:00.000Z",
      "last_sync_status": "ok",
      "last_sync_error": null,
      "configured": true
    }
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/bancame/connectCopy Anchor Link

Connect the business's own banca.me account

Connects the business's OWN banca.me partner account (buy now, pay later: the buyer pays in installments from a bank account, no card; banca.me pays the business). The money never passes through Vitrina. The private key is verified against banca.me (400 bancame_key_rejected when banca.me refuses it), then the merchant (400 bancame_entity_rejected for an unknown or inactive merchant_entity or one without BNPL), then Vitrina registers its loan_approved webhook on the account (400 bancame_webhook_limit when the account already has 10 active webhooks) and stores the private key and the webhook secret encrypted; nothing is stored when a step fails. Use automation to try it with banca.me’s fixed test outcomes. A reconnect replaces the credentials and the webhook. Requires tenant_bank_accounts:write (or clinic_money:write).

Body

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/bancame/connect \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "private_key": "<your partner Private Key>",
    "public_key": "<your partner Public Key>",
    "merchant_entity": "ex-46df3310759e9000",
    "environment": "automation"
  }'

Example response (200)

{
  "data": {
    "connected": true,
    "environment": "automation",
    "merchant_entity": "ex-46df3310759e9000",
    "public_key": "pk_bancame_example",
    "private_key_preview": "eyJh••••c5",
    "connected_at": "2026-11-02T14:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/bancame/disconnectCopy Anchor Link

Disconnect banca.me

Reversible: the connection survives disabled and a later connect re-enables it (with a new webhook). Vitrina deactivates its webhook on the account. Payment links fall back to another connected provider or the transfer. Requires tenant_bank_accounts:write (or clinic_money:write).

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/bancame/disconnect \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /payment-settings/bancame/statusCopy Anchor Link

banca.me connection status

Whether a banca.me partner account («cuotas sin tarjeta») is connected: its environment, merchant merchant_entity (banca.me’s entityId), public_key (not a secret) and a masked private_key_preview. The private key and the webhook secret are never returned. Requires tenant_bank_accounts:read (or clinic_money:read).

curl https://api.vitrinadev.com/api/v1/payment-settings/bancame/status \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "connected": true,
    "environment": "automation",
    "merchant_entity": "ex-46df3310759e9000",
    "public_key": "pk_bancame_example",
    "private_key_preview": "eyJh••••c5",
    "connected_at": "2026-11-02T14:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

PUT /payment-settings/budgetsCopy Anchor Link

Set what «aceptar y pagar» charges for a presupuesto

When the charging preference offers a Mercado Pago link for final charges, the public presupuesto page offers «aceptar y pagar». accept_charge decides its amount: full (default) or first_installment (the accepted amount divided by the presupuesto's installments). Returns the saved choice. Requires tenant_bank_accounts:write (or clinic_money:write).

Body

curl -X PUT https://api.vitrinadev.com/api/v1/payment-settings/budgets \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accept_charge": "first_installment"
  }'

Example response (200)

{
  "data": {
    "accept_charge": "first_installment"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

PUT /payment-settings/chargingCopy Anchor Link

Set how this business charges, per charge type

Pass reservation and/or final; null resets that type to the vertical default, an omitted type is left as it is. Every payment block (the agent booking tools, the hosted booking page) follows it. Returns the resolved preference. Requires tenant_bank_accounts:write (or clinic_money:write).

Body

curl -X PUT https://api.vitrinadev.com/api/v1/payment-settings/charging \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reservation": "transfer_first",
    "final": null
  }'

Example response (200)

{
  "data": {
    "reservation": {
      "mode": "transfer_first",
      "source": "default",
      "default_mode": "transfer_first"
    },
    "final": {
      "mode": "mp_first",
      "source": "tenant",
      "default_mode": "mp_first"
    }
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/fintoc/connectCopy Anchor Link

Connect the business's own Fintoc account

Connects the business's OWN Fintoc account with its secret key; the money never passes through Vitrina. The key is verified against Fintoc (400 when Fintoc rejects it), a webhook endpoint pointing at Vitrina is registered on that account, and the key and the endpoint secret are stored encrypted. A test-mode key is Fintoc’s sandbox (test banks, no real money); a live-mode key charges real transfers. A reconnect replaces the credentials and the endpoint. Requires tenant_bank_accounts:write (or clinic_money:write).

Body

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/fintoc/connect \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_key": "<your Fintoc secret key>"
  }'

Example response (200)

{
  "data": {
    "connected": true,
    "mode": "test",
    "secret_key_preview": "••••Ab12",
    "connected_at": "2026-10-20T14:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/fintoc/disconnectCopy Anchor Link

Disconnect Fintoc

Reversible: removes the webhook endpoint Vitrina registered and disables the connection; a later connect re-enables it. Payment links fall back to another connected provider or the transfer. Requires tenant_bank_accounts:write (or clinic_money:write).

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/fintoc/disconnect \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /payment-settings/fintoc/statusCopy Anchor Link

Fintoc connection status

Connected mode (test | live) and a masked key preview, or connected: false. The secret is never returned. Requires tenant_bank_accounts:read (or clinic_money:read).

curl https://api.vitrinadev.com/api/v1/payment-settings/fintoc/status \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "connected": true,
    "mode": "test",
    "secret_key_preview": "••••Ab12",
    "connected_at": "2026-10-20T14:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/flow/connectCopy Anchor Link

Connect the business's own Flow commerce

Connects the business's OWN Flow commerce (API Key + Secret Key); the money never passes through Vitrina. The pair is verified against Flow for the chosen environment before it is stored encrypted: 400 when Flow rejects it. Use sandbox (sandbox.flow.cl) to try it without real money. A reconnect replaces the credentials. Requires tenant_bank_accounts:write (or clinic_money:write).

Body

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/flow/connect \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "flow-api-key-example",
    "secret_key": "<your commerce Secret Key>",
    "environment": "sandbox"
  }'

Example response (200)

{
  "data": {
    "connected": true,
    "environment": "sandbox",
    "api_key": "flow-api-key-example",
    "secret_key_preview": "4c1a••••9e",
    "connected_at": "2026-10-20T14:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/flow/disconnectCopy Anchor Link

Disconnect Flow

Reversible: the connection survives disabled and a later connect re-enables it. Payment links fall back to another connected provider or the transfer. Requires tenant_bank_accounts:write (or clinic_money:write).

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/flow/disconnect \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /payment-settings/flow/statusCopy Anchor Link

Flow connection status

Connected API key, environment and a masked secret key preview, or connected: false. The secret is never returned. Requires tenant_bank_accounts:read (or clinic_money:read).

curl https://api.vitrinadev.com/api/v1/payment-settings/flow/status \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "connected": true,
    "environment": "sandbox",
    "api_key": "flow-api-key-example",
    "secret_key_preview": "4c1a••••9e",
    "connected_at": "2026-10-20T14:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

PUT /payment-settings/installmentsCopy Anchor Link

Set from which amount a payment link offers installments

From min_clp CLP up, a Mercado Pago link for a FINAL charge (balance, budget, pack) offers installments («cuotas»); null turns them off (the default). Reservations and deposits are always one payment. Returns the saved threshold. Requires tenant_bank_accounts:write (or clinic_money:write).

Body

curl -X PUT https://api.vitrinadev.com/api/v1/payment-settings/installments \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "min_clp": 200000
  }'

Example response (200)

{
  "data": {
    "min_clp": 200000
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/khipu/connectCopy Anchor Link

Connect the business's own Khipu account

Connects the business's OWN Khipu collection account with its secret key; the money never passes through Vitrina. The key is verified against Khipu before it is stored encrypted: 400 when Khipu rejects it. Khipu has no separate sandbox: a developer collection account accepts only Khipu's DemoBank test bank, so connect one to try it without real money. A reconnect replaces the key. Requires tenant_bank_accounts:write (or clinic_money:write).

Body

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/khipu/connect \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<your collection account secret key>"
  }'

Example response (200)

{
  "data": {
    "connected": true,
    "api_key_preview": "9d2f••••a7",
    "connected_at": "2026-10-20T14:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/khipu/disconnectCopy Anchor Link

Disconnect Khipu

Reversible: the connection survives disabled and a later connect re-enables it. Payment links fall back to another connected provider or the transfer. Requires tenant_bank_accounts:write (or clinic_money:write).

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/khipu/disconnect \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /payment-settings/khipu/statusCopy Anchor Link

Khipu connection status

Whether a Khipu collection account is connected, with a masked key preview. The secret is never returned. Requires tenant_bank_accounts:read (or clinic_money:read).

curl https://api.vitrinadev.com/api/v1/payment-settings/khipu/status \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "connected": true,
    "api_key_preview": "9d2f••••a7",
    "connected_at": "2026-10-20T14:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/mercadopago/connectCopy Anchor Link

Start the Mercado Pago OAuth consent flow

Returns the consent URL for a person to open. Connects the business's OWN Mercado Pago account, never Vitrina's. return_to is where the browser lands after the callback. Requires tenant_bank_accounts:write (or clinic_money:write).

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/mercadopago/connect \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "url": "https://auth.mercadopago.cl/authorization?client_id=4688094843266502&response_type=code&platform_id=mp&state=…"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/mercadopago/disconnectCopy Anchor Link

Disconnect the Mercado Pago account

Reversible: the connection survives disabled and a later reconnect re-enables it. Payment blocks fall back to the transfer. Requires tenant_bank_accounts:write (or clinic_money:write).

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/mercadopago/disconnect \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /payment-settings/mercadopago/statusCopy Anchor Link

Mercado Pago connection status

Connected as … / last sync / last sync error, or connected: false. Requires tenant_bank_accounts:read (or clinic_money:read).

curl https://api.vitrinadev.com/api/v1/payment-settings/mercadopago/status \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "connected": true,
    "mp_user_id": "1234567890",
    "mp_nickname": "AUTOMOTORAEJEMPLO",
    "environment": "production",
    "connected_at": "2026-10-08T14:00:00.000Z",
    "last_sync_at": "2026-10-08T15:00:00.000Z",
    "last_sync_status": "ok",
    "last_sync_error": null
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/mercadopago/syncCopy Anchor Link

Sincronizar ahora — enqueue an incremental pull

Enqueues the same job the daily tick uses; dedups with an in-flight sync. 400 when nothing is connected. Requires tenant_bank_accounts:write (or clinic_money:write).

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/mercadopago/sync \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (202)

{
  "data": {
    "enqueued": true
  }
}

Answers: 202 · 400 · 401 · 403 · 404 · 409 · 429

PUT /payment-settings/providerCopy Anchor Link

Choose which connected provider payment links use

When the business connected more than one customer payment provider (Mercado Pago, Webpay Plus, Fintoc, Flow, Khipu, banca.me), payment links go through the one chosen here; null clears the choice (the first connected one is used). A choice that is not connected is ignored at link time. Returns the choice and the provider a new link would use now. Requires tenant_bank_accounts:write (or clinic_money:write).

Body

curl -X PUT https://api.vitrinadev.com/api/v1/payment-settings/provider \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "webpay"
  }'

Example response (200)

{
  "data": {
    "preferred": "webpay",
    "active": "webpay"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/webpay/connectCopy Anchor Link

Connect the business's own Webpay Plus commerce

Connects the business's OWN Transbank commerce (code + API key secret); the money never passes through Vitrina. The pair is verified against Transbank for the chosen environment before it is stored encrypted: 400 when Transbank rejects it. Use integration with Transbank's public test commerce to try it with test cards. A reconnect replaces the credentials. Requires tenant_bank_accounts:write (or clinic_money:write).

Body

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/webpay/connect \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commerce_code": "597055555532",
    "api_key_secret": "<your commerce API key secret>",
    "environment": "integration"
  }'

Example response (200)

{
  "data": {
    "connected": true,
    "environment": "integration",
    "commerce_code": "597055555532",
    "api_key_preview": "579B••••1C",
    "connected_at": "2026-10-20T14:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /payment-settings/webpay/disconnectCopy Anchor Link

Disconnect Webpay Plus

Reversible: the connection survives disabled and a later connect re-enables it. Payment links fall back to another connected provider or the transfer. Requires tenant_bank_accounts:write (or clinic_money:write).

curl -X POST https://api.vitrinadev.com/api/v1/payment-settings/webpay/disconnect \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /payment-settings/webpay/statusCopy Anchor Link

Webpay Plus connection status

Connected commerce code, environment and a masked key preview, or connected: false. The secret is never returned. Requires tenant_bank_accounts:read (or clinic_money:read).

curl https://api.vitrinadev.com/api/v1/payment-settings/webpay/status \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "connected": true,
    "environment": "integration",
    "commerce_code": "597055555532",
    "api_key_preview": "579B••••1C",
    "connected_at": "2026-10-20T14:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429