Overview

🚧

Important:

We do not consider adding a new property to the PaymentIntent payload as a breaking change to the API. Please build your integration to allow for new properties to be added to this and other resources.

PaymentIntent is the central resource of this payment API.
It is a JSON object and when reading one from the API you get the following response:

{
    "id": "56d95a7a-ca9b-4fa5-9a4c-687363ddaa69",
    "state": "completed",
    "stateReason": "completed_exact_amount",
    "orderId": "123456",
    "merchant": {
        "id": "d560b17e-bae5-4fbf-8822-518273498c7a",
        "name": "Demo payment merchant"
    },
    "subaccount": null,
    "requested": {
        "amount": "100",
        "currency": "EUR"
    },
    "quotes": [
        {
            "id": "7eb9dc7e-e679-47b3-80d1-95d89454c3c6",
            "amount": "0.00364137",
            "currency": "BTC",
            "address": "2MzCBiYtzJrKBQLSDcXd4bgkNP7hhZnsq8V",
            "tag": null,
            "paymentUri": "bitcoin:2MzCBiYtzJrKBQLSDcXd4bgkNP7hhZnsq8V?amount=0.00364137",
            "expirationTime": "2022-06-02T10:15:01.307Z"
        }
    ],
    "payments": [
        {
            "quoteId": "7eb9dc7e-e679-47b3-80d1-95d89454c3c6",
            "amount": "0.00364137",
            "currency": "BTC",
            "transactionId": "61e5679c44d2ebe0f29d24013efd3385bc523d665cc89fd75cda503e211be740",
            "receiverAddress": "2NC1mWFCVpBMZ5S72KhhnVsTFcvbqTbyPKd",
            "receiveTime": "2022-06-01T11:27:11.892Z",
            "confirmTime": "2022-06-01T11:27:11.892Z",
            "senderAddresses": [],
            "automaticRefund": null
        }
    ],
    "merchantRefunds": [],
    "redirects": {
        "successUrl": "https://www.merchant-eshop/success",
    	  "failureUrl": "https://www.merchant-eshop/failure"
    }
}

As a general rule of thumb, all properties containing monetary data have the following interface.

PropertyType
amountstring
currencystring

In the following sections, a description of the specific properties is provided.

id

The ID of the PaymentIntent.

state

A PaymentIntent instance has a state property that is used to keep track of its current state.
By default, each new PaymentIntent will be in a pending state.

In the following table, a description of the various states is provided.

StateDescription
pendingPaymentIntent has been created or has received an incoming payment transaction and waits for more confirmations.
completedThe incoming payment transaction has the right number of confirmations and the transacted amount is equal or higher than the requested amount.
failedThere are many reasons for failure.
Check the stateReason property for the actual reason.

Here is the diagram of the main PaymentIntent states and how they relate to each other:

stateReason

stateReason property exposes the reason that brought the PaymentIntent to the current state.

❗️

Important

Merchants are advised to not do their integration on “stateReason” because these are eligible for change while the previously mentioned states will stay the same.

The following table describes all possible state reasons for each state:

stateReasonDescriptionState
pending_transactionsPaymentIntent has been created and is awaiting for payment transactions.pending
pending_confirmationsPaymentIntent has received an incoming payment transaction and waits for more confirmations.pending
completed_exact_amountThe exact amount was sent and on time.completed
completed_overpaidAmount received is more than the requested amount. Applicable to BTC payments only.completed
failed_complianceThe customer accessed the Payment Window from a geo-blocked jurisdiction. The PaymentIntent is automatically failed.failed
failed_overpaidAmount received is more than the requested amount. This state reason happens only with cryptocurrencies other than BTC.failed
failed_underpaidThe transaction for a PaymentIntent is confirmed but the amount sent by the payer is less than the amount requested in the PaymentIntent.failed
failed_late_transactionThe transaction for a PaymentIntent was received or confirmed after the quote has expired.failed
failed_expiredThe quotes of the PaymentIntent have expired without receiving a transaction.failed

The following diagram lays out all the mentioned stateReason values and their relations:

orderId

The ID of an order from the merchant system.

merchant

A PaymentIntent instance is created from a Merchant for their Customer.
Merchant data are captured within the merchant JSON object.

PropertyTypeDescription
idstringThe Merchant ID in Coinify's system.
namestringThe Merchant name as set in Coinify's system.

For example:

{
    "id": "de15d585-ed82-4627-953e-41f74353959d",
    "name": "Demo Merchant"
}

subaccount

The subaccount object tells you which specific merchant sub-account created the PaymentIntent. If no subaccountId is provided when creating the PaymentIntent, the value of the object will equal to null. You can find the properties of the object in the following table:

PropertyTypeDescription
idstringUnique identifier of a created sub-account.
namestringName given when creating the sub-account.

For example:

