Skip to main content

Capture

View as Markdown

An authorization reserves an amount on the buyer's payment instrument, temporarily reducing its available balance. The authorized amount can either be captured, which starts the process that leads to the merchant being credited, or released through a cancellation and made available to the buyer again, according to the timings of the Issuer or of the payment method provider.

A capture lets you capture all or part of the amount of an authorized transaction. A capture can be requested separately from the authorization only if the ShopLogin is configured with separate authorization and capture. If the configuration uses unified capture, the amount is captured automatically after a successful authorization. How to configure this separation is explained on this page: getting_started/#moto.

If the capture request cannot be completed immediately because of technical issues, the transaction moves to the PRE state. In this case Fabrick automatically retries the captures at the start of the following day. If the new attempt succeeds, a MOV event is recorded on the transaction; otherwise the transaction undergoes further checks by the Fabrick teams.

More details on the state and events of a transaction are available on the Transaction state page.

Important

A transaction with transactionResult = APPROVED and transactionState = MOV means that a capture has been requested, but the actual credit must be verified with the party handling the settlement.

Some payment methods, once enabled, allow more than one capture to be requested up to the authorized amount: see Multiple capture.

Multiple Capture​

"Multiple Captures" or "Multicapture" (multiple MOVs) is the feature that lets you execute one or more captures (MOV) on a single authorization (AUT), up to the authorized amount.

An AUT can therefore be followed by one or more MOVs, each independent of the others.

Capture and settlementID​

When the feature is active, on each authorization (AUT) you can execute:

  • A full capture (MOV) covering the authorized amount
  • One or more partial MOVs whose total can:
    • cover the authorized amount
    • or leave an uncaptured part, which is released when the authorization expires
  • A full cancellation of the authorization (only if no captures have been made yet)

Each capture request must have a settlementID that is unique within the authorization.

The settlementID:

  • can be passed in the API request (max 20 characters)
  • can be set from the Dashboard, in the capture ID field (ID cattura, max 20 characters)
  • if not provided, is assigned automatically by the system

When it is assigned automatically, the identifier is made up of:

  • BankTransactionID
  • "_"
  • progressive capture number

For example, the first and second captures of the transaction with BankTransactionID = 123 have settlementID "123_1" and "123_2" respectively.

Refund and settlementID​

On each MOV you can execute:

  • A full refund (STO) covering the amount of that capture
  • One or more partial STOs whose total can cover the amount of that same capture

Refunds always refer to a single capture (MOV), not to the authorization as a whole. With multiple captures, you therefore need to specify which capture to refund by setting the settlementID.

For capture requests:

  • the settlementID must be unique within the authorization
  • requests with the same settlementID are rejected

For refunds:

  • there is no uniqueness constraint on the settlementID
  • several refund requests can be made on the same capture
  • requests are accepted as long as the total amount is less than or equal to the captured amount
Example:
AUT: 160.00€
MOV1: 80.00€ – settlementID = Capture_01
MOV2: 18.50€ – settlementID = Capture_02
MOV3: 60.00€ - settlementID = Capture_03
STO1: 50.00€ – settlementID = Capture_01
STO2: 18.50€ – settlementID = Capture_02
STO3: 30.00€ – settlementID = Capture_03
STO4: 30.00€ – settlementID = Capture_01
STO5: 30.00€ – settlementID = Capture_03

In this example:
- the authorization is split into several captures (MOV)
- each MOV is independent
- refunds are made on the individual captures
- the total refunded on each MOV does not exceed the amount of that capture

Below is the response of a detail call containing these movements. The state is STO because all the captured amounts have been fully refunded.

Request

GET /api/v1/payment/detail/{paymentID}
Host (sandbox): sandbox.gestpay.net
Host (production): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

Response

