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 'Content-Type: application/json' \
	--header 'Idempotency-Key: abc123' \
	--data '{"channel":"web","processingTerminalId":"1023","operator":"Postman","order":{"orderId":"order123","description":"Example payment","currency":"USD","amount":100},"customer":{"firstName":"Robert","lastName":"Red","billingAddress":{"address1":"billing address1","address2":"billing address2","address3":"billing address3","city":"Los Angeles","state":"California","country":"US","postalCode":90005},"shippingAddress":{"recipientName":"shipping recipientName","address":{"address1":"shipping address1","address2":"shipping address2","address3":"shipping address3","city":"San Diego","state":"California","country":"US","postalCode":91911}}},"paymentMethod":{"type":"card","cardDetails":{"entryMethod":"keyed","keyedData":{"dataFormat":"plainText","device":{"model":"paxA80","serialNumber":"WPC202833004712"},"expiryDate":"0328","cardNumber":"5001650000000000"}}}}'

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": "KP77BIWR96",
  "processingTerminalId": "1023",
  "operator": "Postman",
  "order": {
    "orderId": "order123",
    "dateTime": "2023-07-26T16:42:25.018Z",
    "description": "Example payment",
    "amount": 100,
    "currency": "USD"
  },
  "customer": {
    "firstName": "Robert",
    "lastName": "Red",
    "billingAddress": {
      "address1": "billing address",
      "address2": "billing address2",
      "address3": "billing address3",
      "city": "Los Angeles",
      "state": "California",
      "country": "US",
      "postalCode": "90005"
    },
    "shippingAddress": {
      "recipientName": "shipping recipientName",
      "address": {
        "address1": "shipping address1",
        "address2": "shipping address2",
        "address3": "shipping address3",
        "city": "San Diego",
        "state": "California",
        "country": "US",
        "postalCode": "91911"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "500165******0000",
    "expiryDate": "0328",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK3",
    "authorizedAmount": 100,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK3"
  }
}

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/abc123/adjust \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: abc123' \
	--data '{"adjustments":[{"type":"customer","shippingAddress":{"recipientName":"new recipientName","address":{"address1":"new address1","address2":"address2","address3":"address3","city":"Miami","state":"Florida","country":"US","postalCode":33101}}},{"type":"order","amount":1000}]}'

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": "HW986AQOBB",
  "processingTerminalId": "1023",
  "order": {
    "orderId": "6u6",
    "dateTime": "2023-07-27T09:28:44.000Z",
    "description": "Example payment",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "firstName": "Robert",
    "lastName": "Red",
    "billingAddress": {
      "address1": "billing address",
      "address2": "billing address2",
      "address3": "billing address3",
      "city": "Los Angeles",
      "state": "California",
      "country": "US",
      "postalCode": "90005"
    },
    "shippingAddress": {
      "recipientName": "new recipientName",
      "address": {
        "address1": "new address1",
        "address2": "address2",
        "address3": "address3",
        "city": "Miami",
        "state": "Florida",
        "country": "US",
        "postalCode": "33101"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "500165******0000",
    "expiryDate": "0328",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK6",
    "authorizedAmount": 1000,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK6"
  }
}

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:

Body parameters

Example request

Request

curl --request post \
	--url https://api.payroc.com/v1/payments/abc123/capture \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: abc123' \
	--data '{"processingTerminalId":"abc123","operator":"abc123","amount":89,"breakdown":{"subtotal":89,"dutyAmount":89,"freightAmount":89,"cashbackAmount":89,"tip":{"type":"percentage","amount":0,"percentage":0},"taxes":[{"name":"abc123","rate":0}],"surcharge":{"bypass":false},"dualPricing":{"offered":false,"alternativeTender":"card"},"items":[{"commodityCode":"abc123","productCode":"abc123","description":"abc123","unitOfMeasure":"ACR","unitPrice":0,"quantity":0,"discountRate":0,"taxes":[{"name":"abc123","rate":0}]}]}}'

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": "KP77BIWR96",
  "processingTerminalId": "1023",
  "operator": "Postman",
  "order": {
    "orderId": "order123",
    "dateTime": "2023-07-26T16:42:25.018Z",
    "description": "Example payment",
    "amount": 100,
    "currency": "USD"
  },
  "customer": {
    "firstName": "Robert",
    "lastName": "Red",
    "billingAddress": {
      "address1": "billing address",
      "address2": "billing address2",
      "address3": "billing address3",
      "city": "Los Angeles",
      "state": "California",
      "country": "US",
      "postalCode": "90005"
    },
    "shippingAddress": {
      "recipientName": "shipping recipientName",
      "address": {
        "address1": "shipping address1",
        "address2": "shipping address2",
        "address3": "shipping address3",
        "city": "San Diego",
        "state": "California",
        "country": "US",
        "postalCode": "91911"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "500165******0000",
    "expiryDate": "0328",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK3",
    "authorizedAmount": 100,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK3"
  }
}

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"
	}
}