About sale vs. authorization

Two ways to process a card payment

Paradise Pay provides two card transaction flows that differ in when funds are captured from the person's account.

Flow	Transaction types	Steps	Funds captured
One-step (sale)	`sale`	1	Immediately upon authorization
Two-step (auth + capture)	`auth` → `capture`	2	When you explicitly capture

One-step: sale

A sale authorizes and captures the payment in a single request. Use this when you can fulfill the order immediately.

When to use a sale

Digital goods (software, subscriptions, downloads)
In-person retail where the item is handed to the person at purchase
Services rendered at the time of payment

How it works

Send POST /v1/transactions with type: sale. 2.Reefpay authorizes with the processor and automatically marks the transaction for capture.
The transaction enters the next settlement batch.

Example request

{
  "type": "sale",
  "amount": 1999,
  "payment_method": {
    "type": "card",
    "pan": "4111111111111234",
    "expiry_month": "03",
    "expiry_year": "2028",
    "cardholder_name": "John Doe",
    "cvv": "456",
    "address_line1": "123 Main St",
    "zip": "10001"
  }
}

Example response

{
  "id": "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "object": "transaction",
  "type": "sale",
  "transaction_state": "authorized",
  "response_status": "Approved",
  "response_code": "00",
  "amount": 1999,
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Two-step: authorization then capture

An authorization places a hold on the person's funds without transferring them. You capture when ready — typically when the order ships or the service is confirmed.

When to use authorization + capture

E-commerce where items ship after ordering
Pre-orders or backorders
Hotel or rental reservations (hold amount, capture final amount)
Any scenario where the final amount may differ from the initial hold

How it works step by step

Send POST /v1/transactions with type: auth to authorize.
The processor places a hold on the person's account.
When ready, send POST /v1/transactions/{id}/capture with the final amount.
The captured transaction enters the next settlement batch.

Step 1: Authorize

{
  "type": "auth",
  "amount": 25000,
  "payment_method": {
    "type": "card",
    "pan": "5500000000005678",
    "expiry_month": "07",
    "expiry_year": "2029",
    "cardholder_name": "Jane Smith",
    "cvv": "789",
    "address_line1": "42 Oak Ave",
    "zip": "30301"
  }
}

Response returns transaction_state: authorized.

Step 2: Capture

{
  "type": "capture",
  "amount": 25000,
  "tip": 0
}

Send this to POST /v1/transactions/{id}/capture, where {id} is the transaction ID from the authorization response.

Partial captures

You can capture an amount less than or equal to the authorized amount. This is useful when only part of an order ships. The remaining hold is released back to the person.

Comparing the two flows

Aspect	Sale	Authorization + capture
API calls	1	2
Funds held	Authorized and captured immediately	Held until you explicitly capture
Amount flexibility	Fixed at time of sale	Can capture less than authorized
Void window	Before batch settlement	Before capture or before batch settlement
Best for	Immediate fulfillment	Delayed or variable-amount fulfillment
Authorization expiry	Not applicable	Authorizations expire if not captured (typically 7–30 days, varies by issuer)

What happens if you do not capture

If you authorize but never capture, the hold on the person's account expires after a period set by the issuing bank (typically 7–30 days). The funds are released back to the person and no settlement occurs.

This does not generate a cancel or void — the authorization simply expires. However, it is best practice to explicitly cancel authorizations you do not intend to capture, so the person's funds are released immediately.