Hosted FieldsExtend your integrationSave payment details

Save payment details when running a sale

View as Markdown

Save payment details when running a sale

You can use the single-use token from your existing Hosted Fields integration to save a customer’s payment details at the same time that you run a sale.

If you save a customer’s payment details during a sale, our gateway uses the single-use token from Hosted Fields to charge the customer, and then saves the customer’s payment details as a secure token. You can use the secure token multiple times, and it doesn’t expire.

To tokenize payment details during a sale, you need to send some additional parameters in your request to our API. You don’t need to change the JavaScript configuration or authentication for your existing Hosted Fields integration.

Before you begin

Make sure that you’ve set up your Hosted Fields integration to run a sale with the single-use token from the submissionSuccess event. For more information, go to Run a sale.

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

Integration steps

The steps that you need to follow depend on whether your single-use token represents card details or bank account details:

Save card details when you run a sale

To run a sale and tokenize the card details, you need to update your POST request to our Payments endpoint.

Request parameters

Important: The request includes parameters for functions and features that we don’t cover in this guide. These functions and features might require additional integration effort and cost. For more information, contact our Integrations Team at [email protected].

To save a customer’s card details when you run a sale, update your request to our Payments endpoint. Send the single-use token from Hosted Fields in the paymentMethod object, and include the following parameters in the credentialOnFile object:

  • tokenize - Send a value of true.
  • secureTokenId - Assign a unique identifier to the secure token.

Note: If you want to use the stored payment details to run repeat payments with your own software, include the standingInstructions object in your request. For more information about repeat payments with Hosted Fields, go to Repeat payments with Hosted Fields.

Request

Example request

POST
/v1/payments
1curl -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": "Large Pepperoni Pizza"
13  },
14  "paymentMethod": {
15    "type": "singleUseToken",
16    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
17  },
18  "operator": "Jane",
19  "customer": {
20    "firstName": "Sarah",
21    "lastName": "Hopper",
22    "billingAddress": {
23      "address1": "1 Example Ave.",
24      "city": "Chicago",
25      "state": "Illinois",
26      "country": "US",
27      "postalCode": "60056",
28      "address2": "Example Address Line 2",
29      "address3": "Example Address Line 3"
30    },
31    "shippingAddress": {
32      "recipientName": "Sarah Hopper",
33      "address": {
34        "address1": "1 Example Ave.",
35        "city": "Chicago",
36        "state": "Illinois",
37        "country": "US",
38        "postalCode": "60056",
39        "address2": "Example Address Line 2",
40        "address3": "Example Address Line 3"
41      }
42    }
43  },
44  "credentialOnFile": {
45    "tokenize": true,
46    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
47  },
48  "customFields": [
49    {
50      "name": "yourCustomField",
51      "value": "abc123"
52    }
53  ]
54}'
Try it

Response fields

If your request is successful, our gateway runs the sale and converts the single-use token into a secure token that we return in the response. You need to store the token so that you can use it in follow-up requests.

The response also 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": "Large Pepperoni Pizza"
10  },
11  "card": {
12    "type": "Visa Credit",
13    "entryMethod": "keyed",
14    "cardNumber": "453985******7062",
15    "expiryDate": "1230",
16    "cardholderName": "Sarah Hopper",
17    "secureToken": {
18      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
19      "customerName": "Sarah Hopper",
20      "token": "296753123456",
21      "status": "notValidated",
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    "securityChecks": {
29      "cvvResult": "M",
30      "avsResult": "Y"
31    }
32  },
33  "transactionResult": {
34    "status": "ready",
35    "responseCode": "A",
36    "type": "sale",
37    "approvalCode": "OK3",
38    "authorizedAmount": 4999,
39    "currency": "USD",
40    "responseMessage": "OK3",
41    "cardSchemeReferenceId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
42  },
43  "operator": "Jane",
44  "customer": {
45    "firstName": "Sarah",
46    "lastName": "Hopper",
47    "billingAddress": {
48      "address1": "1 Example Ave.",
49      "address2": "Example Address Line 2",
50      "address3": "Example Address Line 3",
51      "city": "Chicago",
52      "state": "Illinois",
53      "country": "US",
54      "postalCode": "60056"
55    },
56    "shippingAddress": {
57      "recipientName": "Sarah Hopper",
58      "address": {
59        "address1": "1 Example Ave.",
60        "address2": "Example Address Line 2",
61        "address3": "Example Address Line 3",
62        "city": "Chicago",
63        "state": "Illinois",
64        "country": "US",
65        "postalCode": "60056"
66      }
67    }
68  },
69  "supportedOperations": [
70    "capture",
71    "fullyReverse",
72    "partiallyReverse",
73    "incrementAuthorization",
74    "adjustTip",
75    "setAsPending"
76  ],
77  "customFields": [
78    {
79      "name": "yourCustomField",
80      "value": "abc123"
81    }
82  ]
83}

