getPayments

Retrieve payments.

In Erply, a payment is associated with a customer (customerID), and optionally an invoice (documentID; or some other sales document, eg. a sales order). One invoice can have many payments. Payment, on the other hand, can only be associated with one invoice at a time. If customer makes an aggregate payment towards several invoices, it needs to be split up into parts.

A payment may not always be associated with a specific invoice (eg. deposits, store credit).

To register a new payment or update an existing one, see savePayment.

Input parameters

Parameter name Description Possible value Required
paymentID Retrieve one specific payment. Integer
paymentIDs Retrieve multiple payments, IDs separated by commas. Eg. "1,2,3,4,5". String
customerID Integer
documentID Retrieve payments on a specific invoice. Integer
documentIDs Retrieve payments on multiple invoices (or sales documents), IDs separated by commas. Eg. "1,2,3,4,5". String
dateFrom Filter payments by date range. Date (yyyy-mm-dd)
dateTo Date (yyyy-mm-dd)
type Filter payments by type. For a more detailed explanation of possible payment types, see the "type" field below. String(10)
typeID Filter payments by type ID. If you set field "type" (see above), "typeID" is not necessary. For a list of payment types, see getPaymentTypes. Integer
giftCardVatRateID Filter payments by gift card VAT rate ID. Integer
excludeStoreCreditPayments 0 or 1, by default 0.

Set this filter flag to retrieve only payments that have been paid explicitly towards a specific invoice. This is because customer may also pay an invoice partly or fully with "store credit". Paying with "store credit" typically means that an earlier, existing prepayment is associated with the given invoice. This filter helps to exclude those payments.

Typically, this filter should be used together with invoiceID.
Integer
archivalNumber

Search for a payment (a wire transfer payment imported from bank) by its archival number.

Note that even though archival numbers are meant to be unique, this search may return multiple results if one wire transfer imported from bank has been split into multiple payments in Erply. This may happen if customer paid for multiple invoices.

String (255)
searchAttributeName Name of attribute to search from. Both "searchAttributeName" and "searchAttributeValue" have to be specified. Error 1030 will be returned if value is an array. String
searchAttributeValue Attribute value to search for. Error 1030 will be returned if value is an array. String
changedSince Retrieve only items that have been added or modified since the specified timestamp. Use it to keep a local database in sync with Erply. Integer (Unix timestamp)
isReservation Integer (0 or 1) Retrieve either only reserved payments or non reserved payments. Do not use the parameter to get both.
recordsOnPage Number of records API should return. By default 20, at most 100. Integer
pageNo API returns at most recordsOnPage items at a time. To retrive the next recordsOnPage items, send a new request with pageNo incremented by one. By default, API returns "page 1". Integer

Response

Field name Type Description
paymentID Integer
documentID Integer ID of the invoice that was paid. It is not possible to associate a payment with more than 1 invoice; in that case, the payment should be split into parts.
customerID Integer ID of the customer who made the payment. In most cases, it should be the same as the customer who received the invoice.
typeID Integer Payment type ID. See getPaymentTypes.
type String(10) Payment type code name. It corresponds to the type ID above, but especially with standard payment types (cash payment, card payment etc.) the code name is easier to identify.

Standard code names recognized by Erply are CASH, TRANSFER (for wire transfer), CARD, CREDIT, GIFTCARD, CHECK, TIP — but you can also create your own custom code names with savePaymentType.

"CREDIT" means "paid with a credit invoice", this type should be used when a due amount is cleared with a credit invoice, or in case of any other balancing transaction.
date Date eg. 2010-01-29
sum Decimal Paid amount
currencyCode String Currency code: EUR, USD.
currencyRate Decimal eg. 1.25543
Exchange rate of the payment currency against system's default currency.
cashPaid Decimal
cashChange Decimal
info String(255) Information about the payer. Deprecated name: "receipt_payer".
cardHolder String(255) Cardholder's name (for card payments only).

The same field is also returned as an attribute, named "cardholder_name". If you want to update this field using API call savePayment, you should pass the new value through "cardholder_name" attribute.
cardNumber String(255) Last 4 digits of credit card number (for card payments only). Erply does not store full credit card numbers.

The same field is also returned as an attribute, named "card_number". If you want to update this field using API call savePayment, you should pass the new value through "card_number" attribute.
cardType String(255) Credit card type, eg. VISA, AMEX, M/C etc. (for card payments only). Erply's Z Report displays card payments separately by type.

The same field is also returned as an attribute, named "card_type". If you want to update this field using API call savePayment, you should pass the new value through "card_type" attribute.
authorizationCode String(255) Card payment authorization code.

The same field is also returned as an attribute, named "authCode". If you want to update this field using API call savePayment, you should pass the new value through "authCode" attribute.
referenceNumber String(255) Card payment reference number.

