Pricing entity
The Pricing entity is used to define pricing for a merchant. It enables you to control the fees that are to be charged for different Products linked to a merchant (i.e., an Account entity). The merchant onboarding API is flexible; as such, you can associate different Pricing for the same Product using parameter combinations. For example, for a Card product type within the Product entity, you can associate one Pricing entity for Local-Debit and an entirely different Pricing entity for International-Credit. Both Pricing entities can then be linked to the single Product entity that contains the Card product type.
The Pricing entity also enables you to charge fixed fees, such as a set-up fee, or recurring monthly rental fees for POS terminals (in the in store model). For example, a merchant has the Product entity of uP Payments (Solution) enabled and is using the e-commerce (model) – see the Product entity section for more details on how the Product entity is structure. This Product can be associated with multiple Pricing entities, for example, one can account for a set-up fee, one can account for a 3DS fee, etc. Similarly, the rental fee for wired or wireless POS terminals in the in store model can be also captured using the Pricing entity.
There are different Pricing fields required for each Product category:
-
Models (In Store and ecommerce): setupFee, monthlyFee, transactionalFee (and its currencies) can be set. For ‘In Store’ (ID 63c3dbfd4e03ca9d1), it is also possible to set monthlyPOSRentalWired and monthlyPOSRentalWireless. For ‘Ecommerce’ (ID 63c3dc62dc635e8c2), it is possible to set fee3DS.
-
Payment methods: refundFee, cbkFee, percentageFee, transactionalFee, flatFee, minFee, maxFee can be set. For the Payment Types of ‘Cards’, it is also required to set cardType, cardProductType and localOrInternational. For each option of cardType and localOrInternational it is expected a new pricing record.
As an example, if a merchant has an Opportunity with the Product ‘uP Payments | In store | Card | Visa/Mastercard’ (productId 63c3c94b699e644a0), there will need to be at least 4 different pricing objects, even if the pricing is the same:
- Debit – Local – CnB
- Debit – International – CnB
- Credit – Local – CnB
- Credit – International – CnB
The table below captures the Pricing entity’s required fields.
Some field values are case sensitive. These field will be denoted with an * for clarity.
| Field Name | Value | Description | Type |
|---|---|---|---|
| parentId | 6410461062cebb512 | ID of the "Parent" for this location. This will be the unique uP POM Account ID of the merchant on the uP Platform. This is provided automatically by the uP POM after the Account entity is created. | Mandatory |
| parentType | Account | Type of the "Parent" for this location. Should always send "Account". * Case sensitive submission | Mandatory |
| productEntityId | 63c3ce1225c229832 | ID of the product related to this Pricing entity. | Mandatory |
| effectFrom | YYYY-MM-DD | Year, month, date from which the pricing will take effect. * Date must be formatted as shown in the Value column. | Mandatory |
| term | 36 | Duration, in months, of the contractual agreement for this pricing. * Numerical digits only. | Mandatory |
| cardType | Credit | Card type. Options are: • Debit • Credit. Case sensitive submission. * Conditional - only required if the payment Type in the Product ID is "Card". | Conditional - only required if the payment Type in the Product ID is “Card” |
| cardProductType | Consumer | Card product type. • Options are: • Consumer • Business • Corporate • CnB. Note: CnB is to be submitted when the pricing will be the same regardless of the Card product type. * Case sensitive submission. | Conditional - only required if the payment Type in the Product ID is "Card". |
| localOrInternational | Local | Informs pricing for local or international cards. Options are: • Local • International. * Case sensitive submission. | Conditional - only required if the payment Type in the Product ID is "Card". |
| percentageFee | 3 | Percentage fee (MDR) for e-commerce or in store product. Two decimal digits. Amounts are formatted using a dot ("."). * Numerical digits, field will not accept comma formatting | Conditional - only required if Product ID includes a payment method and if "flatFee" is empty. |
| flatFee | 5.00 | Flat fee (fixed amount regardless of the value of the transaction) for the payment method. Two decimal digits. Amounts are formatted using a dot ("."). * Numerical digits, field will not accept comma formatting. | Conditional - only required if Product ID includes a payment method and if "percentageFee" is empty. |
| flatFeeCurrency | HKD | Currency of the flat fee. Currency 3 letter code ISO 4217-Alpha 3. * Case sensitive submission. | Conditional - only required if Product ID includes a payment method and if "percentageFee" is empty. |
| cbkFee | 150.00 | Chargeback fee for the payment method. Two decimal digits. Amounts are formatted using a dot ("."). * Numerical digits, field will not accept comma formatting. | Conditional - only required if Product ID includes a payment method. |
| cbkFeeCurrency | HKD | Currency of the chargeback fee. Currency 3 letter code ISO 4217-Alpha 3. * Case sensitive submission. | Conditional - only required if Product ID includes a payment method. |
| refundFee | 40.00 | Refund fee for the payment method. Two decimal digits. Amounts are formatted using a dot ("."). * Numerical digits, field will not accept comma formatting. | Conditional - only required if Product ID includes a payment method. |
| refundFeeCurrency | HKD | Currency of the refund fee. Currency 3 letter code ISO 4217-Alpha 3. * Case sensitive submission. | Conditional - only required if Product ID includes a payment method. |