PayPal Payment Authorization Using Vault Id

Overview

Payment Authorization is the last API call in the PayPal checkout flow, and it is used to finally authorize the payment. If the ResponseCode from the Payment Authorization response is Success then the Order has been placed successfully and the PayPal checkout flow is complete.

The Payment Authorization API uses the Vault Id created through either the PayPal DoAuthorization or PayPal Vault Id Creation APIs; Along with that include the optional Customer Id in the request to link Vault Ids under the same Shopper. If not provided, PayPal will generate a Customer Id automatically.

Auto-Capture and Post-Capture flows are specificed by the authorizationMode chosen by the Webstore.

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.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
orderInformation.orderId	Yes	Unique identifier for an order.	String	Min 3 char Max 40 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 either the PayPal DoAuthorization API or the PayPal Payment Method Create API.	String	Min 4 characters
paymentMethod.payPalVaultData.customerId	No	PayPal customer id. Customer Id will be present only when Vault is enabled.	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 Contact Information and Address.	ObjectType
billingInformation.address	Yes	Represents Shopper 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 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	It only allows AUTO_CAPTURE. To enable AutoCapture set authorizationMode as AUTO_CAPTURE, otherwise ignore processingOptions object for post-capture.

Request Example

Payment Authorization request with Post-Capture.

Copy

{
    "orderInformation": {
        "orderId": "365",
        "softDescriptor": "Paypal*Amazon*5699 $40.00"
    },
    "requestId": "PAYAU541501814",
    "createTimestamp": "2025-04-02T09:29:13Z",
    "paymentMethod": {
        "payPalVaultData": {
            "id": "7c282279pb3649525"
        }
    },
    "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"
            ]
        }
    }
}

Payment Authorization request with Auto-Capture

Copy

{
    "orderInformation": {
        "orderId": "365"
    },
    "requestId": "PAYAU541501814",
    "createTimestamp": "2025-04-02T09:29:13Z",
    "paymentMethod": {
        "payPalVaultData": {
            "id": "7c282279pb3649525"
        }
    },
    "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"
   }
}

Response Elements

Element	Required	Description	Type	Restriction
success	Yes	Attribute that indicates whether the authorization is success or not.	Boolean	true or false
result	Yes	This contains details of the authorization result.	ObjectType
orderId	Yes	Unique identifier for an order.	String	Min 3 characters Max 40 characters
paymentMethod	Yes	Unique identifier of the payment transaction for the order.	ObjectType
paymentMethod.tender	Yes	Identifies the tender. PY is the tender for PayPal.	String	Only 2 characters
paymentMethod.accountIdentifier	Yes	Contains identifier and token information.	ObjectType
paymentMethod.accountIdentifier.identifier	Yes	PAYPAL	String
paymentMethod.accountIdentifier.token	Yes	Attribute that indicates whether the account identifier is tokenized.	Boolean	true or false
result.amountAuthorized	Yes	Amount value and currency code of the order	ObjectType
result.amountAuthorized.value	Yes	Total value of the authorization.	Decimal	Min 0.00 Max 9 digits Fraction 2 digits
result.amountAuthorized.currencyCode	Yes	The currency of the order amount	ISO 4217 currency code
result.responseCode	Yes	Used by client to determine APPROVED or DECLINED or ERROR response.	Enum	Can be any of these values: APPROVED DECLINED ERROR
result.responseCodeDescription	Yes	Reponse code description.	String
errors.systemId	Yes	Radial generated unique identifier for the error.	String
errors.code	Yes	Error code of the transaction.	Enum	TIMEOUT
errors.message	Yes	Error code description.	String
riskData	No	Risk data from PayPal.	ObjectType
riskData.paymentStatus	No	Payment status information.	enum	COMPLETE
riskData.payerInformation	No	Payer Information.	ObjectType
riskData.payerInformation.payerId	No	Payer Id.	String	Max 40 Characters
riskData.payerInformation.payerStatus	No	Give the status of the payer, whether payer is Verified or Unverified payer.	String	VERIFIED, UNVERIFIED
riskData.payerInformation.contact	No	Payer Contact Information of the payer.	ObjectType
riskData.payerInformation.contact.emailAddresses	No	Payer contact email addresses.	Array	Min 3 characters Max 150 characters
riskData.payerInformation.contact.phoneNumbers	No	Payer contact phone numbers.	Array	Min 10 characters Max 40 characters
riskData.payerInformation.address	No	Payer Contact address.	ObjectType
riskData.payerInformation.country	No	Payer country.	String	2 Characters. Two digit ISO 3166 alpha 2 code country code. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.
riskData.paypal	No	PayPal Protection Information.	ObjectType
riskData.paypal.protectionEligibility	No	PayPal Protection Eligibility.	String	It can be "ELIGIBLE", "PARTIALLY_ELIGIBLE" or "INELIGIBLE"
riskData.paypal.expressCheckoutToken	No	PayPal Express checkout token.	String	Min 3 characters Max 40 characters
riskData.paypal.protectionEligibilityTypes	No	PayPal Express protection eligibility type.	Array	It can be ITEM_NOT_RECEIVED or UNAUTHORIZED_TRANSACTION

