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.
|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|
|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)|
|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
|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)|
|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|
|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.
|currencyCode||String||Currency code: EUR, USD.|
Exchange rate of the payment currency against system's default currency.
|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
|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
|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
|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
|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
|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
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.
|bankAccount||String(255)||Receiver's account number or IBAN.|
|bankDate||String(255)||Date of wire transfer.|
|bankPayerAccount||String(255)||Payer's account number or IBAN.|
|bankPayerCode||String(255)||Payer's ID code (for persons) or registry code (for companies).|
|bankReferenceNumber||String(255)||Reference number specified on the wire transfer.|
|bankDescription||String(255)||Description of the wire transfer.|
|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") or "Tyro payment data" (returns "tyro") 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.|
|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.|
|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.|
On payments with
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: