Prepare a card payment (v1)

POST/v1/api/store/{team_slug}/sales_order/{hash_id}/payment/{payment_gateway}/pre_execute

v1Legacy · deprecatedOperation ID v1_public_sales_order_payment_gateway_pre_execute

Legacy (deprecated)

A newer operation does this better.Use Prepare a card payment (POST /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment/{payment_gateway}/pre_execute) instead.

Its answers say so in the Deprecation and X-YoPrint-Successor headers; see Deprecated operations.

The older path for preparing a card payment. It runs exactly the same code as Prepare a card payment (v2.public.sales_order.payment.gateway.pre_execute): use that one.

Permission

Any member of the team.

Path parameters

• team_slugstringrequired

  Your team slug, shown as Team ID next to your API key in Profile.

  • Example your-team
• hash_idstringrequired

  The sales order's or quote's id (a hash id). The ord_ unique key and the order number do not work here.

  • Example V4keXwwxMQyXw7
• payment_gatewaystringrequired

  The payment gateway.

  • One of: "stripe", "square", "square_v2", "paypal", "authorize_net", "charge_it_pro"
  • Example stripe

Request body

application/json, required.

• amountintegerrequired

  The amount to charge. Send a whole number of thousandths: 12500 is 12.50. Required for every gateway.

• internal_idstring (uuid) | null

  charge_it_pro only, optional: a UUID to use as the pending payment's internal_id. Anything that isn't a UUID is refused with 422 "The internal id must be a valid UUID."

• locking_tokenstring | null

  charge_it_pro only: your one-time token for this payment.

• skip_terminalboolean

  charge_it_pro only.

• surchargedecimal pair

  Optional card surcharge included in amount, read only when the team charges one. It must not be negative; it is taken off amount for the minimum check.

  • { "value": 1250, "dp": 2 } is 12.50: value holds the digits, dp the decimal places. See Money and quantities.

Response

200Successful response.

• dataobjectrequired

  What the gateway needs next; stripe shown. Other gateways return their own fields.

  Child fields (2)

  • client_secretstring

    stripe: the secret for Stripe.js.

  • payment_intent_idstring

    stripe: the payment intent to confirm.

• statusintegerrequired
• successbooleanrequired

Errors

• 401The API key is missing or wrong (unauthenticated).

• 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.

• 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.

  When

  An unknown {payment_gateway} or order (page_not_found or "No query results for …").

  Fix

  Use one of the gateway names.

• 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

  square_v2 without a Square v2 connection (gateway_not_setup), square when the team's old Square connection is switched off (using_deprecated_old_square_gateway), a missing gateway field, the provider refused (for example payment_capture_failed), or a Shopify order deleted in Shopify (shopify_order_deleted_externally).

  Fix

  Connect the gateway in Settings and send its fields.

  When

  The gateway has no first step (square, square_v2, paypal, authorize_net): payment_pre_execute_failed "Pre Execution Not Supported".

  Fix

  Call Charge a card directly.

  When

  amount is missing or not a whole number (validation_failed), less than 1.00 after the surcharge (payment_below_minimum), or the surcharge is negative (payment_surcharge_invalid).

  Fix

  Send at least 1.00 (1000) in thousandths.

  When

  A valid order id that no longer exists: "Cannot Start Transaction: Sales Order Not Found".

  Fix

  Check the order id.

Related

• POSTPrepare a card payment/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment/{payment_gateway}/pre_execute

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/sales_order/V4keXwwxMQyXw7/payment/stripe/pre_execute' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "amount": 85000  }'

Example response 200

Response

{
  "data": {
    "client_secret": "client-secret-from-stripe",
    "payment_intent_id": "pi_example_1001"
  },
  "status": 200,
  "success": true
}