# Update payment gateway settings

```http
PUT https://secure.yoprint.com/v1/api/store/{team_slug}/setting/payment_gateway
```

- API version: v1
- Operation ID: `v1_public_setting_payment_gateway_update`
- Section: Team settings › [Payment gateways](https://developer.yoprint.com/reference/payment-gateways.md)
- Web page: https://developer.yoprint.com/reference/payment-gateways/v1-setting-payment-gateway-update/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Turns card payment gateways on or off and stores their credentials: Stripe, PayPal, Square, Charge It Pro and Authorize.Net. Returns the team settings, as Show team settings does.

Send only the gateways you are changing; stored values you leave out stay as they are. Turning a gateway off (`enable_stripe: false`, for example) keeps its stored credentials.

Before saving, YoPrint checks the credentials with the provider and sets up the provider's notifications to YoPrint:

- **Stripe:** reads your Stripe account with the key, then creates or updates a webhook endpoint in your Stripe account, pointing at `stripe_webhook_url`, for refunds (`charge.refunded`, `charge.refund.updated`, `refund.created`, `refund.updated`, `refund.failed`), disputes (`charge.dispute.created`, `.updated`, `.closed`, `.funds_withdrawn`, `.funds_reinstated`) and payments (`payment_intent.succeeded`, `payment_intent.payment_failed`, `payment_intent.canceled`). An existing endpoint on another Stripe API version is deleted and made again.
- **PayPal:** checks the credentials (they must be live), then creates or updates a PayPal webhook for payment capture, refund and dispute events.
- **Square:** for each location in `square_webhook_locations`, turns on Square's `PAYMENT_UPDATED` notification. Add YoPrint's `square_webhook_url` in the Square Developer Dashboard first.
- **Authorize.Net:** checks the login id, transaction key and client key, then creates a webhook.
- **Charge It Pro** (Gravity Payments in the web app) is being retired. You can't connect it as a new gateway: the call is refused with 422 `charge_it_pro_retired`. A team that already has it on can still change its settings, until Charge It Pro is retired (planned for 1 January 2027). Turning it off while a payment is still being processed is refused with 422 `charge_it_pro_payment_in_progress`: try again later. Connect another gateway to take card payments. For a team that can still save its settings, YoPrint doesn't call Gravity Payments: when `charge_it_pro_oid` or `charge_it_pro_auth_key` differs from the stored value, it checks only that both are present and not too long.

When the save changes a gateway's credentials, YoPrint records who changed which gateway (never the values) and emails the team owner.

This operation only configures gateways. Card charges and refunds go through the sales order payment operations (see Related).

## Permission

Needs the Manage Settings permission.

## Business rules

- Turning a gateway on (`enable_*: true`) requires all of its credential fields in the same request.
- The Stripe secret key must start with `sk_live_`, `sk_test_`, `rk_live_` or `rk_test_`, and the publishable key with `pk_live_` or `pk_test_`, followed by letters and digits only.
- Each gateway is checked only when it is being turned on in this request. Charge It Pro is checked only when its org id or auth key also changes: each must be non-blank, the org id at most 100 characters and the key at most 4,096 (surrounding spaces ignored).
- YoPrint checks the gateways in this order: Square, Stripe, Charge It Pro, PayPal, Authorize.Net. The first refusal ends the request and nothing is saved in YoPrint, but webhook changes already made at providers checked earlier in the same request stay.

## Side effects

- Calls the providers to check credentials and to create or update their webhooks (Stripe, PayPal, Square, Authorize.Net). No money moves.
- Stores the credentials with the team.
- When a credential field changes (a Stripe key, PayPal client id or secret, Square application id, access token, location id or signature key, Charge It Pro org id, auth key or device id, or an Authorize.Net key), YoPrint records a security event naming who changed which gateway and fields, never the values, and emails the team owner which gateways changed and who changed them. Re-sending the stored values, or only turning a gateway off, records and sends nothing.

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.

## Request body

Content type `application/json`, required.

Fields:

- `authorize_client_key` (string, optional): Your public client key. Required when `enable_authorize_net` is true.
- `authorize_login_id` (string, optional): Required when `enable_authorize_net` is true.
- `authorize_sig_key` (string, optional): Your signature key. Required when `enable_authorize_net` is true.
- `authorize_trans_key` (string, optional): Required when `enable_authorize_net` is true.
- `charge_it_pro_auth_key` (string, optional): Retired. Required when `enable_charge_it_pro` is true.
- `charge_it_pro_device_id` (string, optional): Retired. The default card device. Required when `charge_it_pro_mode` is `in-person` or `both`.
- `charge_it_pro_mode` (string, optional): Retired. Required when `enable_charge_it_pro` is true. One of: `"in-person"`, `"online"`, `"both"`.
- `charge_it_pro_oid` (string, optional): Retired. Required when `enable_charge_it_pro` is true.
- `enable_authorize_net` (boolean, optional): Turns Authorize.Net on or off.
- `enable_charge_it_pro` (boolean, optional): Retired. Turns Charge It Pro off. Turning it on for a team that does not already have it is refused with 422 `charge_it_pro_retired`.
- `enable_paypal` (boolean, optional): Turns PayPal on or off.
- `enable_square` (boolean, optional): Turns Square on or off.
- `enable_square_payment` (boolean, optional): Whether online payments go to Square. Required when `enable_square` is true.
- `enable_stripe` (boolean, optional): Turns Stripe card payments on or off.
- `paypal_client_id` (string, optional): Required when `enable_paypal` is true. Use live credentials.
- `paypal_secret` (string, optional): Required when `enable_paypal` is true.
- `publishable_key` (string, optional): Your Stripe publishable key, starting with `pk_live_` or `pk_test_`. Required when `enable_stripe` is true.
- `square_access_token` (string, optional): Required when `enable_square` is true.
- `square_client_id` (string, optional): Your Square application id. Required when `enable_square` is true.
- `square_location_id` (string, optional): The Square location online payments are credited to. Required when `enable_square_payment` is true. Get ids from List Square locations.
- `square_webhook_locations` (array of objects, optional): The Square locations whose payments YoPrint listens to. Required when `enable_square` is true.
  - Each item:
    - `id` (string, required): A Square location id.
- `square_webhook_sig` (string, optional): The signature key of the webhook you added in Square. Required when `enable_square` is true.
- `stripe_secret_key` (string, optional): Your Stripe secret key (`sk_live_`, `sk_test_`) or restricted key (`rk_live_`, `rk_test_`). A restricted key needs Accounts (under Connect) set to Read and Webhook Endpoints set to Write. Required when `enable_stripe` is true.

### Example request

```bash
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/payment_gateway' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "enable_paypal": false
  }'
```

Another example: Turn on Stripe:

```bash
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/payment_gateway' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "enable_stripe": true,
    "publishable_key": "YOUR_PUBLISHABLE_KEY",
    "stripe_secret_key": "YOUR_GATEWAY_SECRET"
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required): Every stored team setting, keyed by name, with defaults filled in for the display options, and the team's stored payment gateway values: all of them for the team owner and members with Manage Settings, only the account identifiers for other members (see Show team settings).
  - `cust_msg_status` (boolean, optional)
  - `customer_portal_account_login_available` (boolean, optional): Worked out by YoPrint: whether customers can sign in to your customer portal with an email account. True when your plan includes the customer portal.
  - `customer_portal_rollout` (object, optional): Worked out by YoPrint: where the customer portal's move to email-account sign-in stands for your team. YoPrint sets the dates; you can't change them here.
    - `account_only` (boolean, required): True when customers must sign in with an email account: a direct portal link alone no longer opens the portal.
    - `all_teams_at` (string (date-time) | null, required): When account login becomes mandatory for all teams (UTC), or null if not set.
    - `configuration_warning` (string | null, required): A system warning if rollout dates are inconsistent (`new_teams_cutoff_not_before_all_teams_cutoff` or `invalid_rollout_date`), or null. One of: `"new_teams_cutoff_not_before_all_teams_cutoff"`, `"invalid_rollout_date"`.
    - `legacy_access_allowed` (boolean, required): True when direct portal links still open the portal without an account sign-in.
    - `new_teams_at` (string (date-time) | null, required): When account login became mandatory for new teams (UTC), or null if not set.
    - `reason` (string, required): Why this rollout policy applies to your team: `transition` (standard rollout period), `new_team_cutoff` (new team policy), or `all_teams_cutoff` (mandatory for all teams). One of: `"transition"`, `"new_team_cutoff"`, `"all_teams_cutoff"`.
  - `default_pricing_strategy` (string, optional): How new jobs are priced by default. `job_separately` when never set. One of: `"job_separately"`, `"job_together"`, `"service_loc_together"`.
  - `enable_stripe` (boolean, optional): Present once it was sent to Update payment gateway settings, with the value sent. The same for `enable_paypal`, `enable_square`, `enable_square_payment`, `enable_charge_it_pro`, `enable_authorize_net` and `charge_it_pro_mode`.
  - `payment_amount_policies` (object | array, optional): Read only: the minimum payment policy for each of your currencies (deleted ones included), keyed by ISO currency code. An empty list `[]` when the team has no currencies.
  - `payment_amount_policy` (object | null, optional): Read only: the smallest payment YoPrint accepts in your default currency, or null when the team has no default currency.
    - `currency` (string, optional): The currency code.
    - `minimum_payment` (decimal pair, optional): A decimal pair whose `value` is a string: the amount is `value` ÷ 10^`dp` (`{"value": "1000", "dp": 3}` is 1.00). YoPrint refuses smaller payments. See https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `minimum_remaining_balance` (null, optional): Always null here.
  - `paypal_webhook_url` (string, optional)
  - `pdf_date_format` (string, optional): The date format on PDFs. `std` is the default for a team that never changed it; PDFs show it like `other_1` (05 Nov 2026). A team whose saved settings have no date format reads `other_1`. Update general settings accepts only the other five values. One of: `"std"`, `"default"`, `"british_standard"`, `"us_standard"`, `"international"`, `"other_1"`.
  - `shipping_label_create_cost_line_item` (boolean, optional): Whether "Create Shipping Cost Line Item" starts checked when someone buys a shipping label in the web app. `true` when never set.
  - `square_webhook_url` (string, optional): Add this URL in the Square Developer Dashboard before you turn Square on.
  - `stripe_webhook_url` (string, optional): The URL Stripe calls for this team. YoPrint registers it in your Stripe account when you save Stripe settings.
  - `tax_label_name` (string, optional): The name used for tax on documents. `Tax` when never set.
  - `web_date_format` (string, optional): The date format in the web app. `us` is the default for a team that never changed it; the web app shows it like `default` (Nov 05, 2026). A team whose saved settings have no date format reads `default`. Update general settings accepts only the other five values. One of: `"us"`, `"default"`, `"british_standard"`, `"us_standard"`, `"international"`, `"other_1"`.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "cust_msg_status": true,
    "customer_portal_account_login_available": true,
    "customer_portal_rollout": {
      "account_only": false,
      "all_teams_at": null,
      "configuration_warning": null,
      "legacy_access_allowed": true,
      "new_teams_at": null,
      "reason": "transition"
    },
    "default_pricing_strategy": "job_separately",
    "enable_stripe": true,
    "payment_amount_policies": {
      "USD": {
        "currency": "USD",
        "minimum_payment": {
          "dp": 3,
          "value": "1000"
        },
        "minimum_remaining_balance": null
      }
    },
    "payment_amount_policy": {
      "currency": "USD",
      "minimum_payment": {
        "dp": 3,
        "value": "1000"
      },
      "minimum_remaining_balance": null
    },
    "paypal_webhook_url": "https://secure.yoprint.com/api/store/your-team/webhook/v1/payment/paypal",
    "pdf_date_format": "other_1",
    "shipping_label_create_cost_line_item": true,
    "square_webhook_url": "https://secure.yoprint.com/api/store/your-team/webhook/v1/payment/square",
    "stripe_webhook_url": "https://secure.yoprint.com/api/store/your-team/webhook/v1/payment/stripe",
    "tax_label_name": "Tax",
    "web_date_format": "default"
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
  - When: The API key is missing or wrong. Fix: Send your personal API key as `Authorization: Bearer YOUR_API_KEY`.
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
  - When: Your permission group lacks Manage Settings. This 403 has a short body, `{"message": "Insufficient Permission"}`, without `success` or `error`. Fix: Ask the team owner to give your permission group Manage Settings.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
- `422` The request was refused and changed nothing. `validation_failed` lists what to fix in `error.fields`; other codes name a business rule, explained in `error.message`. A few checks answer with only `{"message": "..."}`. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer `connect_timeout` ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
  - When: A required credential is missing or malformed. `error.code` is `validation_failed`, and `error.fields` names each field with its messages. Fix: Fix the fields listed in `error.fields` and send the request again.
  - When: Stripe refused or failed: `error.code` `stripe_setup_error`, with `error.reason` and `error.stripe_permission`. `reason` is `missing_permission` (the key lacks a permission; `stripe_permission` is `connected_account_read` or `webhook_write`), `key_rejected` (Stripe didn't accept the key), `stripe_unreachable` (YoPrint couldn't check the key) or `webhook_failed` (the webhook couldn't be set up); `stripe_permission` is null for the last three. `error.message` says what to do. Fix: For `missing_permission`, edit the key in Stripe: Accounts (under Connect) Read for `connected_account_read`, Webhook Endpoints Write for `webhook_write`. For `key_rejected`, paste the key again or make a new restricted key. Otherwise try again in a minute.
  - When: Another provider rejected the credentials or the webhook setup. `error.code` is `paypal_setup_error`, `square_setup_error` or `authorize_setup_error`, with a message. Fix: Check the credentials in the provider's dashboard. For Square, add YoPrint's webhook URL in Square first.
  - When: Charge It Pro is retired: you sent a Charge It Pro key or setting for a team that does not have it on, or after it was retired (`charge_it_pro_retired`, "Gravity Payments is no longer supported in YoPrint. Connect another payment provider to take card payments."). Fix: Connect Stripe, PayPal, Square or Authorize.Net instead.
  - When: You turned Charge It Pro off while one of its payments is still being processed (`charge_it_pro_payment_in_progress`, "A Gravity Payments payment is still being processed, so Gravity Payments can't be removed yet. Try again later."). Fix: Try again later.
  - When: Charge It Pro: a new org id or auth key is blank or too long (`charge_it_pro_setup_error`, "Charge It Pro Credentials are Invalid"). YoPrint doesn't ask Gravity Payments, so a well-formed wrong key is saved. Fix: Copy the org id and auth key again from Gravity Payments.

## Notes

- Never put real credentials in source control or logs. The examples use placeholders.
- Use Show team settings to read which gateways are on (`enable_*`) and the webhook URLs to register with providers.

## Related

- [Show team settings](https://developer.yoprint.com/reference/company-settings/v1-setting-show.md): `GET /v1/api/store/{team_slug}/setting`
- [List Square locations](https://developer.yoprint.com/reference/payment-gateways/v1-setting-payment-gateway-square-location-list.md): `PUT /v1/api/store/{team_slug}/setting/payment_gateway/get_square_location_list`
- [Charge a card through the payment gateway](https://developer.yoprint.com/reference/payments/v2-sales-order-payment-gateway-execute.md): `POST /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment/{payment_reference}`
- [Refund a card payment through the gateway](https://developer.yoprint.com/reference/payments/v2-sales-order-payment-gateway-refund.md): `PUT /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment_gateway_refund/{id}`