Run a pre-authorization

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:

1. A hotel pre-authorizes a one-night stay for a customer at $100.
2. The customer decides to have dinner in the hotel for $50. The hotel adjusts the $100 pre-authorization to $150.
3. 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:

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.

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.

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 \
2
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3
     -H "Authorization: Bearer <token>" \
4
     -H "Content-Type: application/json" \
5
     -d '{
6
  "channel": "web",
7
  "processingTerminalId": "1234001",
8
  "order": {
9
    "amount": 4999,
10
    "currency": "USD",
11
    "orderId": "OrderRef6543",
12
    "description": "Large Pepperoni Pizza"
13
  },
14
  "paymentMethod": {
15
    "type": "card",
16
    "cardDetails": {
17
      "entryMethod": "keyed",
18
      "keyedData": {
19
        "dataFormat": "plainText",
20
        "device": {
21
          "model": "paxA80",
22
          "serialNumber": "WPC202833004712"
23
        },
24
        "cardNumber": "4539858876047062",
25
        "expiryDate": "1225"
26
      }
27
    }
28
  },
29
  "operator": "Postman",
30
  "customer": {
31
    "firstName": "Sarah",
32
    "lastName": "Hopper",
33
    "billingAddress": {
34
      "address1": "1 Example Ave.",
35
      "city": "Chicago",
36
      "state": "Illinois",
37
      "country": "US",
38
      "postalCode": "60056",
39
      "address2": "Example Address Line 2",
40
      "address3": "Example Address Line 3"
41
    },
42
    "shippingAddress": {
43
      "recipientName": "Sarah Hopper",
44
      "address": {
45
        "address1": "1 Example Ave.",
46
        "city": "Chicago",
47
        "state": "Illinois",
48
        "country": "US",
49
        "postalCode": "60056",
50
        "address2": "Example Address Line 2",
51
        "address3": "Example Address Line 3"
52
      }
53
    }
54
  },
55
  "customFields": [
56
    {
57
      "name": "yourCustomField",
58
      "value": "abc123"
59
    }
60
  ]
61
}'

Response fields

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:

Example response

Step 2. (Optional) Adjust a payment

To adjust a pre-authorized amount, send a POST request to our Payments endpoint.

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/adjust \
2
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3
     -H "Authorization: Bearer <token>" \
4
     -H "Content-Type: application/json" \
5
     -d '{
6
  "adjustments": [
7
    {
8
      "type": "customer",
9
      "shippingAddress": {
10
        "recipientName": "Sarah Hopper",
11
        "address": {
12
          "address1": "1 Example Ave.",
13
          "address2": "Example Address Line 2",
14
          "address3": "Example Address Line 3",
15
          "city": "Chicago",
16
          "state": "Illinois",
17
          "country": "US",
18
          "postalCode": "60056"
19
        }
20
      }
21
    },
22
    {
23
      "type": "order",
24
      "amount": 3999
25
    }
26
  ]
27
}'

Response fields

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

Example response

Step 3. Capture a payment

To capture the pre-authorization, send a POST request to our Payments endpoint.

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
        "unitPrice": 4000,
16
        "quantity": 1
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

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

Example response

1
{
2
	"paymentId": "C7BHY7KWCW",
3
	"processingTerminalId": "3204001",
4
	"operator": "Davi-Crisostomo-CHP",
5
	"order": {
6
		"orderId": "1234567890Q1",
7
		"dateTime": "2023-06-20T21:03:30.925+01:00",
8
		"description": "PreAuth Card Transaction (WEB) - Sale - KEYED (plain_text) with CVV",
9
		"amount": 12346,
10
		"currency": "USD"
11
	},
12
	"card": {
13
		"type": "Visa Credit",
14
		"entryMethod": "keyed",
15
		"cardholderName": "Davi",
16
		"cardNumber": "444433******1111",
17
		"expiryDate": "1223",
18
		"securityChecks": {
19
			"cvvResult": "M",
20
			"avsResult": "Y"
21
		}
22
	},
23
	"transactionResult": {
24
		"type": "sale",
25
		"status": "pending",
26
		"approvalCode": "OK24233",
27
		"authorizedAmount": 12346,
28
		"currency": "USD",
29
		"responseCode": "A",
30
		"responseMessage": "OK24233"
31
	}
32
}

Capture a pre-authorization

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/payments/{paymentId}/capture

Example response

1
{
2
	"paymentId": "C7BHY7KWCW",
3
	"processingTerminalId": "3204001",
4
	"operator": "Davi-Crisostomo-CHP",
5
	"order": {
6
		"orderId": "1234567890Q1",
7
		"dateTime": "2023-06-20T21:03:31+01:00",
8
		"description": "PreAuth Card Transaction (WEB) - Sale - KEYED (plain_text) with CVV",
9
		"amount": 6532,
10
		"currency": "USD"
11
	},
12
	"card": {
13
		"type": "Visa Credit",
14
		"entryMethod": "keyed",
15
		"cardholderName": "Davi",
16
		"cardNumber": "444433******1111",
17
		"expiryDate": "1223",
18
		"securityChecks": {
19
			"cvvResult": "M",
20
			"avsResult": "Y"
21
		}
22
	},
23
	"transactionResult": {
24
		"type": "sale",
25
		"status": "ready",
26
		"approvalCode": "OK24233",
27
		"authorizedAmount": 6532,
28
		"currency": "USD",
29
		"responseCode": "A",
30
		"responseMessage": "OK24233"
31
	}
32
}