Authorize and capture transactions

For some businesses, it makes sense to authorize a transaction first and then capture later. When you authorize, you verify that the customer has sufficient funds, and you place a hold on that amount without actually processing the transaction and taking the money. Authorizing a transaction gives merchants time to verify inventory, prepare shipments, or complete services before finalizing the charge. Capturing the transaction is what puts the transaction in a batch for settlement and starts the process of moving the funds from the customer to the merchant account.

Capturing an authorized transaction later also allows merchants to capture part of the authorized amount if the final total ends up being less than expected, avoiding the need for refunds.

This guide covers how to authorize and capture transactions through the API. To authorize and capture a payment in one step, use the Make a transaction endpoint instead.

Considerations

Keep these considerations in mind when working with transactions:

• Authorizing a transaction reserves funds for the merchant but doesn’t move them.
• You must capture an authorized transaction to complete it and move the funds.
• You can capture an amount equal to or less than the original authorization, but not less than 85% of the original authorized amount.
• If you need to capture less than 85% of the authorized amount or more than the authorized amount, then void the authorization and create a new sale transaction.
• Service fees can be adjusted proportionally when capturing partial amounts, and can vary based on your service fee configuration. See Pass-through fees for more information.
• Authorized transactions aren’t flagged for settlement until they’re captured.
• If an authorized transaction isn’t captured within 10 days, Payabli voids the transaction. If you try to capture the voided transaction, the capture will fail.

Authorize a transaction

Send a POST request to /api/MoneyIn/authorize to authorize a payment transaction. This action reserves funds and returns an authorization code. See the API reference for this endpoint for full documentation.

This example authorizes a card transaction for $100, with no service fee, for entrypoint f743aed24a. The customer ID is 4440.

1
curl -X POST https://api-sandbox.payabli.com/api/MoneyIn/authorize \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "paymentDetails": {
6
    "totalAmount": 100,
7
    "serviceFee": 0
8
  },
9
  "paymentMethod": {
10
    "cardcvv": "999",
11
    "cardexp": "02/27",
12
    "cardHolder": "John Cassian",
13
    "cardnumber": "4111111111111111",
14
    "cardzip": "12345",
15
    "initiator": "payor",
16
    "method": "card"
17
  },
18
  "customerData": {
19
    "customerId": 4440
20
  },
21
  "entryPoint": "f743aed24a",
22
  "ipaddress": "255.255.255.255"
23
}'

A successful request returns a 200 response with a JSON body containing a referenceId which you’ll need for the capture operation.

1
{
2
  "responseText": "Success",
3
  "isSuccess": true,
4
  "responseData": {
5
    "authCode": "123456",
6
    "referenceId": "10-7d9cd67d-2d5d-4cd7-a1b7-72b8b201ec13",
7
    "resultCode": 1,
8
    "resultText": "Authorized",
9
    "avsResponseText": "No address or ZIP match only",
10
    "cvvResponseText": "CVV2/CVC2 no match",
11
    "customerId": 4440,
12
    "methodReferenceId": null
13
  },
14
  "pageIdentifier": null
15
}

Capture a transaction

To capture an authorized transaction and start the settlement process, send a POST request to /MoneyIn/capture/{transId}. This endpoint allows you to capture the full authorized amount or a partial amount (minimum 85% of the original authorization) with flexible service fee adjustments. See the API reference for full documentation.

When capturing a transaction, the following rules apply:

• Full capture: Capture the exact authorized amount with the original or adjusted service fee
• Partial capture: Capture less than the authorized amount (minimum 85% of original total)
• Service fee adjustment: Adjust the service fee proportionally or as needed when capturing partial amounts
• Out-of-range captures: If you need to capture less than 85% or more than the authorized amount, you must void the original authorization and create a new sale transaction with the correct amount.

Each example captures a $100 card transaction for the transaction 10-7d9cd67d-2d5d-4cd7-a1b7-72b8b201ec13.

1
curl -X POST https://api-sandbox.payabli.com/api/MoneyIn/capture/10-7d9cd67d-2d5d-4cd7-a1b7-72b8b201ec13 \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "paymentDetails": {
6
    "totalAmount": 105,
7
    "serviceFee": 5
8
  }
9
}'

A successful capture request returns a 200 response with a JSON body containing the transaction details.

1
{
2
  "responseCode": 1,
3
  "pageIdentifier": null,
4
  "roomId": 0,
5
  "isSuccess": true,
6
  "responseText": "Success",
7
  "responseData": {
8
    "authCode": "123456",
9
    "referenceId": "10-7d9cd67d-2d5d-4cd7-a1b7-72b8b201ec13",
10
    "resultCode": 1,
11
    "resultText": "SUCCESS",
12
    "avsResponseText": null,
13
    "cvvResponseText": null,
14
    "customerId": null,
15
    "methodReferenceId": null
16
  }
17
}

Real-world example

This example illustrates a homeowner reserving a clubhouse for an event with a $200 deposit for cleaning and damages, plus a 3% service fee. After the event, the clubhouse admin calculates the actual charges and charges the homeowner for the final amount.

Initial authorization: $200.00 + $6.00 (3% fee) = $206.00 total

1
  POST /api/MoneyIn/capture/{transId}
2
  {
3
    "paymentDetails": {
4
      "totalAmount": 185.40,
5
      "serviceFee": 5.40
6
    }
7
  }

Migrating from GET to POST endpoint

If you’re currently using the GET endpoint (/MoneyIn/capture/{transId}/{amount}), you need to migrate to the POST endpoint before November 24, 2025.

Here are the key differences between the two endpoints:

And here are examples for both endpoints:

Before (GET endpoint):

1
curl https://api-sandbox.payabli.com/api/MoneyIn/capture/10-7d9cd67d-2d5d-4cd7-a1b7-72b8b201ec13/0 \
2
     -H "requestToken: <apiKey>"

After (POST endpoint):

1
curl -X POST https://api-sandbox.payabli.com/api/MoneyIn/capture/10-7d9cd67d-2d5d-4cd7-a1b7-72b8b201ec13 \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "paymentDetails": {
6
    "totalAmount": 105,
7
    "serviceFee": 5
8
  }
9
}'