_Confirmo merchant API_ consists of the APIs for the Merchant communication with the Confirmo.com service. **Be sure to use HTTPS protocol.** All API requests are redirected to HTTPS, thus most of the plain HTTP requests won't work (those using PUT, POST, or PATCH methods). **Please be aware that this API is subject to change.** Confirmo can add some new fields. Please, remember that when writing your clients. Your client is required to ignore any fields it does not know. ## Authentication Currently, this API supports only one model of authentication - _API keys_. The keys are private for every merchant and should only be used to access your invoices and settlements from the outside of the user interface. #### API key management API keys can be created and deleted in the user interface. After you log in to your account, navigate to `Settings` and continue to the `API Keys` section. The new key will be created and its token will be displayed for a limited time. Make sure to store it in a __safe__ place as it will not be accessible via the UI for security reasons later. Each token will provide read/write access outside the UI to your account. It will remain valid until its deletion in the UI. #### API key best practices When you use API keys in your applications, keep them secure. Publicly exposing your credentials can result in your account being compromised. To keep your API keys secure, follow these best practices: * __Do not embed API keys directly in code__: API keys embedded in code can be accidentally exposed to the public. For example, if you forget to remove the keys from the code that you share. Instead of embedding your API keys in your applications, store them in environment variables or files outside your application's source tree. * __Do not store API keys in files inside your application's source tree__: If you store API keys in files, keep the files outside your application's source tree to help ensure your keys do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub. * __Restrict your API keys to IP addresses that need them__: By restricting the IP addresses that can use each key, you can reduce the impact of a compromised API key. * __Delete unneeded API keys__: To minimize your exposure to attack, delete any API keys that you no longer need. * __Review your code before publicly releasing it__: Ensure that code does not contain API keys or any other private information before you make your code publicly available. #### API key usage Each request made from the outside of the application must include an `Authorization` header containing a valid API key token. Example using curl:

  
    curl https://confirmo.net/api/v3/invoices -H 'Authorization: Bearer {YOUR_API_KEY}'

