Integrate

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:

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

Before you begin

Bearer tokens

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

Headers

To create the header of each POST request, you must include the following parameters:

  • Content-Type: Include application/json as the value for this parameter.
  • Authorization: Include your Bearer token in this parameter.
  • Idempotency-Key: Include a UUID v4 to make the request idempotent.
$curl
>-H "Content-Type: application/json"
>-H "Authorization: <Bearer token>"
>-H "Idempotency-Key: <UUID v4>"

Errors

If your request is unsuccessful, we return an error. For more information about errors, 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.

Save payment details

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

Request parameters

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

Request

sourceobjectRequired
Object that contains information about the payment method to tokenize.
secureTokenIdstringOptional>=1 character<=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.
operatorstringOptional>=1 character<=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.
Allowed values:
customerobjectOptional
Object that contains the customer's contact details and address information.
ipAddressobjectOptional
Object that contains information about the IP address of the device that sent the request.
threeDSecureobjectOptional
Object that contains information for an authentication check on the customer's payment details using the 3-D Secure protocol.
customFieldslist of objectsOptional
Array of customField objects.

Example request

POST
/v1/processing-terminals/:processingTerminalId/secure-tokens
1curl -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        "expiryDate": "1225",
14        "cvv": "234"
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}'

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

secureTokenIdstringRequired>=0 characters<=200 characters
Unique identifier that the merchant created for the secure token that represents the customer's payment details.
processingTerminalIdstringRequired>=4 characters<=50 characters
Unique identifier that we assigned to the terminal.
sourceobjectRequired
Object that contains information about the payment method that we tokenized.
tokenstringRequired>=12 characters<=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
Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. **Note:** Depending on the merchant's account settings, this feature may be unavailable.
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.
Allowed values:
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    "cardholderName": "Sarah Hazel Hopper",
7    "cardNumber": "453985******7062",
8    "expiryDate": "1225"
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      "city": "Chicago",
21      "state": "Illinois",
22      "country": "US",
23      "postalCode": "60056",
24      "address2": "Example Address Line 2",
25      "address3": "Example Address Line 3"
26    },
27    "shippingAddress": {
28      "recipientName": "Sarah Hopper",
29      "address": {
30        "address1": "1 Example Ave.",
31        "city": "Chicago",
32        "state": "Illinois",
33        "country": "US",
34        "postalCode": "60056",
35        "address2": "Example Address Line 2",
36        "address3": "Example Address Line 3"
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}