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]+". |
| @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
<?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
<?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
<?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
<?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>