savePayment

Create or update a payment.

In ERPLY, a payment is associated with a customer, and optionally an invoice (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 list payments, see getPayments.

A typical use case for the savePayment API call is recording a sale (that has been made in POS or in a web shop). In that case, send a saveSalesDocument API call, followed by savePayment.

See also calculateShoppingCart. That API call helps you calculate cart total, and also gives instructions regarding other retail features (issuing and redeeming coupons etc.)

Input parameters

Parameter name Description Possible value Required
paymentID  Payment ID.
If this parameter is present the specified payment will be updated. 
Integer    
customerID  Customer's unique ID.
Not required if updating an existing payment. 
Integer    
documentID  Invoice ID.
If specified, you don't need to specify customerID — API will set customer ID equal to invoice customer.
Not required if updating an existing payment.

If you want to save an invoice and its associated payment together in one bulk request, set this field to a special value: "CURRENT_INVOICE_ID". Normally, creating two records where one references the other cannot be done within one bulk request; you would have to retrieve one record's ID before you can create the other. This is a special workaround for savePayment, saveGiftCard, saveIssuedCoupon, redeemIssuedCoupon, and subtractCustomerRewardPoints.

Note that if saving the invoice results in an error, the payments, coupons etc. will be created nevertheless, but without a reference to any invoice. For better error checking you may still want to do saveSalesDocument as a separate request. 
Integer    
type  There are two ways for specifying payment type: either by its code name (field "type") or ID (field "typeID").

Standard code names recognized by ERPLY are CASH, TRANSFER, CARD, CREDIT, GIFTCARD, CHECK, TIP — but you can also create your own custom code names with savePaymentType.

By default: TRANSFER

Explanation:
CASH - in cash.
TRANSFER - by wire transfer.
CARD - by credit or debit card.
CHECK - by check.
CREDIT - via 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.
GIFTCARD - with a gift card. 
String    
typeID  Payment type ID. If you set field "type" (see above), "typeID" is not necessary. For a list of payment types, see getPaymentTypes Integer    
date  eg. 2010-01-29
If omitted, current date will be used. 
Date    
sum  Payment sum. If omitted, 0.00 will be used.  Decimal    
cashPaid  If omitted, 0.00 will be used.  Decimal    
cashChange  If omitted, 0.00 will be used.  Decimal    
currencyCode  Currency code: EUR, USD. Currency must be defined in Erply. If omitted, or an unknown currency code is provided, API uses your default currency instead. If editing an existing payment, currency code is not necessary.  String (3)    
info  Information about the payer or payment transaction.  String(255)    
cardHolder  Cardholder's name (empty if not card payment or if the information has not been supplied)  String(255)    
cardNumber  Last 4 digits of credit card number (empty if not card payment or if the information has not been supplied). Erply does not store full credit card numbers.  String(255)    
cardType  Credit card type, eg. VISA, AMEX, M/C etc. (empty if not card payment or if the information has not been supplied) Erply's Z Report displays card payments separately by type.  String(255)    
signature  Cardholder's signature. Signature encoding and encryption methods are UNSPECIFIED at the moment. Additionally in case of encryption, both parties must share a common encryption key. Not available in all accounts (savePayment may return an error if either signature or signatureIV is set)  String (up to 65,535 B)    
signatureIV  Initialization vector to be used if the signature is encrypted  String (up to 65,535 B)    
addedToStoreCredit  A flag indicating that this payment is a contribution to customer's store credit account, and it is not specifically meant for paying a particular invoice.

System will try to associate it with any previous unpaid invoices the customer might have. 
Integer (0 or 1)    
paymentServiceProvider  This field is required for disambiguation if you want to set integration-specific fields.

Most importantly, it is necessary if you want to set the "aid" or "applicationLabel" fields; API needs to know whether you intend to store a PAX payment or a Cayan payment, as they both have fields with that name.

To store a PAX payment, you need to specify paymentServiceProvider = "pax". Your account also needs to have the "PAX payment data" module enabled. The fields you can set for a PAX payment are "aid", "applicationLabel" and "transactionNumber".

To store a Cayan (Merchant Warehouse) payment, you need to specify paymentServiceProvider = "merchant_warehouse" or leave it unset. Your account also needs to have the "Cayan / Merchant Warehouse payment data" module enabled. The fields that you can set for a Cayan payment are "aid", "applicationLabel", "pinStatement", "cryptogramType", "cryptogram", and "expirationDate".

To store a Tyro payment, you need to specify paymentServiceProvider = "tyro". Your account also needs to have the "Tyro payment data" module enabled. The field you can set for a Tyro payment is "transactionId".

To store a Klarna payment, you need to specify paymentServiceProvider = "klarna". Your account also needs to have the "Klarna payment data" module enabled. The field you can set for a Klarna payment is "klarnaPaymentID". 
String    
aid  Use this field only if you have "Cayan / Merchant Warehouse payment data" or "PAX payment data" module enabled (otherwise returns error 1006).  String(20)    
applicationLabel  Use this field only if you have "Cayan / Merchant Warehouse payment data" or "PAX payment data" module enabled (otherwise returns error 1006).  String(30)    
pinStatement  Use this field only if you have "Cayan / Merchant Warehouse payment data" module enabled (otherwise returns error 1006).  String(30)    
cryptogramType  Use this field only if you have "Cayan / Merchant Warehouse payment data" module enabled (otherwise returns error 1006).  String(10)    
cryptogram  Use this field only if you have "Cayan / Merchant Warehouse payment data" module enabled (otherwise returns error 1006).  String(30)    
expirationDate  Use this field only if you have "Cayan / Merchant Warehouse payment data" module enabled (otherwise returns error 1006).  String(10)    
transactionNumber  Use this field only if you have "PAX payment data" module enabled (otherwise returns error 1006).  String(20)    
transactionId  Use this field only if you have "Tyro payment data" module enabled (otherwise returns error 1006).  String(50)    
transactionTime  Use this field only if you have "Transaction Time of a Payment" module enabled (otherwise returns error 1028).

This is used for a Verifone Finland or a Nixpay payment. 
Unix timestamp    
klarnaPaymentID  Use this field only if you have "Klarna payment data" module enabled (otherwise returns error 1006).  String(40)    
isPrepayment  A flag, which you can apply to indicate that this payment has originally been a prepayment (meaning that it was associated with a Prepayment Invoice or a Sales Order). Payments that are currently associated with a Prepayment Invoice, or a Sales Order, are typically not marked with this flag!  Integer (0 or 1)    
added  If not set, server will assign a timestamp automatically.  Unix timestamp    
***** 

Additional information about the payment from bank.

You can specify this information if you are importing wire transfer payments from bank.

All the following fields are intended as informative text fields (even bankDate and bankSum). In your own integration, you can supply this data in a well-defined format, but for payments received from other sources, we do not make any assumptions about the contents of these fields or 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.

The ability to associate multiple payments with one bank record is not currently exposed through API.

 
   
bankAccount  Receiver's account number or IBAN.  String(255)    
bankDocumentNumber  Transaction number.  String(255)    
bankDate  Date of wire transfer.  String(255)    
bankPayerAccount  Payer's account number or IBAN.  String(255)    
bankPayerName  Payer's name.  String(255)    
bankPayerCode  Payer's ID code (for persons) or registry code (for companies).  String(255)    
bankSum  Paid amount.  String(255)    
bankReferenceNumber  Reference number specified on the wire transfer.  String(255)    
bankDescription  Description of the wire transfer.  String(255)    
bankCurrency  Currency code.  String(255)    
archivalNumber  Archival number of the transaction.  String(255)    
*****  Additional attributes associated with this item.
Attributes must be supplied as a flat list, each attribute defined by the following set of three parameters. Replace # with set number (1, 2, 3, ...). When updating an existing entry, API will only update the attributes specified in input data and leave all other existing attributes unchanged. To delete an attribute, set its value to 'null' or 'undefined'.  
   
attributeName#  Attribute name. Name can only contain the following symbols: A-Z, a-z, 0-9, dash and underscore.  String    
attributeType#  Attribute type, possible types are 'text', 'int' and 'double'. By default 'text'.  String    
attributeValue#  Value of the attribute. Set value to 'null' or 'undefined' to delete an attribute.
'text' attribute can be any string, maximum 255 characters.
'int' must be a signed 32-bit integer.
'double' must be a decimal number. 
String    

Response

Field name Type Description
paymentID  Integer  ID of the newly-created item