PayPal CreateBillingAgreement

Overview

The Create Billing Agreement call is performed after the user confirms the billing agreement and accepts the terms and condition on PayPal's site. The response includes a Billing Agreement Id, which is used in the DoReference call to place recurring orders. The Billing Agreement Id is valid for 2 years.

URI Summary

Action	URI Template	URI Example	Non-URI Request	Response
POST	/vM.m/stores/[StoreId]/payments/ paypal/createBillingAgreement.[format]	/v1.0/stores/AStoreId/payments/ paypal/createBillingAgreement.xml	XML	200 + XML Response containing PayPal Billing Agreement Id

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
Token	Yes	The timestamped token value that was returned by PayPalSetExpressCheckoutReply.	String	Generated by PayPal
CurrencyCode	Yes	Currency used.	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 globally identifies a request message and is used to protect against duplicate request processing.	String	40 Characters

Request Example

The request is a PayPalCreateBillingAgreementRequest message.

<?xml version="1.0" encoding="UTF-8"?>
<PayPalCreateBillingAgreementRequest 
      xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567890">
  <OrderId>123456789</OrderId>
  <Token>EC-3NL47026L2991115Y</Token>
  <CurrencyCode>USD</CurrencyCode>
  <SchemaVersion>1.1</SchemaVersion>
</PayPalCreateBillingAgreementRequest>

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
BillingAgreementID	Yes	Billing Agreement Id for recurring payment.	String	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 PayPalCreateBillingAgreementReply message.

<?xml version="1.0" encoding="UTF-8"?>
<PayPalCreateBillingAgreementReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <ResponseCode>Success</ResponseCode>
  <BillingAgreementID>B-6D293734CP434905R</BillingAgreementID>
</PayPalCreateBillingAgreementReply>

Failure Response Example

The response is a PayPalCreateBillingAgreementReply 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 Token.</ErrorMessage>
    <ShortErrorMessage>Cannot find Token.</ShortErrorMessage>
    <ErrorCode>1234</ErrorCode>
</PayPalCreateBillingAgreementReply>

Timeout Response Example

The response is a XmlFaultReply message.

<?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>SocketTimeoutException</payment:Code>
  <payment:Description>Read timed out</payment:Description>
</XmlFaultReply>