Technical GuidesRates

Set Up Default and Tier Rates

Do the following to successfully approve a new rate contract and assign a merchant to a tier rate:

  1. The Afterpay team creates a new contract that outlines the default buy rate as well as any additional tiers with their associated buy rates and GMV ranges. There is one contract per country and the contract remains active until it is explicitly deprecated.

  2. Once the contract is created, you, the partner, must approve or reject the proposed rate contract via Approve Contract. Afterpay can provide the contractId for the pending contract or you can listen to webhooks for contract creation events.

1curl --location 'https://agencyapi.afterpay.com/v1/rates-contract/{{contractId}}/review' \
2--header 'X-Afterpay-Request-Signature: <Request Signature>' \
3--header 'X-Afterpay-Request-Date: <Request Date>' \
4--header 'X-Afterpay-Request-Apikey: <API Key>' \
5--header 'Content-Type: application/json' \
6--data-raw '{
7"contractId": {{contractId}},
8"userDetails": {
9  "firstName": "John",
10  "lastName": "Doe",
11  "email": "john.doe@psp.com"
12},
13"comment": "LGTM",
14"status": "APPROVED",
15"countryCode": "US",
16"buyRates": {
17   "defaultRates": {
18     "variableRatePercentage": "6",
19     "fixedRate": "0.30",
20     "fixedRateCurrencyCode": "USD",
21     "rateType": "ONGOING"
22   },
23   "tierDetails": [
24     {
25       "tier": "1",
26       "minimumGmv": "0",
27       "maximumGmv": "1000000",
28       "gmvCurrencyCode": "USD",
29       "tieredRates": [
30         {
31           "variableRatePercentage": "5",
32           "fixedRate": "0.30",
33           "fixedRateCurrencyCode": "USD",
34           "rateType": "ONGOING"
35         }
36       ]
37     },
38     {
39       "tier": "2",
40       "minimumGmv": "1000001",
41       "maximumGmv": "10000000",
42       "gmvCurrencyCode": "USD",
43       "tieredRates": [
44         {
45           "variableRatePercentage": "4",
46           "fixedRate": "0.30",
47           "fixedRateCurrencyCode": "USD",
48           "rateType": "ONGOING"
49         }
50       ]
51     },
52     {
53       "tier": "3",
54       "minimumGmv": "10000001",
55       "maximumGmv": "100000000",
56       "gmvCurrencyCode": "USD",
57       "tieredRates": [
58         {
59           "variableRatePercentage": "3",
60           "fixedRate": "0.30",
61           "fixedRateCurrencyCode": "USD",
62           "rateType": "ONGOING"
63         }
64       ]
65     }
66   ]
67 }
68}
69'
  1. Once a contract is successfully approved, you, the partner, can assign merchants to tiers associated with the approved contract using Update Tier only.
Note

You can use both the UpdateOnboarding or UpdateTier endpoints to set the initial tier for a merchant. For subsequent tier updates, use the UpdateTier endpoint.

1curl --location 'https://agencyapi.afterpay.com/v1/onboardings/{{onboardingId}}/capabilities/buy-rate' \
2--header 'X-Afterpay-Request-Signature: <Request Signature>' \
3--header 'X-Afterpay-Request-Date: <Request Date>' \
4--header 'X-Afterpay-Request-Apikey: <API Key>' \
5--header 'Content-Type: application/json' \
6--data-raw '{ 
7"tier": 1, 
8"gmv": "10000000", 
9"gmvCurrencyCode": "USD", 
10"agencyMerchantContractDetails": { 
11  "contractId": "{{partner-generated contractId}}", 
12  "contractDate": "2023-09-17T00:00:00.000+00:00" } 
13}'
  1. If a merchant’s tier needs to be updated, use Update Tier to update the merchant’s associated tier and GMV.
Notes

Step 4: Tier updates require a unique partner-generated contract ID and can only be updated for a specific merchant once per quarter.

When a merchant’s tier is updated through UpdateTier, the agencyMerchantContractDetails.contractId refers to a unique identifier for a contract. This contract is between the Payment Service Provider and the merchant and represents the Afterpay rate change. This contractId is different from the contractId specified for custom rates and can only be updated once per quarter.