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.
If a payment is not associated with any sales document, it represents a deposit (a prepayment, customer's store credit) and can be used to pay off unpaid invoices.
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.)
To make savePayment calls idempotent, use the "temporaryUUID" field.
| Parameter name | Description | Possible value | Required |
|---|---|---|---|
| paymentID | Payment ID. Set this parameter to edit an existing payment. Omit it to create a new payment. |
integer | |
| customerID | Customer ID. Not required when updating an existing payment. |
integer | |
| documentID | Invoice ID. If specified, you do not need to specify customerID — API will set customer ID equal to invoice customer if input parameter customerID is omitted.Not required when 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. Format: yyyy-mm-dd. |
string | |
| time | eg. 12:00:00 This can only be used together with date field. Value will be ignored when used together with added parameter. |
Time | |
| 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) | |
| authorizationCode | Card payment authorization code. | String(255) | |
| referenceNumber | Card payment reference number. | 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", "entryMethod", "applicationLabel", "transactionType" 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".To store a Givex payment, you need to specify paymentServiceProvider = "givex". Your account also needs to have the "Givex payment data" module enabled. The fields that you can set for a Givex payment are "certificateBalance", "transactionType", "statusMessage", "statusCode" and "expirationDate". |
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" or "Givex payment data" module enabled (otherwise returns error 1006). | String(10) | |
| entryMethod | Use this field only if you have "PAX payment data" module enabled (otherwise returns error 1006). | String(20) | |
| transactionType | Use this field only if you have "PAX payment data" module enabled (otherwise returns error 1006). | String(30) | |
| 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) | |
| transactionType | Use this field only if you have "Givex payment data" module enabled (otherwise returns error 1006). | String(30) | |
| 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) | |
| certificateBalance | Use this field only if you have "Givex payment data" module enabled (otherwise returns error 1006). | Decimal string or empty string | |
| statusCode | Use this field only if you have "Givex payment data" module enabled (otherwise returns error 1006). | Integer string or empty string | |
| statusMessage | Use this field only if you have "Givex payment data" module enabled (otherwise returns error 1006). | String(100) | |
| 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) | |
| isReservation | A flag which you can apply to indicate that this payment is a reservation. Payments that have been marked as reservation will be omitted from transaction reports until the flag is removed. | Integer (0 or 1) | |
| giftCardVatRateID | If the payment is a gift card payment, indicate the tax rate (VAT rate) the gift card was originally sold with. If left unset, or set to 0, Erply will assume that the gift card was sold with 0% tax. If a gift card has been sold with tax, and customer redeems the gift card, Erply back office and Erply Books will need to be aware of that. The amount of goods and services that corresponds to the gift card's value no longer needs to be taxed, as tax has already been paid once. For this sales transaction, Erply will then produce a printout that indicates the taxable total is correspondingly smaller. Set this field only if payment type is |
integer | |
| jdoc | Attach extra information to the payment, in JSON format. To ensure interoperability, only certain JSON properties, defined by Erply, are allowed. The contents of the field are validated using a JSON schema, and the schema is globally the same for all Erply accounts. Thus this field is best suited for standard applications that get used on many accounts. The general pattern is that each application, integration or workflow stores its data under its own top-level object (a namespace). All custom properties added by Brazil POS are under BrazilPOS.*, for example.API clients that modify existing documents and add data to JSON must take care to preserve the data created by other applications, too. This is the same data that can be retrieved and saved using standalone calls in JSON API. |
string | |
| 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 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) | |
| temporaryUUID | Optional id value. Used as custom identification on creating new payments. Can be used as a unique value to identify new payment creation requests for duplicate requests prevention. A valid value can contain characters a-z+A-Z+0-9, symbols (. and -) and can be maximum of 128 characters long. | string | |
| ***** | 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 |
| Field name | Type | Description |
|---|---|---|
| paymentID | integer | ID of the newly-created item |