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.2 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 The requestId value 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>12345</OrderId>
  <Amount currencyCode="USD">60.00</Amount>
  <SchemaVersion>1.2</SchemaVersion>
</PayPalDoAuthorizationRequest>

Response Elements

Element Required Description Type Restriction
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.2.
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.2.
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.2.

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"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <CreateTimestamp>2018-08-17T17:36:20.482+05:30</CreateTimestamp>
   <Code>SystemProcessingError</Code>
   <Description>A system error has occurred.</Description>
</Fault>