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:

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.

Run a sale

To run a sale, 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

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:

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

If your request is successful, our gateway uses the card details to run a sale. 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"
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "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 card sale without a surcharge

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

{
	"paymentId": "F1I17KBL0E",
	"processingTerminalId": "3204001",
	"order": {
		"orderId": "Test_001",
		"dateTime": "2023-05-24T14:44:20.63+01:00",
		"amount": 4000,
		"currency": "USD"
	},
	"card": {
		"type": "Visa Credit",
		"entryMethod": "keyed",
		"cardNumber": "444433******1111",
		"expiryDate": "0334",
		"securityChecks": {
			"cvvResult": "M",
			"avsResult": "Y"
		}
	},
	"paymentResult": {
		"type": "sale",
		"status": "ready",
		"approvalCode": "OK14472",
		"authorizedAmount": 4000,
		"currency": "USD",
		"responseCode": "A",
		"responseMessage": "OK14472"
	}
}

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

{
	"paymentId": "CBA7UOVS0J",
	"processingTerminalId": "3204001",
	"order": {
		"orderId": "Test_005",
		"dateTime": "2023-05-24T14:48:39.548+01:00",
		"amount": 4160,
		"currency": "USD",
		"breakdown": {
			"subtotal": 4000,
			"surcharge": {
				"bypass": false,
				"amount": 160,
				"percentage": 4.0
			}
		}
	},
	"card": {
		"type": "Visa Credit",
		"entryMethod": "keyed",
		"cardNumber": "444433******1111",
		"expiryDate": "0334",
		"securityChecks": {
			"cvvResult": "M",
			"avsResult": "Y"
		}
	},
	"paymentResult": {
		"type": "sale",
		"status": "ready",
		"approvalCode": "OK14476",
		"authorizedAmount": 4160,
		"currency": "USD",
		"responseCode": "A",
		"responseMessage": "OK14476"
	}
}