Set the pricing rate

DOCSCurrent

Last updated: Sept 23rd, 9:55pm

Follow these steps to add the pricing ID to your Orders API integration so that you can specify the contracted transaction rate:

Know before you code

Create order

Capture order

Troubleshooting

Know before you code

You must be an approved partner with a tiered pricing contract to use this feature.

You must set up your Partner Specific Pricing configuration correctly with PayPal.

The Orders API accepts the pricing ID in create only. You cannot pass the pricing ID in the capture, auth, or other endpoints.

Create order

Create an order with a tiered pricing rate by using this code from the Orders API.

For purchase_units, pass the currency code and the value of the order where value is the total number of purchase units.

Update payee_pricing_tier_id to the specific pricing ID that is assigned to you by PayPal. You may have multiple pricing IDs with different rates. Make sure you pass the ID with the rate you want to apply to this transaction.

Update any other parameters to create an order that reflects the order details.

1{
2  "intent":"CAPTURE",
3  "purchase_units":[
4    {
5      "payment_group_id":"1",
6      "reference_id":"REFID-000-1001",
7      "description":"Description of PU1",
8      "custom_id":"CUSTOMID-1001",
9      "soft_descriptor":"SOFT-1001",
10      "invoice_id":"1594680747209",
11      "amount":{
12        "currency_code":"CAD",
13        "value":"10.00",
14        "breakdown":{
15          "item_total":{
16            "currency_code":"CAD",
17            "value":"10.00"
18          }
19        }
20      },
21      "items":[
22        {
23          "name":"VRLens1",
24          "description":"VRLens1",
25          "sku":"259483234816",
26          "unit_amount":{
27            "currency_code":"CAD",
28            "value":"10.00"
29          },
30          "quantity":"1",
31          "category":"PHYSICAL_GOODS",
32          "postback_data":[
33            {
34              "name":"order_id",
35              "value":"test1"
36            }
37          ]
38        }
39      ],
40      "payee":{
41        "email_address":"[email protected]"
42      },
43      "payment_instruction":{
44        "platform_fees":[
45          {
46            "amount":{
47              "currency_code":"CAD",
48              "value":"1.00"
49            },
50            "payee":{
51              "email_address":"[email protected]"
52            }
53          }
54        ],
55        "disbursement_mode":"INSTANT",
56        "payee_pricing_tier_id":"MTFFQS1DNkMxLUVCM0Y0MDY0LUE1MEMtNDI4NkFCNTQxMjZE"
57      }
58    }
59  ],
60  "payment_source":{
61    "card":{
62      "number":"4605189739648329",
63      "expiry":"2025-06",
64      "security_code":"719",
65      "name":"John Doe",
66      "billing_address":{
67        "address_line_1":"2211 N First Street",
68        "address_line_2":"Building 17",
69        "admin_area_2":"San Jose",
70        "admin_area_1":"CA",
71        "postal_code":"95131",
72        "country_code":"US"
73      },
74      "attributes":{
75        "customer":{
76          "email_address":"[email protected]"
77        }
78      }
79    }
80  }
81}

Step result

A successful request results in the following:

A return status code of HTTP 201 Created.

A JSON response body that contains the order ID. You'll use the order ID in the next step.

PayPal_fee is calculated based on the pricing ID you passed.

Sample response

