Skip to main content

Manage payment methods for a consumer profile

You can manage the payment methods on a consumer profile using the following operations:

  • Add a new payment method to an existing consumer profile
  • Update a payment method
  • Set the default payment method
  • Delete a payment method

Before you begin

Learn about the payment methods available on Consumer Profile Management.

Add a new payment method to an existing consumer profile

You can add a payment method to an existing consumer profile by sending a POST request to the /consumer-profiles/{consumer-profile-id}/payment-methods endpoint. The response includes the system-generated paymentMethodId field which is used to make subsequent updates to the new payment method.

Method: POST

Endpoint: /consumer-profiles/PACJGQ/payment-methods

Scenario: Adding a new payment method to the consumer profile with consumer-profile-id = PACJGQ

Json
{
    "cardList": [
        {
            "cardExpirationMonthYearNumber": "02/2025",
            "accountNumber": "4234555678990919",
            "accountStatus": "ACTIVE",
            "cardType": "DI",
            "firstName": "John",
            "lastName": "Doe",
            "consumerProfileAddress": {
                "firstName": "John",
                "lastName": "Doe",
                "consumerAssignedAddressName": "Work",
                "primaryAddressIndicator": true,
                "addressType": "SHIPPING",
                "line1": "400 Elton Farm",
                "line2": "Apt 123",
                "city": "Glen Mills",
                "state": "PA",
                "postalCode": "19342",
                "countryCode": "USA",
                "addressStatus": "ACTIVE"
            }
        }
    ]
}

Response:

Json
{
    "consumerProfileId": "PACJGQ",
    "cardOnFileReferenceNumber": "123",
    "firstName": "John",
    "lastName": "Doe",
    "communication": {
        "phoneList": [
            {
                "phoneNumber": "8888888828",
                "countryCode": "1",
                "phoneNumberType": "Home",
                "communicationIdentifier": "HH04423498968"
            }
        ],
        "emailList": [
            {
                "emailAddress": "john.doe.x@gmail.com",
                "emailAddressType": "Home",
                "communicationIdentifier": "EE8141240230923"
            }
        ]
    },
    "paymentMethodType": {
        "cardList": [
            {
                "paymentMethodId": "77ccba29-4857-494a-82bc-2a80e1fa2b9d",
                "cardExpirationMonthYearNumber": "01/2025",
                "last4CardNumber": "9999",
                "accountStatus": "ACTIVE",
                "cardType": "MC",
                "firstName": "John",
                "lastName": "Doe",
                "addressIdentifier": "8d452494-ec75-4ef9-9b45-e4bd7debf6a0"
            },
            {
                "paymentMethodId": "63aaba29-4857-494a-82bc-2a80e1fa2b1e",
                "cardExpirationMonthYearNumber": "02/2025",
                "last4CardNumber": "0919",
                "accountStatus": "ACTIVE",
                "cardType": "DI",
                "firstName": "John",
                "lastName": "Doe",
                "addressIdentifier": "e17a1ecd-b177-4c3d-a99b-c72e132b260f"
            }
        ]
    },
    "addresses": [
        {
            "addressIdentifier": "8d452494-ec75-4ef9-9b45-e4bd7debf6a0",
            "firstName": "John",
            "lastName": "Doe",
            "consumerAssignedAddressName": "Work",
            "primaryAddressIndicator": true,
            "addressType": "SHIPPING",
            "line1": "200 Elton Farm",
            "line2": "Apt 123",
            "city": "Glen Mills",
            "state": "PA",
            "postalCode": "19342",
            "countryCode": "USA",
            "addressStatus": "ACTIVE"
        },
        {
            "addressIdentifier": "e17a1ecd-b177-4c3d-a99b-c72e132b260f",
            "firstName": "John",
            "lastName": "Doe",
            "consumerAssignedAddressName": "Work2",
            "primaryAddressIndicator": true,
            "addressType": "SHIPPING",
            "line1": "400 Elton Farm",
            "line2": "Apt 123",
            "city": "Glen Mills",
            "state": "PA",
            "postalCode": "19342",
            "countryCode": "USA",
            "addressStatus": "ACTIVE"
        }
    ],
    "correlationIdentifier": "648ccc37-e006-45ee-a127-2718bffeadad",
    "createTimestamp": "2021-08-23T00:23:05.353Z",
    "createUserIdentifier": "jack",
    "updateTimestamp": "2024-07-02T09:38:54.781Z",
    "updateUserIdentifier": "jack",
    "profileStatus": "ACTIVE"
}

Update a payment method

