Run a sale

After you configure a device for Payroc Cloud, program your POS to send a payment instruction to the payment device. Your POS then checks the status of the instruction until the payment finishes, and views the details of the payment.

How it works

1. Your POS submits a payment instruction to the device. Our gateway sends the instruction to the device and returns a paymentInstructionId with a status of inProgress.
2. The cardholder completes the payment on the device. Your POS checks the status of the payment instruction. Our gateway waits up to a minute for the status to change before it responds. If the status is still inProgress, your POS sends another request and keeps checking until the status changes.
3. When the payment finishes, your POS uses the link in the response to view the details of the payment and to check whether the processor approved it or declined it.

You can also cancel the payment instruction while its status is inProgress.

Before you begin

Authenticate your requests before making API calls. If your request fails, see Errors.

Step 1. Submit a payment instruction

To submit a payment instruction to the device, send a POST request to the Devices 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/devices/1850010868/payment-instructions \
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
  "order": {
8
    "orderId": "OrderRef6543",
9
    "amount": 4999,
10
    "currency": "USD"
11
  },
12
  "operator": "Jane",
13
  "customizationOptions": {
14
    "entryMethod": "deviceRead"
15
  },
16
  "autoCapture": true
17
}'

Response fields

If your request is successful, we send the payment instruction to the device.

Response parameters

1
{
2
  "status": "inProgress",
3
  "paymentInstructionId": "a37439165d134678a9100ebba3b29597",
4
  "link": {
5
    "rel": "self",
6
    "method": "GET",
7
    "href": "https://api.payroc.com/v1/payment-instructions/a37439165d134678a9100ebba3b29597"
8
  }
9
}

Step 2. View the status of a payment instruction

To check for updates to the status of the payment instruction, send a GET request to the Payment Instructions endpoint.

Before our gateway sends a response, it waits for up to a minute for the status of the instruction to change. We recommend that you keep the session open until the status of the instruction changes or the request times out.

If the status of the instruction doesn’t change, send another GET request. Our gateway waits up to a minute for the status of the instruction to change. Continue to send GET requests until the status changes.

Request parameters

To create your request, use the following parameters:

Example request

1
curl https://api.payroc.com/v1/payment-instructions/e743a9165d134678a9100ebba3b29597 \
2
     -H "Authorization: Bearer <token>"

Response fields

If your request is successful, we return the details of the payment instruction, including HATEOAS links to check the details of the payment. Use the HATEOAS links to get the paymentId, which you need in Step 3.

If the status of the payment instruction is inProgress, our gateway waits up to a minute for the status to change before it returns a response.

Example response

1
{
2
  "status": "completed",
3
  "paymentInstructionId": "a37439165d134678a9100ebba3b29597",
4
  "link": {
5
    "rel": "payment",
6
    "method": "GET",
7
    "href": "https://api.payroc.com/v1/payments/M2MJOG6O2Y"
8
  }
9
}

Step 3. View the details of the payment

To check whether the processor approved or declined the payment, send a GET request to the Payments endpoint.

Request parameters

To create your request, use the following parameters:

Example request

1
curl https://api.payroc.com/v1/payments/M2MJOG6O2Y \
2
     -H "Authorization: Bearer <token>"

Response fields

If your request is successful, we return the details of the payment.

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

(Optional) Cancel a payment instruction

To cancel a payment instruction, send a DELETE request to the Payment Instructions endpoint.

Request parameters

To create your request, use the following parameters:

Example request

Response

If your request is successful, we cancel the payment instruction.