PayPal DoAuthorization

Overview

DoAuthorization is the last API call in the PayPal checkout flow, and it is used to finally authorize the payment. If the ResponseCode from the DoAuthorization response is Success or SuccessWithWarning then the Order has been placed successfully and the PayPal checkout flow is complete.

URI Summary

Action	URI Template	URI Example	Non-URI Request	Response
POST	/vM.m/stores/[StoreId]/payments/paypal/doAuth.[format]	/v1.0/stores/AStoreId/payments/ paypal/doAuth.xml	XML	200 + XML Response.

Request Elements

Element	Required	Description	Type	Restriction
StoreId	Yes	Store identifier used in the URL.	String	20 Characters
OrderId	Yes	Order identifier.	String	20 Characters
Amount	Yes	The amount to be authorized. This amount must match the amount from the DoExpress call for the same order.	Decimal	2 precision points. (123.34)
currencyCode	Yes	Code identifies the currency for the Amount.	String	IS-4217 three-letter code
SchemaVersion	Yes	Although marked as optional in the the schema, this element needs to be passed at all times with a value of 1.1 or greater in order to receive elements like 'ErrorMessage', ‘ShortErrorMessage’, ‘ErrorCode’ in the Response message.	String	pattern = "([0-9]+\.)*[0-9]+". Value Example: 1.1, 1.2
requestId	Yes	RequestId globally identifies a request message and is used to protect against duplicate request processing.	String	40 Characters

Request Example

The request is a PayPalDoAuthorizationRequest message.

<?xml version="1.0" encoding="UTF-8"?>
<PayPalDoAuthorizationRequest 
    xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="123456">
  <OrderId>1234567</OrderId>
  <Amount currencyCode="USD">150.00</Amount>
  <SchemaVersion>1.1</SchemaVersion>
</PayPalDoAuthorizationRequest>

Response Elements

Element	Required	Description	Type	Restriction
OrderId	Yes	Order Identifier.	String	20 Characters
ResponseCode	Yes	Response code returned from Payment Service	String	3 possible codes: Success, Failure, Timeout.
AuthorizationInfo	No	Details regarding the transaction.	Complex Type	Includes: PaymentStatus, PaymentReason, PaymentCode
PaymentStatus	No	Status of the transaction on PayPal's site.	String	64 Characters
PaymentReason	No	Reason for the transaction's status on PayPal's site.	String	64 Characters
PaymentCode	No	Code associated with the transaction on PayPal's site.	String	64 Characters
ErrorMessage	No	Full Error Description.	String	Present only when the ResponseCode is Failure and SchemaVersion in the Request is equal to or greater than 1.1.
ShortErrorMessage	No	Short Error Description.	String	Present only when the ResponseCode is Failure and SchemaVersion in the Request is equal to or greater than 1.1.
ErrorCode	No	Error code coming from PayPal.	String	Present only when the ResponseCode is Failure and SchemaVersion in the Request is equal to or greater than 1.1.

Successful Response Example

The response is a PayPalDoAuthorizationReply message

<?xml version="1.0" encoding="UTF-8"?>
<PayPalDoAuthorizationReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <ResponseCode>Success</ResponseCode>
  <AuthorizationInfo>
    <PaymentStatus>Pending</PaymentStatus>
    <PendingReason>authorization</PendingReason>
    <ReasonCode>1234</ReasonCode>
  </AuthorizationInfo>
</PayPalDoAuthorizationReply>

Failure Response Example

The response is a PayPalDoAuthorizationReply message

<?xml version="1.0" encoding="UTF-8"?>
<PayPalDoAuthorizationReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <ResponseCode>Failure</ResponseCode>
  <AuthorizationInfo>
    <PaymentStatus>None</PaymentStatus>
    <PendingReason>None</PendingReason>
    <ReasonCode>None</ReasonCode>
  </AuthorizationInfo>
  <ErrorMessage>Cannot find Order.</ErrorMessage>
  <ShortErrorMessage>Cannot find Order.</ShortErrorMessage>
  <ErrorCode>1234</ErrorCode>
</PayPalDoAuthorizationReply>

Timeout Response Example

The response is a XmlFaultReply message.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<XmlFaultReply xmlns="http://schema.gsicommerce.com/payments/services/1.0/"
      xmlns:payment="http://schema.gsicommerce.com/payments/types/1.0/">
  <payment:CreateTimestamp>2012-01-26T17:09:07.046Z</payment:CreateTimestamp>
  <payment:Code>SocketTimeoutException</payment:Code>
  <payment:Description>Read timed out</payment:Description>
</XmlFaultReply>