APIs for Subscription Purchase With Vault Id
This API call is Initiated by Merchant’s Subscription Engine.
With a merchant initiated subscription transaction the Customer Id and Vault Id are passed in the regular Payment Authorization using Vault Id API, as detailed below.
URI Description
| Action | URI Template | URI Example | Request Content Type | Response Content Type |
|---|---|---|---|---|
| POST | /vM.m/stores/{StoreID}/payments/authorization/create/{tenderType}.json | /v1.0/stores/TMSUS/payments/authorization/create/PY.json | application/json | application/json |
Request Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| createTimestamp | Yes | Timestamp when the request is sent | String | dateTime |
| orderInformation | Yes | Information about the order which is the unique identifier of an order. | ObjectType | |
| orderInformation.orderId | Yes | Unique identifier for an order. | String | Min 3 char Max 40 characters |
| orderInformation.orderId | Yes | Unique identifier for an order. | String | Min 3 char Max 40 characters |
| orderInformation.softDescriptor | Yes | Merchants to pass their soft description to be displayed on the shoppers bank statement, generally business name in short form. | String | Min 1 characters Max 130 characters |
| paymentMethod | Yes | Unique identifier of the payment transaction for the order. | ObjectType | |
| paymentMethod.payPalVaultData | Yes | Payment Information of the PayPal. | ObjectType | |
| paymentMethod.payPalVaultData.id | Yes | PayPal Vault Id is created through the PayPal Vault Id Create With Purchase . | String | Min 4 characters |
| paymentMethod.payPalVaultData.customerId | No | PayPal customer id through the PayPal Vault Id Create With Purchase . | String | Min 4 characters |
| amounts | Yes | Amount value and currency code of the order | ObjectType | |
| amounts.total | Yes | Total amount value and currency code of the order | ObjectType | |
| amounts.total.currencyCode | Yes | The currency of the order amount | ISO 4217 currency code | |
| amounts.total.value | Yes | Total value of the authorization. | Decimal | Min 0.00 Max 9 digits Fraction 2 digits |
| billingInformation | Yes | Represents Billing Information of the order. Contains Shopper's Contact Information and Address. | ObjectType | |
| billingInformation.address | Yes | Represents Shopper's billing address information. | ObjectType | |
| billingInformation.address.line1 | Yes | The line1 components contain the street address. | String | Min 1 character Max 70 characters |
| billingInformation.address.city | Yes | City of the Billing Address. | String | Min 1 character Max 40 characters |
| billingInformation.address.mainDivision | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. | ObjectType | |
| billingInformation.address.mainDivision.code | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. This does not necessarily conform to the ISO 3166-2 code. | String | Min 1 character Max 5 characters |
| billingInformation.address.country | Yes | Two-digit ISO country code conforming to ISO 3166 alpha 2. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 | String | |
| billingInformation.address.postalCode | Yes | Postal code of the Billing Address. | String | Min 1 character Max 35 characters |
| billingInformation.contact | Yes | Represents Shopper's billing contact information. | ObjectType | |
| billingInformation.contact.person | Yes | Represents Shopper billing contact person information. | ObjectType | |
| billingInformation.contact.person.name | Yes | Represents Shopper billing contact person name information. | ObjectType | |
| billingInformation.contact.person.name.firstName | Yes | The first name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| billingInformation.contact.person.name.lastName | Yes | The last name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| billingInformation.contact.emailAddresses | Yes | Email address of the Shopper. | Array of String | Min 3 characters Max 150 characters |
| billingInformation.contact.phoneNumbers | Yes | Shopper phone number used for order follow-up. | Array of String | Min 10 characters Max 40 characters |
| shippingInformation | Yes | Represents Shipping Information of the order. Contains Shopper Contact Information and Address. | ObjectType | |
| shippingInformation.address | Yes | Represents Shopper shipping address information. | ObjectType | |
| shippingInformation.address.line1 | Yes | The line1 components contain the street address. | String | Min 1 character Max 70 characters |
| shippingInformation.address.city | Yes | City of the Shipping Address. | String | Min 1 character Max 40 characters |
| shippingInformation.address.mainDivision | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. | ObjectType | |
| shippingInformation.address.mainDivision.code | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. This does not necessarily conform to the ISO 3166-2 code. | String | Min 1 character Max 5 characters |
| shippingInformation.address.country | Yes | Two-digit ISO country code conforming to ISO 3166 alpha 2. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 | String | |
| shippingInformation.address.postalCode | Yes | Postal code of the Shipping Address. | String | Min 1 character Max 35 characters |
| shippingInformation.contact | Yes | Represents Shopper shippingInformation contact information. | ObjectType | |
| shippingInformation.contact.person | Yes | Represents Shopper shippingInformation contact person information. | ObjectType | |
| shippingInformation.contact.person.name | Yes | Represents Shopper shippingInformation contact person name information. | ObjectType | |
| shippingInformation.contact.person.name.firstName | Yes | The first name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| shippingInformation.contact.person.name.lastName | Yes | The last name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| shippingInformation.contact.emailAddresses | Yes | Email address of the Shopper. | Array of String | Min 3 characters Max 150 characters |
| shippingInformation.contact.phoneNumbers | Yes | Shopper phone number used for order follow-up. | String | Min 10 characters Max 40 characters |
| processingOptions | No | Processing options. | ObjectType | |
| processingOptions.authorizationMode | No | Processing option for the shipment. | Enum | In the subscription purchase with Vault Id use case, set AUTO_CAPTURE. |
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| createTimestamp | Yes | Timestamp when the request is sent | String | dateTime |
| orderInformation | Yes | Information about the order which is the unique identifier of an order. | ObjectType | |
| orderInformation.orderId | Yes | Unique identifier for an order. | String | Min 3 char Max 40 characters |
| orderInformation.softDescriptor | Yes | Merchants to pass their soft description to be displayed on the shoppers bank statement, generally business name in short form. | String | Min 1 characters Max 130 characters |
| paymentMethod | Yes | Unique identifier of the payment transaction for the order. | ObjectType | |
| paymentMethod.payPalVaultData | Yes | Payment Information of the PayPal. | ObjectType | |
| paymentMethod.payPalVaultData.id | Yes | PayPal Vault Id is created through the PayPal Vault Id Create With Purchase . | String | Min 4 characters |
| paymentMethod.payPalVaultData.customerId | No | PayPal customer id through the PayPal Vault Id Create With Purchase . | String | Min 4 characters |
| amounts | Yes | Amount value and currency code of the order | ObjectType | |
| amounts.total | Yes | Total amount value and currency code of the order | ObjectType | |
| amounts.total.currencyCode | Yes | The currency of the order amount | ISO 4217 currency code | |
| amounts.total.value | Yes | Total value of the authorization. | Decimal | Min 0.00 Max 9 digits Fraction 2 digits |
| billingInformation | Yes | Represents Billing Information of the order. Contains Shopper's Contact Information and Address. | ObjectType | |
| billingInformation.address | Yes | Represents Shopper's billing address information. | ObjectType | |
| billingInformation.address.line1 | Yes | The line1 components contain the street address. | String | Min 1 character Max 70 characters |
| billingInformation.address.city | Yes | City of the Billing Address. | String | Min 1 character Max 40 characters |
| billingInformation.address.mainDivision | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. | ObjectType | |
| billingInformation.address.mainDivision.code | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. This does not necessarily conform to the ISO 3166-2 code. | String | Min 1 character Max 5 characters |
| billingInformation.address.country | Yes | Two-digit ISO country code conforming to ISO 3166 alpha 2. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 | String | |
| billingInformation.address.postalCode | Yes | Postal code of the Billing Address. | String | Min 1 character Max 35 characters |
| billingInformation.contact | Yes | Represents Shopper's billing contact information. | ObjectType | |
| billingInformation.contact.person | Yes | Represents Shopper billing contact person information. | ObjectType | |
| billingInformation.contact.person.name | Yes | Represents Shopper billing contact person name information. | ObjectType | |
| billingInformation.contact.person.name.firstName | Yes | The first name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| billingInformation.contact.person.name.lastName | Yes | The last name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| billingInformation.contact.emailAddresses | Yes | Email address of the Shopper. | Array of String | Min 3 characters Max 150 characters |
| billingInformation.contact.phoneNumbers | Yes | Shopper phone number used for order follow-up. | Array of String | Min 10 characters Max 40 characters |
| shippingInformation | Yes | Represents Shipping Information of the order. Contains Shopper Contact Information and Address. | ObjectType | |
| shippingInformation.address | Yes | Represents Shopper shipping address information. | ObjectType | |
| shippingInformation.address.line1 | Yes | The line1 components contain the street address. | String | Min 1 character Max 70 characters |
| shippingInformation.contact.phoneNumbers | Yes | Shopper phone number used for order follow-up. | String | Min 10 characters Max 40 characters |
| shippingInformation.address.city | Yes | City of the Shipping Address. | String | Min 1 character Max 40 characters |
| shippingInformation.address.mainDivision | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. | ObjectType | |
| shippingInformation.address.mainDivision.code | Yes | Typically, a two- or three-digit postal abbreviation for the state or province. This does not necessarily conform to the ISO 3166-2 code. | String | Min 1 character Max 5 characters |
| shippingInformation.address.country | Yes | Two-digit ISO country code conforming to ISO 3166 alpha 2. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 | String | |
| shippingInformation.address.postalCode | Yes | Postal code of the Shipping Address. | String | Min 1 character Max 35 characters |
| shippingInformation.contact | Yes | Represents Shopper shippingInformation contact information. | ObjectType | |
| shippingInformation.contact.person | Yes | Represents Shopper shippingInformation contact person information. | ObjectType | |
| shippingInformation.contact.person.name | Yes | Represents Shopper shippingInformation contact person name information. | ObjectType | |
| shippingInformation.contact.person.name.firstName | Yes | The first name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| shippingInformation.contact.person.name.lastName | Yes | The last name of the Shopper placing the order. | String | Min 1 Character Max 64 characters |
| shippingInformation.contact.emailAddresses | Yes | Email address of the Shopper. | Array of String | Min 3 characters Max 150 characters |
| processingOptions | No | Processing options. | ObjectType | |
| processingOptions.authorizationMode | No | Processing option for the shipment. | Enum | In the subscription purchase with Vault Id use case, set AUTO_CAPTURE. |
Request Example
Payment Authorization request with Vault Id and Customer Id.
Copy
{
"orderInformation": {
"orderId": "365",
"softDescriptor": "Paypal*Amazon*5699 $40.00"
},
"requestId": "PAYAU541501814",
"createTimestamp": "2025-04-02T09:29:13Z",
"paymentMethod": {
"payPalVaultData": {
"id": "7c282279pb3649525",
"customerId": "92279uy36497"
}
},
"amounts": {
"total": {
"currencyCode": "USD",
"value": 45
}
},
"billingInformation": {
"address": {
"city": "King of Prussia",
"country": "US",
"line1": "935 First Ave",
"mainDivision": {
"code": "PA"
},
"postalCode": "19406"
},
"contact": {
"emailAddresses": [
"testtest@gmail.com"
],
"person": {
"name": {
"firstName": "Test",
"lastName": "Tester"
}
},
"phoneNumbers": [
"9876543120"
]
}
},
"processingOptions": {
"authorizationMode": "AUTO_CAPTURE"
}
}
For details of the API request and response, see PayPal Payment Authorization using Vault Id.