Search

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 nameDescriptionPossible valueRequired
paymentIDRetrieve one specific payment.Integer
paymentIDsRetrieve multiple payments, IDs separated by commas. Eg. "1,2,3,4,5".String
customerIDInteger
documentIDRetrieve payments on a specific invoice.Integer
documentIDsRetrieve payments on multiple invoices (or sales documents), IDs separated by commas. Eg. "1,2,3,4,5".String
dateFromFilter payments by date range.Date (yyyy-mm-dd)
dateToDate (yyyy-mm-dd)
typeFilter payments by type. For a more detailed explanation of possible payment types, see the "type" field below.String(10)
excludeStoreCreditPayments0 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
searchAttributeNameSearch from attribute name.searchAttributeName and searchAttributeValue have to be specified bothString
searchAttributeValueSearch from attribute valueString
changedSinceRetrieve 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)
recordsOnPageNumber of records API should return. By default 20, at most 100.Integer
pageNoAPI 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 nameTypeDescription
paymentIDInteger
documentIDIntegerID 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.
customerIDIntegerID of the customer who made the payment. In most cases, it should be the same as the customer who received the invoice.
typeIDIntegerPayment type ID. See getPaymentTypes.
typeString(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.
dateDateeg. 2010-01-29
sumDecimalPaid amount
currencyCodeStringCurrency code: EUR, USD.
currencyRateDecimaleg. 1.25543
Exchange rate of the payment currency against system's default currency.
cashPaidDecimal
cashChangeDecimal
infoString(255)Information about the payer. Deprecated name: "receipt_payer".
cardHolderString(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.
cardNumberString(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.
cardTypeString(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.
authorizationCodeString(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.
referenceNumberString(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.
isPrepaymentInteger (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.

bankAccountString(255)Receiver's account number or IBAN.
bankDocumentNumberString(255)Transaction number.
bankDateString(255)Date of wire transfer.
bankPayerAccountString(255)Payer's account number or IBAN.
bankPayerNameString(255)Payer's name.
bankPayerCodeString(255)Payer's ID code (for persons) or registry code (for companies).
bankSumString(255)Paid amount.
bankReferenceNumberString(255)Reference number specified on the wire transfer.
bankDescriptionString(255)Description of the wire transfer.
bankCurrencyString(255)Currency code.
archivalNumberString(255)Archival number of the transaction.
*************
storeCreditInteger (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.
paymentServiceProviderStringAPI 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.
aidString(20)API only returns this field if "Cayan / Merchant Warehouse payment data" or "PAX payment data" module is enabled on your account.
applicationLabelString(30)API only returns this field if "Cayan / Merchant Warehouse payment data" or "PAX payment data" module is enabled on your account.
pinStatementString(30)API only returns this field if "Cayan / Merchant Warehouse payment data" module is enabled on your account.
cryptogramTypeString(10)API only returns this field if "Cayan / Merchant Warehouse payment data" module is enabled on your account.
cryptogramString(30)API only returns this field if "Cayan / Merchant Warehouse payment data" module is enabled on your account.
expirationDateString(10)API only returns this field if "Cayan / Merchant Warehouse payment data" module is enabled on your account.
transactionNumberString(20)API only returns this field if "PAX payment data" module is enabled on your account.
entryModeString(20)API only returns this field if "Element TriPOS payment data" module is enabled on your account.
signatureNotRequiredInteger (0 or 1)API only returns this field if "Element TriPOS payment data" module is enabled on your account.
transactionIdString(20)API only returns this field if "Tyro payment data" module is enabled on your account.
addedUnix timestampCreation time.
lastModifiedUnix timestampLast modification time.
attributesArrayAdditional attributes. Each item looks like this:

Field nameTypeDescription
attributeNameStringAttribute name
attributeTypeStringAttribute type
attributeValueStringAttribute value