Payments

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:

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

Shell

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.

JSON

{
  "access_token": "eyJhbGc....adQssw5c",
  "expires_in": 3600,
  "scope": "service_a service_b",
  "token_type": "Bearer"
}

Example request header

Shell

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

Test cards

Note: Our gateway accepts any value for the CVV.

Card scheme	Card number	Requires CVV?
American Express	3400000000000000	Yes
Debit MasterCard	5100270000000007	Yes
Diners	3600000000000008	No
Discover	6011000000000004	Yes
JCB	3528000000000007	Yes
Maestro	5000330000000000	Yes
MasterCard	5001650000000000	Yes
Visa Credit	4539858876047062	Yes
Visa Debit	4000060000000006	Yes
Visa Electron	4001020000000009	No

EBT test cards

Note: You can only test EBT transactions if the processor is Fiserv or TSYS.

Card number	Benefit category	PIN
6007602801003837964	Food Stamp	1234
6007602801003837965	Food Stamp	1234
060076028010038379673	Cash Only	1234
6007602801003837968	Cash Only	1234
6007602801003837969	Cash Only	1234
6007602801003837971	Inactive card	1234

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:

Value	Response	Example
01	Declined	501
02	Referral	1002
03	CVV failure	1403
Any other	Authorized	4541

Testing recommendations

Important: Do not use live card data to test your integration. This is a breach of PCI DSS.

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 one hour, and you must generate a new Bearer token before the previous token expires. Test your integration to make sure that it can correctly refresh Bearer tokens.

Test cases

We provide you with test cases for the following:

Card payments

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

JSON

{
	"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 integrationsupport@payroc.com.

Example response

JSON

{
	"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"
	}
}

Run a pre-authorization

Send a POST request to the following endpoint:

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

Note: Set the value for the autoCapture and the processAsSale parameters to false in the request body.

Example response

JSON

{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "amount": 9999,
    "currency": "USD",
    "dateTime": "2026-08-19T16:16:22+01:00",
    "description": "Large Pepperoni Pizza"
  },
  "card": {
    "type": "Visa Credit",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1230",
    "securityChecks": {
      "avsResult": "U"
    }
  },
  "transactionResult": {
    "status": "pending",
    "responseCode": "A",
    "type": "sale",
    "approvalCode": "582235",
    "authorizedAmount": 9999,
    "currency": "USD",
    "responseMessage": "APPROVAL",
    "processorResponseCode": "00"
  },
  "operator": "Jane",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "setAsReady"
  ]
}

Capture a pre-authorization

Send a POST request to the following endpoint:

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

Example response

JSON

{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "amount": 3999,
    "currency": "USD",
    "dateTime": "2026-08-19T16:16:22+01:00",
    "description": "Large Pepperoni Pizza"
  },
  "card": {
    "type": "Visa Credit",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1230",
    "securityChecks": {
      "avsResult": "U"
    }
  },
  "transactionResult": {
    "status": "ready",
    "responseCode": "A",
    "type": "sale",
    "approvalCode": "582235",
    "authorizedAmount": 3999,
    "currency": "USD",
    "responseMessage": "APPROVAL",
    "processorResponseCode": "00"
  },
  "operator": "Jane",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "setAsPending"
  ]
}

Adjust a card payment

Send a POST request to the following endpoint:

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

Example response

JSON

{
	"paymentId": "C7BHY7KWCW",
	"processingTerminalId": "3204001",
	"operator": "ROBBIE-KIRWAN-adjust",
	"order": {
		"orderId": "1234567890Q1",
		"dateTime": "2023-06-20T21:03:31+01:00",
		"description": "PreAuth Card Transaction (WEB) - Sale - KEYED (plain_text) with CVV",
		"amount": 400,
		"currency": "USD"
	},
	"card": {
		"type": "Visa Credit",
		"entryMethod": "keyed",
		"cardholderName": "Davi",
		"cardNumber": "444433******1111",
		"expiryDate": "1223",
		"securityChecks": {
			"cvvResult": "M",
			"avsResult": "Y"
		}
	},
	"transactionResult": {
		"type": "sale",
		"status": "ready",
		"approvalCode": "OK24233",
		"authorizedAmount": 400,
		"currency": "USD",
		"responseCode": "A",
		"responseMessage": "OK24233"
	}
}

