Payment Methods and Costs

A payment method is how a payee receives money: a bank account, a debit card, PayPal and others. The payee chooses it during onboarding; you decide which methods are offered and how much of the fee you cover. This page lists the methods, shows how to read their cost, and explains how fees are split.

Before you start

• The methods available to your payees are enabled on your account by Payment Labs.
• Reading costs needs the read permission.

The payout methods

Treat the list as open: new methods are added over time. Your code should accept a type it does not know.

Who picks what:

• The payee chooses their payout method. You cannot choose it on a payment.
• You restrict the methods for a batch with allowedPaymentMethods (see Batches). Payees are only offered methods that the batch allows and that support their country and currency.
• If a payee's method cannot take a payment, the payment waits in WAITING_PAYMENT_METHOD and the payee is asked to pick another. See Payment Statuses.

Step 1: Read your costs

Get Payment Methods Cost returns the price of each method enabled on your account.

curl "https://api-sandbox.paymentlabs.io/payors/me/payment-methods?destinationCountry=MX&destinationCurrency=MXN" \
  -H "Authorization: Bearer $TOKEN"

{
  "bank-transfer-1": {
    "local": { "cost": 2.5, "initialCap": 2.5, "retryCap": 2.5, "price": { "flat": 2.5 } },
    "wire-fx": { "cost": 15, "initialCap": 15, "retryCap": 15, "price": { "flat": 15 } }
  },
  "paypal": { "cost": "2% + 1.50", "initialCap": 5, "retryCap": 5, "price": { "percent": 0.02, "fixed": 1.5 } }
}

Each method maps to a cost entry. Bank transfers are broken down by corridor:

Each entry has:

How fees work

A payment can carry two kinds of fee:

• Service fee: a per-payment fee charged when you create the payment, shown as chargedServiceFee. It is refunded if you cancel the payment within its grace period (refundedServiceFee).
• Transfer fee: the cost of the payout method, calculated when the payment is sent. It is split between you and the payee by the fee cap.

To see the exact split for one payment before you send it, call Submit Payment Dry Run (see Creating and Submitting Payments). After the payment is sent, totalPayorFees, totalPayeeFees and totalFxLosses on the payment show what was charged, as integers in the payment currency's minor units (1250 is 12.50). They are returned only by Search Payments. totalPayeeFees is every fee deducted from the payee. For the breakdown per attempt, List Payee Payments returns each attempt's payeePaymentFee, payeeServiceFee and payeeIdentityVerificationFee, with the exchange rate (fxRate) and the amount the payee received (resultingSourceAmount, destinationAmount).

Fee caps

The fee cap is the most you pay toward a payment's transfer fee. Anything above it is deducted from what the payee receives. A cap of 0 means the payee pays the whole fee; a cap at or above the fee means you pay all of it.

The cap for a payment is chosen in this order:

1. The feeCap you send when you submit (a decimal string in the payment's currency, for example "5.00").
2. The cap configured on your account for the payee's payout method (the initialCap and retryCap that Get Payment Methods Cost reports).
3. Your account's default cap, which can differ by payment category and between first attempts and resends.

When a returned payment is sent again, the exchange rate and fees can differ from the first attempt. fxDifferenceCoverage decides who covers that difference (payor or payee). See Payment Statuses.

Errors and edge cases

Next steps

• Creating and Submitting Payments
• Payment Statuses