Skip to main content

​
Why Authorization and Capture?

Most payments are simple: you charge the customer immediately and you’re done. But sometimes you need to reserve funds without actually charging them right away. That’s where authorization and capture comes in. Authorization = “Can this customer pay 100?Ifyes,holdthat100? If yes, hold that 100 for me.” Capture = “Actually charge that $100 you’re holding.” Think of it like a hotel room: when you check in, they authorize your card (put a hold on funds) but don’t charge you yet. When you check out, they capture the funds (actually charge you) for the final amount (which might be different if you used the minibar or had room service).

​
When to Use Authorization & Capture

Use this two-step process when:
  • You don’t know the final amount yet (hotels, car rentals, restaurants with tips)
  • You want to verify the card before shipping (pre-orders, custom products)
  • You need to hold funds temporarily (deposits, reservations)
  • The service happens over time (subscriptions that start later, services with variable pricing)
When NOT to use it: For simple e-commerce purchases where you know the exact amount and want to charge immediately, use the regular sale endpoint instead.

​
Real-World Use Cases

​
Hotel Booking

  1. Check-in: Authorize $200 (estimated room + incidentals)
  2. During stay: Customer might use room service, minibar, etc.
  3. Check-out: Capture the actual amount (maybe $250 after incidentals)

​
Pre-Order Products

  1. Customer pre-orders: Authorize the full amount to verify their card is valid
  2. Product ships: Capture the funds when you actually ship (weeks or months later)
  3. If customer cancels: Reverse the authorization, no charge

​
Restaurant with Tips

  1. Customer orders: Authorize the bill amount
  2. Customer adds tip: Capture the total (bill + tip)
  3. Or if they walk out: Capture just the bill amount

​
Custom Products

  1. Customer orders custom item: Authorize to verify payment method
  2. You build the product: Takes time, customer’s card is verified
  3. You ship: Capture when ready to charge

​
How Authorization & Capture Works

Here’s the flow:
  1. Authorize → Bank checks if customer has funds, puts a hold on the money
  2. Wait → Funds are reserved but not charged (authorization lasts ~7 days)
  3. Capture → Actually charge the customer (can be same amount or different)
  4. Or Reverse → Release the hold if you don’t need to charge
The key difference from a regular sale:
  • Regular sale: Authorize + Capture happens immediately in one step
  • Authorization/Capture: You control when each step happens

​
Step 1: Authorize a Payment

When you authorize, you’re asking the bank “Can this customer pay $X?” If yes, they put a hold on that amount. The customer’s available balance decreases, but the money hasn’t actually been charged yet.

​
API Endpoint

POST {{Api Root}}/api/Payments/authorization

​
Sample Authorization Request

{
  "PaymentMethod": {
    "BillingAddress": {
      "AddressLine1": "100 Main",
      "AddressLine2": null,
      "City": "Santa Ana",
      "State": "CA",
      "PostalCode": "91111",
      "Country": "US"
    },
    "BillingFullName": "John Doe",
    "CreditCard": {
      "PaymentAccountNumber": "4111111111111111",
      "ExpirationDate": "1025" // Format: MMYY
    }
  },
  "NetworkProcessing": {
    "ProcessingType": "initialInstallment",
    "OriginalNetworkTransactionId": null
  },
  "Amount": {
    "Value": 30.99 // Amount to authorize (hold)
  }
}

​
Understanding the Request

FieldDescription
PaymentMethodThe customer’s payment details (card, billing address, etc.)
BillingAddressCardholder’s billing address (used for fraud prevention)
BillingFullNameName on the credit card
CreditCard.PaymentAccountNumberFull credit card number
CreditCard.ExpirationDateCard expiration in MMYY format (e.g., “1025” = October 2025)
NetworkProcessing.ProcessingTypeTransaction type. Use initialInstallment for one-time authorizations
Amount.ValueHow much to authorize (hold). This can be your best estimate—you can capture a different amount later

​
Alternative: Authorize with Stored Payment Method

If you already have a paymentMethodId (from a previous transaction), you can use that instead of sending full card details: 
POST {{Api Root}}/api/Payments/authorization/{paymentMethodId}
Request (much simpler—no card details needed): 
{
  "NetworkProcessing": {
    "processingType": "initialInstallment",
    "originalNetworkTransactionId": null
  },
  "Amount": {
    "value": 1.03
  }
}

​
Authorization Response

When authorization succeeds, you’ll get back a paymentMethodAuthorizationId—this is what you’ll use to capture or reverse the payment later. 
{
  "networkTransactionId": "431241081661798",
  "paymentMethodAuthorizationId": 2055, // ⭐ Save this! You'll need it to capture
  "paymentMethod": {
    "paymentMethodId": 6061,
    "billingAddressId": 7056,
    "billingAddress": {
      "addressId": 7056,
      "addressLine1": "381 Forest Ave. Suite C",
      "addressLine2": null,
      "city": "Laguna Beach",
      "state": "CA",
      "postalCode": "92651",
      "phoneNumber": null,
      "email": null,
      "country": "US"
    },
    "billingFirstName": "Joe",
    "billingLastName": "Smith",
    "merchantPaymentMethodRefId": null,
    "paymentMethodCreditCardDetails": {
      "paymentLast4Digit": "1111",
      "paymentExpirationDate": "0330"
    }
  }
}

​
Understanding the Response

FieldDescription
paymentMethodAuthorizationIdThe most important field—save this! You’ll need it to capture or reverse the payment
networkTransactionIdUnique ID from the card network. Store this for your records
paymentMethod.paymentMethodIdIf a payment method was created, you can use this for future transactions
paymentMethodCreditCardDetails.paymentLast4DigitLast 4 digits of the card (safe to display)
Important: Store the paymentMethodAuthorizationId immediately. You’ll need it to capture or reverse, and authorizations expire after about 7 days.