Secure tokens

Create a secure token

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/secure-tokens

Example response

JSON

{
	"secureTokenId": "MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA",
	"processingTerminalId": "3204001",
	"source": {
		"type": "card",
		"cardholderName": "",
		"cardNumber": "444433******1111",
		"expiryDate": "1226"
	},
	"token": "2967538502417872",
	"status": "cvv_validated"
}

Create a payment with a secure token

Send a POST request to the following endpoint:

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

Example response

JSON

{
	"paymentId": "C8Y177VHWR",
	"processingTerminalId": "3204001",
	"order": {
		"orderId": "Test_006",
		"dateTime": "2023-05-24T15:21:01.037+01:00",
		"amount": 4000,
		"currency": "USD"
	},
	"card": {
		"type": "Visa Credit",
		"entryMethod": "keyed",
		"cardNumber": "444433******1111",
		"expiryDate": "1226",
		"secureToken": {
			"secureTokenId": "MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA",
			"customerName": "",
			"token": "2967538502417872",
			"status": "cvv_validated",
			"link": {
				"rel": "self",
				"method": "GET",
				"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/secure-tokens/MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA"
			}
		},
		"securityChecks": {
			"cvvResult": "M",
			"avsResult": "Y"
		}
	},
	"transactionResult": {
		"type": "sale",
		"status": "ready",
		"approvalCode": "OK14486",
		"authorizedAmount": 4000,
		"currency": "USD",
		"responseCode": "A",
		"responseMessage": "OK14486",
		"cardSchemeReferenceId": "JxDfFMHyOE2lyQJ2MnFp"
	}
}

Delete a secure token

Send a DELETE request to the following endpoint:

DELETE https://api.uat.payroc.com/v1/payments/processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}
Example response

No response body.

Update a secure token

Send a PATCH request to the following endpoint:

PATCH https://api.uat.payroc.com/v1/payments/processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}

Example response

JSON

{
	"secureTokenId": "MREF_fe532d13-d330-4872-b646-61750144030bG4",
	"processingTerminalId": "3204001",
	"customer": {
		"contactMethods": [
			{
				"type": "email",
				"value": "EMAIL3@gmail.com"
			}
		]
	},
	"source": {
		"type": "card",
		"cardholderName": "Test Card 13 Uat Usa",
		"cardNumber": "374245*****1003",
		"expiryDate": "1224"
	},
	"token": "2967538321403871",
	"status": "cvv_validated"
}

Payment plans and subscriptions

Create a payment plan

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/payment-plans

Example response

JSON

{
	"paymentPlanId": "PaymentPlanTest",
	"processingTerminalId": "3204001",
	"name": "Davi Crisostomo",
	"description": "Payment Plan creation",
	"currency": "USD",
	"setupOrder": {
		"amount": 11000,
		"description": "Setup Amount"
	},
	"length": 24,
	"type": "manual",
	"frequency": "monthly",
	"onUpdate": "update",
	"onDelete": "complete"
}

Update a payment plan

Send a PATCH request to the following endpoint:

PATCH https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/payment-plans/{paymentPlanId}

Example response

JSON

{
	"paymentPlanId": "PaymentPlanTest",
	"processingTerminalId": "3204001",
	"name": "Davi Crisostomo",
	"description": "Payment Plan creation",
	"currency": "USD",
	"setupOrder": {
		"amount": 11000,
		"description": "Setup Amount"
	},
	"length": 24,
	"type": "automatic",
	"frequency": "weekly",
	"onUpdate": "update",
	"onDelete": "complete"
}

Create a subscription for a payment plan

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/subscriptions

Example response

JSON

