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    
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    
searchAttributeName  Search from attribute name.searchAttributeName and searchAttributeValue have to be specified both  String    
searchAttributeValue  Search from attribute value  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    

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.

 
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") 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.  
expirationDate  String(10)  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.  
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