The same field is also returned as an attribute, named "refNo". If you want to update this field using API call savePayment, you should pass the new value through "refNo" attribute.
isPrepayment Integer (0 or 1) A flag indicating whether this payment has originally been a prepayment (meaning that it was associated with a Prepayment Invoice or a Sales Order). If the payment is currently associated with a Prepayment Invoice, or a Sales Order, it does not have this flag! The flag is only applied by Erply back office when a payment is transferred from a Prepayment Invoice / Sales Order to an Invoice or an Invoice-Waybill.
*****

Additional information about the payment from bank.

This information appears if a wire transfer payment has been imported from bank. All these fields are just informative text fields (even bankDate and bankSum) and we do not have any insight into the date or number format being used. Thus the fields cannot be used in calculations.

Internally, in our data model, this "bank record" can actually be associated with multiple payments (eg. if one wire transfer has been made to pay multiple invoices simultaneously). Therefore, API getPayments may return other payments which contain exactly the same bank information, including archival number.

Furthermore, if you edit bank information on one of these payments, the same changes will appear on other payments associated with the same bank record, and the "last modification" timestamp of those payments will be updated.

bankTransactionID Integer
bankAccount String(255) Receiver's account number or IBAN.
bankDocumentNumber String(255) Transaction number.
bankDate String(255) Date of wire transfer.
bankPayerAccount String(255) Payer's account number or IBAN.
bankPayerName String(255) Payer's name.
bankPayerCode String(255) Payer's ID code (for persons) or registry code (for companies).
bankSum String(255) Paid amount.
bankReferenceNumber String(255) Reference number specified on the wire transfer.
bankDescription String(255) Description of the wire transfer.
bankCurrency String(255) Currency code.
archivalNumber String(255) Archival number of the transaction.
*****
storeCredit Integer (0 or 1) A flag indicating that this payment was once a part of customer's store credit (a pending prepayment, not associated with any invoice), but it has now been applied to a particular invoice. Customer used his/her "store credit" to pay off this invoice.
paymentServiceProvider String API only returns this field if "Cayan / Merchant Warehouse payment data" (returns "merchant_warehouse"), "PAX payment data" (returns "pax"), "Tyro payment data" (returns "tyro") or "Givex payment data" (returns "givex) module is enabled on your account.
aid String(20) API only returns this field if "Cayan / Merchant Warehouse payment data" or "PAX payment data" module is enabled on your account.
applicationLabel String(30) API only returns this field if "Cayan / Merchant Warehouse payment data" or "PAX payment data" module is enabled on your account.
pinStatement String(30) API only returns this field if "Cayan / Merchant Warehouse payment data" module is enabled on your account.
cryptogramType String(10) API only returns this field if "Cayan / Merchant Warehouse payment data" module is enabled on your account.
cryptogram String(30) API only returns this field if "Cayan / Merchant Warehouse payment data" module is enabled on your account.
expirationDate String(10) API only returns this field if "Cayan / Merchant Warehouse payment data" or "Givex payment data" module is enabled on your account.
entryMethod String(20) API only returns this field if "PAX payment data" module is enabled on your account.
transactionType String(30) API only returns this field if "PAX payment data" module is enabled on your account.
transactionNumber String(20) API only returns this field if "PAX payment data" module is enabled on your account.
transactionId String(20) API only returns this field if "Tyro payment data" module is enabled on your account.
transactionType String(20) API only returns this field if "Givex payment data" module is enabled on your account.
transactionTime Unix timestamp API only returns this field if "Transaction Time of a Payment" module is enabled on your account.
klarnaPaymentID String(40) API only returns this field if "Klarna payment data" module is enabled on your account.
certificateBalance Decimal string or empty string API only returns this field if "Givex payment data" module is enabled on your account.
statusCode Integer string or empty string API only returns this field if "Givex payment data" module is enabled on your account.
statusMessage String(100) API only returns this field if "Givex payment data" module is enabled on your account.
giftCardVatRateID Integer

On payments with type = "GIFTCARD", this value indicates the tax rate (VAT rate) the gift card was originally sold with. On payments of any other type, the value will presumably be always 0.

If the value is 0, you may assume that the gift card was sold without tax. (Historically, this was the only option that Erply supported.) Support for taxed gift cards has been added due to the EU Council Directive 2016/1065, which defines the concept of "single-purpose vouchers".

If customer has redeemed a gift card with tax, it means that on the sales transaction associated with this payment, taxable total and amount of tax should be correspondingly regarded smaller. (Please note that getSalesDocuments itself does not report that information.)

The full workflow (selling gift cards with tax and redeeming them properly) requires Berlin POS.

added Unix timestamp Creation time.
lastModified Unix timestamp Last modification time.
attributes Array Additional attributes. Each item looks like this:

Field nameTypeDescription
attributeNameStringAttribute name
attributeTypeStringAttribute type
attributeValueStringAttribute value