{
	"subscriptionId": "SubTest",
	"processingTerminalId": "3204001",
	"paymentPlan": {
		"paymentPlanId": "PaymentPlanTest",
		"name": "Davi Crisostomo",
		"link": {
			"rel": "self",
			"method": "GET",
			"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/payment-plans/PaymentPlanTest"
		}
	},
	"secureToken": {
		"secureTokenId": "MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA",
		"customerName": "",
		"token": "2967538502417872",
		"status": "cvv_validated",
		"link": {
			"rel": "self",
			"method": "GET",
			"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/secure-tokens/MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA"
		}
	},
	"name": "Davi Crisostomo",
	"description": "Create Subscription from ICC payment",
	"currency": "USD",
	"setupOrder": {
		"orderId": "TheOrderID",
		"amount": 11000,
		"description": "Description of SETUPORDER"
	},
	"recurringOrder": {
		"amount": 11000,
		"description": "RECURRING Order price"
	},
	"currentState": {
		"status": "active",
		"nextDueDate": "2023-08-02",
		"paidInvoices": 0,
		"outstandingInvoices": 122
	},
	"startDate": "2023-08-02",
	"endDate": "2025-12-02",
	"length": 24,
	"type": "automatic",
	"frequency": "weekly",
	"pauseCollectionFor": 0
}

Manually pay a subscription

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/pay

Example response

JSON

{
	"paymentId": "KOHM1D3EZH",
	"processingTerminalId": "3204001",
	"operator": "Davi Crisostomo",
	"order": {
		"orderId": "UniqueValueForOrderID",
		"dateTime": "2023-06-20T20:25:57.641+01:00",
		"description": "Subscription Payment - Manual",
		"amount": 11000,
		"currency": "USD"
	},
	"card": {
		"type": "Visa Credit",
		"entryMethod": "keyed",
		"cardNumber": "444433******1111",
		"expiryDate": "1226",
		"secureToken": {
			"secureTokenId": "MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA",
			"customerName": "",
			"token": "2967538502417872",
			"status": "cvv_validated",
			"link": {
				"rel": "self",
				"method": "GET",
				"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/secure-tokens/MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA"
			}
		},
		"securityChecks": {
			"cvvResult": "M",
			"avsResult": "Y"
		}
	},
	"transactionResult": {
		"type": "sale",
		"status": "ready",
		"approvalCode": "OK24225",
		"authorizedAmount": 11000,
		"currency": "USD",
		"responseCode": "A",
		"responseMessage": "OK24225",
		"cardSchemeReferenceId": "nkMX2G7ZqPavgbYiYacQ"
	}
}

Update a subscription

Send a PATCH request to the following endpoint:

PATCH https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}

Example response

JSON

{
	"subscriptionId": "SubTest",
	"processingTerminalId": "3204001",
	"paymentPlan": {
		"paymentPlanId": "PaymentPlanTest",
		"name": "Davi Crisostomo",
		"link": {
			"rel": "self",
			"method": "GET",
			"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/payment-plans/PaymentPlanTest"
		}
	},
	"secureToken": {
		"secureTokenId": "MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA",
		"customerName": "",
		"token": "2967538502417872",
		"status": "cvv_validated",
		"link": {
			"rel": "self",
			"method": "GET",
			"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/secure-tokens/MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA"
		}
	},
	"name": "Davi Crisostomo",
	"description": "NEW DESCRIPTION FOR SUBSCRIPTION",
	"currency": "USD",
	"setupOrder": {
		"orderId": "TheOrderID",
		"amount": 11000,
		"description": "Description of SETUPORDER"
	},
	"recurringOrder": {
		"amount": 11000,
		"description": "RECURRING Order price"
	},
	"currentState": {
		"status": "active",
		"nextDueDate": "2023-08-02",
		"paidInvoices": 1,
		"outstandingInvoices": 121
	},
	"startDate": "2023-08-02",
	"endDate": "2025-12-02",
	"length": 24,
	"type": "automatic",
	"frequency": "weekly",
	"pauseCollectionFor": 0
}

Deactivate a subscription

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/deactivate

Example response

JSON

