Test your integration

PayByCloud

Before you can run live payments, we require you to run our test cases to make sure that you have correctly integrated against our API.

Note: If you have any issues when you run our test cases, email our integrations team at integrationsupport@payroc.com.

Before you begin

To help you with testing, we provide you with:

  • Test environment
  • Test cards
  • Test values

You should also review our testing recommendations.

Test environment

Send your requests to our test environment:

Test environment base URI: https://api.uat.payroc.com/v1

Important: Use only test cards in our test environment.

Authenticating your requests

Use our test 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.uat.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.uat.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}

Example request header

$curl
>-H "Authorization: Bearer <access token>"

Test cards

Important: Use only test cards in our test environment.

Card schemeCard numberVerification
Visa4761 7300 0000 0011Online only
Mastercard5413 3300 8960 4111Online only
Visa4761 7310 0000 0043Online or offline
Mastercard5413 3300 8960 4111Online or offline
Visa4761 7310 0000 0043Online or offline
Mastercard5413 3300 8960 4111Online or offline

Test values

To return a specific response from the gateway, change the value in the amount parameter to end in one of the following values:

ValueResponseExample
01Declined501
02Referral1002
03CVV failure1403
Any otherAuthorized4541

Testing recommendations

When you test your integration, we recommend that you do the following:

  • Test error scenarios – To check that your integration can handle errors, run scenarios that produce errors. For example, test that your integration can handle the response when the value for a request parameter is in the wrong format.
  • Follow PCI DSS – To help protect the payment data, make sure that your integration complies with PCI DSS.
  • Test all card types – If your integration accepts multiple card types, test your integration with each card type. For example, if your integration accepts EBT cards, you should test with an EBT card.
  • Refresh tokens for authentication – Bearer tokens expire after a fixed period. Test your integration to make sure that it can correctly refresh Bearer tokens.

Test cases

We provide you with test cases for the following:

Note: For some test cases you need to adjust the gateway settings, for example, to display a tip prompt. If you need help to adjust the gateway settings, contact your Payroc Integration Engineer.

Create a payment instruction using options that you configured in the gateway

Step 1. Create a payment instruction

Use our gateway to configure the surcharging options, tip options, and tax amounts.

Note: If you’re unsure about how to configure these options, contact your Payroc Integration Engineer.

Send a POST request to the Devices test endpoint:

https://api.uat.payroc.com/v1/devices/{serialNumber}/payment-instructions

Example request

1{
2    "operator": "jbloggs",
3    "processingTerminalId": "1021",
4    "order": {
5        "orderId": "4fd4-99bc",
6        "currency": "USD",
7        "amount": 1000,
8        "orderBreakdown": {
9            "subtotalAmount": 1000
10        }
11    },
12    "customizationOptions": {
13        "entryMethod": "deviceRead"
14    },
15    "autoCapture": true,
16    "processAsSale": false
17}

Step 2. Retrieve the status of the payment instruction

Send a GET request to the Payment Instructions test endpoint:

https://api.uat.payroc.com/v1/payment-instructions/{paymentInstructionId}

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. Send GET requests until the value for status changes to completed.

Note: If the status of the payment instruction is failed or canceled, contact your Payroc Integration Engineer.

Example response

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

Step 3. Retrieve the status of the payment instruction

Send a GET request to the Payment test endpoint:

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

Use the paymentID that you received in the response from Step 2.

Example response

1{
2    "operator": "XYZ",
3    "terminal": 1021,
4    "order": {
5        "orderId": "4fd4-99bc",
6        "description": "Payment Instruction",
7        "currency": "USD",
8        "totalAmount": 10.00,
9        "orderBreakdown": {
10            "subtotalAmount": 10.00,
11            "surcharge": {
12                "bypass": "true"
13            },
14            "taxes": [
15                {
16                    "name": "TAX10",
17                    "rate": 10.0
18                }
19            ],
20            "tip": {}
21        }
22    },
23    "customizationOptions": {
24        "entryMethod": "DEVICE_READ"
25    },
26    "customer": {
27        "name": "First Last",
28        "dateOfBirth": "2023-01-01",
29        "referenceNumber": "ABCDEFGH",
30        "billingAddress": {
31            "line1": "billing Addr Line1",
32            "line2": "billing Addr Line2",
33            "city": "billCity",
34            "state": "AZ",
35            "country": "US",
36            "postalCode": 12345
37        },
38        "shippingAddress": {
39            "name": "shipping recipient name",
40            "line1": "shipping Addr Line1",
41            "line2": "shipping Addr Line2",
42            "city": "shipCity",
43            "state": "AZ",
44            "country": "US",
45            "postalCode": "SH12345"
46        },
47        "email": "email@domain.com",
48        "phone": "+353891234567",
49        "notificationLanguage": "en"
50    },
51    "autoCapture": true,
52    "processAsSale": false
53}

Create a payment instruction that overrides the values that you configured in the gateway

