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

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

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.

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

Note: The request format follows the RFC 6902 standard.

Request parameters

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

Request

Example request

PATCH

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

curl -X PATCH https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '[
  {
    "op": "add",
    "path": "/customer/lastName",
    "value": null
  },
  {
    "op": "add",
    "path": "/shippingAddress/recipientName",
    "value": null
  },
  {
    "op": "add",
    "path": "/source/cardDetails/cardholderName",
    "value": null
  }
]'

Try it

Response fields

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

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

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.

customFieldslist of objectsOptional

Array of customField objects.

Example response

Response

{
  "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
  "processingTerminalId": "1234001",
  "source": {
    "type": "card",
    "cardNumber": "453985******7062",
    "cardholderName": "Sarah Reed",
    "expiryDate": "1230"
  },
  "token": "296753123456",
  "status": "notValidated",
  "mitAgreement": "unscheduled",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Reed",
    "dateOfBirth": "1990-07-15",
    "referenceNumber": "Customer-12",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Reed",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    },
    "contactMethods": [
      {
        "type": "email",
        "value": "[email protected]"
      }
    ],
    "notificationLanguage": "en"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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.

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

Request parameters

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

Request

singleUseTokenobjectRequired

Object that contains the token.

Example request

POST

/v1/processing-terminals/:processingTerminalId/secure-tokens/:secureTokenId/update-account

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

Try it

Response fields

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

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

tokenstringRequired12-19 characters

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

{
  "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
  "processingTerminalId": "1234001",
  "source": {
    "type": "card",
    "cardNumber": "453985******7062",
    "cardholderName": "Sarah Hazel Hopper",
    "expiryDate": "1230"
  },
  "token": "296753123456",
  "status": "notValidated",
  "mitAgreement": "unscheduled",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "dateOfBirth": "1990-07-15",
    "referenceNumber": "Customer-12",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    },
    "contactMethods": [
      {
        "type": "email",
        "value": "[email protected]"
      }
    ],
    "notificationLanguage": "en"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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.

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

Note: The request format follows the RFC 6902 standard.

Request parameters

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

Request

Example request

PATCH

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

curl -X PATCH https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '[
  {
    "op": "add",
    "path": "/customer/lastName",
    "value": null
  },
  {
    "op": "add",
    "path": "/shippingAddress/recipientName",
    "value": null
  },
  {
    "op": "add",
    "path": "/source/cardDetails/cardholderName",
    "value": null
  }
]'

Try it

Response fields

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

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

tokenstringRequired12-19 characters

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

{
  "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
  "processingTerminalId": "1234001",
  "source": {
    "type": "card",
    "cardNumber": "453985******7062",
    "cardholderName": "Sarah Reed",
    "expiryDate": "1230"
  },
  "token": "296753123456",
  "status": "notValidated",
  "mitAgreement": "unscheduled",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Reed",
    "dateOfBirth": "1990-07-15",
    "referenceNumber": "Customer-12",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Reed",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    },
    "contactMethods": [
      {
        "type": "email",
        "value": "[email protected]"
      }
    ],
    "notificationLanguage": "en"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}