Use your own software | Payroc

If you use your own software to manage repeat payments, program your software to run a sale each time the merchant wants to take a payment. Each request should also include the following information:

Type of repeat payment
Position of the payment in the billing cycle
Information about the first payment

You can also use our tokenization service to save the customer’s payment details as a secure token. For each repeat payment, you can use the secure token instead of the customer’s payment details.

Integration steps

To use your own software for repeat payments, integrate with the following:

Step 1. (Optional) Create a secure token.
Step 2. Create a payment.

Before you begin

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

Step 1. (Optional) Create a secure token

Note: If you have already set up your integration to create a secure token, go to Step 2. Create a payment.

To save the customer’s payment details, send a POST request to our Secure Tokens endpoint.

Environment	URL
Test	https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/secure-tokens
Production	https://api.payroc.com/v1/processing-terminals/{processingTerminalId}/secure-tokens

Note: We assign the secure token to the terminal that sent the request. Depending on the merchant’s account settings, other terminals within the merchant’s account can also use the secure token.

Request parameters

To create the body of your request, use the following parameters:

Request

sourceobjectRequired

Polymorphic object that contains the payment method to tokenize. The value of the type parameter determines which variant you should use: - `ach` - Automated Clearing House (ACH) details - `pad` - Pre-authorized debit (PAD) details - `card` - Payment card details - `singleUseToken` - Single-use token details

secureTokenIdstringOptional1-200 characters

Unique identifier that you create for the secure token that represents the customer’s payment details. **Note:** If you don't send a value for the secureTokenId, our gateway generates a unique identifier for the token.

operatorstringOptional1-50 characters

Operator who saved the customer's payment details.

mitAgreementenumOptional

Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration.

customerobjectOptional

Object that contains the customer's contact details and address information. Contains parameters required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data).

ipAddressobjectOptional

Object that contains the IP address of the device that sent the request.

threeDSecureobjectOptional

Polymorphic object that contains authentication information from 3-D Secure. The value of the type parameter determines which variant you should use: - `gatewayThreeDSecure` - Use our gateway to run a 3-D Secure check. - `thirdPartyThreeDSecure` - Use a third party to run a 3-D Secure check.

customFieldslist of objectsOptional

Array of customField objects.

Example request

POST

/v1/processing-terminals/:processingTerminalId/secure-tokens

1 curl -X POST https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens \
2      -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3      -H "Authorization: Bearer <token>" \
4      -H "Content-Type: application/json" \
5      -d '{
6   "source": {
7     "type": "card",
8     "cardDetails": {
9       "entryMethod": "keyed",
10       "keyedData": {
11         "dataFormat": "plainText",
12         "cardNumber": "4539858876047062",
13         "cvv": "234",
14         "expiryDate": "1230"
15       },
16       "cardholderName": "Sarah Hazel Hopper"
17     }
18   },
19   "operator": "Jane",
20   "mitAgreement": "unscheduled",
21   "customer": {
22     "firstName": "Sarah",
23     "lastName": "Hopper",
24     "dateOfBirth": "1990-07-15",
25     "referenceNumber": "Customer-12",
26     "billingAddress": {
27       "address1": "1 Example Ave.",
28       "city": "Chicago",
29       "state": "Illinois",
30       "country": "US",
31       "postalCode": "60056",
32       "address2": "Example Address Line 2",
33       "address3": "Example Address Line 3"
34     },
35     "shippingAddress": {
36       "recipientName": "Sarah Hopper",
37       "address": {
38         "address1": "1 Example Ave.",
39         "city": "Chicago",
40         "state": "Illinois",
41         "country": "US",
42         "postalCode": "60056",
43         "address2": "Example Address Line 2",
44         "address3": "Example Address Line 3"
45       }
46     },
47     "contactMethods": [
48       {
49         "type": "email",
50         "value": "[email protected]"
51       }
52     ],
53     "notificationLanguage": "en"
54   },
55   "ipAddress": {
56     "type": "ipv4",
57     "value": "104.18.24.203"
58   },
59   "customFields": [
60     {
61       "name": "yourCustomField",
62       "value": "abc123"
63     }
64   ]
65 }'

Try it

Response fields

If your request is successful, we store the customer’s payment details and return a response. The response contains the following fields:

Response

secureTokenIdstringRequired0-200 characters

Unique identifier that the merchant created for the secure token that represents the customer's payment details.

processingTerminalIdstringRequired4-50 characters

Unique identifier that we assigned to the terminal.

sourceobjectRequired

Polymorphic object that contains the payment method that we tokenized. The value of the type parameter determines which variant you should use: - `ach` - Automated Clearing House (ACH) details - `pad` - Pre-authorized debit (PAD) details - `card` - Payment card details

tokenstringRequired12-19 characters

Token that the merchant can use in future transactions to represent the customer's payment details. The token: - Begins with the six-digit identification number **296753**. - Contains up to 12 digits. - Contains a single check digit that we calculate using the Luhn algorithm.

