Accepting cash

Customers without cards pay in cash, in two ways: with a reference at a cash collection location, or across the counter at your store.

Online: a reference to pay

Confirm a payment intent with payment_method_data[type] set to cash. It comes back requires_action with next_action.cash_display_reference: a unique reference, the amount and currency to pay, when it expires_at, and instructions you can show. Give the reference to your customer, who pays that exact amount in cash at a location in the cash collection network. The network tells us, and the intent moves through processing to succeeded at once: a payment_intent.processing event, then payment_intent.succeeded.

requires_confirmation

requires_action

processing

succeeded

requires_payment_method

canceled

Press enter or space to select a node. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

requires_confirmation

requires_action

processing

succeeded

requires_payment_method

canceled

Press enter or space to select a node. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

How a payment intent paid in cash changes. Its states: requires_confirmation, requires_action, processing, succeeded (final), requires_payment_method, canceled (final).

1. requires_confirmation to requires_action
2. requires_action to processing
3. processing to succeeded
4. requires_action to requires_payment_method: expired
5. requires_action to canceled: canceled by you

curl https://api.example.com/v1/payment_intents/pi_01j9x2m8k4q7r5t3v6w8y0z2a4/confirm \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 5d1f9c3e-7a42-4b0e-9a55-2c8d6e1b4f70" \
  -H "Content-Type: application/json" \
  -d '{"payment_method_data": {"type": "cash"}}'

• A reference expires, after 48 hours unless your platform sets another time. An unpaid reference then fails the attempt: payment_intent.payment_failed with last_payment_error.code payment_intent_payment_attempt_expired, and the intent is back in requires_payment_method. Confirm it again for a new reference.
• Canceling the intent cancels its reference, so cash can no longer be paid against it.
• Cash is offered only where your account is eligible for it. Check GET /v1/payment_methods. A suspended account cannot be given a new reference. Refusals are the ones in Create a payment intent: method_not_enabled, method_suspended and the rest.

At the counter: a terminal records cash

A paired terminal records cash it took with POST /v1/terminal/cash_payments. The payment is already made, so the answer is the succeeded payment intent and the receipt to print, with the change to hand back. See Record a cash payment.

The terminal sends its own idempotency_key for each sale, in the body: it is what makes a retry safe, and it is never reused for another sale. The same key with the same terms answers the same payment with 200 and records nothing twice; the same key with other terms is refused with 409 idempotency_key_reused.

If the platform answers 503 service_unavailable, whether the sale was recorded is not known, and the cash is in the till either way. Send the same request again with the same idempotency_key, and never make a new key for the retry: a sale that was recorded, in whole or in part, is answered with that payment (200) and recorded once. Print the receipt from an answer only.

Accepted, deposited, settled

succeeded means the cash was accepted. It is not yet your money to be paid out: cash is collected by the network, or by your staff at the counter, and reaches us as a deposit. Your payout for a cash payment waits until its deposit is confirmed, and only then is it counted in your settlement. So a payment can be succeeded while its payout is still to come. Your platform operator can tell you how long deposits take to confirm.

Refunds are assisted

A cash payment is refunded through POST /v1/refunds, for the whole payment only: amount must be the whole amount, or left out. The refund is accepted and stays processing: cash is handed back across a counter, so the operator's finance team record that it was paid out, and only then does the refund become succeeded (refund.succeeded). Cash whose deposit was already confirmed cannot be refunded this way; that refund fails as refund_not_possible.