Making Payments

Topics

This section describes how to use prepaid and postpaid payment instruments to make purchases. Do not confuse this with funding the prepaid instrument (using FundPrepaid) or paying off the debt (using SettleDebt) accumulated in a postpaid token. This section uses a Pay request along with parameter values returned in the prepaid or postpaid Co-Branded service responses to make purchases.

Transacting the Payment

The sender uses the CBUI to create prepaid or postpaid payment tokens. In this process, the sender authorizes the use of the tokens to pay for items given the restrictions placed upon the use of the token in the Co-Branded service request.

The prepaid response includes prepaidSenderTokenID and the postpaid response includes creditSenderTokenID. You use these values for SenderTokenId in Pay requests.

Payment Transaction Process Using the Pay Action

Submit a Pay request similar to the following.

https://fps.amazonaws.com/?
  Action=Pay&
  AWSAccessKeyId=0656Example83G2&
  SignatureVersion=1&
  Timestamp=2008-08-06T13%3A00%3A01Z&
  SenderTokenId=254656Example83987&
  CallerReference=29834WSDF29384&
  TransactionAmount=1200&
  Version=2008-09-17&
  Signature=[URL-encoded signature value]

The required parameters include the following:

SenderTokenId, which for prepaid maps to the prepaidSenderTokenID or for postpaid maps to creditSenderTokenID. You stored these token IDs when they were returned in the Co-Branded service response.
TransactionAmount
CallerReference, which is a value the you supply to uniquely identify the Pay transaction. See Important Values to Store in Your Database.

For prepaid payment tokens, the prepaid instrument is the payment instrument, and for postpaid payment tokens, the postpaid credit instrument is the payment instrument.

Parse the response.

Two important values the Pay request returns are TransactionStatus, which tells whether the charge was successful against the sender's payment instrument, and TransactionId, which is the identifier Amazon Payments uses to identify this transaction. You should maintain the TransactionId in your database and associate it with your CallerReference value for the transaction.

Failed Payment Transactions

There can be times when Amazon Payments charges a sender's payment instrument and that transaction fails. There are two kinds of failure:

Failure—A transaction is canceled for non-payment reasons.
For example, a transaction might be considered fraudulent and is therefore refused.
Hard decline—A financial institution refuses the transaction.
This could happen when a credit card has exceeded its maximum limit or when a credit card has expired. There is no retry after a hard decline.

You do not need to take any action in either of these cases. In the case of a failed transaction, Amazon Payments e-mails the sender and you about the transaction decline.

Repeated Pay Requests

Due to network problems, some Pay requests might not complete successfully. If this happens, it might be possible to recapture the information and resend the request. For more information, see Resending Requests.

Modifying the Payment Instrument

It is possible that before a postpaid payment token expires, the sender must change the payment instrument used to pay the debt. This might happen, for example, when a credit card expires or is otherwise terminated. To handle this issue, you must enable the sender to change the payment instrument for an ongoing payment token. You do that by sending an Edit Token Co-Branded service request, as follows.

Modifying a Payment Instrument

1	On your web site, enable senders to discover the postpaid payment token they need to modify.
2	Use the input to construct a Co-Branded service request that uses the Edit Payment Token Co-Branded service API. You include the new payment instrument information in the `paymentMethod` parameter. For more information about creating a Co-Branded service request, see Getting Authorization. Make sure to use the Edit Token API.
3	Create a button with a label such as Change Payment Method and attach code to the button that issues the Co-Branded service request.
4	Parse the returned URI. In addition to the URL specified by `returnURL`, the URI contains parameters added by the CBUI. Those parameters include `status`, which tells you whether the sender successfully modified the payment instrument. Part of the job of parsing the URI is evaluating the `signature` parameter to make sure the response has not been altered. For more information, see Handling Signatures in Responses.
5	Display an appropriate web page to the sender based on the value of the `status` parameter.

Notifications

To be notified of the status of the transaction, you must host a script that receives Instant Payment Notification (IPN) updates. For more information, see Instant Payment Notification.