Integrate

Update saved payment details

Integrate with our API to update a customer’s saved payment details. Our API has two endpoints to update payment details represented by a secure token:

  • Update saved payment details – Use our Update Secure Token endpoint if you are sending the raw payment details, for example, if you are updating a card’s expiry date or a billing address.
  • Update saved payment details with a single-use token – Use our Update Account Details endpoint if you have a single-use token that represents updated payment details, for example, if you have a single-use token from Hosted Fields.

Note: To update saved payment details, you need the ID of the secure token that represents the payment details. If you don’t know the ID, go to List Secure Tokens.

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.

Update saved payment details

Use the Update Secure Token method if you have the raw information that a customer wants to update. You can update the following payment details:

  • Sensitive payment details, including:
    • Card - Cardholder name and expiry date
    • ACH - Accountholder name and account type
    • PAD - Accountholder name and institution number
  • MIT agreement
  • Customer’s contact details
  • Customer’s address details

Integration steps

  • Update a secure token

Update a secure token

To update the payment details represented by a secure token, send a PATCH request to our Update Secure Token endpoint.

Note: The request format follows the RFC 6902 standard.

Request parameters

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

Request

Patch Add OperationobjectRequired
OR
Patch Remove OperationobjectRequired
OR
Patch Replace OperationobjectRequired
OR
Patch Move OperationobjectRequired
OR
Patch Copy OperationobjectRequired
OR
Patch Test OperationobjectRequired

Example request

PATCH
/v1/processing-terminals/:processingTerminalId/secure-tokens/:secureTokenId
1curl -X PATCH https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '[
6  {
7    "op": "add",
8    "path": "/customer/lastName",
9    "value": null
10  },
11  {
12    "op": "add",
13    "path": "/shippingAddress/recipientName",
14    "value": null
15  },
16  {
17    "op": "add",
18    "path": "/source/cardDetails/cardholderName",
19    "value": null
20  }
21]'

Response fields

If your request is successful, we update the secure token and return the details represented by the secure token.

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}

Update saved payment details with a single-use token

If you use our Hosted Fields solution, our gateway creates a single-use token to represent the customer’s updates to their card, ACH, or PAD details. Send the single-use token to our gateway so that we can update the details represented by the secure token.

You can also send a secondary request to our gateway to update other details that the single-use token doesn’t change:

  • MIT agreement
  • Customer’s contact details
  • Customer’s address details

Integration steps

Step 1. Update saved payment details with a single-use token
Step 2. (Optional) Update a secure token

Step 1. Update saved payment details with a single-use token

To update saved payment details with a single-use token, send a POST request to our Update Account Details endpoint.

Request parameters

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

Request

singleUseTokenobjectRequired

Example request

POST
/v1/processing-terminals/:processingTerminalId/secure-tokens/:secureTokenId/update-account
1curl -X POST https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa/update-account \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "type": "singleUseToken",
7  "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
8}'

Response fields

If your request is successful, we update the secure token and return the details represented by the secure token.

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}

Step 2. (Optional) Update a secure token

To update the payment details represented by a secure token, send a PATCH request to our Update Secure Token endpoint.

Note: The request format follows the RFC 6902 standard.

Request parameters

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

Request

Patch Add OperationobjectRequired
OR
Patch Remove OperationobjectRequired
OR
Patch Replace OperationobjectRequired
OR
Patch Move OperationobjectRequired
OR
Patch Copy OperationobjectRequired
OR
Patch Test OperationobjectRequired

Example request

PATCH
/v1/processing-terminals/:processingTerminalId/secure-tokens/:secureTokenId
1curl -X PATCH https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '[
6  {
7    "op": "add",
8    "path": "/customer/lastName",
9    "value": null
10  },
11  {
12    "op": "add",
13    "path": "/shippingAddress/recipientName",
14    "value": null
15  },
16  {
17    "op": "add",
18    "path": "/source/cardDetails/cardholderName",
19    "value": null
20  }
21]'

Response fields

If your request is successful, we update the secure token and return the details represented by the secure token.

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}