Success Response Example

Payment Authorization Response with Post-Capture

Copy

{
    "success" : true,
    "requestId" : "PAYAU1043050331",
    "result" : {
        "orderId" : "359",
        "paymentMethod" : {
            "tender" : "PY",
            "accountIdentifier" : {
                "identifier" : "PAYPAL",
                "token" : true
            }
        },
        "responseCode" : "APPROVED",
        "amountAuthorized" : {
            "value" : 45,
            "currencyCode" : "USD"
        },
        "riskData" : {
            "paymentStatus" : "COMPLETED",
            "payerInformation" : {
                "payerId" : "QHR4ZMQ8FZ5K6",
                "payerStatus" : "VERIFIED",
                "contact" : {
                    "emailAddresses" : [
                        "qa@gsi.com"
                    ],
                    "phoneNumbers" : [
                        "4843407988"
                    ]
                },
                "address" : {
                    "country" : "US"
                }
            },
            "paypal" : {
                "protectionEligibility" : "ELIGIBLE",
                "expressCheckoutToken" : "07W52911LT768222D",
                "protectionEligibilityTypes" : [
                    "ITEM_NOT_RECEIVED",
                    "UNAUTHORIZED_TRANSACTION"
                ]
            }
        }
    }
}

Payment Authorization Response with Auto-Capture

Copy

{
    "success" : true,
    "requestId" : "PAYAU541501814",
    "result" : {
        "orderId" : "365",
        "paymentMethod" : {
            "tender" : "PY",
            "accountIdentifier" : {
                "identifier" : "PAYPAL",
                "token" : true
            }
        },
        "responseCode" : "SUCCESS",
        "amountAuthorized" : {
            "value" : 45,
            "currencyCode" : "USD"
        },
        "riskData" : {
            "paymentStatus" : "COMPLETED",
            "payerInformation" : {
                "payerId" : "QHR4ZMQ8FZ5K6",
                "payerStatus" : "VERIFIED",
                "contact" : {
                    "emailAddresses" : [
                        "qa@gsi.com"
                    ],
                    "phoneNumbers" : [
                        "4843407988"
                    ]
                },
                "address" : {
                    "country" : "US"
                }
            },
            "paypal" : {
                "protectionEligibility" : "ELIGIBLE",
                "expressCheckoutToken" : "9MP514270K5810902",
                "protectionEligibilityTypes" : [
                    "ITEM_NOT_RECEIVED",
                    "UNAUTHORIZED_TRANSACTION"
                ]
            }
        }
    }
}

Response Handling

The Payment Authorization request and response handling include failure, fault and timeout scenarios.

Failure Processing

A Failure in the Payment Authorization call will return Failure in the ResponseCode, as shown in the following example.

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

Example: 1

Copy

{
    "success" : false,
    "requestId" : "PAYAU1986296268",
    "result" : {
        "orderId" : "267",
        "paymentMethod" : {
            "tender" : "PY",
            "accountIdentifier" : {
                "identifier" : "PAYPAL",
                "token" : true
            }
        },
        "responseCode" : "FAIL",
"responseCodeDescription" : "If the currency supports decimals, only two decimal place precision is
supported. (field: /purchase_units/@reference_id=='default'/amount/value, value: 109.0000)",
        "amountAuthorized" : {
            "value" : 0,
            "currencyCode" : "USD"
        }
    }
}

Example: 2

Copy

{
    "success" : false,
    "requestId" : "Testt-12345",
    "result" : {
        "orderId" : "267",
        "paymentMethod" : {
            "tender" : "PY",
            "accountIdentifier" : {
                "identifier" : "PAYPAL",
                "token" : true
            }
        },
        "responseCode" : "FAIL",
"responseCodeDescription" : "You do not have permission to access or perform operations on this
resource.",
        "amountAuthorized" : {
            "value" : 0,
            "currencyCode" : "USD"
        }
    }
}

If the ResponseCode value is Failure, the following steps should be performed to conclude the Express Checkout flow:

The webstore refuses the order and show the Shopper alternate payment options.

For details of the PayPal Payment Authorization request and response, see PayPal Payment Authorization Using Vault Id.

Timeout Processing

If the ResponseCode value is Timeout, the webstore can retry the Payment Authorization call. The following example shows a timeout response.

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

Copy

{
    "success" : false,
    "requestId" : "526ae2b0-c763-4046-b012-9655a0e9bc1d",
    "errors" : [
        {
            "systemId" : "890664a3-8ae7-4b23-8ca4-b755bdda3d25",
            "code" : "TIMEOUT",
            "message" : "A gateway timeout occurred while processing the request."
        }
    ]
}

Radial recommends a maximum of three retry attempts, but the Payment service does not enforce a specific limit in the number of retries.

For detailed API interactions, refer to: PayPal SetExpress, PayPal Vault Creation, PayPal Payment Authorization Using Vault Id and PayPal Vault Id Deletion.

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

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