This documentation site is retired and will soon be removed. Current information can be found at the new documentation portal here! Please update your bookmarks.
Radial Payments & Fraud Documentation
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>What are you waiting for?