Create Payment Wallet

Overview

The Create Payment Wallet call creates a new wallet for the specified customer ID.

If a wallet already exists for the specified customer ID, an error is returned; otherwise, a unique ID for the new wallet is returned. The wallet ID must be used in all subsequent payment wallet API requests for that customer's wallet.

For an overview of payment wallet workflows, see Payment Wallet. See a list of supported tender types.

URI Summary

Action

URI Template

Non-URI Request

Response

POST

/api/user/wallet/create

JSON

200 + JSON response

Request Elements

The request is a CreateWalletRequest JSON object.

Element

Required

Description

Type/Restriction

CreateWalletRequest

Required

Create a new wallet.

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

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

Response Elements

The response is a CreateWalletReply JSON object.

Element

Required

Description

Type/Restriction

CreateWalletReply

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

Reply returned when a new wallet has been successfully created.

Copy this code sample. 
{
    "responseCode" : "success",
    "data" : {
        "walletId" : "123456789"
    }
}

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" : "WalletAlreadyExists",
            "errorMessage" : "A wallet already 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.
WalletAlreadyExists A wallet already exists for the customer ID provided. Please lookup in the local system and if the wallet can not be found please contact support.