Update Payment Tender

Overview

The Update Payment Tender call updates a customer's existing payment tender with the provided information. Only information specifically provided is updated. Information not specified remains unchanged.

When the call is successful, a response code of success is returned. An error is returned if the referenced wallet or tender is unknown. Detailed information about other errors is provided in the error response.

For an overview of payment wallet workflows, see Payment Wallet.

URI Summary

Action	URI Template	Non-URI Request	Response
POST	/api/user/payment_tender/update	JSON	200 + JSON response

Request Elements

The request is an UpdatePaymentTenderRequest JSON object.

Element	Required	Description	Type/Restriction
UpdatePaymentTenderRequest	Required	Update a specified payment tender.	Object
requestId		RequestId is used to uniquely identify a request, including as part of idempotent duplicate request processing. The value must be unique. It is recommended to use a variant 4 UUID for the request ID. The same request ID should only be reused if a read timeout occurs when attempting to receive a response from the wallet service, or the wallet service responds with a system error. In all other cases a new request ID must be sent for retried requests.	String
paymentTenderReference	Required	A reference to a specific payment tender in a wallet on which to perform an operation.	PaymentTenderReference object
paymentTender	Required	Information to be updated within the payment tender. Only information specified will be updated. At least one of the fields must be provided.	UpdatedPaymentTender object

PaymentTenderReference object

Element	Required	Description	Type/Restriction
paymentTenderReference	Required	A reference to a specific payment tender in a wallet on which to perform an operation.	PaymentTenderReference object
walletReference	Required	A reference to a specific wallet on which to perform an operation.	WalletReference object
paymentTenderId	Required	The unique identifier for the payment tender returned when it was created. Example: 123456789000	String. Pattern: [1-9][0-9]{0,37}

WalletReference object

Element	Required	Description	Type/Restriction
WalletReference	Required	A reference to a specific wallet on which to perform an operation.	WalletReference object
walletId	Required	Radial-generated identifier, unique across all wallet identifiers. Example: 123456789000	String, 0 to 37 characters. Pattern: [1-9][0-9]{0,37}
storeId	Required	Radial-assigned store ID. Example: TMSUS	String
customerId	Required	The store's unique identifier for a single customer. This value is assigned by the store and may be an email address, UUID, or any other non-empty value. Example: 7f7b5670-9794-4943-8bf3-d26a4f7284b0	String

UpdatedPaymentTender object

Element	Required	Description	Type/Restriction
UpdatedPaymentTender	Required	Information to be updated within the payment tender. Only information specified will be updated. At least one of the fields must be provided.	UpdatedPaymentTender object
billingContactInformation		Information describing a person that can be contacted. At least one of name, email address, or phone number must be specified. See usages for further requirements.	ContactInformation object
billingAddress		The billing address associated with the payment tender.	Address object
defaultTender		If this tender is the default tender for the wallet.	boolean
subscriptionTender		If this tender is the tender used for subscriptions in the wallet.	boolean
creditCardData	Required for credit card tenders	Additional information required for credit card tender types (for example, tender codes VC, AM)	CreditCardData object

ContactInformation object

Element	Required	Description	Type/Restriction
ContactInformation		Information describing a person that can be contacted. At least one of name, email address, or phone number must be specified. See usages for further requirements.	ContactInformation object
name		The name of a person. At least one of first or last is required. See usage for further requirements.	Name object
emailAddress		Email address of the end user.	String
phoneNumber		Phone number of the end user. Must be only digits.	String, 4-16 characters. Pattern: [0-9]{4,16}

Name object

Element	Required	Description	Type/Restriction
Name		The name of a person. At least one of first or last is required. See usage for further requirements.	Name object
first		First name of the person.	String, 1 to 62 characters
first		Last name of the person.	String, 1 to 62 characters

Address object

Element	Required	Description	Type/Restriction
Address		The billing address associated with the payment tender.	Address object
line1			String, 1 to 126 characters
line2			String, 1 to 126 characters
line3			String, 1 to 126 characters
line4			String, 1 to 126 characters
city			String, 1 to 93 characters
mainDivisionCode			String, 2-5 characters. Pattern: [A-Z]{2,5}
countryCode			String, 2 characters. Pattern: [A-Z]{2,2}
postalCode			String, 3-15 characters. Pattern: [a-zA-Z0-9 \-]{3,15}

CreditCardData object

Element	Required	Description	Type/Restriction
CreditCardData	Required for credit card tenders	Additional information required for credit card tender types (for example, tender codes VC, AM)	CreditCardData object
expirationDate	Required for credit card tenders	Expiration date of the card in the format YYYY-MM	String, date-time format

Request Examples

Update All Data

Request to update the information for a payment tender for all acceptable fields.

{
   "requestId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0",
   "paymentTenderReference": {
      "walletReference": {
         "walletId": "123456789000",
         "storeId": "TMSUS",
         "customerId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0"
      },
      "paymentTenderId": "123456789000"
   },
   "paymentTender": {
      "billingContactInformation": {
         "name": {
            "first": "john",
            "last": "smith"
         },
         "emailAddress": "john_smith@radial.com",
         "phoneNumber": "4845551234"
      },
      "billingAddress": {
         "line1": "935 First Ave",
         "line2": "line 2",
         "line3": "line 3",
         "line4": "line 4",
         "city": "King of Prussia",
         "mainDivisionCode": "PA",
         "countryCode": "US",
         "postalCode": "19406"
      },
      "defaultTender": true,
      "subscriptionTender": true,
      "creditCardData": {
         "expirationDate": "2053-08"
      }
   }
}

Update Billing Address

