A token from hosted fields starts pending: it is deleted after 24 hours unless you keep it. You keep it either by charging it successfully (retain_on_success is on by default) or by calling retain. A retained card stays in the vault until you redact it.
Cards per customer
File each kept card under its customer from your server, with your own id for them. The first time OrderCard sees a reference it creates the customer:
curl -X POST https://api.ordercard.io/v1/payment_methods/tok_…/retain \
-H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "customer_reference": "user_1001" }'Sending customer_reference with the first charge does the same once the charge succeeds. List a customer’s cards with GET /v1/payment_methods?customer_reference=user_1001 (or ?customer=cus_…). Never take the customer from the browser: hosted fields refuse it.
Who started the charge
Card networks treat a charge differently depending on whether the cardholder is present. Tell OrderCard with initiator:
initiator |
Use for | What OrderCard does |
|---|---|---|
customer (default) |
Checkout, with the cardholder present. | Sends the security code if it is still on hand. |
merchant |
An unscheduled charge on a stored card, like an add-on or a no-show fee. | Never sends a security code. Marks the charge as a stored-credential charge and references the card’s first customer-initiated transaction on the same gateway. |
recurring |
A scheduled subscription charge. | Like merchant, and also flags it as recurring. Surcharges only apply if the gateway allows them on recurring charges. |
curl -X POST https://api.ordercard.io/v1/gateways/gw_…/purchase \
-H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
-H "Idempotency-Key: sub-77-2026-11" \
-H "Content-Type: application/json" \
-d '{ "payment_method_token": "tok_…", "amount": 1900, "initiator": "recurring", "reference": "sub-77-2026-11" }'Make the first charge on a card a customer-initiated one (or a verify at checkout) so later merchant-initiated charges have an original transaction to reference.
The security code
The CVV is never stored. It is kept encrypted for 15 minutes after the card is tokenized, used once by the first customer-initiated charge or verification, and deleted. Later charges go without it, which issuers expect for stored cards.
Expired and reissued cards
When the bank reissues a card with a new expiry, update the token rather than collecting the card again:
curl -X PATCH https://api.ordercard.io/v1/payment_methods/tok_… \
-H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "exp_month": 12, "exp_year": 2031 }'The card number can never change: a new card number is a new token.
Moving between gateways
A token is not tied to a gateway. Charge the same card through a different gateway by sending its id; nothing needs to be re-collected. Merchant-initiated charges reference the card’s first customer-initiated transaction on that gateway, so make one customer-initiated charge or verification on the new gateway first if the processor requires it.
Removing a card
Redact the token (DELETE /v1/payment_methods/{token}) or use Delete on the card’s page in the dashboard. The card number, any cached security code, the fingerprint and the cardholder’s name, email, phone, billing address and metadata are deleted for good. The token stays, with status redacted, and keeps its brand, first six and last four digits, expiry and your customer reference, so past transactions still make sense. Transactions keep the billing details that were sent with each charge.