IntegratePayments

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.

Note: 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.

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

POST
/v1/payments
1curl -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    "orderId": "OrderRef6543",
10    "amount": 4999,
11    "currency": "USD",
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": "Jane",
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

Important: 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:

Example response

Response
1{
2  "paymentId": "M2MJOG6O2Y",
3  "processingTerminalId": "1234001",
4  "order": {
5    "orderId": "OrderRef6543",
6    "amount": 4999,
7    "currency": "USD",
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": "1225",
16    "securityChecks": {
17      "cvvResult": "M",
18      "avsResult": "Y"
19    }
20  },
21  "transactionResult": {
22    "type": "sale",
23    "status": "ready",
24    "responseCode": "A",
25    "responseMessage": "OK3",
26    "approvalCode": "OK3",
27    "authorizedAmount": 4999,
28    "currency": "USD"
29  },
30  "operator": "Jane",
31  "customer": {
32    "firstName": "Sarah",
33    "lastName": "Hopper",
34    "billingAddress": {
35      "address1": "1 Example Ave.",
36      "city": "Chicago",
37      "state": "Illinois",
38      "country": "US",
39      "postalCode": "60056",
40      "address2": "Example Address Line 2",
41      "address3": "Example Address Line 3"
42    },
43    "shippingAddress": {
44      "recipientName": "Sarah Hopper",
45      "address": {
46        "address1": "1 Example Ave.",
47        "city": "Chicago",
48        "state": "Illinois",
49        "country": "US",
50        "postalCode": "60056",
51        "address2": "Example Address Line 2",
52        "address3": "Example Address Line 3"
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}

Step 2. (Optional) Adjust a payment

Important: 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.

Request parameters

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

Example request

POST
/v1/payments/:paymentId/adjust
1curl -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

Response
1{
2  "paymentId": "M2MJOG6O2Y",
3  "processingTerminalId": "1234001",
4  "order": {
5    "orderId": "OrderRef6543",
6    "amount": 4999,
7    "currency": "USD",
8    "dateTime": "2024-07-02T15:30:00Z",
9    "description": "Example payment"
10  },
11  "card": {
12    "type": "MasterCard",
13    "entryMethod": "keyed",
14    "cardNumber": "453985******7062",
15    "expiryDate": "1225",
16    "securityChecks": {
17      "cvvResult": "M",
18      "avsResult": "Y"
19    }
20  },
21  "transactionResult": {
22    "type": "sale",
23    "status": "ready",
24    "responseCode": "A",
25    "responseMessage": "OK6",
26    "approvalCode": "OK6",
27    "authorizedAmount": 4999,
28    "currency": "USD"
29  },
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  "supportedOperations": [
56    "capture",
57    "fullyReverse",
58    "partiallyReverse",
59    "incrementAuthorization",
60    "adjustTip",
61    "setAsPending"
62  ],
63  "customFields": [
64    {
65      "name": "yourCustomField",
66      "value": "abc123"
67    }
68  ]
69}

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

POST
/v1/payments/:paymentId/capture
1curl -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

Response
1{
2  "paymentId": "M2MJOG6O2Y",
3  "processingTerminalId": "1234001",
4  "order": {
5    "orderId": "OrderRef6543",
6    "amount": 4999,
7    "currency": "USD",
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": "1225",
16    "securityChecks": {
17      "cvvResult": "M",
18      "avsResult": "Y"
19    }
20  },
21  "transactionResult": {
22    "type": "sale",
23    "status": "ready",
24    "responseCode": "A",
25    "responseMessage": "OK3",
26    "approvalCode": "OK3",
27    "authorizedAmount": 4999,
28    "currency": "USD"
29  },
30  "operator": "Jane",
31  "customer": {
32    "firstName": "Sarah",
33    "lastName": "Hopper",
34    "billingAddress": {
35      "address1": "1 Example Ave.",
36      "city": "Chicago",
37      "state": "Illinois",
38      "country": "US",
39      "postalCode": "60056",
40      "address2": "Example Address Line 2",
41      "address3": "Example Address Line 3"
42    },
43    "shippingAddress": {
44      "recipientName": "Sarah Hopper",
45      "address": {
46        "address1": "1 Example Ave.",
47        "city": "Chicago",
48        "state": "Illinois",
49        "country": "US",
50        "postalCode": "60056",
51        "address2": "Example Address Line 2",
52        "address3": "Example Address Line 3"
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}

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

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}