You can modify a payment method for an existing consumer profile by sending a PATCH request to the /consumer-profiles/{consumer-profile-id}/payment-methods/{payment-method-Id} endpoint.

Method: PATCH

Endpoint: /consumer-profiles/PACJGQ/payment-methods/63aaba29-4857-494a-82bc-2a80e1fa2b1e

Scenario: Updating the payment method with payment-method-Id = 63aaba29-4857-494a-82bc-2a80e1fa2b1e on the consumer profile with consumer-profile-id = PACJGQ

Json
{
    "card": {
        "cardExpirationMonthYearNumber": "02/2025",
        "accountStatus": "ACTIVE",
        "firstName": "John",
        "lastName": "Doe",
        "consumerProfileAddress": {
            "firstName": "John",
            "lastName": "Doe",
            "consumerAssignedAddressName": "Work",
            "primaryAddressIndicator": true,
            "addressType": "BILLING",
            "line1": "300 Elton Street",
            "line2": "Apt 123",
            "city": "Glen Mills",
            "state": "PA",
            "postalCode": "19342",
            "countryCode": "USA",
            "addressStatus": "ACTIVE"
        }
    }
}

Response:

Json
{
    "consumerProfileId": "PACJGQ",
    "cardOnFileReferenceNumber": "123",
    "firstName": "John",
    "lastName": "Doe",
    "communication": {
        "phoneList": [
            {
                "phoneNumber": "8888888828",
                "countryCode": "1",
                "phoneNumberType": "Home",
                "communicationIdentifier": "HH04423498968"
            }
        ],
        "emailList": [
            {
                "emailAddress": "john.doe.x@gmail.com",
                "emailAddressType": "Home",
                "communicationIdentifier": "EE8141240230923"
            }
        ]
    },
    "paymentMethodType": {
        "cardList": [
            {
                "paymentMethodId": "77ccba29-4857-494a-82bc-2a80e1fa2b9d",
                "cardExpirationMonthYearNumber": "01/2025",
                "last4CardNumber": "9999",
                "accountStatus": "ACTIVE",
                "cardType": "MC",
                "firstName": "John",
                "lastName": "Doe",
                "addressIdentifier": "8d452494-ec75-4ef9-9b45-e4bd7debf6a0"
            },
            {
                "paymentMethodId": "63aaba29-4857-494a-82bc-2a80e1fa2b1e",
                "cardExpirationMonthYearNumber": "02/2025",
                "last4CardNumber": "0919",
                "accountStatus": "ACTIVE",
                "cardType": "DI",
                "firstName": "John",
                "lastName": "Doe",
                "addressIdentifier": "f99a1ecd-b177-4c3d-a99b-c72e132b260g"
            }
        ]
    },
    "addresses": [
        {
            "addressIdentifier": "8d452494-ec75-4ef9-9b45-e4bd7debf6a0",
            "firstName": "John",
            "lastName": "Doe",
            "consumerAssignedAddressName": "Work",
            "primaryAddressIndicator": true,
            "addressType": "SHIPPING",
            "line1": "200 Elton Farm",
            "line2": "Apt 123",
            "city": "Glen Mills",
            "state": "PA",
            "postalCode": "19342",
            "countryCode": "USA",
            "addressStatus": "ACTIVE"
        },
        {
            "addressIdentifier": "e17a1ecd-b177-4c3d-a99b-c72e132b260f",
            "firstName": "John",
            "lastName": "Doe",
            "consumerAssignedAddressName": "Work2",
            "primaryAddressIndicator": true,
            "addressType": "SHIPPING",
            "line1": "400 Elton Farm",
            "line2": "Apt 123",
            "city": "Glen Mills",
            "state": "PA",
            "postalCode": "19342",
            "countryCode": "USA",
            "addressStatus": "ACTIVE"
        },
        {
            "addressIdentifier": "f99a1ecd-b177-4c3d-a99b-c72e132b260g",
            "firstName": "John",
            "lastName": "Doe",
            "consumerAssignedAddressName": "Work",
            "primaryAddressIndicator": true,
            "addressType": "BILLING",
            "line1": "300 Elton Street",
            "line2": "Apt 123",
            "city": "Glen Mills",
            "state": "PA",
            "postalCode": "19342",
            "countryCode": "USA",
            "addressStatus": "ACTIVE"
        }
    ],
    "correlationIdentifier": "648ccc37-e006-45ee-a127-2718bffeadad",
    "createTimestamp": "2021-08-23T00:23:05.353Z",
    "createUserIdentifier": "jack",
    "updateTimestamp": "2024-07-02T11:37:22.303Z",
    "updateUserIdentifier": "jack",
    "profileStatus": "ACTIVE"
}

