Captures

Using the paymentId and authorization values returned from a previous 2-pass authorization, capture requests are submitted as POST requests to the /payments/paymentId/capture path.

As an example, let's assume we've created an authorization of $15.25 and received a paymentId of 64af96f1c79c5e590217a203 and an authorization of EP273834 in the response.

Then, to capturing $11.10 against the authorization, we'd send the request to /payments/64af96f1c79c5e590217a203/capture, as follows:

Request: Capture an Authorization

POST /payments/64af96f1c79c5e590217a203/capture
{
  "amount": 1110,
  "authorization": "EP273834"
}

Response: Capture an Authorization

{
  "paymentId": "64aca4e5c79c5e590217a16a",
  "type": "capture",
  "status": "completed",
  "approved": true,
  "captured": true,
  "authorization": "EP273834",
  "amount": 1110,
  ...
}

Now, if you look up the original transaction, you will see that its status has changed to 'completed' and that there is a captureDetails attribute which is an array of paymentIds of the capture transactions. There is also a remaining value, which is the amount of un-captured funds — 415 cents in this case.

Request: Get Payment Details

GET /payments/64af96f1c79c5e590217a203

Response: Get Payment Details

{
  "paymentId": "64af96f1c79c5e590217a203",
  "type": "payment",
  "status": "completed",
  "approved": true,
  "captured": true,
  ...
  "captureDetails": {
    "captures": [
      "64af970bc79c5e590217a218"
    ],
    "remaining": 415
  }
}

Let's assume we then did another capture of $2.20 againt the original authorization, and looked up the original details again...

Response: Second Get Payment Details

{
  "paymentId": "64af96f1c79c5e590217a203",
  "type": "payment",
  "status": "completed",
  "approved": true,
  "captured": true,
  ...
  "captureDetails": {
    "captures": [
      "64af970bc79c5e590217a218",
      "64af9835c79c5e590217a22d"
    ],
    "remaining": 195
  }
}

You can now see that the paymentIds of both captures are listed, and that the remaining amount has decreased. When the remaining amount reaches zero, no further captures will be permitted against the original authorization.

Usage Notes

You can only capture a previous authorization, ie: a payment where you included capture: false.

You can submit multiple captures against a single authorization, as long as the total amount captured does not exceed 200% of the authorized amount.

As an example, let's assume a customer has bought 3 items totalling $100, only two of which are in stock.

You would submit an initial authorization for $100, followed by a capture when sending the first two items, say $75 incl. shipping. When the final item comes back in stock you would submit a second capture for the remaining amount, plus shipping, say $35.