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_transactions | PaymentIntent has been created and is awaiting for payment transactions. | 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 |
| 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 payment URI 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. |
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.
| 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"
}