Valdyr
View as MarkdownOpen in ClaudeOpen in ChatGPT

Payment Intents

The payments that the platform collected, or tried to collect, for those invoices.

List payment intents

GET/payment-intents

Retrieve a paginated list of payment intents with optional filtering by status, customer, or date range.

Query parameters

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

customerIdarray of string

Filter payment intents by customer IDs

statusarray of PaymentIntentStatus

Filter payment intents by status

Responses

200

Payment intents retrieved successfully

application/json

Payment intents retrieved successfully

object

itemsarray of PaymentIntentListItemrequired
Show child attributes
amountMinorintegerint64required

The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

createdAtstringdate-timerequired

When the payment intent was created.

currencystringrequired

The ISO 4217 currency code the amount is collected in (e.g., "USD").

customerIdstringrequired

The customer this payment intent collects from.

descriptionstring

A human-readable description of what is being collected.

dueAtstringdate-time

When the amount is due.

paymentIntentIdstringrequired

The unique identifier for this payment intent.

statusenum<string>required

Current stage of a payment intent as it is collected through the payment provider.

  • UNKNOWN: The platform has no supported mapping for the current provider state.
  • PENDING: Created, no charge attempted yet.
  • REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
  • PROCESSING: A charge is in flight with the payment provider.
  • SUCCEEDED: The full amount has been collected.
  • REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
  • CANCELED: Collection was canceled and no further charges will be attempted.

values

  • UNKNOWN
  • PENDING
  • REQUIRES_ACTION
  • PROCESSING
  • SUCCEEDED
  • REQUIRES_PAYMENT_METHOD
  • CANCELED
typeenum<string>required

What the payment intent collects.

  • UNKNOWN: The platform does not have a supported type for this intent.
  • PREPAID_RENEWAL: A scheduled prepaid subscription renewal.
  • TOPUP: An immediate prepaid balance or allowance top-up.
  • INITIAL_ORDER: Payment collected while placing an order.

values

  • UNKNOWN
  • PREPAID_RENEWAL
  • TOPUP
  • INITIAL_ORDER
updatedAtstringdate-timerequired

When the payment intent was last updated.

paginationobjectrequired

Cursor-based pagination information returned by list endpoints. Pass nextCursor as the cursor query parameter of the next request to fetch the following page.

Show child attributes
nextCursorstring | nullrequired

Opaque token for fetching the next page. Null when no more results.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /payment-intents
curl https://apiv2.example.com/api/v2/end-user/payment-intents \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/payment-intents', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/payment-intents",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/payment-intents"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "items": [
    {
      "amountMinor": 2900,
      "createdAt": "2024-01-15T10:00:00Z",
      "currency": "USD",
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "description": "Mobile subscription renewal",
      "dueAt": "2024-01-15T10:00:00Z",
      "paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
      "status": "SUCCEEDED",
      "type": "PREPAID_RENEWAL",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvZmZzZXQiOjEwMH0"
  }
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Get payment intent

GET/payment-intents/{paymentIntentId}

Get a payment intent by ID, including its charge attempts, refunds, and line items.

Path parameters

paymentIntentIdstringrequired

The unique identifier of the payment intent to retrieve.

Responses

200

Payment intent retrieved successfully

application/json

Payment intent retrieved successfully

objectPaymentIntent

The amount the platform is collecting from a customer, with its payment attempts, refunds, and billed line items.

A payment intent is created automatically when payment collection starts for an order or invoice; you do not create one directly. Read it to see what is due, what was attempted, and what was refunded. Card collection starts through a payment session or payment link; invoice collection creates the payment intent as part of issuing the invoice.

amountMinorintegerint64required

The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

attemptsarray of PaymentAttemptrequired

Charge attempts made against this payment intent, most recent first.

Show child attributes
amountMinorintegerint64required

The amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

chargedAtstringdate-time

When the charge was made.

createdAtstringdate-timerequired

When the attempt was created.

currencystringrequired

The ISO 4217 currency code the attempt was charged in (e.g., "USD").

paymentAttemptIdstringrequired

The unique identifier for this charge attempt.

reasonstring

Failure reason when the attempt did not succeed.

resultenum<string>required

Whether the charge attempt succeeded or failed.

values

  • SUCCEEDED
  • FAILED
createdAtstringdate-timerequired

When the payment intent was created.

currencystringrequired

The ISO 4217 currency code the amount is collected in (e.g., "USD").

customerIdstringrequired

The customer this payment intent collects from.

descriptionstring

A human-readable description of what is being collected.

discountsarray of PaymentIntentDiscountrequired

Reductions applied to the payment intent as a whole rather than to one billed line.

Show child attributes
amountMinorintegerint64required

