Settlement is the process of actually transferring funds between parties to finalize a transaction.

Settlements are resolved in batches. All outstanding authorized transactions are resolved together. This processing transfers funds to the merchants' accounts.

The merchant defines a settlement time in their merchant dashboard. This the time of day, typically at night or after the store's closing. Settlements are done automatically at that time. There is no explicit API call needed to start this automatic processing.

Alternatively, the batch settlement may be explicitly started at any time.
Use: POST {{baseURL}}/v2/settlements/batches/close
This does not process individual transactions. It processes only outstanding authorized transactions. The only difference is the endpoint gives the merchant some flexibility in the settlement batches.

A typical workflow for settlement includes:

Authorization
An authorized transaction is one that has been approved and funds are held or reserved. No money has moved yet. That means funds are not instantly available for each transaction. Merchants may see a delay between a sale and the funds deposited in their account.

For example, the following call starts a transaction with the captureMethod of Auto. This automatically adds the transaction in an open settlement batch when the transaction is completed. The call returns transactionId, which may be used to reference this transaction.

  POST /v2/transactions
  Authorization: Bearer {{apiKey}}                                                                                          
  Content-Type: application/json
  {                                                                                                                         
  "baseAmount": 150.00,                                                                                                 
  "currencyCode": "USD",
  "customerInitiatedTransaction": true,
      "transactionDetails": 
      {
          "cardData":
          {
              "captureMethod": "Auto",
              "paymentMethodDetails":
              {
                "cardNumber": "4111111111111111",
                "securityCode": "737",
                "expirationMonth": 9,
                "expirationYear": 2027
                }
            }
        }
    }

Capture or batch
Approved transactions are grouped together, or batched, for later processing.

If captureMethod is Auto, no additional processing is required at this step. The transaction has been added to the settlement batch automatically.

If captureMethod is Manual, the transaction must be explicitly added to the settlement batch. In this case use POST /v2/transactions/{{transactionId}}/capture to capture it to the settlement batch.

Care must be taken when using Manual because if the transaction is never captured, the authorization simply expires and no funds move.

POST /v2/transactions/{{transactionId}}/capture
Authorization: Bearer {{apiKey}}
Content-Type: application/json

{
  "amount": 150.00
}

Settlement
Settlement is the step where an authorized transaction becomes a real transfer of money.

The batch is submitted to the card networks or banks. This processing includes moving the money from the cardholder's bank, through the network, to the acquiring bank. It eventually ends at merchant's account, minus fees. This batch processing usually happens on a schedule, such as daily batch settlement at the end of business.

Verifying
It may take a while for settlement processing to finish. To verify the status of the settlement processing use:
POST /v2/settlements/batches/close
See batchStatus for the settlement status. The processing is complete with the status Settled.

Rather than polling GET /v2/settlements/batches, subscribe to webhook endpoint for settlement.batch.completed. This returns a pushed notification once the settlement batch finishes processing.

The webhook return payload is a reduced portion of the full payload. It intends to be complete enough to verify the result. No status is included because this event is triggered only by a Settled status.

    {
        "id": "0f27fcce-a282-4049-b984-e82325ea1d6b",
        "data": { "object": { "id": "555e779c-...", "resourceType": "settlement" } },
        "type": "settlement.batch.completed",
        "created": 1784068840,
        "apiVersion": "v2"
    }