Set the default payment method

You can set the default payment method for a consumer profile by sending a PATCH request to the /consumer-profiles/{consumer-profile-id}/payment-methods/{payment-method-Id}/default endpoint.

Method: PATCH

Endpoint: /consumer-profiles/PACJGQ/payment-methods/63aaba29-4857-494a-82bc-2a80e1fa2b1e/default

Scenario: Setting the payment method with payment-method-Id = 63aaba29-4857-494a-82bc-2a80e1fa2b1e as the default payment method for the consumer-profile-id = PACJGQ

Json
{
    "consumerProfileId": "PACJGQ",
    "cardOnFileReferenceNumber": "123",
    "firstName": "John",
    "lastName": "Doe",
    "communication": {
        "phoneList": [
            {
                "phoneNumber": "8888888828",
                "countryCode": "1",
                "phoneNumberType": "Home",
                "communicationIdentifier": "HH04423498968"
            }
        ],
        "emailList": [
            {
                "emailAddress": "john.doe.x@gmail.com",
                "emailAddressType": "Home",
                "communicationIdentifier": "EE8141240230923"
            }
        ]
    },
    "paymentMethodType": {
        "cardList": [
            {
                "paymentMethodId": "77ccba29-4857-494a-82bc-2a80e1fa2b9d",
                "cardExpirationMonthYearNumber": "01/2025",
                "last4CardNumber": "9999",
                "accountStatus": "ACTIVE",
                "cardType": "MC",
                "firstName": "John",
                "lastName": "Doe",
                "addressIdentifier": "8d452494-ec75-4ef9-9b45-e4bd7debf6a0"
            },
            {
                "paymentMethodId": "63aaba29-4857-494a-82bc-2a80e1fa2b1e",
                "cardExpirationMonthYearNumber": "02/2025",
                "last4CardNumber": "0919",
                "accountStatus": "ACTIVE",
                "cardType": "DI",
                "firstName": "John",
                "lastName": "Doe",
                "addressIdentifier": "f99a1ecd-b177-4c3d-a99b-c72e132b260g"
            }
        ],
        "defaultMOP": {
            "card": {
                "paymentMethodId": "63aaba29-4857-494a-82bc-2a80e1fa2b1e",
                "cardExpirationMonthYearNumber": "02/2025",
                "last4CardNumber": "0919",
                "accountStatus": "ACTIVE",
                "cardType": "DI",
                "firstName": "John",
                "lastName": "Doe",
                "addressIdentifier": "f99a1ecd-b177-4c3d-a99b-c72e132b260g"
            }
        }
    },
    "addresses": [
        {
            "addressIdentifier": "8d452494-ec75-4ef9-9b45-e4bd7debf6a0",
            "firstName": "John",
            "lastName": "Doe",
            "consumerAssignedAddressName": "Work",
            "primaryAddressIndicator": true,
            "addressType": "SHIPPING",
            "line1": "200 Elton Farm",
            "line2": "Apt 123",
            "city": "Glen Mills",
            "state": "PA",
            "postalCode": "19342",
            "countryCode": "USA",
            "addressStatus": "ACTIVE"
        },
        {
            "addressIdentifier": "f99a1ecd-b177-4c3d-a99b-c72e132b260g",
            "firstName": "John",
            "lastName": "Doe",
            "consumerAssignedAddressName": "Work2",
            "primaryAddressIndicator": true,
            "addressType": "SHIPPING",
            "line1": "400 Elton Farm",
            "line2": "Apt 123",
            "city": "Glen Mills",
            "state": "PA",
            "postalCode": "19342",
            "countryCode": "USA",
            "addressStatus": "ACTIVE"
        }
    ],
    "correlationIdentifier": "648ccc37-e006-45ee-a127-2718bffeadad",
    "createTimestamp": "2021-08-23T00:23:05.353Z",
    "createUserIdentifier": "jack",
    "updateTimestamp": "2024-07-02T11:44:52.219Z",
    "updateUserIdentifier": "jack",
    "profileStatus": "ACTIVE"
}

Delete a payment method

You can delete a payment method from a consumer profile by sending a DELETE request to the /consumer-profiles/{consumer-profile-id}/payment-methods/{payment-method-Id} endpoint.

Note

You cannot delete the default payment method of a consumer profile.

Method: DELETE

