Charge a card through the payment gateway

POST/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment/{payment_reference}

v2InternalOperation ID v2_public_sales_order_payment_gateway_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.

Completes a card payment and records it on the order. charge_it_pro answers status pending with poll_id (its internal_id) and poll_token, and YoPrint records the payment when the sale finishes, checking the provider in the background. Every other gateway records the payment now and answers status success, with poll_id and poll_token as empty strings.

The path segment shown as {payment_reference} is the gateway name here. {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

• locking_token and order_id are required, plus the gateway's own field.
• For square, square_v2 (except square_token cash), paypal and authorize_net, amount is checked before the provider is called, so nothing is charged when it fails: it is required as a whole number of thousandths. 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.
• square_v2 records the payment only when Square answers COMPLETED; any other Square status is 422 payment_capture_failed.
• charge_it_pro refuses a pending payment that isn't this order's, or that belongs to a Customer Portal payment: 422 payment_capture_failed "Payment Failure: We cannot find the pending payment record".
• A payment the provider already recorded is refused: "Transaction Already Processed".
• The order must be published, but YoPrint checks only when it records the payment, after the provider has charged: on a draft order the charge goes through and the answer is 422 "Payment Action Not Allowed - due to order internal state". Publish first.

Side effects

• Moves money square, square_v2, authorize_net and paypal capture the charge here (real money moves); for stripe the browser already confirmed the charge, and this call checks and records it.
• Records the payment and updates the order, invoices and customer totals. Customer Portal pages the order's customer has open refresh.
• Sends the payment_received.any_amount webhook; also payment_received.deposit_amount when the order's paid total now exactly equals its deposit amount, and payment_received.full_amount when the balance due (invoiced total minus paid) is now exactly 0. A payment that goes past the deposit, or overpays, sends neither of those two.
• A dispute the provider later reports on a stripe, paypal or square_v2 payment freezes it: refunds and moves to customer credit are refused until the provider decides (see Refund a card payment).

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_referencestringrequired

  The payment gateway (this path segment is a gateway name here, not a payment id).

  • 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

• POSTPrepare a card payment/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment/{payment_gateway}/pre_execute
• 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 POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/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
}