Are you looking for test card numbers?

Would you like to contact support?

No momento, esta página não está disponível em português
Marketpay icon

Tipping

Implement tipping (gratuity) in your payment flow.

When a customer includes a tip in their payment, it is booked to your liable account by default. However, you can book the entire tip amount directly to your user's balance account by providing an additional split item in the payment request.

Before you begin

Before you can split a payment that includes a tip, you must:

Book a payment's tip to your user

  1. When splitting a payment, add a split item for the tip.

    When adding a new split item, always include this in the total number of split items specified in the split.nrOfItems field.

  2. For the split item of the tip, specify:

    Key Description Example
    split.item[ITEM_NUMBER].type The type of split. Set this to Tip. split.item3.type=Tip
    split.item[ITEM_NUMBER].account Account that will receive the tip. This is the balanceAccountID of one of your user's balance accounts.
    You cannot split the tip between multiple balance accounts.
    		 split.item3.account=BA00000000000000000000001
    split.item[ITEM_NUMBER].reference Your reference for the tip, reflected in the Balance Platform Accounting Report. split.item3.reference=reference_tip
    split.item[ITEM_NUMBER].description Your description for the tip, reflected in the Balance Platform Accounting Report. split.item3.description=description_tip

    You do not need to include the tip amount in the split.totalAmount or split.item[ITEM_NUMBER].amount fields, since the tip amount may not be known when creating the payment request.

For example, a payment of EUR 630.00 is split into:

  • EUR 600.00 to be paid to your user's first balance account as the sale amount.
  • The payment fee to be booked against your user's first balance account. This will be deducted from the sale amount.
  • EUR 10.00 to be paid to your user's first balance account as the tip.
  • EUR 20.00 to be paid to your liable account as your platform's commission.

In this case, set the split.nrOfItems to 4 and split.totalAmount to 62000 (the amounts for the tip and the payment fee are not known when sending the payment request).

Adjust the payment request depending on the configured method of tipping:

When the tip is implemented from the POS app, include an additional AmountsReq.TipAmount object, where you specify the amount of the tip.

In the PaymentResponse note the following:

  • POIData.POITransactionID.TransactionID: Transaction identifier for the payment.

  • PaymentResult.AmountsResp:

    • TipAmount: amount of the tip. If the customer didn't add a tip, this field is not included.
    • AuthorizedAmount: total amount of the payment (original transaction amount plus tip amount).
    • Currency: currency of the payment.
    • Response.Result: Success
    • Response.AdditionalResponse: additional transaction data. Depending on the format you used in the request, you receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object. This includes:
      • posadditionalamounts.originalAmountValue: the original transaction amount in minor units.
      • posAmountGratuityValue: the tip amount in minor units.
      • authorisedAmountValue: the total authorised amount in minor units.