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.

<?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.

<?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.

<?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.

<?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>