invoice
The invoice model is intended for invoicing customers and replenishing the merchant's balances by the merchant itself.
Customer's choice of the payment method is restricted by the payway/s that is/are specified by the merchant.
Parameter is_multipay defines the criteria for crediting funds to the merchant:
- is_multipay = true - funds are credited to the merchant's balance only after receiving the full amount, indicated
in the invoice.
If the amount of the base payment is less than the invoiced, the client can pay extra or return the funds are already transferred. In case of overpayment - the client can get the change back.
- is_multipay = false - client can't surcharge or return funds. The amount of payment immediately and in full, excepts for the fee, credited to the merchant's balance. In this case, the payway must be specified.
The share of the fee total amount for receipts paid by the merchant is determined by the value of the merchant_payfee argument [0..1], the rest of the commission is paid by customers. The operating costs of a refunds are always beared by customers.
Using the invoice model methods the merchant can:
- Create a payment invoice - method invoice.create;
- Calculate preliminary invoice parameters - method invoice.calc;
- Get information of the selected invoice - method invoice.get.
endpoint
Queries for the model's methods are sent to endpoint https://api.any.money/.
invoice.create
The method to create an incoming payment order, taking into account the amounts of invoice and payment.
Input method arguments
| Param | Required | Example | Description |
|---|---|---|---|
| amount | yes | "1000,25" | invoice-payment amount |
| externalid | yes | "123" | unique ID specified by the merchant |
| in_curr | yes | "UAH" | invoice-payment credit currency |
| callback_url | no | "https://callback_example.com" | url-address for order status change messages. Messages format |
| client_email | no | "[email protected]" | email payer's address for notifications about changes in the status of an invoice payment |
| comment | no | "some info for order #1234" | comment for invoice-payment (won't be returned in invoice representation) |
| is_multipay | no | false | the flag providing the surcharge and receiving a refund possibility (true = surcharge and return are possible, false = blocked). default=false |
| lifetime | no | "1d12h" | "lifetime" of the order, in seconds or in the timedelta format (the string like "1w1d1h1m1s1ms"). The valid value range is ["7d" .. "3600s"]. default = "7d" |
| merchant_payfee | no | "0,35" | the share of the incoming payments fee paid by the merchant (values in the [0..1] range, accurate to two decimal places. 0=0%..1=100% |
| out_curr | no | "USD" | optional debit currency of the invoice-payment |
| payway | no | "card" | payway for the replenishment (options: "btc", "perfect", "qiwi" ... etc.). For a merchant linked to payway (typed), only a linked payway is available). Required if is_multipay = false. |
| redirect_url | no | "https://example.com/order_page/" | url-address for redirecting the user after method executing or pressing the "Back" button |
Caution!
If the payway name is transmitted to the method, make sure to transmit the following arguments for the corresponding payment system together with it:
Required arguments for the payways
- qiwi
-
- payer - payer bank details (wallet number in the cryptopatway) (e.g. +380123456789)
- payoneer
-
- payer - payer's email (e.g. [email protected]).
- exmo, kuna, anycash
-
- code - full code payway number. Required argument if
is_multipay = false. - code - full code payway number. Required argument if
- cash
-
- contact - payer's contact info: phone number or telegram account (e.g. "+380441232344")
- country - payment country name (e.g. "ukraine")
- region - payment region name (e.g. "kiev")
- iban
-
- payer - full name of the payer (it must match the name of the account holder from which the transfer will be made)
If the name of the transmitted debit currency (out_curr) name differs from the credit currency name (in_curr), after successful finalization of the order will be made an attempt to convert the received amount into the debit currency at the actual rate. If successful, the funds will be debited to the debit currency balance, otherwise - to the credit currency balance. If the transmitted debit currency name is equal to the credit currency name the invoice.create method will ignore the out_curr argument value.
If the query does not contains the out_curr the currency with the name in_curr will be credited to the balance.
timedelta values are transmitted in pairs: <value><key><value><key> ... <value><key> without spaces between
pairs. Only seconds can be transmitted as a keyless value. But, if in timedelta line presents at least one
key, the whole string must ends with a key, not a digit. Otherwise an error will be raised.
Caution!
For typed merchants, the transmitted payway must match the type of merchant, otherwise the method will return an error
Method response data
order representation of the incoming payment
Exceptions
- EParamAmountFormatInvalid
- amount argument wrong format
- EParamAmountTooBig
- amount exceeds the operation maximum amount
- EParamAmountTooSmall
- amount is less than the operation minimum amount
- EParamCurrencyInvalid
- no currency in a system
- EParamFieldInvalid
- invalid callback_url argument
- EParamInvalid
-
- required argument missed
- transmitted lifetime expired
- cryptoaddress for payment receiving not found or not generated
- wrong format of email or timedelta
- merch_fee and merchant_payfee transmitted simultaneously
- is_multipay and is_multypay transmitted simultaneously
- expiry and lifetime transmitted simultaneously
- transmitted payway does not match the merchant type
- EParamPaywayInvalid
- the wrong payway
- EParamPeriodInvalid
- the wrong format of the expiry, lifetime, timedelta arguments
- EParamPeriodTooLong
- lifetime value exceeds the acceptable system maximum
- EParamPeriodTooShort
- lifetime value is less than the acceptable system minimum
- EParamUnique
- an order with such externalid already exists
- EStateCurrencyInactive
- inactive deposit currency has been transmitted
- EStateCurrencyUnavail
- unavailable deposit currency has been transmitted
- EStatePaywayInactive
- inactive payway
- EStatePaywayUnavail
- the payway is administratively blocked
- EStatePwcurrencyUnavail
- payway currency is not available for current merchant
- EStatePwcurrencyInactive
- payway currency is inactive for current merchant
invoice.calc
The method of calculating the invoice payment parameters, taking into account the amount of debit sum.
Input method arguments
| Param | Required | Example | Description |
|---|---|---|---|
| amount | yes | "500" | input payment amount |
| in_curr | yes | "USD" | credit currency |
| out_curr | no | "USD" | debit currency |
| payway | no | "anycash" | paway for the possible payment |
Caution!
For typed merchants, the transmitted payway must match the type of merchant, otherwise, the method will return an error
Method response data
- account_amount
- debit amount excepts for the fee amount
- in_amount
- credit amount
- orig_amount
- amount set when creating an order
- out_amount
- amount debited to the merchant balance
- rate
- convertation rate, if convertation tooks place
Exceptions
- EParamAmountFormatInvalid
- amount argument wrong format
- EParamAmountTooBig
- amount exceeds the operation maximum amount
- EParamAmountTooSmall
- amount is less than the operation minimum amount
- EParamCurrencyInvalid
- no currency in a system
- EParamInvalid
-
- wrong argument volume
- payway does not match to the merchant type
- EParamPaywayInvalid
- wrong payway
- EStateCurrencyInactive
- credits in the credit currency cannot be made - it is inactive in the transferred payway or in Any.Money
- EStateCurrencyUnavail
- currency is invalid in transmitted payway
- EStatePaywayInactive
- inactive payway
- EStatePaywayUnavail
- payway is administratively blocked
- EStatePwcurrencyUnavail
- payway currency is not available for current merchant
- EStatePwcurrencyInactive
- payway currency is inactive for current merchant
invoice.get
Method for invoice-payment parameters requesting by its external ID.
Input method arguments
| Param | Required | Example | Description |
|---|---|---|---|
| externalid | yes | "257" | unique ID specified by the merchant |
Method response data
order representation of incoming payment transaction
Exceptions
- EParamInvalid
- empty externalid or has a wrong type or value
- EParamNotFound
- order with transmitted externalid not found