PayPal DoReference

API Description

The DoReference API call should be used by a merchant that previously set up a Billing Agreement Id for recurring payments.

URI Summary

Action URI Template URI Example Non-URI Request Response
POST /vM.m/stores/StoreId/
payments/paypal/doRef.[format]		 /v1.0/stores/AStoreId/
payments/ paypal/doRef.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
BillingAgreementID Yes Billing Agreement Id for recurring payment. String 19 Characters.
Amount Yes Order total amount. Calculated as the sum of LineItemsTotal + ShippingTotal + TaxTotal. 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 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 PayPalDoReferenceTransactionRequest message.

Copy this code sample. 
<?xml version="1.0" encoding="UTF-8"?>
  <PayPalDoReferenceTransactionRequest 
  xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567890">
    <OrderId>123456789</OrderId>
    <Amount currencyCode="USD">50.00</Amount>
    <BillingAgreementID>1234567</BillingAgreementID>
    <SchemaVersion>1.1</SchemaVersion>
  </PayPalDoReferenceTransactionRequest>

Response Elements

Element Required Description Type Restriction
OrderId Yes Order Identifier. String 20 Characters
ResponseCode Yes Response Code returned from Payment Service String Success, Failure
TransactionID No A transaction identification number. String Length: 19 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 PayPalDoReferenceTransactionReply message.

Copy this code sample. 
<?xml version="1.0" encoding="UTF-8"?>
<PayPalCreateBillingAgreementReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <ResponseCode>Success</ResponseCode>
  <TransactionID>O-3A919253XG323924A</TransactionID>
</PayPalCreateBillingAgreementReply>

Failure Response Example

The response is a PayPalDoReferenceTransactionReply message.

Copy this code sample. 
<?xml version="1.0" encoding="UTF-8"?>
<PayPalCreateBillingAgreementReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <ResponseCode>Failure</ResponseCode>
  <ErrorMessage>Cannot find Billing Agreement Id.</ErrorMessage>
  <ShortErrorMessage>Cannot find Billing Agreement Id.</ShortErrorMessage>
  <ErrorCode>1234</ErrorCode>
</PayPalCreateBillingAgreementReply>

Timeout Response Example

The response is a XmlFaultReply message.

Copy this code sample. 
<?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>