{
    "id": "541c296b-1386-4407-a84c-8f4d123c3b53",
    "name": "Merchant store 1"
}

requested

A PaymentIntent instance is created for an amount in a fiat currency.
These data are captured in an object called requested and have the following interface.

PropertyTypeDescription
amountstringThe amount of the PaymentIntent.
currencystringThe denomination fiat currency.

For example:

{
    "amount": "99.99",
    "currency": "EUR"
}

quotes

A PaymentIntent instance is created so a Customer of a Merchant can pay to the Merchant with a virtual currency through Coinify's system.

Coinify provides the payment details for a Customer within an object called quotes. Each time the Customer selects a virtual currency, a new quote is created that contains the payment details for the Customer. All requested quotes are all stored and chronologically ordered inside the quotes array in the PaymentIntent instance - from the first requested quote being on top of the list.

All the quotes of a PaymentIntent are returned in the quotes array and each quote has the following interface:

PropertyTypeDescription
idstring (UUID v4)The ID of the quote.
amountstringThe amount to be paid.
currencystringThe virtual currency that denominates the amount.
addressstringThe address to which Coinify expects the payment to be sent.
tagstring or nullSome virtual currencies need some extra information from the customer in order to identify the payment. The tag property contains the tag value the customer must send as part of the transaction.

When the virtual currency does not need this extra information, the value is null.
paymentUristringThe payment URI for wallets.
expirationTimestring (ISO-8601 timestamp)A string representation of the date and time after which all payments to this address will be rejected.

For example:

[
    {
        "id": "ccfd3c7a-ecca-4e4e-a8ff-90a637e75d8b",
        "amount": "0.0019",
        "currency": "BTC",
        "address": "2NFbYupBUCm5iJ4jMvkxN5g6Z515oNkePXv",
        "paymentUri": "bitcoin:2NFbYupBUCm5iJ4jMvkxN5g6Z515oNkePXv?v=0.0019",
        "tag": null,
        "expirationTime": "2021-10-29T10:38:52.514+00:00"
    },
    {
        "id": "5a0e7356-95e9-497d-ab3c-c46599359842",
        "amount": "1013.0212687",
        "currency": "XLM",
        "address": "GCMUIH5THNEHBN6D26HVBCDWGYSX3D42D2CCTERNJLMRFFR2YI7H3IXJ",
        "paymentUri": "stellar:GCMUIH5THNEHBN6D26HVBCDWGYSX3D42D2CCTERNJLMRFFR2YI7H3IXJ?amount=1013.0212687&tag=7608108815524329",
        "tag": "7608108815524329",
        "expirationTime": "2021-10-29T10:55:52.514+00:00"
    }
]

payments

The payments property captures all the payments targeting a PaymentIntent and they have the following interface. Inside of a PaymentIntent instance, in case of multiple payments, received payments are chronologically ordered in the payments array by their receive time - from the first received payment being on top of the list.

PropertyTypeDescription
quoteIdstring (UUID v4)The ID of the quote for which the payment was sent.
amountstringThe amount of the payment denominated in a virtual currency.
currencystringThe denomination virtual currency of the amount property.
transactionIdstringThe ID of the blockchain transaction.
receiverAddressstringThe address to which the customer sends the requested amount.
confirmTimestringThe date and time that the blockchain transaction was confirmed.
receiveTimestringThe date and time when the blockchain transaction for the payment was received.
senderAddressesarrayThe list of address/es from which the transaction/s for the PaymentIntent was received from. When the address is unknown then the array is empty.
automaticRefundobject or nullWhen a payment is less than the requested amount, it arrived after the quote expired, or it is a new subsequent payment then it is eligible for refund.

Moreover, the same applies for the excess amount of a payment which is more than requested.

In all these cases, when the refundable amount is more than the dust limit of the virtual currency, the system refunds the payment automatically.

For example:

