Prepare a card payment

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

v2InternalOperation ID v2_public_sales_order_payment_gateway_pre_execute

Internal

Built for YoPrint's own apps, not for integrations. It is listed so the reference is complete; don't build on it, and use the other operations in this section.

Card payments run through the team's connected payment gateway and charge real money. They are built for YoPrint's own payment screens, which collect the card with the provider's browser library: the card token or confirmation in the body comes from that library.

Starts a card payment where the gateway needs a first step. stripe answers payment_intent_id and client_secret to confirm in the browser. charge_it_pro starts a Charge It Pro sale (on the team's terminal unless skip_terminal is true) and answers Charge It Pro's reply plus internal_id, which Charge a card needs. square, square_v2, paypal and authorize_net have no first step.

{payment_gateway} is the gateway: stripe, square, square_v2, paypal, authorize_net or charge_it_pro. {hash_id} is the order's id (for example V4keXwwxMQyXw7); the ord_ unique key is not accepted here.

Permission

Any member of the team.

Business rules

• amount is required for every gateway, as a whole number of thousandths (422 validation_failed otherwise). This is checked before the gateway is: for square, square_v2, paypal and authorize_net a missing amount is 422 validation_failed, not "Pre Execution Not Supported".
• The amount to charge, less any surcharge, must be at least 1.00 in the order's currency: otherwise 422 payment_below_minimum ("Enter at least USD 1.00.", with the order's currency code), and error.payment_amount_policy gives currency, minimum_payment (a decimal pair, { "value": "1000", "dp": 3 }) and minimum_remaining_balance (null). A negative surcharge is 422 payment_surcharge_invalid ("The payment surcharge cannot be negative."). The provider's own limits still apply.
• stripe also checks the amount against its own minimum and maximum charge for the currency.
• The order's state is not checked here.

Side effects

• stripe: creates a payment intent with the provider; no money moves yet. charge_it_pro: starts a sale with Charge It Pro.

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

• POSTCharge a card through the payment gateway/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment/{payment_reference}

Example request

curl

curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/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
}