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.
| 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) | |
| cardNumber | Filter payments by card number (last 4 digits of credit card number). | String | |
| cardHolder | Filter payments by cardholder's name. | String | |
| referenceNumber | Filter payments by card payment reference number. | String | |
| sumTo | Decimal | ||
| sumFrom | Decimal | ||
| associatedWithDocument | Integer (0 or 1) | ||
| associatedWithCustomer | Integer (0 or 1) | ||
| 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 | Retrieve either only reserved payments or non reserved payments. Do not use the parameter to get both. | Integer (0 or 1) | |
| getSignatures | Set to 1 to retrieve card payment signatures. | Integer (0 or 1) | |
| orderBy | Possible values: 'paymentID', 'cardNumber', 'cardHolder', 'referenceNumber', or 'sum'. By default, 'paymentID'. | string | |
| orderByDir | Sort direction: 'asc' (ascending order) or 'desc' (descending order). By default, items are sorted in ascending order. | string | |
| 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 retrieve the next recordsOnPage items, send a new request with pageNo incremented by one. By default, API returns "page 1". | integer |
| 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 | string | Format: yyyy-mm-dd. eg. 2010-01-29 | ||||||||||||
| sum | number | Paid amount | ||||||||||||
| currencyCode | string | Currency code: EUR, USD. | ||||||||||||
| currencyRate | number | 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, we recommend to use the field "authorizationCode", although passing the new value as attribute "authCode" is supported, too. |
||||||||||||
| 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, we recommend to use the field "referenceNumber", although passing the new value as attribute "refNo" is supported, too. |
||||||||||||
| 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. |
|||||||||||||
| 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. | ||||||||||||
| imported | Integer | Unix timestamp. | ||||||||||||
| importedByUserName | String (16) | An identifier referring to the user who imported this payment. This is NOT actually the user's name; it's just a string, at most 16 characters long. However, typically it matches the first 16 characters of the user's name. | ||||||||||||
| ***** | ||||||||||||||
| 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 | integer | 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 | string | Decimal string or empty string. API only returns this field if "Givex payment data" module is enabled on your account. | ||||||||||||
| statusCode | string | 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 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. |
||||||||||||
| signature | String (up to 65,535 B) | Cardholder's signature. | ||||||||||||
| signatureIV | String (up to 65,535 B) | Initialization vector to be used if the signature is encrypted. | ||||||||||||
| jdoc | Object | Contains data that is saved using the JSON Api. Contents of this field change depending on what is saved into the json field. Output is always given as valid json or null when the field is not set. Example: {"myValue":"123"} |
||||||||||||
| added | integer | Unix timestamp. Creation time. | ||||||||||||
| lastModified | integer | Unix timestamp. Last modification time. | ||||||||||||
| attributes | array | Additional attributes. Each item looks like this:
|