Get Payment Wallet

Overview

The Get Payment Wallet call returns wallet information with a list of all payment tenders that have been saved in the wallet. If filters are specified, then the payment tender list includes only those tenders that match all specified filters.

Errors are returned if the referenced wallet does not exist or the specified filters are an invalid format. 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/wallet/get	JSON	200 + JSON response

Request Elements

The request is a GetWalletRequest JSON object.

Element	Path	Required	Description/Example	Type/Restriction
GetWalletRequest	GetWalletRequest	Required	Get a wallet.	Object
requestId	GetWalletRequest/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
walletReference	GetWalletRequest/walletReference	Required	A reference to a specific wallet on which to perform an operation.	WalletReference object
filters	GetWalletRequest/filters		An optional list of filters. When specified, only details for tenders which match all filters will be returned.	Array of PaymentTenderFilter objects

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

PaymentTenderFilter object

Element	Required	Description	Type/Restriction
PaymentTenderFilter		A filter used to select specific payment tenders within a wallet	Object
type	Required for each PaymentTenderFilter	The type of filter.	String. Any of these values: TenderClass, TenderType, Default, Subscription
value	Required for each PaymentTenderFilter	The value for the filter. For TenderClass and TenderType, use the associated codes e.g. "VC", "CC". For Default and Subscription, the value must be either "true" or "false".	String. Pattern: [a-zA-Z]{1,}

Element

Required

Description

Type/Restriction

PaymentTenderFilter

A filter used to select specific payment tenders within a wallet

Object

type

Required for each PaymentTenderFilter

The type of filter.

String. Any of these values: TenderClass, TenderType, Default, Subscription

value

Required for each PaymentTenderFilter

The value for the filter. For TenderClass and TenderType, use the associated codes e.g. "VC", "CC".

For Default and Subscription, the value must be either "true" or "false".

String. Pattern: [a-zA-Z]{1,}

Response Elements

The response is a GetWalletReply JSON object.

Element	Required	Description	Type/Restriction
GetWalletReply	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

ContactInformation object

Element	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	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	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

Error object

Element	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

Element

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

Returns Wallet information with a list of all active payment tender information. If filters specified then payment tender list will include only those tenders which match with the filter. Otherwise all payment tenders associated to the wallet will be returned.

Copy this code sample.

{
    "responseCode" : "success",
    "data" : {
        "walletId" : "123456789",
        "storeId" : "TMSUS",
        "customerId" : "3b706405-d01d-40a9-b3f3-66f5952c291f",
        "paymentTenders" : [
            {
                "paymentTenderId" : "1111",
                "tenderType" : "VC",
                "tenderClass" : "CC",
                "token" : "8364abcdefgh8356",
                "billingContactInformation" : {
                    "name" : {
                        "first" : "john",
                        "last" : "smith"
                    },
                    "emailAddress" : "john_smith@radial.com",
                    "phoneNumber" : "4845551234"
                },
                "billingAddress" : {
                    "line1" : "935 First Ave",
                    "city" : "King of Prussia",
                    "mainDivisionCode" : "PA",
                    "countryCode" : "US",
                    "postalCode" : "19406"
                },
                "creditCardData" : {
                    "expirationDate" : "2099-01"
                },
                "defaultTender" : false,
                "subscriptionTender" : false,
                "dateAdded" : "2003-08-23T21:35:46Z",
                "dateUpdated" : "2003-08-23T21:35:46Z"
            },
            {
                "paymentTenderId" : "3142",
                "tenderType" : "SP",
                "tenderClass" : "GC",
                "token" : "9151abcd5555",
                "billingContactInformation" : {
                    "name" : {
                        "first" : "john",
                        "last" : "smith"
                    },
                    "emailAddress" : "john_smith@radial.com",
                    "phoneNumber" : "4845551234"
                },
                "billingAddress" : {
                    "line1" : "935 First Ave",
                    "city" : "King of Prussia",
                    "mainDivisionCode" : "PA",
                    "countryCode" : "US",
                    "postalCode" : "19406"
                },
                "defaultTender" : false,
                "subscriptionTender" : false,
                "dateAdded" : "2003-08-23T21:35:46Z",
                "dateUpdated" : "2003-08-23T21:35:46Z"
            }
        ]
    }
}

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.

Copy this code sample.

{
    "responseCode" : "error",
    "errors" : [
        {
            "errorCode" : "WalletDoesNotExist",
            "errorMessage" : "A wallet does not exists for the specified customer id."
        }
    ]
}

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.
WalletDoesNotExist	The specified wallet does not exists for the customer.
InvalidFilterValue	The supplied filter is not valid. Please change the value and try again. Valid TenderType filter values: AM, VC, MC, DC and GS Valid TenderClass filter values: CC, GC Valid Default filter values: true, false Valid Subscription filter values: true, false