Update payment gateway settings

PUT/v1/api/store/{team_slug}/setting/payment_gateway

v1Operation ID v1_public_setting_payment_gateway_update

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_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team

Request body

application/json, required.

authorize_client_keystring
Your public client key. Required when enable_authorize_net is true.
authorize_login_idstring
Required when enable_authorize_net is true.
authorize_sig_keystring
Your signature key. Required when enable_authorize_net is true.
authorize_trans_keystring
Required when enable_authorize_net is true.
charge_it_pro_auth_keystring
Retired. Required when enable_charge_it_pro is true.
charge_it_pro_device_idstring
Retired. The default card device. Required when charge_it_pro_mode is in-person or both.
charge_it_pro_modestring
Retired. Required when enable_charge_it_pro is true.
- One of: "in-person", "online", "both"
charge_it_pro_oidstring
Retired. Required when enable_charge_it_pro is true.
enable_authorize_netboolean
Turns Authorize.Net on or off.
enable_charge_it_proboolean
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_paypalboolean
Turns PayPal on or off.
enable_squareboolean
Turns Square on or off.
enable_square_paymentboolean
Whether online payments go to Square. Required when enable_square is true.
enable_stripeboolean
Turns Stripe card payments on or off.
paypal_client_idstring
Required when enable_paypal is true. Use live credentials.
paypal_secretstring
Required when enable_paypal is true.
publishable_keystring
Your Stripe publishable key, starting with pk_live_ or pk_test_. Required when enable_stripe is true.
square_access_tokenstring
Required when enable_square is true.
square_client_idstring
Your Square application id. Required when enable_square is true.
square_location_idstring
The Square location online payments are credited to. Required when enable_square_payment is true. Get ids from List Square locations.
square_webhook_locationsarray of objects
The Square locations whose payments YoPrint listens to. Required when enable_square is true.
Fields of each item (1)
- idstringrequired
  A Square location id.
square_webhook_sigstring
The signature key of the webhook you added in Square. Required when enable_square is true.
stripe_secret_keystring
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.

More examples (1)

Turn on Stripe

curl

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

200Successful response.

dataobjectrequired
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).
Child fields (14)
- cust_msg_statusboolean
- customer_portal_account_login_availableboolean
  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_rolloutobject
  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.
  Child fields (6)
  - account_onlybooleanrequired
    True when customers must sign in with an email account: a direct portal link alone no longer opens the portal.
  - all_teams_atstring (date-time) | nullrequired
    When account login becomes mandatory for all teams (UTC), or null if not set.
  - configuration_warningstring | nullrequired
    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_allowedbooleanrequired
    True when direct portal links still open the portal without an account sign-in.
  - new_teams_atstring (date-time) | nullrequired
    When account login became mandatory for new teams (UTC), or null if not set.
  - reasonstringrequired
    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_strategystring
  How new jobs are priced by default. job_separately when never set.
  - One of: "job_separately", "job_together", "service_loc_together"
- enable_stripeboolean
  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_policiesobject | array
  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_policyobject | null
  Read only: the smallest payment YoPrint accepts in your default currency, or null when the team has no default currency.
  Child fields (3)
  - currencystring
    The currency code.
  - minimum_paymentdecimal pair
    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 Money and quantities.
  - minimum_remaining_balancenull
    Always null here.
- paypal_webhook_urlstring
- pdf_date_formatstring
  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_itemboolean
  Whether "Create Shipping Cost Line Item" starts checked when someone buys a shipping label in the web app. true when never set.
- square_webhook_urlstring
  Add this URL in the Square Developer Dashboard before you turn Square on.
- stripe_webhook_urlstring
  The URL Stripe calls for this team. YoPrint registers it in your Stripe account when you save Stripe settings.
- tax_label_namestring
  The name used for tax on documents. Tax when never set.
- web_date_formatstring
  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"
statusintegerrequired
successbooleanrequired

Errors

401The 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.
403You 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.
404Not 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.
422The 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.

GETShow team settings/v1/api/store/{team_slug}/setting
PUTList Square locations/v1/api/store/{team_slug}/setting/payment_gateway/get_square_location_list
POSTCharge a card through the payment gateway/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment/{payment_reference}
PUTRefund a card payment through the gateway/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment_gateway_refund/{id}

Example request

curl

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  }'

Example response 200

{
  "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
}

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com