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. |
|
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. |
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. |
|
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. |
|
billingAddress |
|
The billing address associated with the payment tender. |
|
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) |
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. |
|
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. |
|
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. |
|
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) |
|
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. |