Search

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 nameDescriptionPossible valueRequired
paymentIDPayment ID.
If this parameter is present the specified payment will be updated.
Integer
customerIDCustomer's unique ID.
Not required if updating an existing payment.
Integer
documentIDInvoice 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
typeThere 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
typeIDPayment type ID. If you set field "type" (see above), "typeID" is not necessary. For a list of payment types, see getPaymentTypes.Integer
dateeg. 2010-01-29
If omitted, current date will be used.
Date
sumPayment sum. If omitted, 0.00 will be used.Decimal
cashPaidIf omitted, 0.00 will be used.Decimal
cashChangeIf omitted, 0.00 will be used.Decimal
currencyCodeCurrency 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)
infoInformation about the payer or payment transaction.String(255)
cardHolderCardholder's name (empty if not card payment or if the information has not been supplied)String(255)
cardNumberLast 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)
cardTypeCredit 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)
signatureCardholder'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)
signatureIVInitialization vector to be used if the signature is encryptedString (up to 65,535 B)
addedToStoreCreditA 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)
paymentServiceProviderThis 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".
String
aidUse this field only if you have "Cayan / Merchant Warehouse payment data" or "PAX payment data" module enabled (otherwise returns error 1006).String(20)
applicationLabelUse this field only if you have "Cayan / Merchant Warehouse payment data" or "PAX payment data" module enabled (otherwise returns error 1006).String(30)
pinStatementUse this field only if you have "Cayan / Merchant Warehouse payment data" module enabled (otherwise returns error 1006).String(30)
cryptogramTypeUse this field only if you have "Cayan / Merchant Warehouse payment data" module enabled (otherwise returns error 1006).String(10)
cryptogramUse this field only if you have "Cayan / Merchant Warehouse payment data" module enabled (otherwise returns error 1006).String(30)
expirationDateUse this field only if you have "Cayan / Merchant Warehouse payment data" module enabled (otherwise returns error 1006).String(10)
transactionNumberUse this field only if you have "PAX payment data" module enabled (otherwise returns error 1006).String(20)
entryModeUse this field only if you have "Element TriPOS payment data" module enabled (otherwise returns error 1006).String(20)
signatureNotRequiredUse this field only if you have "Element TriPOS payment data" module enabled (otherwise returns error 1006).Integer (0 or 1)
transactionIdUse this field only if you have "Tyro payment data" module enabled (otherwise returns error 1006).String(50)
isPrepaymentA 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)
addedIf 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.

bankAccountReceiver's account number or IBAN.String(255)
bankDocumentNumberTransaction number.String(255)
bankDateDate of wire transfer.String(255)
bankPayerAccountPayer's account number or IBAN.String(255)
bankPayerNamePayer's name.String(255)
bankPayerCodePayer's ID code (for persons) or registry code (for companies).String(255)
bankSumPaid amount.String(255)
bankReferenceNumberReference number specified on the wire transfer.String(255)
bankDescriptionDescription of the wire transfer.String(255)
bankCurrencyCurrency code.String(255)
archivalNumberArchival 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 nameTypeDescription
paymentIDIntegerID of the newly-created item