Request to update the billing address for a payment tender.

{
   "requestId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0",
   "paymentTenderReference": {
      "walletReference": {
         "walletId": "123456789000",
         "storeId": "TMSUS",
         "customerId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0"
      },
      "paymentTenderId": "123456789000"
   },
   "paymentTender": {
      "billingAddress": {
         "line1": "123 Main St.",
         "line2": "Apartment 4",
         "city": "King of Prussia",
         "mainDivisionCode": "PA",
         "countryCode": "US",
         "postalCode": "19406"
      }
   }
}

Update Credit Card Expiration Date

Request to update the credit card expiration date for a payment tender.

{
   "requestId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0",
   "paymentTenderReference": {
      "walletReference": {
         "walletId": "123456789000",
         "storeId": "TMSUS",
         "customerId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0"
      },
      "paymentTenderId": "123456789000"
   },
   "paymentTender": {
      "creditCardData": {
         "expirationDate": "2053-08"
      }
   }
}

Set Payment Tender As Default

Request to set a payment tender as the new default tender for the wallet.

{
   "requestId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0",
   "paymentTenderReference": {
      "walletReference": {
         "walletId": "123456789000",
         "storeId": "TMSUS",
         "customerId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0"
      },
      "paymentTenderId": "123456789000"
   },
   "paymentTender": {
      "defaultTender": true
   }
}

Response Elements

The response is an UpdatePaymentTenderReply JSON object.

Element	Required	Description	Type/Restriction
UpdatePaymentTenderReply	Required		Object
responseCode	Required	If the request was valid, either "success" or "error"	String: success or error
data		The data payload representing the contents of the wallet.	Data object
errors		Information about errors if the request could not be processed. Populated if the response code is "error".	Array of Error objects

Data object

Element	Required	Description	Type/Restriction
data		The data payload representing the contents of the wallet.	Object
walletId		Radial-generated identifier, unique across all wallet identifiers. Example: 123456789000	String
storeId	Required if data element is included	Radial-assigned store ID. Example: TMSUS	String
customerId	Required if data element is included	The store's unique identifier for a single customer. This value is assigned by the store and may be an email address, UUID, or any other non-empty value. Example: 7f7b5670-9794-4943-8bf3-d26a4f7284b0	String
paymentTenders	Required if data element is included	All payment tenders in the wallet or which matched specified filters.	Array of PaymentTender objects

PaymentTender object

Element	Required	Description	Type/Restriction
PaymentTender		Information about a payment tender which is currently stored within a wallet.	Object
paymentTenderId		The unique identifier of the payment tender. Example: 123456789000	String
tenderType		The tender type of the payment tender. Example: VC	String
tenderClass		The tender class to which the tender type belongs. Example: CC	String
token		Token identifying the payment tender. This value is tender-specific, for example, a PAN token for a credit card, or a billing agreement ID for PayPal. Example: 4111Ax8Df5yN1234	String
billingContactInformation		Information describing a person that can be contacted. At least one of name, email address, or phone number must be specified. See usages for further requirements.	ContactInformation object
billingAddress		The billing address associated with the payment tender.	Address object
creditCardData	Required for credit card tenders	Additional information required for credit card tender types (for example, tender codes VC, AM)	CreditCardData object
defaultTender		If this tender is the default tender for the wallet.	boolean
subscriptionTender		If this tender is the tender used for subscriptions in the wallet.	boolean
dateAdded		When this tender was added to the wallet.	String, date-time format
dateUpdated		When the information for this tender was last updated.	String, date-time format

Error object

Element	Optional/Required	Description	Type/Restriction
Error		An error which prevented a request from being processed.	Object
errorCode		A machine-readable error code. Example: SubscriptionNotAllowed	String
errorMessage		A human readable description of the error that occurred. Example: The tenders of class GC may not be used for subscriptions.	String

Response Examples

Success Response

Reply returned when tender has been successfully updated in wallet.

{
    "responseCode" : "success"
}

Error Response

Reply returned when the request could not be processed. This reply will contain one or more errors describing why the request could not be processed.

{
    "responseCode" : "error",
    "errors" : [
        {
            "errorCode" : "TenderDoesNotExist",
            "errorMessage" : "No tender exists with id 123456789000"
        }
    ]
}

Retryable Errors

In case of a timeout during a payment wallet API call, or if a reply is received with a response code of SystemError, the store should retry the transaction until the number of attempts reaches the configured maximum number. The suggested maximum value is 3. If the problem still persists for more than three attempts, please contact Radial support.

Error Codes

Error Code	Description
Unauthorized	A problem exists with the credentials used, contact support immediately.
InvalidRequestData	The request json message of the API is not well formed. Please fix the errors and retry.
UnsetDefaultNotAllowed	A tender may not be changed from default to not default. Instead a different tender must be chosen as the new default tender.
UnsetSubscriptionNotAllowed	A tender may not be changed from subscription to not subscription. Instead a different tender must be chosen as the new subscription tender.
TenderDoesNotExist	The specified tender does not exist for the associated wallet.
WalletDoesNotExist	The specified wallet does not exist for the customer.
InvalidTenderClassData	The tender details supplied does not match with the tender type provided. Correct the request to specify data appropriate for the tender class (e.g. credit cards must include and expiration date)
InvalidTenderType	The tender type supplied should be valid. See the list of supported tender types.
DefaultNotAllowed	The tender cannot be a default tender. The default flag must be set as false or a different eligible tender type must be chosen.
SubscriptionNotAllowed	The tender cannot be a subscription tender. The subscription flag must be set as false or a different eligible tender type must be chosen.