Step 1: Making a Co-Branded Service Request

Before you can make a Pay request, you must first create a payment token, which represents the sender's authorization of the payment. You do this by sending a Co-Branded service request. The response contains a sender token ID, which is a reference to the payment token. The following diagram shows the process for the DigitalDownload use case.

On the DigitalDownload web site, the sender (John) selects a song or a video and clicks Buy Now.
DigitalDownload (the caller) sends a Co-Branded service request, which directs John to the Amazon-hosted CBUI web pages.
A sample Co-Branded service request follows this procedure.
John signs in on the CBUI pages with his Amazon Payments login name and password.
The Payment Authorization page displays.
John selects a payment method and clicks the Continue button.
A confirmation page displays the payment details.
John clicks the Continue button after reviewing the details.
Amazon FPS redirects John away from the Amazon-hosted CBUI pages to the URL DigitalDownload specified in the returnURL parameter in the Co-Branded service request.

Example Co-Branded Service Request

The Co-Branded service request is a URL. Following is an example request for the DigitalDownload use case. Note that the endpoint is for the Amazon FPS sandbox.

https://authorize.payments-sandbox.amazon.com/cobranded-ui/actions/start?
callerReference=DigitalDownload1177495829105
&paymentReason=Now and Forever - Richard Marx
&paymentMethod=ABT,ACH,CC
&transactionAmount=0.90
&accessKey=weoiw8example45ow7e
&awsSignature=weoir2098523exampler2oi340w098e1
&pipelineName=SingleUse
&returnURL=https://myWebStore.com/return
&version=2009-01-09

The following table describes the parameters in this request.

Parameter	Definition
`callerReference`	A unique value DigitalDownload generated to identify the sender token for future references.
`paymentReason`	Description of this transaction. John can see this on the Payment Authorization page.
`paymentMethod`	Payment methods that DigitalDownload supports. In this case the payment methods include an Amazon Payments account balance, bank transfers, and credit cards.
`transactionAmount`	The total purchase price in USD, including tax and shipping.
`accessKey`	DigitalDownload's AWS Access Key ID.
`awsSignature`	A value Digital Download calculated using a SHA-1 encryption mechanism. For information about how to create the signature, go to the Amazon FPS Basic Quick Start Developer Guide.
`pipelineName`	Name of the particular CBUI authorization pipeline DigitalDownload requested. The value `SingleUse` refers to the pipeline that creates a payment token that is to be used only once. For information about payment tokens that can be used more than once (e.g., for recurring payments), go to the Amazon FPS Advanced Quick Start Developer Guide.
`returnURL`	The destination web site John is redirected to after completing the payment authorization. This is a location on DigitalDownload's site.
`version`	The version of the Co-Branded service API to use. This should always be set to `2009-01-09`.

Generating the Signed Request

The following sample code shows how to generate a Co-Branded service request.

Java

AmazonFPSCBUIUtils cbuiUtils = new AmazonFPSCBUIUtils(accessKeyId, secretAccessKey);

// Setting request parameters 
cbuiUtils.setMandatoryParams("SingleUse", "<Your Return URL>");
cbuiUtils.setCallerReference("<some unique id to identify the request>");
cbuiUtils.setTransactionAmount("<transaction amount>");
cbuiUtils.setPaymentReason("<payment reason>");

// Use this URL to redirect your customer to a co-branded authorization page
String redirectURL = cbuiUtils.getURL();

C#

AmazonFPSCBUIUtils cbuiUtils = new AmazonFPSCBUIUtils(accessKeyId, secretAccessKey);
				
// Setting request parameters 
cbuiUtils.setMandatoryParams("SingleUse", "<Your Return URL>");
cbuiUtils.setCallerReference("<some unique id to identify the request>");
cbuiUtils.setTransactionAmount("<transaction amount>");
cbuiUtils.setPaymentReason("<payment reason>");

// Use this URL to redirect your customer to a Co-Branded authorization page
String redirectURL=cbuiUtils.getURL();

PHP

$cbuiUtils = new Amazon_FPS_CBUIUtils(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY);
				
// Setting request parameters 
$cbuiUtils->setMandatoryParams("SingleUse", "<Your Return URL>");
$cbuiUtils->setCallerReference("<some unique id to identify the request>");
$cbuiUtils->setTransactionAmount("<transaction amount>");
$cbuiUtils->setPaymentReason("<payment reason>");

// Use this URL to redirect your customer to a Co-Branded authorization page
String redirectURL = $cbuiUtils->getURL();

Validating the Co-Branded Service Response

After you send a Co-Branded service request, the service redirects the buyer to the web page you specified in the returnURL request parameter. The Co-Branded service appends parameters to that URL to give you information about the status of the request. One of the parameters is a signature, which you should validate to confirm the request came from the Co-Branded service. The following code snippets parse the URL and validate the signature.

	Note
	The response you receive is URL encoded. The `validateQueryString` function in the following code snippets decodes the name-value pairs in the response before validating the signature.

Java

// the returnedQueryString below is a URL you host; it is appended with response parameters
String returnedQueryString = "< Query string received in Co-Branded service response>";

// parse the query string to get the returned name value pairs in map
String[] params = returnedQueryString.split("&");
Map map = new HashMap();
for (String param : params) {
String name = param.split("=")[0];
String value = param.split("=")[1];
map.put(name, value);
}

String signature = (String)map.get(“signature”);

// sender token ID will be used later in a 'Pay' API request that initiates payment
String senderTokenID = (String)map.get("tokenID");

AmazonFPSCBUIUtils cbuiUtils = new AmazonFPSCBUIUtils(accessKeyId, secretAccessKey);

// invoke your error handling code if the signature does not match
boolean signatureMatched = cbuiUtils.validateQueryString(returnedQueryString, signature);

C#

// the returnedQueryString below is a URL you host; it is appended with response parameters
String returnedQueryString = "< Query string received in Co-Branded service response>";

// parse the query string to get the returned (name, value) tuples in pairs 
NameValueCollection pairs = HttpUtility.ParseQueryString(returnedQueryString);

String signature = pairs["signature"];

// sender token ID will be used later in a 'Pay' API request that initiates payment
String senderTokenID = pairs["tokenID"];

AmazonFPSCBUIUtils cbuiUtils = new AmazonFPSCBUIUtils(accessKeyId, secretAccessKey);

// invoke your error handling code if the signature does not match
bool signatureMatched = cbuiUtils.validateQueryString(returnedQueryString, signature);

PHP

// the returnedQueryString below is a URL you host; it is appended with response parameters
$returnedQueryString = "< Query string received in Co-Branded service response >";

// parse the query string to get the return name value pairs in $pairs
parse_str($returnedQueryString, $pairs);

$signature = $pairs["signature"];

// sender token ID will be used later in a 'Pay' API request that initiates payment
$senderTokenID = $pairs["tokenID"];

$cbuiUtils = new Amazon_FPS_CBUIUtils(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY);

// invoke your error handling code if the signature does not match
$signatureMatched = $cbuiUtils->validateQueryString($returnedQueryString, $signature);