A merchant can use pre-authorizations to hold an amount on a customer’s card to capture later. The merchant can run pre-authorizations only if we have enabled the function on their account. If we have not enabled pre-authorizations on the merchant’s account, we run pre-authorization attempts as sales with a status of ‘pending’. If a merchant needs to capture more than they originally pre-authorized, they can adjust the pre-authorization amount before they capture it. For example:

A hotel pre-authorizes a one-night stay for a customer at $100.
The customer decides to have dinner in the hotel for $50. The hotel adjusts the $100 pre-authorization to $150.
At checkout, the hotel captures $150 from the customer’s account for the one- night stay and dinner.

Integration steps

Step 1. Create a payment.
Step 2. (Optional) Adjust a payment.
Step 3. Capture a payment.

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:

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

You need to generate a new Bearer token before the previous Bearer token expires.

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.

{
"access_token": "eyJhbGc....adQssw5c",
"expires_in": 3600,
"scope": "service_a service_b",
"token_type": "Bearer"
}

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.

Step 1. Create a payment

To run a pre-authorization, set both autoCapture and processAsSale to false in the request body. If both parameters are set to true, the transaction runs as a sale instead of a pre-authorization. To run a pre-authorization, send a POST request to our Payments endpoint. Test endpoint: https://api.uat.payroc.com/v1/payments
Production endpoint: https://api.payroc.com/v1/payments

Request parameters

To create the body of your request, use the following parameters:

Header parameters

Body parameters

Example request

Request

curl --request post \
	--url https://api.payroc.com/v1/payments \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"channel":"web","processingTerminalId":"1234001","operator":"Postman","order":{"orderId":"OrderRef6543","description":"Large Pepperoni Pizza","currency":"USD","amount":4999},"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"}}},"paymentMethod":{"type":"card","cardDetails":{"entryMethod":"keyed","keyedData":{"dataFormat":"plainText","device":{"model":"paxA80","serialNumber":"WPC202833004712"},"expiryDate":"1225","cardNumber":"4539858876047062"}}},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'

Response fields

Save the paymentId to use when you capture the payment.

If your request is successful, we send a pre-authorization request to the customer’s bank or card company for the specific amount. The response contains the following fields:

Response Schema

Status Code 201

Successful request. We processed the transaction.

Response headers

Response body

Example response

Response

application/json

{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "operator": "Postman",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD"
  },
  "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"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK3"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

Step 2. (Optional) Adjust a payment

A merchant can capture more than they originally pre-authorized, however each card brand sets different limits to the additional amount that the merchant can capture. If a merchant needs to capture more than they originally pre-authorized, we recommend that they adjust the pre-authorization before they capture it.

To adjust a pre-authorized amount, send a POST request to our Payments endpoint. Test endpoint: https://api.uat.payroc.com/v1/payments/{paymentId}/adjust
Production endpoint: https://api.payroc.com/v1/payments/{paymentId}/adjust

Request parameters

To create the body of your request, use the following parameters:

Path parameters

Header parameters

Body parameters

Example request

Request

curl --request post \
	--url https://api.payroc.com/v1/payments/M2MJOG6O2Y/adjust \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"adjustments":[{"type":"customer","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"}}},{"type":"order","amount":3999}]}'

Response fields

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

Response Schema

Status Code 200

Successful request. We adjusted the transaction.

Response body

Example response

Response

application/json

{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Example payment",
    "amount": 4999,
    "currency": "USD"
  },
  "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"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK6",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK6"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

Step 3. Capture a payment

To capture the pre-authorization, send a POST request to our Payments endpoint. Payments endpoint: https://api.payroc.com/v1/payments/{paymentId}/capture

Request parameters

To create the body of your request, use the following parameters:

Path parameters

Header parameters

Body parameters

Example request

Request

curl --request post \
	--url https://api.payroc.com/v1/payments/M2MJOG6O2Y/capture \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"processingTerminalId":"abc123","operator":"Jane","amount":4999,"breakdown":{"subtotal":2899,"cashbackAmount":0,"tip":{"type":"percentage","amount":0,"percentage":0},"taxes":[{"name":"Sales Tax","rate":7}],"surcharge":{"bypass":false},"dualPricing":{"offered":false,"alternativeTender":"card"},"dutyAmount":0,"freightAmount":0,"items":[{"commodityCode":"5812-0111","productCode":"PZA-001-LG","description":"Large Pepperoni Pizza","unitOfMeasure":"QAN","unitPrice":2709,"quantity":1,"discountRate":5,"taxes":[{"name":"Sales Tax","rate":7}]}]}}'

Response fields

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

Response Schema

Status Code 200

Successful request. We captured the payment.

Response body

Example response

Response

application/json

{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "operator": "Postman",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD"
  },
  "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"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK3"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

Test cases

Before you run test cases, read the Payments page in Test Your Integration.

Run a pre-authorization

Send a POST request to the following endpoint: POST https://api.uat.payroc.com/v1/payments

Note: Set the value for the autoCapture parameter to false.

Example response

{
	"paymentId": "C7BHY7KWCW",
	"processingTerminalId": "3204001",
	"operator": "Davi-Crisostomo-CHP",
	"order": {
		"orderId": "1234567890Q1",
		"dateTime": "2023-06-20T21:03:30.925+01:00",
		"description": "PreAuth Card Transaction (WEB) - Sale - KEYED (plain_text) with CVV",
		"amount": 12346,
		"currency": "USD"
	},
	"card": {
		"type": "Visa Credit",
		"entryMethod": "keyed",
		"cardholderName": "Davi",
		"cardNumber": "444433******1111",
		"expiryDate": "1223",
		"securityChecks": {
			"cvvResult": "M",
			"avsResult": "Y"
		}
	},
	"transactionResult": {
		"type": "sale",
		"status": "pending",
		"approvalCode": "OK24233",
		"authorizedAmount": 12346,
		"currency": "USD",
		"responseCode": "A",
		"responseMessage": "OK24233"
	}
}

Capture a pre-authorization

Send a POST request to the following endpoint: POST https://api.uat.payroc.com/v1/payments/{paymentId}/capture Example response

{
	"paymentId": "C7BHY7KWCW",
	"processingTerminalId": "3204001",
	"operator": "Davi-Crisostomo-CHP",
	"order": {
		"orderId": "1234567890Q1",
		"dateTime": "2023-06-20T21:03:31+01:00",
		"description": "PreAuth Card Transaction (WEB) - Sale - KEYED (plain_text) with CVV",
		"amount": 6532,
		"currency": "USD"
	},
	"card": {
		"type": "Visa Credit",
		"entryMethod": "keyed",
		"cardholderName": "Davi",
		"cardNumber": "444433******1111",
		"expiryDate": "1223",
		"securityChecks": {
			"cvvResult": "M",
			"avsResult": "Y"
		}
	},
	"transactionResult": {
		"type": "sale",
		"status": "ready",
		"approvalCode": "OK24233",
		"authorizedAmount": 6532,
		"currency": "USD",
		"responseCode": "A",
		"responseMessage": "OK24233"
	}
}