Capture the pre-authorization

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

Bearer tokens

Use our Identity Service to generate a Bearer token to include in the header of your requests. To generate your Bearer token, complete the following steps:

1. Include your API key in the x-api-key parameter in the header of a POST request.
2. Send your request to https://identity.payroc.com/authorize.

Example request

$
curl --location --request POST 'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'

Example response
If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.

1
{
2
  "access_token": "eyJhbGc....adQssw5c",
3
  "expires_in": 3600,
4
  "scope": "service_a service_b",
5
  "token_type": "Bearer"
6
}

Headers

To create the header of each POST request, you must include the following parameters:

• Content-Type: Include application/json as the value for this parameter.
• Authorization: Include your Bearer token in this parameter.
• Idempotency-Key: Include a UUID v4 to make the request idempotent.

$
curl
$
-H "Content-Type: application/json"
$
-H "Authorization: <Bearer token>"
$
-H "Idempotency-Key: <UUID v4>"

Errors

If your request is unsuccessful, we return an error. For more information about errors, 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.

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:

Example request

1
curl -X POST https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture \
2
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3
     -H "Authorization: Bearer <token>" \
4
     -H "Content-Type: application/json" \
5
     -d '{
6
  "processingTerminalId": "1234001",
7
  "operator": "Jane",
8
  "amount": 4999,
9
  "breakdown": {
10
    "subtotal": 4999,
11
    "dutyAmount": 499,
12
    "freightAmount": 500,
13
    "items": [
14
      {
15
        "quantity": 1,
16
        "unitPrice": 4000
17
      }
18
    ]
19
  }
20
}'

Response fields

If your request is successful, we capture the pre-authorization and return a response. The response contains the following fields:

Example response

1
{
2
  "paymentId": "M2MJOG6O2Y",
3
  "processingTerminalId": "1234001",
4
  "order": {
5
    "amount": 4999,
6
    "currency": "USD",
7
    "orderId": "OrderRef6543",
8
    "dateTime": "2024-07-02T15:30:00Z",
9
    "description": "Large Pepperoni Pizza"
10
  },
11
  "card": {
12
    "type": "MasterCard",
13
    "entryMethod": "keyed",
14
    "cardNumber": "453985******7062",
15
    "expiryDate": "1230",
16
    "securityChecks": {
17
      "cvvResult": "M",
18
      "avsResult": "Y"
19
    }
20
  },
21
  "transactionResult": {
22
    "status": "ready",
23
    "responseCode": "A",
24
    "type": "sale",
25
    "approvalCode": "OK3",
26
    "authorizedAmount": 4999,
27
    "currency": "USD",
28
    "responseMessage": "OK3"
29
  },
30
  "operator": "Jane",
31
  "customer": {
32
    "firstName": "Sarah",
33
    "lastName": "Hopper",
34
    "billingAddress": {
35
      "address1": "1 Example Ave.",
36
      "address2": "Example Address Line 2",
37
      "address3": "Example Address Line 3",
38
      "city": "Chicago",
39
      "state": "Illinois",
40
      "country": "US",
41
      "postalCode": "60056"
42
    },
43
    "shippingAddress": {
44
      "recipientName": "Sarah Hopper",
45
      "address": {
46
        "address1": "1 Example Ave.",
47
        "address2": "Example Address Line 2",
48
        "address3": "Example Address Line 3",
49
        "city": "Chicago",
50
        "state": "Illinois",
51
        "country": "US",
52
        "postalCode": "60056"
53
      }
54
    }
55
  },
56
  "supportedOperations": [
57
    "capture",
58
    "fullyReverse",
59
    "partiallyReverse",
60
    "incrementAuthorization",
61
    "adjustTip",
62
    "setAsPending"
63
  ],
64
  "customFields": [
65
    {
66
      "name": "yourCustomField",
67
      "value": "abc123"
68
    }
69
  ]
70
}