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.

Property	Type
amount	string
currency	string

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.

State	Description
`pending`	PaymentIntent has been created or has received an incoming payment transaction and waits for more confirmations.
`completed`	The incoming payment transaction has the right number of confirmations and the transacted amount is equal or higher than the requested amount.
`failed`	There 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:

stateReason	Description	State
`pending_kyc_data`	Payment Intent has been created and is waiting for the customer to provide KYC data. See more info on collected customer data here.	`pending`
`pending_transactions`	Payment Intent is awaiting for payment transactions.	`pending`
`pending_review`	Customer sent funds using the wrong currency and/or network for the Payment Intent.	`pending`
`pending_confirmations`	PaymentIntent has received an incoming payment transaction and waits for more confirmations.	`pending`
`completed_exact_amount`	The exact amount was sent and on time.	`completed`
`completed_overpaid`	Amount received is more than the requested amount. Applicable to BTC payments only.	`completed`
`completed_underpaid`	Amount received is less than the requested amount but it is accepted due to the Merchant setting allowing underpayments to be processed. Opt-in feature.	`completed`
`failed_compliance`	The customer accessed the Payment Window from a geo-blocked jurisdiction. The PaymentIntent is automatically failed.	`failed`
`failed_overpaid`	Amount received is more than the requested amount. This state reason happens only with cryptocurrencies other than BTC.	`failed`
`failed_underpaid`	The 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_transaction`	The transaction for a PaymentIntent was received or confirmed after the quote has expired.	`failed`
`failed_expired`	The 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.

Property	Type	Description
id	string	The Merchant ID in Coinify's system.
name	string	The 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:

Property	Type	Description
id	string	Unique identifier of a created sub-account.
name	string	Name 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.

Property	Type	Description
amount	string	The amount of the PaymentIntent.
currency	string	The 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:

Property	Type	Description
id	string (UUID v4)	The ID of the quote.
amount	string	The amount to be paid.
currency	string	The virtual currency that denominates the amount.
address	string	The address to which Coinify expects the payment to be sent.
tag	string or null	Some 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.
paymentUri	string	The paymentURI for wallets.
expirationTime	string (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.

Property	Type	Description
quoteId	string (UUID v4)	The ID of the quote for which the payment was sent.
amount	string	The amount of the payment denominated in a virtual currency.
currency	string	The denomination virtual currency of the amount property.
transactionId	string	The ID of the blockchain transaction.
receiverAddress	string	The address to which the customer sends the requested amount.
confirmTime	string	The date and time that the blockchain transaction was confirmed.
receiveTime	string	The date and time when the blockchain transaction for the payment was received.
senderAddresses	array	The 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.
automaticRefund	object or null	When 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.

`payments.automaticRefund` possible examples:

[
    {
        "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.

Property	Type	Description
id	string (UUID v4)	The ID of the refund.
state	string	One of the refund states.
refundCosts	array of objects	All costs applied to this particular refund.
refundAmount	object	The refund amount.
destination	object or null	The destination to receive the refund.
transactionId	string or null	The transaction ID of the refund.
createTime	string	The date the refund was created.
updateTime	string	The date the refund was updated.

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

State	Description
created	The refund has been created in the system.
destination_provided	The customer has provided the refund destination. At this state, the final amounts of the refundCosts and refundAmount are calculated.
completed	A transaction with the final refund amount to the provided destination has been created and broadcasted to the blockchain network.
cancelled	This 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.
expired	This 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.

Property	Type	Description
paidBy	string	This property indicates who pays for the refund costs. It can either be `customer` or `merchant`.
baseAmount	string	The initial amount of the refund cost.
baseCurrency	string	The currency of the initial amount of the refund cost.
finalAmount	string or null	The final amount of the refund cost which is calculated when the customer provides the refund destination.
finalCurrency	string or null	The currency of the final amount of the refund cost.

The refundAmount has the following interface.

Property	Type	Description
baseAmount	string	The initial amount of the refund.
baseCurrency	string	The currency of the initial refund amount.
approximateAmount	string or `null`	An 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`.
finalAmount	string or `null`	The final amount of the refund which is provided once the refund address has been provided.
finalCurrency	string	The 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.

Property	Type	Description
successUrl	string	The URL to redirect the Customer on a successful termination of the flow.
failureUrl	string	The 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"
}

creditAmount

Only available for authenticated API calls.

{
   "amount": "21.42",
   "currency": "USD"
}