An AI skill is available for this guide, get it on the Skills Marketplace (GitHub).
If your merchant doesn't capture a pre-authorization, it expires and the issuing bank releases the hold on the customer's card.
To capture the pre-authorization, you must use our API.
Before you begin
Authenticate your requests before making API calls. If your request fails, see Errors.
Send a POST request to capture the pre-authorization
To capture the pre-authorization, you need the UNIQUEREF that we returned to the merchant's receipt page. Send the UNIQUEREF in the paymentId path parameter in a POST request to our Payments endpoint.
| Environment | URL |
|---|---|
| Test | https://api.uat.payroc.com/v1/payments/:paymentId/capture |
| Production | https://api.payroc.com/v1/payments/:paymentId/capture |
Depending on the amount you want to capture:
- Capture the full amount of the pre-authorization - Don’t send a value for the amount parameter in your request.
- Capture less than the amount of the pre-authorization - Send a value for the amount parameter in your request.
- Capture more than the amount of the pre-authorization - Adjust the pre-authorization before you capture it. For more information about adjusting a pre-authorization, go to Adjust Payment.
Request parameters
To create the body of your request, use the following parameters:
Schema (request.body)
Request body schema for POST /payments/{paymentId}/capture
Example request
Request
POST https://api.payroc.com/v1/payments/{paymentId}/capture
Payment capture
curl -X POST https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture \
-H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"processingTerminalId": "1234001",
"operator": "Jane",
"amount": 4999,
"breakdown": {
"subtotal": 4999,
"dutyAmount": 499,
"freightAmount": 500,
"items": [
{
"unitPrice": 4000,
"quantity": 1
}
]
}
}'
Payment capture
import requests
url = "https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture"
payload = {
"processingTerminalId": "1234001",
"operator": "Jane",
"amount": 4999,
"breakdown": {
"subtotal": 4999,
"dutyAmount": 499,
"freightAmount": 500,
"items": [
{
"unitPrice": 4000,
"quantity": 1
}
]
}
}
headers = {
"Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
Payment capture
const url = 'https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture';
const options = {
method: 'POST',
headers: {
'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: '{"processingTerminalId":"1234001","operator":"Jane","amount":4999,"breakdown":{"subtotal":4999,"dutyAmount":499,"freightAmount":500,"items":[{"unitPrice":4000,"quantity":1}]}}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
Payment capture
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture"
payload := strings.NewReader("{\n \"processingTerminalId\": \"1234001\",\n \"operator\": \"Jane\",\n \"amount\": 4999,\n \"breakdown\": {\n \"subtotal\": 4999,\n \"dutyAmount\": 499,\n \"freightAmount\": 500,\n \"items\": [\n {\n \"unitPrice\": 4000,\n \"quantity\": 1\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
Payment capture
require 'uri'
require 'net/http'
url = URI("https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"processingTerminalId\": \"1234001\",\n \"operator\": \"Jane\",\n \"amount\": 4999,\n \"breakdown\": {\n \"subtotal\": 4999,\n \"dutyAmount\": 499,\n \"freightAmount\": 500,\n \"items\": [\n {\n \"unitPrice\": 4000,\n \"quantity\": 1\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body
Payment capture
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture")
.header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"processingTerminalId\": \"1234001\",\n \"operator\": \"Jane\",\n \"amount\": 4999,\n \"breakdown\": {\n \"subtotal\": 4999,\n \"dutyAmount\": 499,\n \"freightAmount\": 500,\n \"items\": [\n {\n \"unitPrice\": 4000,\n \"quantity\": 1\n }\n ]\n }\n}")
.asString();
Payment capture
<?php
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture', [
'body' => '{
"processingTerminalId": "1234001",
"operator": "Jane",
"amount": 4999,
"breakdown": {
"subtotal": 4999,
"dutyAmount": 499,
"freightAmount": 500,
"items": [
{
"unitPrice": 4000,
"quantity": 1
}
]
}
}',
'headers' => [
'Authorization' => 'Bearer <token>',
'Content-Type' => 'application/json',
'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
],
]);
echo $response->getBody();
Payment capture
using RestSharp;
var client = new RestClient("https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"processingTerminalId\": \"1234001\",\n \"operator\": \"Jane\",\n \"amount\": 4999,\n \"breakdown\": {\n \"subtotal\": 4999,\n \"dutyAmount\": 499,\n \"freightAmount\": 500,\n \"items\": [\n {\n \"unitPrice\": 4000,\n \"quantity\": 1\n }\n ]\n }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Payment capture
import Foundation
let headers = [
"Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
]
let parameters = [
"processingTerminalId": "1234001",
"operator": "Jane",
"amount": 4999,
"breakdown": [
"subtotal": 4999,
"dutyAmount": 499,
"freightAmount": 500,
"items": [
[
"unitPrice": 4000,
"quantity": 1
]
]
]
] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
Response fields
If your request is successful, we capture the pre-authorization and return a response. The response contains the following fields:
Schema (response.body)
Response body schema for POST /payments/{paymentId}/capture
Example response
Response (200)
{
"paymentId": "M2MJOG6O2Y",
"processingTerminalId": "1234001",
"order": {
"orderId": "OrderRef6543",
"amount": 4999,
"currency": "USD",
"dateTime": "2024-07-02T15:30:00Z",
"description": "Large Pepperoni Pizza"
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "453985******7062",
"expiryDate": "1230",
"securityChecks": {
"cvvResult": "M",
"avsResult": "Y"
}
},
"transactionResult": {
"status": "ready",
"responseCode": "A",
"type": "sale",
"approvalCode": "OK3",
"authorizedAmount": 4999,
"currency": "USD",
"responseMessage": "OK3"
},
"operator": "Jane",
"customer": {
"firstName": "Sarah",
"lastName": "Hopper",
"billingAddress": {
"address1": "1 Example Ave.",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"shippingAddress": {
"recipientName": "Sarah Hopper",
"address": {
"address1": "1 Example Ave.",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
}
}
},
"supportedOperations": [
"capture",
"fullyReverse",
"partiallyReverse",
"incrementAuthorization",
"adjustTip",
"setAsPending"
],
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}