{
  "error": {
    "code": "0",
    "description": "request correctly processed"
  },
  "payload": {
    "transactionType": "detail",
    "transactionResult": "APPROVED",
    "transactionState": "STO",
    "transactionErrorCode": "0",
    "transactionErrorDescription": "Transazione correttamente effettuata",
    "bankTransactionID": "123",
    "shopTransactionID": "OrderID001",
    "shopTransactionID_2": "",
    "authorizationCode": "123456",
    "paymentID": "1234567891234",
    "currency": "EUR",
    "country": "ITALIA",
    "company": "VISA",
    "tdLevel": "FULL",
    "threeDS": {
      "authenticationResult": {
        "authenticationLevel": "2C",
        "authenticationStatus": "Y",
        "authStatusReason": "",
        "challengeResultTransStatus": "",
        "XID": "8329a454-e1e9-42ad-a5dd-123456",
        "AV": "MTIzNDU2Nzg5MDA5OABCDEFG",
        "ECI": "05",
        "AVAlgorithm": "",
        "threeDsVersion": "2.2.0"
      },
      "transDetails": {
        "authData": "",
        "authMethod": "02",
        "authTimeStamp": "202608201219",
        "acsID": "da8baf41-978f-441d-9a18-ABCDE"
      }
    },
    "events": [
      {
        "event": {
          "eventtype": "AUT",
          "eventamount": "160.00",
          "eventdate": "20/08/26 12:19:40",
          "eventARN": "",
          "eventID": "",
          "eventReferred": ""
        }
      },
      {
        "event": {
          "eventtype": "STO",
          "eventamount": "30.00",
          "eventdate": "20/08/26 12:26:53",
          "eventARN": "",
          "eventID": "",
          "eventReferred": "Capture_03"
        }
      },
      {
        "event": {
          "eventtype": "MOV",
          "eventamount": "80.00",
          "eventdate": "20/08/26 12:21:42",
          "eventARN": "",
          "eventID": "Capture_01",
          "eventReferred": ""
        }
      },
      {
        "event": {
          "eventtype": "STO",
          "eventamount": "30.00",
          "eventdate": "20/08/26 12:28:31",
          "eventARN": "",
          "eventID": "",
          "eventReferred": "Capture_01"
        }
      },
      {
        "event": {
          "eventtype": "STO",
          "eventamount": "30.00",
          "eventdate": "20/08/26 12:28:59",
          "eventARN": "",
          "eventID": "",
          "eventReferred": "Capture_03"
        }
      },
      {
        "event": {
          "eventtype": "STO",
          "eventamount": "50.00",
          "eventdate": "20/08/26 12:25:04",
          "eventARN": "",
          "eventID": "",
          "eventReferred": "Capture_01"
        }
      },
      {
        "event": {
          "eventtype": "STO",
          "eventamount": "18.50",
          "eventdate": "20/08/26 12:25:42",
          "eventARN": "",
          "eventID": "",
          "eventReferred": "Capture_02"
        }
      },
      {
        "event": {
          "eventtype": "MOV",
          "eventamount": "60.00",
          "eventdate": "20/08/26 12:24:13",
          "eventARN": "",
          "eventID": "Capture_03",
          "eventReferred": ""
        }
      },
      {
        "event": {
          "eventtype": "MOV",
          "eventamount": "18.50",
          "eventdate": "20/08/26 12:23:47",
          "eventARN": "",
          "eventID": "Capture_02",
          "eventReferred": ""
        }
      }
    ],
    "buyer": {
      "name": "",
      "email": ""
    },
    "risk": {
      "riskResponseCode": "",
      "riskResponseDescription": ""
    },
    "customInfo": null,
    "alertCode": "",
    "alertDescription": "",
    "cvvPresent": "TRUE",
    "dcc": null,
    "maskedPAN": "",
    "paymentMethod": "VISA",
    "productType": "Credit",
    "token": "40DD1KZB0QJD3101",
    "tokenExpiryMonth": "05",
    "tokenExpiryYear": "27",
    "tokenDetails": {
      "TokenValue": "40DD1KZB0QJD3101",
      "TokenExpiryMonth": "05",
      "TokenExpiryYear": "27",
      "TokenProvider": "AXERVE",
      "CardDetails": {
        "CardSuffix": "3101",
        "CardExpiryMonth": "05",
        "CardExpiryYear": "27",
        "CardHolderName": null
      },
      "CardAssets": {
        "CardArt": {
          "Type": null,
          "MediaContents": null,
          "Height": null,
          "Width": null
        },
        "BrandLogo": {
          "Type": null,
          "MediaContents": null,
          "Height": null,
          "Width": null
        }
      }
    },
    "fraudPrevention": {
      "check": "FALSE",
      "state": "",
      "description": "",
      "order": ""
    },
    "automaticOperation": {
      "type": "MOV",
      "date": "20/08/26 00:00:00",
      "amount": "158.50"
    }
  }
}

