Authorizations and Captures

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

Certain payment methods like credit card and MB WAY go through two distinct phases: authorisation and capture. Our integrations allow you to move through them separately (issuing a card authorisation first and later capturing the funds) or in a single step referred to in our APIs as sale (authorisation followed by capture).

Understanding the Flow

Authorisation

Authorisation is the first step of the process and involves guaranteeing that the buyer has sufficient funds or credit available to make the payment. If so, the funds are put on hold: the customer cannot use them to pay for other goods or services, but they're not yet transferred to the merchant's account. If the merchant fails to capture the funds in the following days, the hold is lifted.

Key Points:

• Verifies customer has sufficient funds
• Puts funds on hold (not transferred yet)
• Hold expires if not captured within timeframe
• No money movement occurs

Use Cases:

• Verify payment method before providing service
• Hold funds for orders that ship later
• Reserve amount for rentals or deposits
• Implement split/multi-captures

Capture

A capture is the actual transfer of funds from the buyer to the merchant.

Key Points:

• Transfers money from customer to merchant
• Can be partial or full amount
• Triggers final payment processing

Sale

In many of our integrations, specifying sale as the type of operation will automatically perform an authorisation and a capture, immediatelly transferring the funds from the customer to the merchant in a single step (if successful).

Key Points:

• Single-step payment
• Authorization + Capture combined
• Immediate fund transfer
• Simpler implementation

When to Use Each Method

Use Authorization + Capture When:

1. Delayed Fulfillment: You don't ship products immediately

   Example: E-commerce with 2-3 day shipping
   - Day 1: Authorize payment when order placed
   - Day 3: Capture when item ships

2. Service-Based Businesses: Service is provided after booking

   Example: Hotel reservation
   - Booking: Authorize to hold funds
   - Check-out: Capture actual amount

3. Variable Final Amount: Final amount unknown at booking

   Example: Car rental
   - Authorize estimated amount
   - Capture actual amount based on usage

Use Sale When:

1. Immediate Digital Products: Instant delivery

   Example: SaaS subscription, e-books, digital downloads

2. In-Person Transactions: Point of sale

   Example: Retail store, restaurant

3. Immediate Services: Service provided instantly

   Example: Online courses, streaming access

Supported Payment Methods

Implementation Examples

Single-Step Sale

# Create a sale (authorization + capture in one step)
curl -X POST 'https://api.test.easypay.pt/2.0/single' \
  -H 'AccountId: YOUR_ACCOUNT_ID' \
  -H 'ApiKey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "sale",
    "value": 50.00,
    "currency": "EUR",
    "method": "cc",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'

Two-Step Authorization and Capture

Step 1: Authorize the payment

curl -X POST 'https://api.test.easypay.pt/2.0/single' \
  -H 'AccountId: YOUR_ACCOUNT_ID' \
  -H 'ApiKey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "authorisation",
    "value": 100.00,
    "currency": "EUR",
    "method": "cc",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'

Response:

{
  "status": "success",
  "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
  "method": "cc"
}

Step 2: Capture the authorized funds

curl -X POST 'https://api.test.easypay.pt/2.0/capture/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8' \
  -H 'AccountId: YOUR_ACCOUNT_ID' \
  -H 'ApiKey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 100.00
  }'

Multi-Captures

It is also possible to issue an authorisation for a value that will later be split among different captures. One example is a store supporting split payments for orders of multiple vendors. The full amount of the order is authorised but the different captures can be issued at different times, after each vendor confirms or ships the goods.

Multi-Capture Example

# Step 1: Authorize the full order amount
POST /single
{
  "type": "authorisation",
  "value": 150.00,
  "method": "cc"
}

# Step 2: Capture product A (when they ship)
POST /capture/:id
{
  "value": 75.00,
  "descriptive": "Electronics"
}

# Step 3: Capture product B (when they ship)
POST /capture/:id
{
  "value": 75.00,
  "descriptive": "Books"
}

Authorization Hold Periods

The authorization hold period varies by payment method and card issuer:

Important: Always capture within the hold period, or the authorization will be automatically released.

Partial Captures

You can capture less than the authorized amount:

# Authorized: €100
# Capture only €75
POST /capture/:id
{
  "value": 75.00
}

Result: €75 is captured, €25 authorization is released.

Voiding an Authorization

If you need to cancel an authorization before it expires:

POST /void/{authorization-id}
{
  "descriptive": "Customer cancelled order"
}

This immediately releases the hold on the customer's funds.

Best Practices

1. Capture Promptly: Don't wait until the last day of the hold period
2. Communicate Clearly: Inform customers about holds on their accounts
3. Void Unused Authorizations: Don't leave authorizations to expire naturally
4. Use Descriptive Text: Help customers identify transactions
5. Monitor Hold Periods: Track authorizations to ensure timely captures
6. Consider Multi-Capture: For complex orders with multiple shipments

Common Workflows

E-Commerce Flow

1. Customer places order → Authorize payment
2. Order is packed → Prepare for shipment
3. Item ships → Capture payment
4. OR order cancelled → Void authorization

Hotel Reservation Flow

1. Customer books room → Authorize expected amount
2. Check-in → Verify authorization still valid
3. Check-out → Calculate final amount
4. Capture actual amount (may be more or less than authorized)

Marketplace Flow

1. Customer orders from multiple vendors → Authorize total
2. Vendor 1 ships → Capture vendor 1's amount
3. Vendor 2 ships → Capture vendor 2's amount
4. Each capture can happen independently

Next Steps

• Payment Methods - Learn which methods support auth/capture
• Payment Types - Understand different payment workflows
• Webhooks - Receive notifications for auth/capture events
• API Reference - Detailed endpoint documentation