PayPal Vault Creation

Overview

The 'PayPal Vault Creation' API generates a Vault Id for secure storage of payment details, enabling seamless repeat transactions without requiring customers to re-enter their information.

The response includes a payPalVaultData element, whose ID is used in the Payment Authorization request.

PayPal Vault creation occurs as a subsequent step to the setExpress API call with Recurring is true with Amount is 0.

URI Description

Action URI Template URI Example Request Content Type Response Content Type
POST /vM.m/stores/{StoreID}/payments/payment-method/create/{tenderType}.json /v1.0/stores/TMSUS/payments/payment-method/create/PY.json application/json application/json

Request Elements

When preparing the request, consider the following data notes:

The request and response are JSON.

  • In the request, the payPalVaultData element contains the token ID returned by the SetExpress API.
  • Amount is always 0
Element Required Description Type Restriction
createTimestamp Required Timestamp when the request is sent String dateTime
@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
OrderInformation/
OrderId		 Yes Order identifier. String minLength: 3, maxLength: 40
Amount/
Total/
Value		 Yes The value always be 0. Decimal 2 precision points. (123.34)
Amount/
Total/
CurrencyCode		 Yes Preferred currency. String 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/
wiki/ISO_4217.
PaymentMethod/
PayPalVaultData/
Token		 Yes Token from SetExpress response String 20 single-byte characters
PaymentMethod/
PayPalVaultData/
CustomerId		 No Customer Id is used to link the Vault Ids belonging to the same customer, helping to associate all Vault Ids under a single customer profile. String Between 1 and 22 Characters.

Request Example

The request is JSON data.

Copy 

                        {
    "orderInformation": {
        "orderId": "17032025-jo-PY-2"
    },
    "amounts": {
        "total": {
            "value": 0,
            "currencyCode": "USD"
        }
    },
    "paymentMethod": {
        "payPalVaultData": {
            "token": "393808972K310902T",
            "customerId" : "pLGjyKxgzK"
        }
    },
    "requestId": "17020505-012",
    "createTimestamp": "2025-02-14T05:06:48Z"
}
                    

Response Elements

The Vault Id and Customer Id will be present in response.

Element Required Description Type Restriction
@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
Success Yes Success or Failure. Boolean true or false
Result/
ResponseCode		 Yes Response code. String Success, Fail, Approved, Declined, Cancelled, Error or Timeout
Result/
ResponseCodeDescription		 Yes Response code description. String Generated by PayPal
PaymentMethod/
tender		 No Tender type. String Tender type.
tenderDescription No Error code coming from PayPal. String Error code coming from PayPal.
PaymentMethod/
payPalVaultData/
id		 Yes The PayPal-generated ID for the vault token. String Vault id from Paypal.
PaymentMethod/
payPalVaultData/
customerId		 No Customer id. String Customer id.

Success Response Example

The response is a JSON data.

Copy 
{
    "success" : true,
    "requestId" : "17020505-012",
    "result" : {
        "responseCode" : "Success",
        "responseCodeDescription" : "PayPal vault successfully created.",
        "paymentMethod" : {
            "tender" : "PY",
            "tenderDescription" : "PayPal",
            "payPalVaultData" : {
                "id" : "3a169526pa987743f",
                "customerId" : "pLGjyKxgzK"
            }
        }
    }
}

Failure Response Example

In the event of a Failure, ensure the different request ID is passed to support idempotency detection.

Example 1:

Copy 
{
    "success" : false,
    "requestId" : "c5bcd084-906b-4f9a-897a-e9188352a141",
    "result" : {
        "responseCode" : "Fail",
        "responseCodeDescription" : "Please make sure setup up token is approved."
    }
}

Example 2:

Copy 
{
    "success" : false,
    "requestId" : "1702001-PY-joo-217",
    "result" : {
        "responseCode" : "Fail",
        "responseCodeDescription" : "The specified token id does not exist."
    }
}

Timeout Response

In the event of a timeout, ensure the same request ID is passed to support idempotency detection.

Copy 
{
    "success" : false,
    "errors" : [
        {
            "systemId" : "fe7daf05-b8ae-42a8-ac8e-b8ca9e799634",
            "code" : "TIMEOUT",
            "message" : "A gateway timeout occurred while processing the request."
        }
    ]
}

Fault Response

The errors are the list.

Copy 
{
    "success": false,
    "errors": [
        {
            "systemId": "84d256fa-5515-48a9-bd2f-cdb1495ba28a",
            "code": "InvalidRequestJsonException",
            "message": "$: required property 'createTimestamp' not found"
        },
        {
            "systemId": "322a1744-92de-4821-a483-0c6006c544e8",
            "code": "InvalidRequestJsonException",
            "message": "$: required property 'requestId' not found"
        }
    ]
}

Next Step

After a successful Payment Method Creation call, the next step in the PayPal check out flow is a Payment Authorization call.

If the vault is no longer needed, delete it using the Payment Method Delete call.