[
    {
        "quoteId": "cd1ed432-dce2-4746-b04a-35f16654b8ac",
        "amount": "0.019",
        "currency": "BTC",
        "transactionId": "85728f94262935ede61390e92c6239539f8d95b85a35bc803ba57b1c8127f384",
        "receiverAddress": "2MuzqjWY6GME5ws9sd2U8HNqBkoAYCT6aTf",
        "confirmTime": "2021-10-29T10:30:52.514+00:00",
        "senderAddresses": [],
        "automaticRefund": null
    }
]
[
    {
        "quoteId": "85b583c8-1c4a-4cc1-bb48-8b022e397de0",
        "amount": "0.019",
        "currency": "BTC",
        "transactionId": "840cfc38041284505c4a61d68d1ad40171427c71e3ef8e2e48f767b82c953201",
        "receiverAddress": "2N4wjkPaiXVpDBGxUaxjLAwCBCdcDQ9immx",
        "confirmTime": "2021-10-29T10:30:52.514+00:00",
      	"senderAddresses": [],
        "automaticRefund": {
            "id": "d20dfa24-57cf-4369-b36e-19e5457f2dfd",
            "state": "created",
            "refundCosts": [
                {
                    "paidBy": "customer",
                    "baseAmount": "5",
                    "baseCurrency": "EUR",
                    "finalAmount": null,
                    "finalCurrency": null
                }
            ],
            "refundAmount": {
                "baseAmount": "0.019",
                "baseCurrency": "BTC",
                "finalAmount": null,
                "finalCurrency": "BTC"
            },
            "destination": null,
            "transactionId": null,
            "createTime": "2021-10-29T10:32:52.514+00:00",
            "updateTime": "2021-10-29T10:32:52.514+00:00"
        }
    }
]
[
    {
        "quoteId": "85b583c8-1c4a-4cc1-bb48-8b022e397de0",
        "amount": "0.019",
        "currency": "BTC",
        "transactionId": "840cfc38041284505c4a61d68d1ad40171427c71e3ef8e2e48f767b82c953201",
        "receiverAddress": "2N4wjkPaiXVpDBGxUaxjLAwCBCdcDQ9immx",
        "confirmTime": "2021-10-29T10:30:52.514+00:00",
      	"senderAddresses": [],
        "automaticRefund": {
            "id": "d20dfa24-57cf-4369-b36e-19e5457f2dfd",
            "state": "destination_provided",
            "refundCosts": [
                {
                    "paidBy": "customer",
                    "baseAmount": "5",
                    "baseCurrency": "EUR",
                    "finalAmount": "0.00023",
                    "finalCurrency": "BTC"
                }
            ],
            "refundAmount": {
                "baseAmount": "0.019",
                "baseCurrency": "BTC",
                "finalAmount": null,
                "finalCurrency": "BTC"
            },
            "destination": {
                "address": "2N56qXMHsoC9y4sJh1ovG6dJ3nHrsecSXrA"
            },
            "transactionId": null,
            "createTime": "2021-10-29T10:32:52.514+00:00",
            "updateTime": "2021-10-29T10:34:52.514+00:00"
        }
    }
]
[
    {
        "quoteId": "85b583c8-1c4a-4cc1-bb48-8b022e397de0",
        "amount": "0.019",
        "currency": "BTC",
        "transactionId": "840cfc38041284505c4a61d68d1ad40171427c71e3ef8e2e48f767b82c953201",
        "receiverAddress": "2N4wjkPaiXVpDBGxUaxjLAwCBCdcDQ9immx",
        "confirmTime": "2021-10-29T10:30:52.514+00:00",
      	"senderAddresses": [],
        "automaticRefund": {
            "id": "d20dfa24-57cf-4369-b36e-19e5457f2dfd",
            "state": "completed",
            "refundCosts": [
                {
                    "paidBy": "customer",
                    "baseAmount": "5",
                    "baseCurrency": "EUR",
                    "finalAmount": "0.00023",
                    "finalCurrency": "BTC"
                }
            ],
            "refundAmount": {
                "baseAmount": "0.019",
                "baseCurrency": "BTC",
                "finalAmount": "0.01877",
                "finalCurrency": "BTC"
            },
            "destination": {
                "address": "2N56qXMHsoC9y4sJh1ovG6dJ3nHrsecSXrA"
            },
            "transactionId": "f67e4ae3ff597f2c13971bf92433d4e96a2811df5bb656762614dc5c023f0783",
            "createTime": "2021-10-29T10:32:52.514+00:00",
            "updateTime": "2021-10-29T10:34:52.514+00:00"
        }
    }
]

merchantRefunds

The merchant can refund a completed PaymentIntent. All refunds initiated by merchants are returned as part of this array.

Refund has a general interface applicable in both merchant and automatic refunds and is described below.

PropertyTypeDescription
idstring (UUID v4)The ID of the refund.
statestringOne of the refund states.
refundCostsarray of objectsAll costs applied to this particular refund.
refundAmountobjectThe refund amount.
destinationobject or nullThe destination to receive the refund.
transactionIdstring or nullThe transaction ID of the refund.
createTimestringThe date the refund was created.
updateTimestringThe date the refund was updated.

The state of a refund can be one of the following.

StateDescription
createdThe refund has been created in the system.
destination_providedThe customer has provided the refund destination. At this state, the final amounts of the refundCosts and refundAmount are calculated.
completedA transaction with the final refund amount to the provided destination has been created and broadcasted to the blockchain network.
cancelledThis state is applicable only to merchant refunds and indicates that the merchant has cancelled a refund. This state is possible only for refunds in the created state.
expiredThis state is applicable only to merchant refunds and indicates that the customer hasn't collected their refund within a week.

The refundCosts is an array of objects with the following interface.

