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]+". |
| @requestId | Yes | RequestId is used to uniquely identify a request, including as part of idempotent duplicate request processing. The value must be unique. It is recommended to use a variant 4 UUID for the request ID. The same request ID should only be reused if a read timeout occurs when attempting to receive a response from the payment service, or the payment service responds with a fault response. In all other cases a new request ID must be sent for retried requests, including responses such as Fail, Timeout or PaymentProcessorTimeout. | String | 40 Characters |
Request Example
The request is a PayPalDoAuthorizationRequest message.
Copy
<?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
Copy
<?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
Copy
<?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.
Copy
<?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>SystemProcessingError</payment:Code>
<payment:Description>A system error has occurred.</payment:Description>
</XmlFaultReply>