IntegratePayments

Run a card sale

A merchant can use their POS to run card sales.

Integration steps

  • Run a sale.

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.

Run a sale

To run a sale, send a POST request to our Payments endpoint.

Important: This method includes the following functions:

  • Tokenization
  • Pre-authorization
  • Currency conversion
  • Offline processing

We don’t describe how to integrate with these functions in this guide.

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

If your request is successful, our gateway uses the card details to run a sale. 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 card sale without a surcharge

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/payments

Example response

1{
2	"paymentId": "F1I17KBL0E",
3	"processingTerminalId": "3204001",
4	"order": {
5		"orderId": "Test_001",
6		"dateTime": "2023-05-24T14:44:20.63+01:00",
7		"amount": 4000,
8		"currency": "USD"
9	},
10	"card": {
11		"type": "Visa Credit",
12		"entryMethod": "keyed",
13		"cardNumber": "444433******1111",
14		"expiryDate": "0334",
15		"securityChecks": {
16			"cvvResult": "M",
17			"avsResult": "Y"
18		}
19	},
20	"paymentResult": {
21		"type": "sale",
22		"status": "ready",
23		"approvalCode": "OK14472",
24		"authorizedAmount": 4000,
25		"currency": "USD",
26		"responseCode": "A",
27		"responseMessage": "OK14472"
28	}
29}

Run a card sale with a surcharge

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/payments

Note: If you are unsure whether your account supports surcharges, email our Integration team at [email protected].

Example response

1{
2	"paymentId": "CBA7UOVS0J",
3	"processingTerminalId": "3204001",
4	"order": {
5		"orderId": "Test_005",
6		"dateTime": "2023-05-24T14:48:39.548+01:00",
7		"amount": 4160,
8		"currency": "USD",
9		"breakdown": {
10			"subtotal": 4000,
11			"surcharge": {
12				"bypass": false,
13				"amount": 160,
14				"percentage": 4.0
15			}
16		}
17	},
18	"card": {
19		"type": "Visa Credit",
20		"entryMethod": "keyed",
21		"cardNumber": "444433******1111",
22		"expiryDate": "0334",
23		"securityChecks": {
24			"cvvResult": "M",
25			"avsResult": "Y"
26		}
27	},
28	"paymentResult": {
29		"type": "sale",
30		"status": "ready",
31		"approvalCode": "OK14476",
32		"authorizedAmount": 4160,
33		"currency": "USD",
34		"responseCode": "A",
35		"responseMessage": "OK14476"
36	}
37}