AWS Documentation » Amazon Flexible Payments Service » Advanced Quick Start » Co-Branded Service API Reference » Multi-Use Token API	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

Multi-Use Token API

The multi-use token API creates a token that makes multiple payments without the sender having to repeatedly authorize payments. The payments can occur at any time; they don't have to be on a regularly recurring basis. This token works like a voucher and the parameters you include in the request govern the token's use, such as how much the token can pay per transaction, how much it can pay during its lifetime, when it expires, what kind of personal payment instruments it can accept, and the minimum payment it can make.

You can specify a maximum amount that can be charged over a period of time. Set usageLimitType1 to Amount, and then use usageLimitPeriod1 and usageLimitValue1 to set the time period and maximum amount.

You can also specify a maximum number of charges that can occur over a period of time. Set usageLimitType2 to Count, and then use usageLimitPeriod2 and usageLimitValue2 to set the time period and maximum number of charges.

Request Parameters

Parameter	Description	Required
`addressName` `addressLine1` `addressLine2` `city` `state` `country` `zip` `phoneNumber`	The sender's shipping address. You might choose to collect the address on your website and pass it to the CBUI. If you choose to collect the shipping address yourself, you can use these parameters to specify it. This address will be displayed to the sender on the payment authorization confirmation page. See also the description of `collectShippingAddress`. Type: String Default: None	No
`amountType`	Specifies whether the amount specified by `transactionAmount` is the exact amount allowed by the token, the minimum amount, or the maximum amount. Type: String Default: `Exact` Valid Values: `Exact` \| `Maximum` \| `Minimum`	No
`callerReference`	A value you provide that uniquely identifies the request. For more information, see Important Values to Store in Your Database. Type: String Default: None Constraint: Max size = 128 bytes	Yes
`collectShippingAddress`	If you set this value to `True`, all the shipping address parameters (`addressName`, `addressLine1`, etc.) are ignored, and the shipping/mailing address that the sender confirms on the CBUI pages is returned as part of the return URL. Type: Boolean Default: `False` Valid Values: `True` \| `False`	No
`currencyCode`	Specifies the currency of all amounts that this pipeline accepts. Type: String Default: `USD` Valid Values: `USD`	No
`globalAmountLimit`	Specifies the maximum amount of money this token can be used for across all payments. Type: String	Yes
`isRecipientCobranding`	This parameter is for marketplace applications where the caller is different from the recipient. If this value is set to `True`, then the co-branding URL is picked up from the recipient's settings. The parameter `recipientToken` is mandatory if this value is set to `True`. If this value is `False`, the co-branding URL is picked up from the caller's setting. Type: Boolean Valid Values: `True` \| `False` Default: `False`	No
`paymentMethod`	Specifies payment methods the recipient supports. Use `CC` for credit cards, `ACH` for bank account withdrawal, and `ABT` for Amazon Payments balance transfer. Type: Comma-separated list Default: `ABT` Valid Values: `CC` \| `ACH` \| `ABT`	No
`paymentReason`	Specifies the reason for this payment transaction. You can provide a limited set of HTML tags to format your text, including <b>, <i>, <u>, <ul>, <li>, <br>, <em>, <strong>, and <strike>. Other tags are ignored. Type: String	No
`recipientTokenList`	Specifies a comma-separated list of recipient token IDs (for the merchants who can receive payment with this token). If you create a merchant token list, you must include the recipient token ID for the caller in addition to any other tokens you add to the list. Type: String Default: Caller's recipient token ID Conditional: Required if `isRecipientCobranding` is True	Conditional
`transactionAmount`	Specifies the amount payable in this transaction. Type: Double Condition: Required if you have specified `amountType`.	Conditional
`usageLimitType1`	See the description at the beginning of this topic for how to use this field. Type: String Valid Values: `Amount` \| `Count`	No
`usageLimitPeriod1`	If you specify `usageLimitType1` but not `usageLimitPeriod1`, the usage period is forever. This parameter accepts an integer followed by one of the following strings: Hour[s] (e.g., `12 Hours`) Day[s] (e.g., `4 Days`) Month[s] (e.g., `6 Months`) Type: String Default: Forever	No
`usageLimitValue1`	Corresponds to the value for the parameter specified by `usageLimitType1`. Type: String if `usageLimitType1`=`Amount`; integer if `usageLimitType1`=`Count` Condition: Required if you specify `usageLimitType1`.	Conditional
`usageLimitType2`	See the description at the beginning of this topic for how to use this field. Type: String Valid Values: `Amount` \| `Count`	No
`usageLimitPeriod2`	If you specify `usageLimitType2` but not `usageLimitPeriod2`, the usage period is forever. This parameter accepts an integer followed by one of the following strings: Hour[s] (e.g., `12 Hours`) Day[s] (e.g., `4 Days`) Month[s] (e.g., `6 Months`) Type: String Default: Forever	No
`usageLimitValue2`	Corresponds to the value for the parameter specified by `usageLimitType2`. Type: String if `usageLimitType2`=`Amount`; integer if `usageLimitType2`=`Count` Condition: Required if you specify `usageLimitType2`.	Conditional
`validityExpiry`	Specifies when the token expires. Use UNIX epoch date format. Type: Date Default: If a value is not provided for this parameter, the expiration defaults to one year. Constraint: Date cannot be earlier than the current date	No
`validityStart`	Specifies when the token becomes valid. Use UNIX epoch date format. Type: Date Default: The current date Constraint: The validity start date should be within one year from the current date. The date cannot be beyond one year or earlier than the current date.	No

The request also uses the parameters common to all Co-Branded service API requests. For more information, see Common Parameters.

Response Parameters

Parameter	Description
`addressName` `addressLine1` `addressLine2` `city` `state` `zip` `phoneNumber`	The sender's shipping address. These parameters are returned only if `collectShippingAddress` was set to `True` in the request. Type: String
`errorMessage`	This is text in a human readable form that specifies the reason for a request failure. Type: String (LOB, Large Object)
`expiry`	Specifies the expiry (if any) of the payment method. Type: String Size: 20 Bytes
`status`	The status of the Co-Branded service request. Type: String Valid Values: See Status Codes. Size: 2 Bytes
`tokenID`	Specifies the token ID string associated with the token just created (installed). Type: String Size: 65 Bytes
`warningCode`	There might be cases when the sender token is installed successfully but there is an associated warning. This parameter denotes that warning. Type: String Valid Values: `invalidShippingAddress` (returned when you pass an incorrect shipping address in the request parameters `addressLine1`, `addressLine2`, `city`, etc.) Size: 64 Bytes
`warningMessage`	Specifies a human readable text that explains the warning corresponding to the `warningCode`. Type: String (LOB, Large Object)

Responses also include parameters common to all responses. For more information, see Response Parameters.

Status Codes

Status Code	Description
SA	Success status for the ABT payment method.
SB	Success status for the ACH (bank account) payment method.
SC	Success status for the credit card payment method.
SE	System error.
A	Buyer abandoned the pipeline.
CE	Specifies a caller exception.
PE	Payment Method Mismatch Error: Specifies that the buyer does not have the payment method you requested.
NP	There are several cases where the NP status is returned: The payment instruction installation was not allowed on the sender's account, because the sender's email account is not verified The sender and the recipient are the same The recipient account is a personal account, and therefore cannot accept credit card payments A user error occurred because the pipeline was cancelled and then restarted The account associated with one of the recipient tokens you specified is closed
NM	You are not registered as a third-party caller to make this transaction. Contact Amazon Payments for more information.

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...