Checking the capture outcome​

To check whether a capture request has been completed successfully, as shown above, query the payment/detail API and analyze the events returned in payload.events.

In particular:

  • A PRE event means that a capture attempt has been started but not yet completed.
  • A MOV event means that the capture has been executed.

For more information on transaction states and on the meaning of each event, see the Transaction state page.

Payload​

POST payment/capture​

Refund payload > POST payment/refund.

Request

POST /api/v1/payment/capture
Host (sandbox): sandbox.gestpay.net
Host (production): ecomms2s.sella.it
Authorization: apikey ****************
{
  "shopLogin":"GESPAY12345",
  "amount":"0.01",
  "currency":"EUR",
  "bankTransactionID":"",
  "shopTransactionID":"",
  "settlementID":"",
  "paymentID":"1234567891234"
}

Response

{
  "error": {
    "code": "0",
    "description": "request correctly processed"
  },
  "payload": {
    "transactionType": "capture",
    "transactionResult": "OK",
    "shopTransactionID": "OrderID001",
    "bankTransactionID": "123",
    "paymentID": "1234567891234"
  }
}

POST payment/capture with settlementID​

Refund payload with settlementID > POST payment/refund with settlementID.

Request

POST /api/v1/payment/capture
Host (sandbox): sandbox.gestpay.net
Host (production): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json
{
  "shopLogin":"GESPAY12345",
  "amount":"18.50",
  "currency":"EUR",
  "paymentID":"1234567891234",
  "settlementID":"Capture_02"
}

Response

{
  "error": {
    "code": "0",
    "description": "request correctly processed"
  },
  "payload": {
    "transactionType": "capture",
    "transactionResult": "OK",
    "shopTransactionID": "OrderID001",
    "bankTransactionID": "123",
    "paymentID": "1234567891234"
  }
}

Error scenarios​

Error code 8014​

If you request to capture more than the authorized amount, you get the following:

Response

{
  "error": {
    "code": "8014",
    "description": "Imp.mov. > Imp.aut"
  },
  "payload": {}
}

Error code 2019​

  • If you request a capture with a settlementID longer than 20 characters.
  • If you request a capture with a settlementID already used in a previous capture for the same authorization (when the requested amount, added to what has already been captured, does not exceed the authorized amount).
  • If you request to capture a transaction that has already been cancelled. More details on the cancel page.

you get the following:

Response

{
  "error": {
    "code": "2019",
    "description": "Transazione non movimentabile"
  },
  "payload": {}
}

Error code 2011​

  • If you request to capture a transaction that does not exist, you get the following:

Response

{
  "error": {
    "code": "2011",
    "description": "Transaction not found"
  },
  "payload": {}
}

Error code 1144​

  • If you request to capture a transaction without specifying the transaction identifier (paymentID), you get the following:

Response

{
  "error": {
    "code": "1144",
    "description": "Campo obbligatorio non valorizzato"
  },
  "payload": {}
}

Support​

Fabrick