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,}

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

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

Error object

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.

{
    "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.

{
    "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