Payments

Your server charges a vaulted card by sending its token to one of your gateways. Every operation is recorded as a transaction and answers the same way whichever gateway you use: 201 when it succeeded, 402 with the reason when it did not.

Charge now: purchase

curl -X POST https://api.ordercard.io/v1/gateways/gw_…/purchase \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_token": "tok_…", "amount": 2500, "reference": "order-1001" }'

Charge later: authorize, then capture

Authorize when the order is placed to hold the money, and capture when you ship. A capture can be for less than the authorization (for example when an item is out of stock) but never more, and only once.

# Hold $89.00
curl -X POST https://api.ordercard.io/v1/gateways/gw_…/authorize \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_token": "tok_…", "amount": 8900 }'

# Take $75.00 of it
curl -X POST https://api.ordercard.io/v1/transactions/txn_…/capture \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 7500 }'

Authorizations expire at the issuer after a few days (it varies by card network), so capture promptly. To release a hold you will not capture, void it.

Undo: void or refund

• Void cancels an authorization, or a purchase or capture that has not settled yet (usually the same day). Nothing reaches the cardholder’s statement.
• Refund returns money from a purchase or capture after it settled, in full or in parts, until nothing is left.

If a void is refused because the charge already settled, refund it instead.

Check a card: verify

verify asks the issuer about the card without charging it, and stores the address and security code results on the card. Use it when you save a card for later.

Rules every request follows

• Amounts are integers in cents. amount is what you charge before any surcharge, tax included; send tax_amount too if you know it.
• Send an Idempotency-Key on every request that moves money, so a network retry cannot charge twice. See Conventions.
• The card’s billing address is sent for address verification. Override it for one charge with billing.
• A charge the issuer declined is still a transaction, with status: declined. See Declines.

Following a payment

Captures, voids and refunds are separate transactions whose parent is the original. The original’s summary shows captured_amount, refunded_amount, voided, remaining_capturable and remaining_refundable, and GET /v1/transactions?parent=txn_… lists everything done to it. Webhooks tell you about each one as it happens.