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