The positive amount deducted, in minor units of the payment intent currency.

descriptionstringrequired

Why the payment intent was reduced.

dueAtstringdate-time

When the amount is due.

lineItemsarray of PaymentIntentLineItemrequired

The items that make up the collected amount.

Show child attributes
amountMinorintegerint64required

The base cost of the line item before discounts, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD). The taxes are added to it, unless includesTax is true and they are a part of it.

descriptionstringrequired

What this line item represents.

discountsarray of object

Discounts applied to this line item.

Show child attributes
amountMinorintegerint64required

The discounted amount (positive value), in minor units of the payment intent's currency.

descriptionstringrequired

What the discount is for.

includesTaxboolean

Whether the taxes are a part of amountMinor rather than added to it.

licenseIdstring

The license this line item is associated with, if any.

subscriptionIdstring

The subscription this line item is associated with, if any.

taxesarray of object

Taxes applied to this line item.

Show child attributes
amountMinorintegerint64required

The tax amount, in minor units of the payment intent's currency.

descriptionstringrequired

The tax component applied (e.g., a named tax and its rate).

paymentIntentIdstringrequired

The unique identifier for this payment intent.

refundsarray of PaymentRefundrequired

Refunds issued against this payment intent.

Show child attributes
amountMinorintegerint64required

The refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).

createdAtstringdate-timerequired

When the refund was created.

currencystringrequired

The ISO 4217 currency code the refund is issued in (e.g., "USD").

reasonenum<string>

Why the refund was issued.

values

  • UNKNOWN
  • DUPLICATE
  • FRAUDULENT
  • REQUESTED_BY_CUSTOMER
  • DISPUTE_LOST
refundIdstringrequired

The unique identifier for this refund.

statusenum<string>required

Current stage of the refund.

values

  • PENDING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • REQUIRES_ACTION
statusenum<string>required

Current stage of a payment intent as it is collected through the payment provider.

  • UNKNOWN: The platform has no supported mapping for the current provider state.
  • PENDING: Created, no charge attempted yet.
  • REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).
  • PROCESSING: A charge is in flight with the payment provider.
  • SUCCEEDED: The full amount has been collected.
  • REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.
  • CANCELED: Collection was canceled and no further charges will be attempted.

values

  • UNKNOWN
  • PENDING
  • REQUIRES_ACTION
  • PROCESSING
  • SUCCEEDED
  • REQUIRES_PAYMENT_METHOD
  • CANCELED
updatedAtstringdate-timerequired

When the payment intent was last updated.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /payment-intents/{paymentIntentId}
curl https://apiv2.example.com/api/v2/end-user/payment-intents/64870b5c-fb61-4c9a-955a-e148e0826c20 \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/payment-intents/64870b5c-fb61-4c9a-955a-e148e0826c20', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/payment-intents/64870b5c-fb61-4c9a-955a-e148e0826c20",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/payment-intents/64870b5c-fb61-4c9a-955a-e148e0826c20"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "amountMinor": 2900,
  "attempts": [
    {
      "amountMinor": 2900,
      "chargedAt": "2024-01-15T10:00:00Z",
      "createdAt": "2024-01-15T10:00:00Z",
      "currency": "USD",
      "paymentAttemptId": "a4da2b04-aa79-4b40-8987-048d6caf118f",
      "reason": "card_declined",
      "result": "SUCCEEDED"
    }
  ],
  "createdAt": "2024-01-15T10:00:00Z",
  "currency": "USD",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "description": "Mobile subscription renewal",
  "discounts": [
    {
      "amountMinor": 1000,
      "description": "Goodwill credit"
    }
  ],
  "dueAt": "2024-01-15T10:00:00Z",
  "lineItems": [
    {
      "amountMinor": 2900,
      "description": "Mobile subscription - Premium Plan",
      "discounts": [
        {
          "amountMinor": 500,
          "description": "Loyalty discount"
        }
      ],
      "includesTax": false,
      "licenseId": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77",
      "subscriptionId": "a8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "taxes": [
        {
          "amountMinor": 725,
          "description": "VAT 25%"
        }
      ]
    }
  ],
  "paymentIntentId": "64870b5c-fb61-4c9a-955a-e148e0826c20",
  "refunds": [
    {
      "amountMinor": 2900,
      "createdAt": "2024-01-15T10:00:00Z",
      "currency": "USD",
      "reason": "REQUESTED_BY_CUSTOMER",
      "refundId": "c014b666-22e4-430e-bb18-9257a383dfe2",
      "status": "SUCCEEDED"
    }
  ],
  "status": "SUCCEEDED",
  "updatedAt": "2024-01-15T10:00:00Z"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}