​
Step 2: Capture the Payment

Once you’re ready to actually charge the customer, you “capture” the authorized amount. You can capture:
  • The same amount you authorized
  • A different amount (more or less)
  • But you can’t capture more than you authorized

​
API Endpoint

POST {{Api Root}}/api/Payments/capture/{paymentMethodAuthorizationId}
Replace {paymentMethodAuthorizationId} with the ID you got from the authorization response.

​
Sample Capture Request

{
  "CustomerId": null, // Optional: link to a customer record
  "Invoice": {
    "MerchantInvoiceRefId": "ABC309500654810", // Your order/invoice ID
    "Amount": {
      "value": 1.03 // Amount to capture (can be different from authorized amount)
    }
  }
}

​
Understanding the Request

FieldDescription
CustomerIdOptional. Link this payment to a customer record in Revolv3
Invoice.MerchantInvoiceRefIdYour internal order or invoice ID (for tracking)
Invoice.Amount.valueThe amount to actually charge. This can be:
  • Same as authorized amount
  • Less than authorized (e.g., authorized 200,capture200, capture 150)
  • But NOT more than authorized |

​
Key Notes About Capturing

  • ✅ You must capture within ~7 days of authorization, or it expires
  • ✅ You can capture a different amount than you authorized (as long as it’s not more)
  • ✅ You can only capture once per authorization
  • ❌ If authorization expires, you’ll need to authorize again

​
Capture Response

The capture response looks similar to a regular payment response: 
{
  "invoiceId": 185317,
  "merchantInvoiceRefId": "ABC309500654810",
  "networkTransactionId": "538302743384089",
  "invoiceStatus": "Paid",
  "invoiceAttemptStatus": "Success",
  "message": "Approved",
  "amount": {
    "currency": "USD",
    "value": 1.03
  },
  "paymentMethodId": 6061,
  "paymentProcessor": "WorldPay"
}
At this point, the customer has been charged and you can fulfill the order.

​
Step 3: Reversing an Authorization (Optional)

If you authorized funds but decide you don’t need to charge the customer (they cancelled, you can’t fulfill the order, etc.), you can reverse the authorization to release the hold.

​
API Endpoint

POST {{Api Root}}/api/PaymentMethod/reverse-auth

​
Sample Reversal Request

{
  "PaymentMethodAuthorizationId": 2055 // The authorization ID from step 1
}

​
What Happens When You Reverse

  • ✅ The hold on the customer’s funds is released immediately
  • ✅ Their available balance goes back to normal
  • ✅ They were never charged
  • ❌ You can’t capture this authorization anymore (it’s cancelled)
When to reverse:
  • Customer cancels before you capture
  • You can’t fulfill the order
  • You want to release the hold for any reason
Note: If you don’t capture or reverse, the authorization will automatically expire after ~7 days and the hold will be released. But it’s better to explicitly reverse if you know you won’t capture.

​
Complete Example: Hotel Booking Flow

Let’s walk through a real scenario:

​
Day 1: Customer Checks In

1. Authorize for estimated amount: 
POST /api/Payments/authorization
{
  "Amount": { "Value": 200.00 }, // Estimated: $150 room + $50 incidentals
  "PaymentMethod": { /* card details */ }
}
Response: 
{
  "paymentMethodAuthorizationId": 2055,
  "networkTransactionId": "431241081661798"
}
✅ Customer’s card is verified, $200 is held

​
Day 2-3: Customer Stays

Customer uses room service, minibar, etc. You track the actual charges.

​
Day 3: Customer Checks Out

2. Capture the actual amount: 
POST /api/Payments/capture/2055
{
  "Invoice": {
    "MerchantInvoiceRefId": "HOTEL-12345",
    "Amount": { "value": 187.50 } // Actual: $150 room + $37.50 incidentals
  }
}
Response: 
{
  "invoiceStatus": "Paid",
  "invoiceAttemptStatus": "Success"
}
✅ Customer is charged 187.50(lessthanthe187.50 (less than the 200 hold) ✅ The remaining $12.50 hold is automatically released

​
Authorization vs. Regular Sale: When to Use Which?

ScenarioUse Authorization/CaptureUse Regular Sale
E-commerce (known amount, ship immediately)❌✅
Hotel booking (variable final amount)✅❌
Pre-order (charge when shipped)✅❌
Subscription (recurring, known amount)❌✅
Custom product (verify card, charge later)✅❌
Restaurant (bill + tip)✅❌
Digital product (instant delivery)❌✅

​
Best Practices

  1. Store authorization IDs immediately: You’ll need them to capture or reverse
  2. Set reminders: Authorizations expire in ~7 days—don’t forget to capture
  3. Capture the right amount: You can capture less than authorized, but not more
  4. Reverse when appropriate: If you won’t capture, reverse to release the hold quickly
  5. Handle expiration: If an authorization expires, you’ll need to authorize again
  6. Use webhooks: Get notified when captures complete or authorizations expire

​
Common Questions

Q: Can I capture more than I authorized? A: No. You can capture the same amount or less, but not more. If you need more, authorize again for the additional amount. Q: What happens if I don’t capture? A: The authorization expires after ~7 days and the hold is automatically released. The customer is never charged. Q: Can I capture multiple times? A: No, each authorization can only be captured once. If you need to charge more, create a new authorization. Q: How long do authorizations last? A: Typically 7 days, but this can vary by processor. Check with Revolv3 support for your specific processor’s expiration time.

​
Next Steps