Step 1. Create a payment instruction

Send a POST request to the Devices test endpoint:

https://api.uat.payroc.com/v1/devices/{serialNumber}/payment-instructions

Example request

1{
2    "operator": "XYZ",
3    "terminal": 1021,
4    "order": {
5        "orderId": "TestPBC-123",
6        "description": "Payment Instruction",
7        "currency": "USD",
8        "totalAmount": 12100,
9        "orderBreakdown": {
10            "subtotalAmount": 12100,
11            "surcharge": {
12                "bypass": "true"
13            },
14            "taxes": [
15                {
16                    "name": "TAX10",
17                    "rate": 10.0
18                }
19            ],
20            "tip": {
21                "percentage": 10,
22                "type": "PERCENTAGE"
23            }
24        }
25    },
26    "customizationOptions": {
27        "entryMethod": "DEVICE_READ"
28    },
29    "autoCapture": true,
30    "processAsSale": false
31}

Step 2. Retrieve the status of the payment instruction

Send a GET request to the Payment Instructions test endpoint:

https://api.uat.payroc.com/v1/payment-instructions/{paymentInstructionId}

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. Send GET requests until the value for status changes to completed.

Note: If the status of the payment instruction is failed or canceled, contact your Payroc Integration Engineer.

Example response

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

Step 3. Retrieve the status of the payment instruction

Send a GET request to the Payment test endpoint:

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

Use the paymentID that you received in the response from Step 2.

Example response

1{
2  "paymentId": "DD6ZDQU7L2",
3  "processingTerminalId": "1021",
4  "operator": "Postman",
5  "order": {
6    "orderId": "4fd4-99bc",
7    "dateTime": "2023-07-26T16:42:25.018Z",
8    "description": "Example payment",
9    "amount": 1000,
10    "currency": "USD"
11  },
12  "customer": {
13    "shippingAddress": {}
14  },
15  "card": {
16    "type": "MasterCard",
17    "entryMethod": "keyed",
18    "cardNumber": "500165******0000",
19    "expiryDate": "0328",
20    "securityChecks": {
21      "cvvResult": "M",
22      "avsResult": "Y"
23    }
24  },
25  "transactionResult": {
26    "type": "sale",
27    "status": "ready",
28    "approvalCode": "OK3",
29    "authorizedAmount": 1000,
30    "currency": "USD",
31    "responseCode": "A",
32    "responseMessage": "OK3"
33  }
34}

Create a refund instruction for when the card isn’t present

Step 1. Create a refund instruction

Send a POST request to the Devices test endpoint:

https://api.uat.payroc.com/v1/devices/{serialNumber}/refund-instructions

Example request

1{
2    "operator": "jbloggs",
3    "processingTerminalId": "1021",
4    "order": {
5        "orderId": "4fd4-99bc",
6        "currency": "USD",
7        "amount": 1000
8    },
9    "customizationOptions": {
10        "entryMethod": "manualEntry"
11    }
12}

Step 2. Retrieve the status of the refund instruction

Send a GET request to the Refund Instructions test endpoint:

https://api.uat.payroc.com/v1/refund-instructions/{refundInstructionId}

If the status of the refund instruction is inProgress, our gateway waits up to a minute for the status to change before it returns a response. Send GET requests until the value for status changes to completed.

Note: If the status of the refund instruction is failed or canceled, contact your Payroc Integration Engineer.

Example response

1{
2  "refundInstructionId": "3743a9165d134678a9100ebba3b29597",
3  "status": "completed",
4  "link": {
5    "rel": "refunds",
6    "method": "GET",
7    "href": "https://api.payroc.com/v1/refunds/DD6ZDQU7L27"
8  }
9}

Step 3. Retrieve the status of the refund instruction

Send a GET request to the Refunds test endpoint:

https://api.uat.payroc.com/v1/refunds/{refundId}

Use the refundID that you received in the response from Step 2.

Example response

1{
2  "paymentId": "DD6ZDQU7L2",
3  "processingTerminalId": "1021",
4  "operator": "Postman",
5  "order": {
6    "orderId": "4fd4-99bc",
7    "dateTime": "2023-07-26T16:42:25.018Z",
8    "description": "Example payment",
9    "amount": 1000,
10    "currency": "USD"
11  },
12  "customer": {
13    "shippingAddress": {}
14  },
15  "card": {
16    "type": "MasterCard",
17    "entryMethod": "keyed",
18    "cardNumber": "500165******0000",
19    "expiryDate": "0328",
20    "securityChecks": {
21      "cvvResult": "M",
22      "avsResult": "Y"
23    }
24  },
25  "transactionResult": {
26    "type": "sale",
27    "status": "ready",
28    "approvalCode": "OK3",
29    "authorizedAmount": 1000,
30    "currency": "USD",
31    "responseCode": "A",
32    "responseMessage": "OK3"
33  }
34}