statusenumRequired

Outcome of a security check on the status of the customer's payment card or bank account. **Note:** Depending on the merchant's account settings, this feature may be unavailable.

mitAgreementenumOptional

customerobjectOptional

Object that contains the customer's contact details and address information.

customFieldslist of objectsOptional

Array of customField objects.

Example response

Response

1 {
2   "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
3   "processingTerminalId": "1234001",
4   "source": {
5     "type": "card",
6     "cardNumber": "453985******7062",
7     "cardholderName": "Sarah Hazel Hopper",
8     "expiryDate": "1230"
9   },
10   "token": "296753123456",
11   "status": "notValidated",
12   "mitAgreement": "unscheduled",
13   "customer": {
14     "firstName": "Sarah",
15     "lastName": "Hopper",
16     "dateOfBirth": "1990-07-15",
17     "referenceNumber": "Customer-12",
18     "billingAddress": {
19       "address1": "1 Example Ave.",
20       "address2": "Example Address Line 2",
21       "address3": "Example Address Line 3",
22       "city": "Chicago",
23       "state": "Illinois",
24       "country": "US",
25       "postalCode": "60056"
26     },
27     "shippingAddress": {
28       "recipientName": "Sarah Hopper",
29       "address": {
30         "address1": "1 Example Ave.",
31         "address2": "Example Address Line 2",
32         "address3": "Example Address Line 3",
33         "city": "Chicago",
34         "state": "Illinois",
35         "country": "US",
36         "postalCode": "60056"
37       }
38     },
39     "contactMethods": [
40       {
41         "type": "email",
42         "value": "[email protected]"
43       }
44     ],
45     "notificationLanguage": "en"
46   },
47   "customFields": [
48     {
49       "name": "yourCustomField",
50       "value": "abc123"
51     }
52   ]
53 }

Step 2. Create a payment

You can run repeat payments with card details or with bank details. The endpoint that you use depends on the payment method:

Create a card payment

To take a payment from the customer, send a POST request to the Payments endpoint. In your request, include the standingInstructions object, which contains information about the repeat payment.

Environment	URL
Test	https://api.uat.payroc.com/v1/payments
Production	https://api.payroc.com/v1/payments

Request parameters

To create the body of your request, use the following parameters:

Request

Example request

POST

/v1/payments

1 curl -X POST https://api.payroc.com/v1/payments \
2      -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3      -H "Authorization: Bearer <token>" \
4      -H "Content-Type: application/json" \
5      -d '{
6   "channel": "web",
7   "processingTerminalId": "1234001",
8   "order": {
9     "orderId": "OrderRef6543",
10     "amount": 4999,
11     "currency": "USD",
12     "description": "Pizza Doe #1234 - Dinner",
13     "standingInstructions": {
14       "sequence": "first",
15       "processingModel": "recurring"
16     }
17   },
18   "paymentMethod": {
19     "type": "secureToken",
20     "token": "296753123456"
21   },
22   "operator": "Jane",
23   "customer": {
24     "firstName": "Sarah",
25     "lastName": "Hopper",
26     "billingAddress": {
27       "address1": "1 Example Ave.",
28       "city": "Chicago",
29       "state": "Illinois",
30       "country": "US",
31       "postalCode": "60056",
32       "address2": "Example Address Line 2",
33       "address3": "Example Address Line 3"
34     },
35     "shippingAddress": {
36       "recipientName": "Sarah Hopper",
37       "address": {
38         "address1": "1 Example Ave.",
39         "city": "Chicago",
40         "state": "Illinois",
41         "country": "US",
42         "postalCode": "60056",
43         "address2": "Example Address Line 2",
44         "address3": "Example Address Line 3"
45       }
46     }
47   },
48   "credentialOnFile": {
49     "mitAgreement": "recurring"
50   },
51   "customFields": [
52     {
53       "name": "yourCustomField",
54       "value": "abc123"
55     }
56   ]
57 }'

Try it

Response fields

If your request is successful, we create the payment and return a response. The response contains the following fields:

Response

