On this page
No Headings
Last updated: June 17, 2026
The Payment Method Tokens API can create a setup token for credit or debit cards that have:
Send a call for each card type to test your integration works as expected.
You'll need a Payment Method Tokens API cards integration.
For cards with no verification, the card data passed to the API is checked only for format.
ACCESS-TOKEN to your sandbox access token.REQUEST-ID to a unique alphanumeric set of characters, for example, a time stamp.Copy and modify the following code sample to create a setup token associated with a credit or debit card with no verification.
Endpoint: Create a setup token
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS-TOKEN" \
-H "PayPal-Request-Id: REQUEST-ID" \
-d '{
"payment_source": {
"card": {
"number": "4111111111111111",
"expiry": "2027-02",
"name": "Firstname Lastname",
"billing_address": {
"address_line_1": "2211 N First Street",
"address_line_2": "17.3.160",
"admin_area_1": "CA",
"admin_area_2": "San Jose",
"postal_code": "95131",
"country_code": "US"
},
"experience_context": {
"brand_name": "YourBrandName",
"locale": "en-US",
"return_url": "https://example.com/returnUrl",
"cancel_url": "https://example.com/cancelUrl"
}
}
}
}'A successful request returns the following:
200 or 201. Returns 200 for an idempotent request.id field.{
"id": "5C991763VB2781612",
"customer": {
"id": "customer_4029352050"
},
"status": "APPROVED",
"payment_source": {
"card": {
"last_digits": "1111",
"expiry": "2027-02",
"name": "Firstname Lastname",
"billing_address": {
"address_line_1": "2211 N First Street",
"address_line_2": "17.3.160",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"country_code": "US"
}
}
},
"links": [{
"href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2781612",
"rel": "self",
"method": "GET",
"encType": "application/json"
},
{
"href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens",
"rel": "confirm",
"method": "POST",
"encType": "application/json"
}
]
}Smart authorization runs a zero-value or minimal-value authorization to validate the card is real and active.
Some issuing banks or regions don't support zero-value authorization, so a minimal-value authorization is run. The seller must manually cancel minimal-value authorizations or the customer will have a small pending charge on their card.
ACCESS-TOKEN to your sandbox access token.REQUEST-ID to a set of unique alphanumeric characters such as a time stamp.verification_method parameter with SCA_WHEN_REQUIRED to verify card data.return_url value with the URL where the payer is redirected after they approve the flow.cancel_url value with the URL where the payer is redirected after they cancel the flow.Copy and modify the following code:
Endpoint: Create a setup token
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS-TOKEN" \
-H "PayPal-Request-Id: REQUEST-ID" \
-d '{
"payment_source": {
"card": {
"number": "4111111111111111",
"expiry": "2027-02",
"name": "Firstname Lastname",
"billing_address": {
"address_line_1": "2211 N First Street",
"address_line_2": "17.3.160",
"admin_area_1": "CA",
"admin_area_2": "San Jose",
"postal_code": "95131",
"country_code": "US"
},
"experience_context": {
"brand_name": "YourBrandName",
"locale": "en-US",
"return_url": "https://example.com/returnUrl",
"cancel_url": "https://example.com/cancelUrl"
}
}
}
}'A successful request returns the following:
200 or 201. Returns 200 for an idempotent request.APPROVEDid field.{
"id": "5C991763VB2781612",
"status": "APPROVED",
"payment_source": {
"card": {
"brand": "VISA",
"last_digits": "1111",
"verification_status": "VERIFIED",
"verification": {
"network_transaction_id": "20286098380002303",
"time": "2020-10-07T22:44:41.000Z",
"amount": {
"value": "0.00",
"currency_code": "USD"
},
"processor_response": {
"avs_code": "M",
"cvv_code": "P"
}
}
}
},
"links": [{
"href": "https://api-m.sandbox.paypal.com/v3/vault/payment-token",
"rel": "confirm",
"method": "POST",
"encType": "application/json"
},
{
"href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2781612",
"rel": "self",
"method": "GET",
"encType": "application/json"
}
]
}Use 3D Secure authentication to reduce the likelihood of fraud and improve transaction performance with supported cards. In some countries, authorizing a card can trigger a 3D Secure contingency.
3D Secure verification may occur in PSD2 countries, including members of the EU. For 3D Secure verification, pass SCA_ALWAYS or SCA_WHEN_REQUIRED in the payment_source.card.attributes.verification.method field for the create order request. The API response returns the order status as PAYER_ACTION_REQUIRED.
ACCESS-TOKEN to your sandbox access token.REQUEST-ID to a set of unique alphanumeric characters such as a time stamp.verification_method parameter with SCA_ALWAYS to verify card data.return_url value with the URL where the payer is redirected after they approve the flow.cancel_url value with the URL where the payer is redirected after they cancel the flow.Copy and modify the following code:
curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens'\
-H "Content-Type: application/json"\
-H "Authorization: Bearer ACCESS-TOKEN"\
-H "PayPal-Request-Id: REQUEST-ID"\
-d '{
"payment_source": {
"card": {
"number": "4111111111111111",
"expiry": "2027-02",
"name": "Firstname Lastname",
"billing_address": {
"address_line_1": "2211 N First Street",
"address_line_2": "17.3.160",
"admin_area_1": "CA",
"admin_area_2": "San Jose",
"postal_code": "95131",
"country_code": "US"
},
"verification_method": "SCA_WHEN_REQUIRED",
"experience_context": {
"brand_name": "YourBrandName",
"locale": "en-US",
"return_url": "https://example.com/returnUrl",
"cancel_url": "https://example.com/cancelUrl"
}
}
}
}'A successful request returns the following:
200 or 201. Returns 200 for an idempotent request.PAYER_ACTION_REQUIRED{
"id": "5C991763VB2781612",
"customer": {
"id": "customer_4029352050"
},
"status": "PAYER_ACTION_REQUIRED",
"payment_source": {
"card": {
"last_digits": "1111",
"brand": "VISA",
"type": "CREDIT",
"expiry": "2027-02"
}
},
"links": [{
"href": "https://paypal.com/webapps/helios?action=authenticate&validate_session_id=82cf4a87-5c40-0a27-1a09-4ffbb0d05fdc",
"rel": "approve",
"method": "GET",
"encType": "application/json"
},
{
"href": "https://api-m.sandbox.paypal.com/v3/vault/payment-token",
"rel": "confirm",
"method": "POST",
"encType": "application/json"
},
{
"href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2771612",
"rel": "self",
"method": "GET",
"encType": "application/json"
}
]
}After the payer completes verification, make a POST request on the payment token endpoint to convert the approved setup token to a payment token.
To retrieve 3D secure verification data associated with a setup token, make a GET request on the setup token endpoint.
curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2781612'\
-H "Content-Type: application/json"\
-H "Authorization: Bearer ACCESS-TOKEN"\
-H "PayPal-Request-Id: REQUEST-ID"\A successful request returns the following:
200 OKAPPROVED| Parameter | Description |
|---|---|
verification_method | The verification method value from the request is included in the response. |
verification_status | If the card is authorized, the status is set to VERIFIED. |
authorization | Details from the authorization are returned in an authorization object. This includes the amount and currency requested, and the AVS and CVV results from the processor response. |
The issuing bank can still issue an authorization if a card fails the AVS and CVV checks. In this case, the setup token is created with an APPROVED status and the processor responses are returned to you. The eci_flag parameter indicates that 3D Secure was not completed.
You can choose whether to use a card that did not complete 3D Secure or failed AVS and CVV checks:
POST request on add-payment-token. Convert the approved setup token to a full payment token.In the sandbox, create a setup token and a 3D Secure token. Validate a card with card data from 3D Secure test scenarios.
{
"id": "5C991763VB2771612",
"status": "APPROVED",
"payment_source": {
"card": {
"brand": "VISA",
"last_digits": "1111",
"verification_status": "VERIFIED",
"verification": {
"network_transaction_id": "20286098380002303",
"time": "2020-10-07T22:44:41.000Z",
"amount": {
"value": "0.00",
"currency_code": "USD"
},
"processor_response": {
"avs_code": "M",
"cvv_code": "P"
},
"three_d_secure": {
"type": "THREE_DS_AUTHENTICATION",
"eci_flag": "FULLY_AUTHENTICATED_TRANSACTION",
"card_brand": "VISA",
"enrolled": "Y",
"pares_status": "Y",
"three_ds_version": "2",
"authentication_type": "DYNAMIC",
"three_ds_server_transaction_id": "3d-secure-txn-id"
}
}
}
},
"links": [{
"href": "https://api-m.sandbox.paypal.com/v3/vault/payment-token",
"rel": "confirm",
"method": "POST",
"encType": "application/json"
},
{
"href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2771612",
"rel": "self",
"method": "GET",
"encType": "application/json"
}
]
}Generate AVS and CVV response codes when running tests in the PayPal sandbox.
Use test card numbers.
Set address_line_1 to the following values to generate an AVS response.
| Address Line 1 | AVS Response | Visa | Mastercard | American Express | Discover |
|---|---|---|---|---|---|
| AVS_A_971 | A | Yes | Yes | Yes | Yes |
| AVS_B_972 | B | Yes | No | No | No |
| AVS_C_973 | C | Yes | No | No | No |
| AVS_D_974 | D | Yes | No | Yes | No |
| AVS_E_975 | E | No | Yes | Yes | No |
| AVS_F_976 | F | Yes | No | Yes | No |
| AVS_G_977 | G | Yes | No | No | Yes |
| AVS_I_979 | I | Yes | No | No | No |
| AVS_K_981 | K | No | No | Yes | No |
| AVS_L_982 | L | No | No | Yes | No |
| AVS_M_983 | M | Yes | No | Yes | No |
| AVS_N_984 | N | Yes | Yes | Yes | Yes |
| AVS_O_985 | O | No | No | Yes | No |
| AVS_P_986 | P | Yes | No | No | No |
| AVS_R_988 | R | Yes | Yes | Yes | Yes |
| AVS_S_989 | S | Yes | Yes | Yes | Yes |
| AVS_U_991 | U | Yes | Yes | Yes | Yes |
| AVS_W_993 | W | Yes | Yes | Yes | Yes |
| AVS_X_994 | X | Yes | Yes | No | Yes |
| AVS_Y_995 | Y | Yes | Yes | Yes | Yes |
| AVS_Z_996 | Z | Yes | Yes | Yes | Yes |
Set the CVV to the following values to generate a CVV response:
| CVV | CVV response | Description |
|---|---|---|
| 115 | M | CVV2/CVC2/CID Match |
| 116 | N | CVV2/CVC2/CID No Match |
| 120 | P | Not Processed |
| 123 | S | CVV2 should be on the card, but merchant indicated that it was not |
| 125 | U | Unknown/Issuer does not participate |
| 130 | X | Server provider did not respond (default) |