1{
2  "id":"6WU455923F879071T",
3  "intent":"CAPTURE",
4  "status":"COMPLETED",
5  "payment_source":{
6    "card":{
7      "last_digits":"8329",
8      "brand":"VISA",
9      "type":"CREDIT"
10    }
11  },
12  "purchase_units":[
13    {
14      "reference_id":"REFID-000-1001",
15      "amount":{
16        "currency_code":"CAD",
17        "value":"10.00",
18        "breakdown":{
19          "item_total":{
20            "currency_code":"CAD",
21            "value":"10.00"
22          },
23          "shipping":{
24            "currency_code":"CAD",
25            "value":"0.00"
26          },
27          "handling":{
28            "currency_code":"CAD",
29            "value":"0.00"
30          },
31          "tax_total":{
32            "currency_code":"CAD",
33            "value":"0.00"
34          },
35          "insurance":{
36            "currency_code":"CAD",
37            "value":"0.00"
38          },
39          "shipping_discount":{
40            "currency_code":"CAD",
41            "value":"0.00"
42          }
43        }
44      },
45      "payee":{
46        "email_address":"[email protected]",
47        "merchant_id":"CWL4VKR4T8VE2"
48      },
49      "payment_instruction":{
50        "platform_fees":[
51          {
52            "amount":{
53              "currency_code":"CAD",
54              "value":"1.00"
55            },
56            "payee":{
57              "merchant_id":"1298945857637325669"
58            }
59          }
60        ],
61        "disbursement_mode":"INSTANT"
62      },
63      "description":"Description of PU1",
64      "custom_id":"CUSTOMID-1001",
65      "invoice_id":"1594680747209",
66      "soft_descriptor":"PAYPAL *SOFT-1001",
67      "items":[
68        {
69          "name":"VRLens1",
70          "unit_amount":{
71            "currency_code":"CAD",
72            "value":"10.00"
73          },
74          "tax":{
75            "currency_code":"CAD",
76            "value":"0.00"
77          },
78          "quantity":"1",
79          "description":"VRLens1",
80          "sku":"259483234816"
81        }
82      ],
83      "shipping":{
84        "address":{
85          "address_line_1":"500 Hillside Street",
86          "address_line_2":"#100",
87          "admin_area_2":"San Jose",
88          "admin_area_1":"CA",
89          "postal_code":"95131",
90          "country_code":"US"
91        }
92      },
93      "payments":{
94        "captures":[
95          {
96            "id":"45E71580WN564964G",
97            "status":"COMPLETED",
98            "amount":{
99              "currency_code":"CAD",
100              "value":"10.00"
101            },
102            "final_capture":true,
103            "disbursement_mode":"INSTANT",
104            "seller_protection":{
105              "status":"ELIGIBLE",
106              "dispute_categories":[
107                "ITEM_NOT_RECEIVED",
108                "UNAUTHORIZED_TRANSACTION"
109              ]
110            },
111            "seller_receivable_breakdown":{
112              "gross_amount":{
113                "currency_code":"CAD",
114                "value":"10.00"
115              },
116              "paypal_fee":{
117                "currency_code":"CAD",
118                "value":"0.59"
119              },
120              "platform_fees":[
121                {
122                  "amount":{
123                    "currency_code":"CAD",
124                    "value":"1.00"
125                  },
126                  "payee":{
127                    "merchant_id":"FCDNN9FSYBZK4"
128                  }
129                }
130              ],
131              "net_amount":{
132                "currency_code":"CAD",
133                "value":"8.41"
134              },
135              "receivable_amount":{
136                "currency_code":"USD",
137                "value":"8.20"
138              },
139              "exchange_rate":{
140                "source_currency":"CAD",
141                "target_currency":"USD",
142                "value":"0.974805272898686"
143              }
144            },
145            "invoice_id":"1594680747209",
146            "custom_id":"CUSTOMID-1001",
147            "links":[
148              {
149                "href":"https://www.${stage_domain}/v2/payments/captures/45E71580WN564964G",
150                "rel":"self",
151                "method":"GET"
152              },
153              {
154                "href":"https://www.${stage_domain}/v2/payments/captures/45E71580WN564964G/refund",
155                "rel":"refund",
156                "method":"POST"
157              },
158              {
159                "href":"https://www.${stage_domain}/v2/checkout/orders/6WU455923F879071T",
160                "rel":"up",
161                "method":"GET"
162              }
163            ],
164            "create_time":"2020-07-13T22:52:43Z",
165            "update_time":"2020-07-13T22:52:43Z"
166          }
167        ]
168      }
169    }
170  ],
171  "create_time":"2020-07-13T22:52:43Z",
172  "update_time":"2020-07-13T22:52:43Z",
173  "links":[
174    {
175      "href":"https://te-alm-19967002012260092035285.qa.paypal.com:18824/v2/checkout/orders/6WU455923F879071T",
176      "rel":"self",
177      "method":"GET"
178    }
179  ]
180}

Capture order

After your buyer approves the order, call capture order to capture the buyer's funds. During this call, PayPal attempts to capture all funds. Then, use confirm payment source so that the buyer can verify the payment source of the order.

Replace Access-Token with your access token.

In the URI for the API call, replace the sample ID with your order ID.

For payment_source, use bancontact as the payment method and include the country code and account holder's full name.

In application_context, specify the following:
- the preferred language for returned errors
- the URL the buyer is returned to after approving the purchase with their selected payment method
- URL the buyer is returned to after canceling an approval with their selected payment method.

Important: Generally,return_url and cancel_url are optional fields, but with this integration, you must specify them to handle the handoff from the payment method back to your site. You can use the cancel_url to redirect buyers when an error occurs while they're on the payment method's site. Verify that the cancel_url works for that situation and for a cancellation by the buyer.

Note: For OXXO payments, set processing_instruction to ORDER_COMPLETE_ON_PAYMENT_APPROVAL.

Sample request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/confirm-payment-source \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer Access-Token" \
4-d '{
5  "payment_source": {
6    "alipay": {
7      "name": "John Doe",
8      "country_code": "C2"
9    }
10  },
11  "application_context": {
12    "locale": "en-PT",
13    "return_url": "https://example.com/returnUrl",
14    "cancel_url": "https://example.com/cancelUrl"
15  }
16}'

Step result

A successful request results in the following:

A return status code of HTTP 200 OK.

A JSON response body that contains order details and HATEOAS links.

Sample response

1"invoice_id":"Invoice-12345",
2"shipping":{
3  "name":{
4    "full_name":"John Doe"
5  },
6  "address":{
7    "address_line_1":"Andrés Bello 29",
8    "admin_area_2":"Mexico City",
9    "postal_code":"11560",
10    "country_code":"MX"
11  }
12}
13}
14],
15"links":[
16{
17"href":"https://sandbox.paypal.com:18824/v2/checkout/orders/5VW09856BH396502J",
18"rel":"self",
19"method":"GET"
20},
21{
22"href":"https://sandbox.paypal.com:20915/payment/oxxo?token=5VW09856BH396502J",
23"rel":"payer-action",
24"method":"GET"
25}
26]
27}

Troubleshooting

Error code	Description
`INVALID_PAYEE_PRICING_TIER_ID`	The value for `payee_pricing_tier_id` is not working. Check that you entered the value provided by PayPal.
`PAYEE_PRICING_TIER_ID_NOT_ENABLED`	The API Caller is not enabled to process transactions with the `payee_pricing_tier_id`. Contact your account manager to get this feature enabled.

Reporting

You can review the corresponding PayPal fee for each transaction on your transaction report.

Set the pricing rate

Know before you code

Create order

Step result

Sample response

Capture order

Sample request

Step result

Sample response

Troubleshooting

Reporting

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more