# Authorizations and Captures

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

| Payment Method | Authorization | Capture | Sale |
|  --- | --- | --- | --- |
| Credit/Debit Card | ✅ | ✅ | ✅ |
| MB WAY | ✅ | ✅ | ✅ |
| Apple Pay | ✅ | ✅ | ✅ |
| Google Pay | ✅ | ✅ | ✅ |
| Samsung Pay | ✅ | ✅ | ✅ |
| Multibanco | ❌ | ❌ | ✅ |
| Direct Debit | ❌ | ❌ | ✅ |
| Virtual IBAN | ❌ | ❌ | ✅ |


## Implementation Examples

### Single-Step Sale


```bash
# 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**


```bash
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:


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

**Step 2: Capture the authorized funds**


```bash
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


```bash
# 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:

| Payment Method | Typical Hold Period |
|  --- | --- |
| Debit Card | 3-7 days |
| MB WAY | 7 days |


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

## Partial Captures

You can capture less than the authorized amount:


```bash
# 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:


```bash
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](/docs/guides/payment-methods) - Learn which methods support auth/capture
- [Payment Types](/docs/guides/payment-types) - Understand different payment workflows
- [Webhooks](/docs/guides/webhooks) - Receive notifications for auth/capture events
- [API Reference](/openapi) - Detailed endpoint documentation