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 The requestId value 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>SystemProcessingError</payment:Code>
  <payment:Description>A system error has occurred.</payment:Description>
</XmlFaultReply>