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 [email protected].
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:
- Include your API key in the x-api-key parameter in the header of a POST request.
- 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
Example response
If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.
Example request header
Test cards
Important: Use only test cards in our test environment.
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:
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:
- Create a payment instruction using options that you configured in the gateway
- Create a payment instruction that overrides the values that you configured in the gateway
- Create a refund instruction for when the card isn’t present
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
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
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
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
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
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
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
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
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