Save payment details

Integrate with our API to create a secure token to represent a customer’s payment details. There are two ways to save the payment details in our vault and get a secure token:

Save the payment details when running a sale.
Save the payment details without running a sale.

When you create your request, you can assign an ID to the secure token. If you don’t, our gateway assigns an ID to the secure token. We return the secureTokenID and the token in the response, which the merchant uses in follow-on transactions, including:

Create a payment with card details or bank account details.
Create a refund with card details or bank account details.
Look up BIN information.

Note: For more information about secure tokens, go to Tokenization.

Before you begin

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

Run a sale and save payment details

To run a sale and save the payment details, send a Create a Payment request. In the request, include a credentialOnFile object and set the tokenize parameter to true.

Our gateway runs the sale and saves the customer’s payment details in our vault. In the response, we return a secureTokenId and the token that the merchant can use for follow-on transactions.

Note: For more information about how to run a sale, go to Run a card sale or Run a sale with bank account details.

To save a customer’s payment details without running a sale, send a POST request to:

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

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 the merchant created for the secure token that represents the customer's payment details. If the merchant doesn't create a secureTokenId, the gateway generates one and returns it in the response.

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.

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 return a token that you can use instead of the customer’s payment details in follow-on transactions.

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.