Save bank account details when you run a sale

To run a sale and tokenize the bank account details, you need to update your POST request to our Bank Transfer Payments endpoint.

Request parameters

Important: The request includes parameters for functions and features that we don’t cover in this guide. These functions and features might require additional integration effort and cost. For more information, contact our Integrations Team at [email protected].

To save a customer’s bank account details when you run a sale, update your request to our Bank Transfer Payments endpoint. Send the single-use token from Hosted Fields in the paymentMethod object, and include the following parameters in the credentialOnFile object:

  • tokenize - Send a value of true.
  • secureTokenId - Assign a unique identifier to the secure token.

Request

processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.
orderobjectRequired
Object that contains information about the transaction.
paymentMethodobjectRequired
Polymorphic object that contains payment detail information. The value of the type parameter determines which variant you should use: - `ach` - Automated Clearing House (ACH) details - `pad` - Pre-authorized debit (PAD) details - `secureToken` - Secure token details - `singleUseToken` - Single-use token details
customerobjectOptional
Object that contains information about the customer.
credentialOnFileobjectOptional
Object that contains information about saving the customer’s payment details.
customFieldslist of objectsOptional
Array of customField objects.

Example request

POST
/v1/bank-transfer-payments
1curl -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": "Large Pepperoni Pizza"
12  },
13  "paymentMethod": {
14    "type": "singleUseToken",
15    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
16    "accountType": "checking",
17    "secCode": "web"
18  },
19  "customer": {
20    "notificationLanguage": "en",
21    "contactMethods": [
22      {
23        "type": "email",
24        "value": "[email protected]"
25      }
26    ]
27  },
28  "credentialOnFile": {
29    "tokenize": true,
30    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
31  },
32  "customFields": [
33    {
34      "name": "yourCustomField",
35      "value": "abc123"
36    }
37  ]
38}'
Try it

Response fields

If your request is successful, our gateway runs the sale and converts the single-use token into a secure token that we return in the response. You need to store the token so that you can use it in follow-up requests.

The response also contains the following fields:

Response

paymentIdstringRequired=10 characters
Unique identifier that we assigned to the payment.
processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.
orderobjectRequired
Object that contains information about the transaction.
bankAccountobjectRequired
Polymorphic object that contains bank account information. The value of the type field determines which variant you should use: - `ach` - Automated Clearing House (ACH) details - `pad` - Pre-authorized debit (PAD) details
transactionResultobjectRequiredRead-only
Object that contains information about the transaction.
customerobjectOptional
Object that contains information about the customer.
refundslist of objectsOptional
List of refunds issued against the payment.
returnslist of objectsOptional
List of returns issued against the payment.
representmentobjectOptional
Object that contains details about the re-presented payment linked to the return.
customFieldslist of objectsOptional
Array of customField objects.

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": "Large Pepperoni Pizza"
10  },
11  "bankAccount": {
12    "type": "ach",
13    "accountNumber": "****3591",
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": "notValidated",
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": "ready",
32    "responseCode": "A",
33    "authorizedAmount": 4999,
34    "currency": "USD",
35    "responseMessage": "NoError",
36    "processorResponseCode": "0"
37  },
38  "customer": {
39    "notificationLanguage": "en",
40    "contactMethods": [
41      {
42        "type": "email",
43        "value": "[email protected]"
44      }
45    ]
46  },
47  "customFields": [
48    {
49      "name": "yourCustomField",
50      "value": "abc123"
51    }
52  ]
53}

Using the secure token

After you receive the secure token that represents the customer’s payment details, you can use it in follow-up requests to our API, including:

Note: You can also use the secure token to set up repeat payments with our gateway, which requires more integration effort and cost. For more information, contact our Integrations Team at [email protected].