{
	"subscriptionId": "SubTest",
	"processingTerminalId": "3204001",
	"paymentPlan": {
		"paymentPlanId": "PaymentPlanTest",
		"name": "Davi Crisostomo",
		"link": {
			"rel": "self",
			"method": "GET",
			"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/payment-plans/PaymentPlanTest"
		}
	},
	"secureToken": {
		"secureTokenId": "MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA",
		"customerName": "",
		"token": "2967538502417872",
		"status": "cvv_validated",
		"link": {
			"rel": "self",
			"method": "GET",
			"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/secure-tokens/MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA"
		}
	},
	"name": "Davi Crisostomo",
	"description": "NEW DESCRIPTION FOR SUBSCRIPTION",
	"currency": "USD",
	"setupOrder": {
		"orderId": "TheOrderID",
		"amount": 11000,
		"description": "Description of SETUPORDER"
	},
	"recurringOrder": {
		"amount": 11000,
		"description": "RECURRING Order price"
	},
	"currentState": {
		"status": "cancelled",
		"nextDueDate": "2023-08-02",
		"paidInvoices": 1,
		"outstandingInvoices": 121
	},
	"startDate": "2023-08-02",
	"endDate": "2025-12-02",
	"length": 24,
	"type": "automatic",
	"frequency": "weekly",
	"pauseCollectionFor": 0
}

Re-activate a subscription

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/reactivate

Example response

JSON

{
	"subscriptionId": "SubTest",
	"processingTerminalId": "3204001",
	"paymentPlan": {
		"paymentPlanId": "PaymentPlanTest",
		"name": "Davi Crisostomo",
		"link": {
			"rel": "self",
			"method": "GET",
			"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/payment-plans/PaymentPlanTest"
		}
	},
	"secureToken": {
		"secureTokenId": "MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA",
		"customerName": "",
		"token": "2967538502417872",
		"status": "cvv_validated",
		"link": {
			"rel": "self",
			"method": "GET",
			"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/secure-tokens/MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA"
		}
	},
	"name": "Davi Crisostomo",
	"description": "NEW DESCRIPTION FOR SUBSCRIPTION",
	"currency": "USD",
	"setupOrder": {
		"orderId": "TheOrderID",
		"amount": 11000,
		"description": "Description of SETUPORDER"
	},
	"recurringOrder": {
		"amount": 11000,
		"description": "RECURRING Order price"
	},
	"currentState": {
		"status": "active",
		"nextDueDate": "2023-08-02",
		"paidInvoices": 1,
		"outstandingInvoices": 121
	},
	"startDate": "2023-08-02",
	"endDate": "2025-12-02",
	"length": 24,
	"type": "automatic",
	"frequency": "weekly",
	"pauseCollectionFor": 0
}

Bank transfers

Run a sale with bank account details

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/bank-transfer-payments

Example response

JSON

{
    "channel": "POS",
    "processingTerminalId": "3204001",
    "operator": "Davi-CHP",
    "order": {
        "orderId": "CC-12",
        "description": "BT ACH - Sale with CC",
        "currency": "USD",
        "amount": 9700
    },
    "paymentMethod": {
        "type": "ach",
        "accountType": "checking",
        "secCode": "web",
        "nameOnAccount": "Davi",
        "accountNumber": "49100130",
        "routingNumber": "292735277"
    }
}

Before you begin

Test environment

Authenticating your requests

Example request

Example response

Example request header

Test cards

EBT test cards

Test values

Testing recommendations

Test cases

Card payments

Run a card sale without a surcharge

Run a card sale with a surcharge

Run a pre-authorization

Capture a pre-authorization

Adjust a card payment

Secure tokens

Create a secure token

Create a payment with a secure token

Delete a secure token

Update a secure token

Payment plans and subscriptions

Create a payment plan

Update a payment plan

Create a subscription for a payment plan

Manually pay a subscription

Update a subscription

Deactivate a subscription

Re-activate a subscription

Bank transfers

Run a sale with bank account details

Browse guides

Menu

Sign out

Talk to an engineer