Example response

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": "Pizza Doe #1234 - Dinner",
10     "standingInstructions": {
11       "sequence": "first",
12       "processingModel": "recurring"
13     }
14   },
15   "card": {
16     "type": "Visa Credit",
17     "entryMethod": "keyed",
18     "cardNumber": "453985******7062",
19     "expiryDate": "1230",
20     "cardholderName": "Sarah Hopper",
21     "secureToken": {
22       "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
23       "customerName": "Sarah Hopper",
24       "token": "296753123456",
25       "status": "notValidated",
26       "link": {
27         "rel": "self",
28         "method": "GET",
29         "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
30       }
31     },
32     "securityChecks": {
33       "avsResult": "Y"
34     }
35   },
36   "transactionResult": {
37     "status": "ready",
38     "responseCode": "A",
39     "type": "sale",
40     "approvalCode": "OK3",
41     "authorizedAmount": 4999,
42     "currency": "USD",
43     "responseMessage": "OK3",
44     "cardSchemeReferenceId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
45   },
46   "operator": "Jane",
47   "customer": {
48     "firstName": "Sarah",
49     "lastName": "Hopper",
50     "billingAddress": {
51       "address1": "1 Example Ave.",
52       "address2": "Example Address Line 2",
53       "address3": "Example Address Line 3",
54       "city": "Chicago",
55       "state": "Illinois",
56       "country": "US",
57       "postalCode": "60056"
58     },
59     "shippingAddress": {
60       "recipientName": "Sarah Hopper",
61       "address": {
62         "address1": "1 Example Ave.",
63         "address2": "Example Address Line 2",
64         "address3": "Example Address Line 3",
65         "city": "Chicago",
66         "state": "Illinois",
67         "country": "US",
68         "postalCode": "60056"
69       }
70     }
71   },
72   "supportedOperations": [
73     "fullyReverse",
74     "setAsPending"
75   ],
76   "customFields": [
77     {
78       "name": "yourCustomField",
79       "value": "abc123"
80     }
81   ]
82 }

Create a bank transfer payment

To take a payment from the customer, send a POST request to our Bank Transfer Payments endpoint.

Environment	URL
Test	https://api.uat.payroc.com/v1/bank-transfer-payments
Production	https://api.payroc.com/v1/bank-transfer-payments

Request parameters

If you have a secure token that represents the bank account details, include the secure token in the paymentMethod object.

Request

Example request

POST

/v1/bank-transfer-payments

1 curl -X POST https://api.payroc.com/v1/bank-transfer-payments \
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     "amount": 4999,
9     "currency": "USD",
10     "orderId": "OrderRef6543",
11     "description": "Pizza Doe"
12   },
13   "paymentMethod": {
14     "type": "secureToken",
15     "token": "296753123456",
16     "accountType": "checking",
17     "secCode": "web"
18   },
19   "customer": {
20     "contactMethods": [
21       {
22         "type": "email",
23         "value": "[email protected]"
24       }
25     ]
26   },
27   "customFields": [
28     {
29       "name": "yourCustomField",
30       "value": "abc123"
31     }
32   ]
33 }'

Try it

Response fields

If your request is successful, we create the payment and return a response. The response contains the following fields:

Response

Example response

Response

1 {
2   "paymentId": "E29U8OU8Q4",
3   "processingTerminalId": "1234001",
4   "order": {
5     "amount": 4999,
6     "currency": "USD",
7     "orderId": "OrderRef6543",
8     "dateTime": "2024-07-02T15:30:00Z",
9     "description": "Pizza Doe #1234 - Dinner"
10   },
11   "bankAccount": {
12     "type": "ach",
13     "accountNumber": "******3491",
14     "nameOnAccount": "Sarah Hazel Hopper",
15     "routingNumber": "063100277",
16     "secCode": "web",
17     "secureToken": {
18       "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
19       "customerName": "Sarah Hazel Hopper",
20       "token": "296753123456",
21       "status": "bankAccountValidated",
22       "link": {
23         "rel": "self",
24         "method": "GET",
25         "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
26       }
27     }
28   },
29   "transactionResult": {
30     "type": "payment",
31     "status": "pending",
32     "responseCode": "P",
33     "authorizedAmount": 4999,
34     "currency": "USD",
35     "responseMessage": "Pending"
36   },
37   "customer": {
38     "contactMethods": [
39       {
40         "type": "email",
41         "value": "[email protected]"
42       }
43     ]
44   },
45   "customFields": [
46     {
47       "name": "yourCustomField",
48       "value": "abc123"
49     }
50   ]
51 }

Test cases

Before you run test cases, read the Payments page in Test Your Integration.

Run a card sale

Send a POST request to the following endpoint:

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

Example response

1 {
2 	"paymentId": "F1I17KBL0E",
3 	"processingTerminalId": "3204001",
4 	"order": {
5 		"orderId": "Test_001",
6 		"dateTime": "2023-05-24T14:44:20.63+01:00",
7 		"amount": 4000,
8 		"currency": "USD"
9 	},
10 	"card": {
11 		"type": "Visa Credit",
12 		"entryMethod": "keyed",
13 		"cardNumber": "444433******1111",
14 		"expiryDate": "0334",
15 		"securityChecks": {
16 			"cvvResult": "M",
17 			"avsResult": "Y"
18 		}
19 	},
20 	"paymentResult": {
21 		"type": "sale",
22 		"status": "ready",
23 		"approvalCode": "OK14472",
24 		"authorizedAmount": 4000,
25 		"currency": "USD",
26 		"responseCode": "A",
27 		"responseMessage": "OK14472"
28 	}
29 }