## Status codes API responses are marked with status codes: * `200 OK` Request resolved * `201 Created` Request resolved by successfully creating a new object in the system * `204 No Content` Request resolved and no content is returned * `400 Bad Request` Invalid format of request * `401 Unauthorized` Invalid or missing API key in the request header * `403 Forbidden` Authorized but not to access the particular resource * `500 Internal Server Error` The server has encountered an unexpected condition; please contact support@confirmo.net * `503 Service Unavailable` The server could not fulfill your request; please contact the Confirmo support ## Idempotent requests Selected endpoints accept an optional `Idempotency-Key` request header to prevent duplicate transactions in cases such as retries caused by network issues or delays. Endpoints that support it note `Idempotency-Key` support in their description. When you supply the header, the value must be a non-empty, printable-ASCII string of at most 255 characters. We recommend generating a fresh UUID for each logical operation. Using the same idempotency key for multiple requests ensures that only the outcome of the original request is ever returned. Confirmo saves the first response and reuses it for any subsequent requests with that same key, without re-executing the operation. Note that when the request failed, you will have the original error response available only on the first call, on the retry with same idempotency key only a generic `409` + `idempotency_key_previously_failed`. The stored response remains available for 24 hours. After that period a new idempotency key must be used. Error responses all share the shape `{ "message": ..., "error": ... }`, where `error` is a stable machine-readable code. `400 Bad Request` — the supplied key is malformed (empty, longer than 255 characters, or containing non-printable-ASCII characters): ```json { "message": "Idempotency-Key must be non-empty, at most 255 printable-ASCII characters.", "error": "idempotency_key_invalid" } ``` `409 Conflict` — the same key was already used with different request parameters (body or query): ```json { "message": "This Idempotency-Key was already used with different request parameters (body or query).", "error": "idempotency_key_reused_with_different_body" } ``` `409 Conflict` — the same key was already used on a different endpoint: ```json { "message": "This Idempotency-Key was already used on a different endpoint.", "error": "idempotency_key_reused_on_different_endpoint" } ``` `409 Conflict` — a request with this key is still being processed: ```json { "message": "A request with this Idempotency-Key is still being processed.", "error": "idempotency_key_in_progress" } ``` `409 Conflict` — the original request with this key failed; retry with a new key: ```json { "message": "The original request with this Idempotency-Key failed, retry with a new Idempotency-Key.", "error": "idempotency_key_previously_failed" } ``` ## Notifications The _Confirmo merchant API_ allows merchants to enable simple notifications as part of invoice creation. These notifications are of the following types: * [webhook notifications](#webhook-notifications) * [e-mail notifications](#email-notifications) Notifications are sent on the following occasions: 1. invoice creation; 2. change of invoice status; 3. received payment/outgoing payment (refund). ### Webhook notifications If `notifyUrl` is defined in an invoice creation request, then the system tries to send an HTTP `POST` request with `Content-Type` set to `application/json` to the URL. The request's body contains the current invoice model (same as creating a new invoice response). By default, the system will continue to send the notification until it receives `200` response or stops after 20 tries. After the first failed try it will wait for 1 second. The waiting period is doubled after each failed request. If the system fails to send a successful request, it will try to send an error report via e-mail. It is sent on `notifyEmail` if it was specified or on the merchant's user e-mail otherwise. This e-mail contains our error message and error response to the last unsuccessful request. #### Callback Password __A callback password__ is an autogenerated pseudo-random alphanumeric string used as a data validation mechanism for stronger security. When a callback password is created, it is used to generate signatures that are included in every webhook notification **request header**. The signature is generated - and **needs to be validated** (to ensure that the webhooks do originate from Confirmo and were not forged by someone else) - by 1. taking the request/response body; 2. suffixing it with the callback password; 3. hashing the result using the SHA256 algorithm; 4. storing the hexadecimal representation in the `bp-signature` header field of the request/response. ##### Example - Callback password: `azLlmIpWHM9NJbMe` - Response body: `{"address":"P3n6Ul5FsSd59xfbzdD2VN3HHycIddjpc","cryptoUri":"bitcoin:P3n6Ul5FsSd59xfbzdD2VN3HHycIddjpc?amount=0.00779057","createAtTime":1509525927,"serverTime":1509525927,"timeoutTime":1509526226,"id":"inv57dkwrrdw","url":"https://pay.confirmo.com/public/invoice/inv57dkwrrdw","reference":"{\"customerEmail\": \"customer@example.com\", \"orderNumber\": 123, \"customerName\": \"Customer Name\"}","returnUrl":"http://yourEShop.com/thankYourForYourOrder","notifyUrl":"https://yourEShop.com/orderReceived","notifyEmail":"notify@email.com","product":{"name":"pName","description":"pDesc"},"status":"active","rate":{"currency":"EUR","currencyX":"BTC","rate":"6418.02"},"txids":[],"invoice":{"amount":"50.00","currency":"EUR"},"crypto":{"amount":"0.00779057","currency":"BTC"},"invoiceSettlements":[],"refunds":[],"paid":{"amount":"0.00000000","currency":"BTC","diff":"-0.00779057"},"flags":{"split":false,"autoUnderpayment":false,"refundable":false},"paidAtTime":0,"completedAtTime":0,"settlementMethodCurrency":"CZK","confirmations":0,"requiredConfirmations":2,"exception":[]}` - SHA256 ** input**:`{"address":"P3n6Ul5FsSd59xfbzdD2VN3HHycIddjpc","cryptoUri":"bitcoin:P3n6Ul5FsSd59xfbzdD2VN3HHycIddjpc?amount=0.00779057","createAtTime":1509525927,"serverTime":1509525927,"timeoutTime":1509526226,"id":"inv57dkwrrdw","url":"https://pay.confirmo.com/public/invoice/inv57dkwrrdw","reference":"{\"customerEmail\": \"customer@example.com\", \"orderNumber\": 123, \"customerName\": \"Customer Name\"}","returnUrl":"http://yourEShop.com/thankYourForYourOrder","notifyUrl":"https://yourEShop.com/orderReceived","notifyEmail":"notify@email.com","product":{"name":"pName","description":"pDesc"},"status":"active","rate":{"currency":"EUR","currencyX":"BTC","rate":"6418.02"},"txids":[],"invoice":{"amount":"50.00","currency":"EUR"},"crypto":{"amount":"0.00779057","currency":"BTC"},"invoiceSettlements":[],"refunds":[],"paid":{"amount":"0.00000000","currency":"BTC","diff":"-0.00779057"},"flags":{"split":false,"autoUnderpayment":false,"refundable":false},"paidAtTime":0,"completedAtTime":0,"settlementMethodCurrency":"CZK","confirmations":0,"requiredConfirmations":2,"exception":[]}azLlmIpWHM9NJbMe` - SHA256 **output** as a hex string (and the value of the `bp-signature` header field): `08468c5b3af81ca14fe5a3b40703773175cba2cc3ef8700e62e943edd4cba3ee` ##### Creating/Deleting To create a callback password, use *Security Settings* in Merchant UI. Merchant can create only one callback password. A unique callback password is generated every time and becomes active right away. Deleting the callback password deactivates the mechanism (`BP_SIGNATURE` is no longer included). #### Final Status Check **It is not recommended to rely on webhook data only.** In case that callback password gets compromised, an attacker would still be able to forge the webhooks. Therefore, after receiving a webhook about reaching a final status of an entity (such as `paid` status for invoice), it's advised to cross-check the result by invoking Confirmo API endpoint for getting details of the entity (such as GET invoice endpoint). This is the ultimate source of truth even in case that somebody managed to forge the webhook. ### Email notifications The system supports two types of email notifications in invoice creation request, each serving a different purpose: #### Merchant Notifications (`notifyEmail`) - Sends basic invoice information in human-readable format to the specified email address - Notification are sent: - When HTTPS notifications fail (see above) - When invoice payment is successful - When invoice expires and enters exception state - **Important**: Do not use customer email addresses here, as those notifications may contain merchant-specific information #### Customer Notifications (`customerEmail`) - Notifies customers about important invoice status changes: - When invoice payment is successful - When invoice expires and enters exception state - Should contain the end-customer's email address only - Note that the customer email can be set also by end-customer on the public invoice when the invoice is in Confirming state ## Entity states ### Invoice ![Invoice state diagram](https://confirmo-test.s3.eu-central-1.amazonaws.com/Invoice-diagram.svg) - `prepared` - customer selects preffered payment method. Status `prepared` exists only if the [Create invoice](#/Invoice/createInvoiceByMerchant") endpoint is called with parameter `invoice.currencyTo= null`, otherwise the end-customer will not be able to select crypto of their choice. It enters `active` state, or `expired` state after 15 minutes of inactivity. - next states: `active`, `expired` - `active` - Invoice with payment instructions including crypto address, crypto asset, crypto network, amount, currency... By default, the invoice is active for 15 min. Expiration time can be adjusted from *Invoice Settings*. - next states: `expired`, `confirming` - `expired` - No payment has been sent within its active period or the amount sent is smaller than the requested amount. An `expired` invoice may have a so-called `exception` [flag](#exception). - final state for invoices with [exception flag](#exception) set to `false`. - next state: `paid` for invoices with [exception flag](#exception) set to `true` and were accepted/taken by the merchant. - `confirming` - payment detected, the amount is correct or higher, but the payment is not finished (usually it means it has not enough confirmations) on its crypto network yet - next states: `error`, `paid` - `error` - confirming failed. Transaction is not confirmed within next 96 hours. - final state - `paid` - the invoice has been credited to the merchant's account and has sufficient confirmation(s). - final state #### Exception `unhandledExceptions` is a special flag informing merchants about an invoice that may need attention. `unhandledExceptions` set to `true` indicates the invoice is **overpaid**, **underpaid** or **incorrect amount** has been sent to an `expired` invoice. Invoices with `unhandledExceptions = true` share the following behavior: 1. Invoices are refundable from invoice `url`. However, only paying customer is allowed to request a refund from invoice `url` for security reasons. Merchant can initiate refund from invoice detail in his dashboard. 2. `paid` invoice. Only overpayment and not the whole amount is refundable. Invoice remains in state `paid` all time. 3. `expired` invoice. The whole amount is refundable. The merchant can review the invoice and accept the payment to his balance additionally. Once the payment is credited to merchant's balance the status of the invoice changes to `paid`. The invoice is no longer refundable and `unhandledExceptions` is set to `false`. 4. If the additional payment is sent to resolved (already refunded or credited) invoice `unhandledExceptions` is set to `true` again. 5. We do not mark invoices with an exception flag if the amount of overpayment or underpayment is very low and the refunding amount would cost more than the network fee or very close to the network fee. 6. Payment that matches rules specified in Dashboard in [Underpayment threshold](https://dashboard.confirmo.com/platform/settings/invoice) have `unhandledExceptions` set to `false`. #### Data Purging Please note that invoices which transition directly from `prepared` to `expired` status (i.e. those which never had their `customerCurrency` (or more generally payment method) set) are subject to data purging after some retention period (e.g. a year). ### Payout ![Payout state diagram](https://confirmo-test.s3.eu-central-1.amazonaws.com/Payout-diagram.svg) - `prepared` - new payout - next states: `confirmed`, `expired` - `confirmed` - Exchange rate has been accepted by a merchant - next state: `sending` - `sending` - payout prepared to be sent. Payouts are sent on a regular basis - next state: `done` - `done` - payment was successful and txid is known - final state - `expired` - payout that has not been `confirmed` in given time. - final state #### Data Purging Similar to invoices, payouts which transition directly from `prepared` to `expired` status are subject to data purging after some retention period (e.g. a year). ## Overlay - no redirection to confirmo.com website To open an invoice in the overlay instead of redirecting the user to our page. Follow these steps in the [library](https://www.npmjs.com/package/@confirmo/overlay) documentation. ## Integration tips - If the notification is not received, please check that `notifyUrl` is specified correctly, a valid SSL certificate is installed on your server and the `notifyUrl` starts with https:// not http://. Verify your notification handler script is receiving POST's. - Once your notification handler receives a response, especially when `paid` status is announced, it is recommended to call [Get invoice detail](#/Invoice/getInvoiceByMerchant) to verify notification data. - It is not recommended to rely on [webhook notification](#webhook-notifications) POST's data only. - Please make sure, that the payment URL is not public nor available for search engines. - It is possible to request a refund via payment URL if the payment was sent incorrectly, so please be very cautious and consider security. Even your support staff can request a refund via payment URL. ## Invoice creation When [creating a new invoice](#/Invoice/createInvoiceByMerchant), the following parameters are the most important ones. | Parameter name | Required | Description | Example | Dedicated Section | |------------------------|----------|--------------------------------------|---------|-------------------------------------------------------| | `invoice.amount` | Yes | The original invoice's amount | 100 | [Invoice original amount](#invoice-original-amount) | | `invoice.currencyFrom` | Yes | Code of the original invoice's asset | USD | [Invoice original amount](#invoice-original-amount) | | `invoice.currencyTo` | No | Code of the payment asset | BTC | [Invoice payment asset](#invoice-payment-asset) | | `settlement.currency` | Yes* | Code of the settlement asset | EUR | [Invoice settlement asset](#invoice-settlement-asset) | * Technically, it's `settlement` (not `settlement.currency`) attribute which is required, i.e. sending a request with an empty `settlement` attribute is also valid (and it's equivalent to sending a request with `settlement.currency = null`). ### Invoice original amount Parameter `invoice.currencyFrom` (code of the original invoice's asset) can be set to almost any world fiat currency (`USD`, `EUR`, `CHF`, … ) and also to `BTC`, please refer to [Get assets endpoint](#/Assets/getAssets) to get list of the currently supported assets (those with `merchantAsset=true`). ### Invoice payment asset Parameter `invoice.currencyTo` is highly recommended to be set to _null_. If set to _null_, the invoice is created and the status of the invoice is set to **prepared**, which allows the customer to select any supported payment methods. Supported payment methods can be enabled/disabled in the dashboard. It's also possible to set it to: * `BTC` to pre-select payment via native Bitcoin * `BTC` (alongside with parameter `invoice.layer2ProtocolName` set to `LIGHTNING`) to pre-select payment via Bitcoin Lightning * `LTC` to pre-select payment via native Litecoin Should you need to create an invoice with other predefined payment method, please contact us at _tech@confirmo.net_. ### Invoice settlement asset Parameter `settlement.currency` configure s the settlement asset in which we credit merchant balance. There are two main options to choose from described in the following subsections. #### Without conversion (Keep in kind) If you set `settlement.currency = null` when creating an Invoice, all the payments sent to the Invoice will be credited to the merchant account in the same crypto asset as the customer used for the payment. For instance, if the customer chooses to pay with TRX, the payment will be credited to the merchant's TRX balance. #### With conversion You can choose in which asset you want to be credited; to do so, use `settlement.currency = `. In this case, all the payments to the Invoice will be converted to the settlement asset you set. Currently, we support the following settlement assets: | `settlement.currency` | Asset name | Asset type | |-----------------------|------------------------|---------------------| | BTC | Bitcoin | Crypto | | CZK | Czech koruna | Fiat | | EUR | Euro | Fiat | | GBP | British pound sterling | Fiat | | HUF | Hungarian forint | Fiat | | PLN | Polish zloty | Fiat | | USD | United States dollar | Fiat | | USDC | USD Coin | Crypto (stablecoin) | | USDT | Tether USD | Crypto (stablecoin) | ### Sample combinations | `invoice.currencyFrom` | `invoice.currencyTo` | `invoice.layer2ProtocolName` | `settlement.currency` | Description | |------------------------|----------------------|------------------------------|-----------------------|--------------------------------------------------------------------------------------| | `USD` | _null_ | | `EUR` | USD invoice to be paid by a customer-chosen method and credited in EUR | | `GBP` | _null_ | | `USDC` | GBP invoice to be paid by a customer-chosen method and credited in USDC | | `BTC` | `BTC` | `LIGHTNING` | `USDT` | BTC invoice to be paid by Bitcoin Lightning and credited in USDT | | `EUR` | _null_ | | _null_ | EUR invoice to be paid by a customer-chosen method and credited in the payment asset | | `CHF` | `LTC` | | `BTC` | CHF invoice to be paid by Litecoin and credited in BTC | ## Developers ### Postman When you have downloaded [the OpenAPI specification](./confirmo-api.json), you can import it to [Postman](https://www.postman.com/). The tool will generate all the endpoints and code snippets, which you could use in your application.

### Swagger tools If you insert the downloaded OpenAPI specification into [Swagger editor](https://editor.swagger.io/), you could then generate a Client SDK that you will be able to use for integration Confirmo API into your application. You can use [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) or [OpenAPI Generator](https://openapi-generator.tech/) too.

400Fiat withdrawal account not found, not owned, or already deleted.

403Forbidden

409Conflict