Add Payment Tender

Overview

The Add Payment Tender call adds a new payment tender to a customer's existing payment wallet. If this tender is the first tender added to the wallet, and if the tender is supported as a default or subscription tender, the new tender is marked as the default tender and the subscription tender. When the call is successful, the unique ID of the new payment tender is returned. The tender ID should be used for subsequent requests for that tender.

Errors are returned if the referenced wallet does not exist or a tender already exists with the same token and tender type. Tenders must include the required tender-specific data where applicable. Detailed information about other errors is provided in the error response.

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/payment_tender/create	JSON	200 + JSON response

Request Elements

The request is an AddPaymentTenderRequest JSON object.

Element	Required	Description	Type/Restriction
AddPaymentTenderRequest	Required	Add a payment tender to a 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
walletReference	Required	A reference to a specific wallet on which to perform an operation.	WalletReference object
paymentTender	Required	Information for a new payment tender to be added to a wallet.	AddedPaymentTender object

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

AddedPaymentTender object

Element	Required	Description	Type/Restriction
AddedPaymentTender	Required	Information for a new payment tender to be added to a wallet.	AddedPaymentTender object
tenderType	Required	The tender type of the payment tender. Example: VC	String, 2 characters. Pattern: [A-Z]{2,2}
token	Required	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. Pattern: [!-~]{1,64}
ipAddress		IP address (v4 or v6) of the end user. Example: 127.0.0.1	String. Pattern: ((?:(?:25[0-5]\|2[0-4][0-9]\|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]\|2[0-4][0-9]\|[01]?[0-9][0-9]?))\|((?:[A-F0-9]{1,4}:){7}[A-F0-9]{1,4})
deviceFingerprint		Fingerprint of the end user device. Example: 92e92b61-aef4-45e2-868a-51d314e009fd	String. Pattern: [!-~]{1,64}
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

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

Request Examples

Add Credit Card With All Fields

Request to add a new credit card payment tender containing data for all acceptable fields.

Copy this code sample.

{
   "requestId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0",
   "walletReference": {
      "walletId": "123456789000",
      "storeId": "TMSUS",
      "customerId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0"
   },
   "paymentTender": {
      "tenderType": "VC",
      "token": "4111Ax8Df5yN1234",
      "ipAddress": "127.0.0.1",
      "deviceFingerprint": "92e92b61-aef4-45e2-868a-51d314e009fd",
      "billingContactInformation": {
         "name": {
            "first": "john",
            "last": "smith"
         },
         "emailAddress": "john_smith@radial.com",
         "phoneNumber": "4845551234"
      },
      "billingAddress": {
         "line1": "Billing Department",
         "line2": "Radial, Inc",
         "line3": "Suite 123",
         "line4": "935 First Ave",
         "city": "King of Prussia",
         "mainDivisionCode": "PA",
         "countryCode": "US",
         "postalCode": "19406"
      },
      "creditCardData": {
         "expirationDate": "2053-08"
      },
      "defaultTender": true,
      "subscriptionTender": true
   }
}

Add Credit Card With Only Required Fields

Request to add a new credit card payment tender containing data for only required fields.

Copy this code sample.

{
   "requestId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0",
   "walletReference": {
      "walletId": "123456789000",
      "storeId": "TMSUS",
      "customerId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0"
   },
   "paymentTender": {
      "tenderType": "VC",
      "token": "4111Ax8Df5yN1234",
      "ipAddress": "127.0.0.1",
      "deviceFingerprint": "92e92b61-aef4-45e2-868a-51d314e009fd",
      "billingContactInformation": {
         "name": {
            "first": "john",
            "last": "smith"
         },
         "emailAddress": "john_smith@radial.com",
         "phoneNumber": "4845551234"
      },
      "billingAddress": {
         "line1": "935 First Ave",
         "city": "King of Prussia",
         "countryCode": "US",
         "postalCode": "19406"
      },
      "creditCardData": {
         "expirationDate": "2053-08"
      }
   }
}

Add Gift Card With All Fields

Request to add a new gift card payment tender containing data for all acceptable fields.

Copy this code sample.

{
   "requestId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0",
   "walletReference": {
      "walletId": "123456789000",
      "storeId": "TMSUS",
      "customerId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0"
   },
   "paymentTender": {
      "tenderType": "GC",
      "token": "964aHtUw3864",
      "ipAddress": "127.0.0.1",
      "deviceFingerprint": "92e92b61-aef4-45e2-868a-51d314e009fd",
      "billingContactInformation": {
         "name": {
            "first": "john",
            "last": "smith"
         },
         "emailAddress": "john_smith@radial.com",
         "phoneNumber": "4845551234"
      },
      "billingAddress": {
         "line1": "Billing Department",
         "line2": "Radial, Inc",
         "line3": "Suite 123",
         "line4": "935 First Ave",
         "city": "King of Prussia",
         "mainDivisionCode": "PA",
         "countryCode": "US",
         "postalCode": "19406"
      },
      "defaultTender": true,
      "subscriptionTender": true
   }
}

Add Gift Card With Only Required Fields

Request to add a new gift card payment tender containing data for only required fields.

Copy this code sample.

{
   "requestId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0",
   "walletReference": {
      "walletId": "123456789000",
      "storeId": "TMSUS",
      "customerId": "7f7b5670-9794-4943-8bf3-d26a4f7284b0"
   },
   "paymentTender": {
      "tenderType": "GC",
      "token": "964aHtUw3864",
      "ipAddress": "127.0.0.1",
      "deviceFingerprint": "92e92b61-aef4-45e2-868a-51d314e009fd",
      "billingContactInformation": {
         "name": {
            "first": "john",
            "last": "smith"
         },
         "emailAddress": "john_smith@radial.com",
         "phoneNumber": "4845551234"
      },
      "billingAddress": {
         "line1": "935 First Ave",
         "city": "King of Prussia",
         "countryCode": "US",
         "postalCode": "19406"
      }
   }
}

Response Elements

The response is an AddPaymentTenderReply JSON object.

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

Reply returned when a new tender has been successfully added to a wallet.

Copy this code sample.

{
    "responseCode" : "success",
    "data" : {
        "paymentTenderId" : "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" : "PaymentTenderExists",
            "errorMessage" : "A payment tender of type VC with token 4111Ax8Df5yN1234 already exists."
        }
    ]
}

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 exist for the customer.
TenderAlreadyExists	A tender already exists for the customer. Please try again with a different tender or an alternate customer id.
InvalidTenderClassData	The tender details supplied does not match with the tender type provided. Please retry with valid input data
InvalidTenderType	The tender type supplied should be valid. Acceptable tender types are AM, VC, MC, DC and GS
DefaultNotAllowed	The tender cannot be a default tender. If an attempt is being made to set a default tender a different tender must be chosen which is eligibile or the request must be repeated with default tender set as false.
SubscriptionNotAllowed	The tender cannot be a subscription tender. If an attempt is being made to set a subscription tender a different tender must be chosen which is eligible or the request must be repeated with subscription tender set as false.
MaximumTendersExceeded	The maximum number of tenders for the wallet has been exceeded. An existing tender must be removed before a new tender may be added.