Endpoint: /consumer-profiles/PACJGQ/payment-methods/77ccba29-4857-494a-82bc-2a80e1fa2b9d

Scenario: Deleting the payment method with payment-method-Id = 77ccba29-4857-494a-82bc-2a80e1fa2b9d from the consumer profile with consumer-profile-id = PACJGQ

Json
{
    "consumerProfileId": "PACJGQ",
    "cardOnFileReferenceNumber": "123",
    "firstName": "John",
    "lastName": "Doe",
    "communication": {
        "phoneList": [
            {
                "phoneNumber": "8888888828",
                "countryCode": "1",
                "phoneNumberType": "Home",
                "communicationIdentifier": "HH04423498968"
            }
        ],
        "emailList": [
            {
                "emailAddress": "john.doe.x@gmail.com",
                "emailAddressType": "Home",
                "communicationIdentifier": "EE8141240230923"
            }
        ]
    },
    "paymentMethodType": {
        "cardList": [
            {
                "paymentMethodId": "63aaba29-4857-494a-82bc-2a80e1fa2b1e",
                "cardExpirationMonthYearNumber": "02/2025",
                "last4CardNumber": "0919",
                "accountStatus": "ACTIVE",
                "cardType": "DI",
                "firstName": "John",
                "lastName": "Doe",
                "addressIdentifier": "f99a1ecd-b177-4c3d-a99b-c72e132b260g"
            }
        ],
        "defaultMOP": {
            "card": {
                "paymentMethodId": "63aaba29-4857-494a-82bc-2a80e1fa2b1e",
                "cardExpirationMonthYearNumber": "02/2025",
                "last4CardNumber": "0919",
                "accountStatus": "ACTIVE",
                "cardType": "DI",
                "firstName": "John",
                "lastName": "Doe",
                "addressIdentifier": "f99a1ecd-b177-4c3d-a99b-c72e132b260g"
            }
        }
    },
    "addresses": [
        {
            "addressIdentifier": "8d452494-ec75-4ef9-9b45-e4bd7debf6a0",
            "firstName": "John",
            "lastName": "Doe",
            "consumerAssignedAddressName": "Work",
            "primaryAddressIndicator": true,
            "addressType": "SHIPPING",
            "line1": "200 Elton Farm",
            "line2": "Apt 123",
            "city": "Glen Mills",
            "state": "PA",
            "postalCode": "19342",
            "countryCode": "USA",
            "addressStatus": "ACTIVE"
        },
        {
            "addressIdentifier": "f99a1ecd-b177-4c3d-a99b-c72e132b260g",
            "firstName": "John",
            "lastName": "Doe",
            "consumerAssignedAddressName": "Work2",
            "primaryAddressIndicator": true,
            "addressType": "SHIPPING",
            "line1": "400 Elton Farm",
            "line2": "Apt 123",
            "city": "Glen Mills",
            "state": "PA",
            "postalCode": "19342",
            "countryCode": "USA",
            "addressStatus": "ACTIVE"
        }
    ],
    "correlationIdentifier": "648ccc37-e006-45ee-a127-2718bffeadad",
    "createTimestamp": "2021-08-23T00:23:05.353Z",
    "createUserIdentifier": "jack",
    "updateTimestamp": "2024-07-02T11:53:51.529Z",
    "updateUserIdentifier": "jack",
    "profileStatus": "ACTIVE"
}

Retrieve the 3D Secure status of a payment method

You can retrieve the 3DS authentication status of a payment menthod on a consumer profile by sending a GET request to the/consumer-profiles/{consumer-profile-id}/payment-methods/{payment-method-Id}/status endpoint.

Method: GET

Endpoint: /consumer-profiles/PACJGQ/payment-methods/6d66f2e5-ad81-4848-9884-d5ff32ee7690/status

Scenario: Retrieving the 3DS authentication status of a payment method with payment-method-Id = 6d66f2e5-ad81-4848-9884-d5ff32ee7690 for the consumer profile with consumer-profile-id = PACJGQ

Json
{
  "requestId": "85b42b15-7f87-45a5-a972-65037acdcf18",
  "consumerProfileId": "PACJGQ",
  "responseMessage": "Request Accepted",
  "cardAuthenticationDetails": {
    "transactionIdentifier": "0eec7ed4-3ecc-4c5c-952e-57a3fbfa5727",
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Request Accepted",
    "hostMessage": "Success",
    "transactionDate": "2025-08-14T10:43:52.100Z",
    "authenticationId": "3aeebeed-1c22-4c32-ae63-5c537c3cbaa2"
  }
}