PropertyTypeDescription
paidBystringThis property indicates who pays for the refund costs. It can either be customer or merchant.
baseAmountstringThe initial amount of the refund cost.
baseCurrencystringThe currency of the initial amount of the refund cost.
finalAmountstring or nullThe final amount of the refund cost which is calculated when the customer provides the refund destination.
finalCurrencystring or nullThe currency of the final amount of the refund cost.

The refundAmount has the following interface.

PropertyTypeDescription
baseAmountstringThe initial amount of the refund.
baseCurrencystringThe currency of the initial refund amount.
approximateAmountstring or nullAn estimated amount of the refund that the end-user will receive when the refund is completed. Once the refund is completed, the exact amount of the refund is shown in the finalAmount parameter and approximateAmount is then set to null.
finalAmountstring or nullThe final amount of the refund which is provided once the refund address has been provided.
finalCurrencystringThe currency of the final refund amount.

A merchant refund example is provided below, one for each available state.

[
    {
        "id": "d20dfa24-57cf-4369-b36e-19e5457f2dfd",
        "state": "created",
        "refundCosts": [
            {
                "paidBy": "merchant",
                "baseAmount": "5",
                "baseCurrency": "EUR",
                "finalAmount": null,
                "finalCurrency": null
            }
        ],
        "refundAmount": {
            "baseAmount": "100",
            "baseCurrency": "EUR",
          	"approximateAmount": "0.00191065",
            "finalAmount": null,
            "finalCurrency": "BTC"
        },
        "destination": null,
        "transactionId": null,
        "createTime": "2021-10-29T10:32:52.514+00:00",
        "updateTime": "2021-10-29T10:32:52.514+00:00"
    }
]
[
    {
        "id": "d20dfa24-57cf-4369-b36e-19e5457f2dfd",
        "state": "destination_provided",
        "refundCosts": [
            {
                "paidBy": "merchant",
                "baseAmount": "5",
                "baseCurrency": "EUR",
                "finalAmount": "8",
                "finalCurrency": "USD"
            }
        ],
        "refundAmount": {
            "baseAmount": "100",
            "baseCurrency": "EUR",
          	"approximateAmount": "0.00191065",
            "finalAmount": "0.00191065",
            "finalCurrency": "BTC"
        },
        "destination": {
            "address": "2N56qXMHsoC9y4sJh1ovG6dJ3nHrsecSXrA"
        },
        "transactionId": null,
        "createTime": "2021-10-29T10:32:52.514+00:00",
        "updateTime": "2021-10-29T10:34:52.514+00:00"
    }
]
[
    {
        "id": "d20dfa24-57cf-4369-b36e-19e5457f2dfd",
        "state": "completed",
        "refundCosts": [
            {
                "paidBy": "merchant",
                "baseAmount": "5",
                "baseCurrency": "EUR",
                "finalAmount": "8",
                "finalCurrency": "USD"
            }
        ],
        "refundAmount": {
            "baseAmount": "100",
            "baseCurrency": "EUR",
          	"approximateAmount": null
            "finalAmount": "0.00191065",
            "finalCurrency": "BTC"
        },
        "destination": {
            "address": "2N56qXMHsoC9y4sJh1ovG6dJ3nHrsecSXrA"
        },
        "transactionId": "f67e4ae3ff597f2c13971bf92433d4e96a2811df5bb656762614dc5c023f0783",
        "createTime": "2021-10-29T10:32:52.514+00:00",
        "updateTime": "2021-10-29T10:36:52.514+00:00"
    }
]
[
    {
        "id": "d20dfa24-57cf-4369-b36e-19e5457f2dfd",
        "state": "cancelled",
        "refundCosts": [
            {
                "paidBy": "merchant",
                "baseAmount": "5",
                "baseCurrency": "EUR",
                "finalAmount": null,
                "finalCurrency": null
            }
        ],
        "refundAmount": {
            "baseAmount": "100",
            "baseCurrency": "EUR",
          	"approximateAmount": null,
            "finalAmount": null,
            "finalCurrency": "BTC"
        },
        "destination": null,
        "transactionId": null,
        "createTime": "2021-10-29T10:32:52.514+00:00",
        "updateTime": "2021-10-29T10:36:52.514+00:00"
    }
]

redirects

When a PaymentIntent receives a successful payment that Coinify can accept in order to complete the PaymentIntent, the Customer is redirected to a given URL.

Also, when the Customer decides to cancel the PaymentIntent is redirected to another given URL.

The redirects property captures the redirect URLs for both cases and has the following interface.

PropertyTypeDescription
successUrlstringThe URL to redirect the Customer on a successful termination of the flow.
failureUrlstringThe URL to redirect the Customer on a failure or cancellation of the PaymentIntent.

For example:

{
    "successUrl": "https://www.merchant-eshop.com/success",
    "failureUrl": "https://www.merchant-eshop.com/failure"
}