Charge a card through the gateway (v1)

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

v1Legacy · deprecatedOperation ID v1_public_sales_order_payment_gateway_execute

Legacy (deprecated)

A newer operation does this better.Use Charge a card through the payment gateway (POST /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment/{payment_reference}) instead.

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

The older path for charging a card ({payment_gateway} is the gateway name). It runs exactly the same code as Charge a card through the payment gateway (v2.public.sales_order.payment.gateway.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.

• locking_tokenstringrequired

  Your one-time token for this payment attempt. Required.

• order_idstringrequired

  The order's id again. Required.

• amountinteger

  The amount to charge. Send a whole number of thousandths: 12500 is 12.50. Required for square, square_v2 (not with square_token cash), paypal, and authorize_net; checked before the provider is called. stripe and charge_it_pro take the amount from Prepare a card payment.

• authorizenet_tokenstring

  authorize_net: the card token.

• internal_idstring

  charge_it_pro: the pending payment from Prepare.

• payment_intent_idstring

  stripe: the confirmed payment intent from Prepare.

• paypal_order_idstring

  paypal: the approved PayPal order.

• square_tokenstring

  square: the card token.

• surchargedecimal pair

  Optional card surcharge included in amount, when the team charges one; the order must have an invoice. It must not be negative.

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

Response

200Successful response.

• dataobjectrequired
  Child fields (3)

  • statusstringrequired

    success, or pending while the provider finishes.

  • poll_idstring

    For pending: the pending payment's id.

  • poll_tokenstring

    For pending: a token for polling.

• 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

  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). Nothing is charged.

  Fix

  Send at least 1.00 (1000) in thousandths.

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/v1/api/store/your-team/sales_order/V4keXwwxMQyXw7/payment/stripe' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "locking_token": "pay-1001-a",    "order_id": "V4keXwwxMQyXw7",    "payment_intent_id": "pi_example_1001"  }'

Example response 200

Response

{
  "data": {
    "poll_id": "",
    "poll_token": "",
    "status": "success"
  },
  "status": 200,
  "success": true
}