Payment Sessions
The payment sessions that collect the money for an order.
Create payment session
/payment-sessionsCreate a new payment session to collect payment information for an order. For orders with a positive total, this initiates payment collection. For zero-total orders, consider creating a payment profile session instead. The order must be complete and ready for submission — an order that would fail submission validation is rejected before any payment is collected. Once the payment succeeds, the order is submitted automatically.
Set hosted to false to collect the payment inside your own checkout page. The response then carries providerContext instead of hostedUrl. Only this call returns providerContext, because it contains a credential that is not stored. To show the form again, create a new session.
Headers
X-stringmax length 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
BodyCreatePaymentSessionRequestrequiredapplication/json
Request to create a new payment session for processing payment for an order.
brandingobjectThe colors and the name that the payment form shows. Every property is optional. A property you leave out keeps the default of the payment provider. Branding does not change the layout or the spacing of the form.
Show child attributes
backgroundstringpattern ^#[0-9a-fA-F]{6}$The background color of the payment form, as a hex value with a leading number sign.
borderenum<string>The shape of the buttons and the input fields of the payment form.
values
PILLRECTANGULARROUNDED
buttonstringpattern ^#[0-9a-fA-F]{6}$The color of the payment button, as a hex value with a leading number sign.
displaystringmax length 100The name that the payment form shows at the top. Your legal business name stays on the receipt and in the terms.
cancelstringThe URL the customer is redirected to if they cancel the payment on the hosted page. A hosted session only.
grantbooleanWhether the customer consents to being charged automatically for future renewals. Only applicable if savePaymentProfile is true. Automatic charging also requires a usable default payment profile. Defaults to false.
hostedbooleanWhether to collect the payment on a hosted page. A hosted session returns hostedUrl, and you send the customer to it. An embedded session (false) returns providerContext, and you show the payment form inside your own checkout page. Defaults to true.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringorderstringrequiredThe unique identifier of the order to create a payment session for.
paymentstringA previously saved payment method to prefill on the payment page, for returning customers.
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
returnstringrequiredThe URL the customer comes back to after they pay. A hosted page redirects to it. An embedded form redirects to it only for a payment method that leaves the page, such as 3D Secure. Must be provided to create a session.
savebooleanWhether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.
setbooleanWhether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated or for the initial order. Defaults to false.
Responses
201Payment session created successfully
application/json
Payment session created successfully
Payment session created successfully
objectPaymentSession
A single checkout attempt that collects payment for an order while the customer is present. Create one during your checkout flow, let the customer pay, then pass its paymentSessionId when you submit the order.
There are two ways to collect the payment. A hosted session gives you hostedUrl, and you send the customer to that page. An embedded session (create it with hosted set to false) gives you providerContext, and you show the payment form inside your own checkout page.
Use a payment link instead when the customer is not in an active checkout (e.g., to send a payment page by email), and read the order's payment intent to see the resulting charges and refunds.
cancelstringThe URL the customer is redirected to if they cancel the payment.
createdstringdate-timerequiredWhen this payment session was created.
hostedstringuriThe hosted checkout page to redirect the customer to in order to complete payment. A hosted session only.
metadataobject with string keysrequiredCustom key-value pairs for additional payment session information.
Show child attributes
*stringorderstringrequiredThe unique identifier of the order this payment session is for.
paymentstringThe saved payment method to use for this payment (for returning customers).
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
paymentstringrequiredThe unique identifier for this payment session.
providerobjectWhat the payment provider needs to render its payment form inside your own checkout page. It is returned only when you create the payment session with hosted set to false, and only by the create call. A hosted session gives you hostedUrl instead.
This object is the one place where the API is specific to a payment provider. Read the child object that agrees with paymentProvider, and add a new child when you add a provider. Every other payment field stays independent of the provider.
Show child attributes
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
stripeobjectThe Stripe values that mount an embedded Stripe Checkout in your own page. Load Stripe.js with the publishable key and the connected account, then mount the checkout with the client secret. The client secret authorizes this one payment session. Do not store it and do not send it to anybody but the payer's browser.
Show child attributes
clientstringrequiredThe client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout.
connectedstringrequiredThe Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account.
publishablestringrequiredThe Stripe publishable key to load Stripe.js with. The key is public.
returnstringThe URL the customer is redirected to after payment completion.
savebooleanrequiredWhether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.
statusenum<string>requiredCurrent status of a payment session lifecycle.
values
PENDINGREQUIRES_ACTIONCOMPLETEDFAILEDCANCELEDEXPIRED
updatedstringdate-timerequiredWhen this payment session was last updated.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
404The requested resource was not found.
application/json
The requested resource was not found.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the 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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
412A precondition for this request was not met.
application/json
A precondition for this request was not met.
A precondition for this request was not met.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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
curl https://apiv2.example.com/api/v2/end-user/payment-sessions \
--request POST \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"cancelUrl": "https://example.com/order/checkout",
"metadata": {
"source": "web-checkout"
},
"orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"paymentProvider": "STRIPE",
"returnUrl": "https://example.com/order/confirmation",
"savePaymentProfile": true
}'fetch('https://apiv2.example.com/api/v2/end-user/payment-sessions', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
cancelUrl: 'https://example.com/order/checkout',
metadata: {
source: 'web-checkout'
},
orderId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
paymentProvider: 'STRIPE',
returnUrl: 'https://example.com/order/confirmation',
savePaymentProfile: true
})
})requests.post(
"https://apiv2.example.com/api/v2/end-user/payment-sessions",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
},
json={
"cancelUrl": "https://example.com/order/checkout",
"metadata": {
"source": "web-checkout"
},
"orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"paymentProvider": "STRIPE",
"returnUrl": "https://example.com/order/confirmation",
"savePaymentProfile": True
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/payment-sessions"
payload := strings.NewReader(`{
"cancelUrl": "https://example.com/order/checkout",
"metadata": {
"source": "web-checkout"
},
"orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"paymentProvider": "STRIPE",
"returnUrl": "https://example.com/order/confirmation",
"savePaymentProfile": true
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"cancelUrl": "https://example.com/order/checkout",
"createdAt": "2024-01-15T10:30:00Z",
"hostedUrl": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901",
"metadata": {
"source": "web-checkout"
},
"orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"paymentProvider": "STRIPE",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"returnUrl": "https://example.com/order/confirmation",
"savePaymentProfile": true,
"status": "PENDING",
"updatedAt": "2024-01-15T10:30: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": "conflict",
"hint": "Reload the resource to get its latest state before retrying.",
"message": "The request conflicts with the current state of the resource."
}{
"code": "precondition_failed",
"hint": "Fetch the current resource and retry with an up-to-date precondition.",
"message": "A precondition given in the request headers was not met."
}{
"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 session
/payment-sessions/{paymentSessionId}Retrieve details of a specific payment session by its identifier.
Path parameters
paymentstringrequiredThe unique identifier of the payment session to retrieve.
Responses
200Payment session retrieved successfully
application/json
Payment session retrieved successfully
Payment session retrieved successfully
objectPaymentSession
A single checkout attempt that collects payment for an order while the customer is present. Create one during your checkout flow, let the customer pay, then pass its paymentSessionId when you submit the order.
There are two ways to collect the payment. A hosted session gives you hostedUrl, and you send the customer to that page. An embedded session (create it with hosted set to false) gives you providerContext, and you show the payment form inside your own checkout page.
Use a payment link instead when the customer is not in an active checkout (e.g., to send a payment page by email), and read the order's payment intent to see the resulting charges and refunds.
cancelstringThe URL the customer is redirected to if they cancel the payment.
createdstringdate-timerequiredWhen this payment session was created.
hostedstringuriThe hosted checkout page to redirect the customer to in order to complete payment. A hosted session only.
metadataobject with string keysrequiredCustom key-value pairs for additional payment session information.
Show child attributes
*stringorderstringrequiredThe unique identifier of the order this payment session is for.
paymentstringThe saved payment method to use for this payment (for returning customers).
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
paymentstringrequiredThe unique identifier for this payment session.
providerobjectWhat the payment provider needs to render its payment form inside your own checkout page. It is returned only when you create the payment session with hosted set to false, and only by the create call. A hosted session gives you hostedUrl instead.
This object is the one place where the API is specific to a payment provider. Read the child object that agrees with paymentProvider, and add a new child when you add a provider. Every other payment field stays independent of the provider.
Show child attributes
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
stripeobjectThe Stripe values that mount an embedded Stripe Checkout in your own page. Load Stripe.js with the publishable key and the connected account, then mount the checkout with the client secret. The client secret authorizes this one payment session. Do not store it and do not send it to anybody but the payer's browser.
Show child attributes
clientstringrequiredThe client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout.
connectedstringrequiredThe Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account.
publishablestringrequiredThe Stripe publishable key to load Stripe.js with. The key is public.
returnstringThe URL the customer is redirected to after payment completion.
savebooleanrequiredWhether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.
statusenum<string>requiredCurrent status of a payment session lifecycle.
values
PENDINGREQUIRES_ACTIONCOMPLETEDFAILEDCANCELEDEXPIRED
updatedstringdate-timerequiredWhen this payment session was last updated.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
404The requested resource was not found.
application/json
The requested resource was not found.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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
curl https://apiv2.example.com/api/v2/end-user/payment-sessions/f2a3b4c5-d6e7-8901-2345-012345678901 \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'fetch('https://apiv2.example.com/api/v2/end-user/payment-sessions/f2a3b4c5-d6e7-8901-2345-012345678901', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN'
}
})requests.get(
"https://apiv2.example.com/api/v2/end-user/payment-sessions/f2a3b4c5-d6e7-8901-2345-012345678901",
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-sessions/f2a3b4c5-d6e7-8901-2345-012345678901"
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))
}{
"cancelUrl": "https://example.com/order/checkout",
"createdAt": "2024-09-29T10:00:00Z",
"hostedUrl": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901",
"metadata": {
"campaign": "summer_2024",
"source": "mobile_app"
},
"orderId": "e3f4a5b6-c7d8-9012-3456-123456789012",
"paymentProfileId": "f4a5b6c7-d8e9-0123-4567-234567890123",
"paymentProvider": "STRIPE",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"providerContext": {
"paymentProvider": "STRIPE",
"stripe": {
"clientSecret": "cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5",
"connectedAccountId": "acct_1H8x2vLkdIwHu7ix",
"publishableKey": "pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9"
}
},
"returnUrl": "https://example.com/order/confirmation",
"savePaymentProfile": true,
"status": "PENDING",
"updatedAt": "2024-09-29T10:30: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."
}Cancel payment session
/payment-sessions/{paymentSessionId}/cancelCancel an active payment session, preventing further payment attempts.
Path parameters
paymentstringrequiredThe unique identifier of the payment session to cancel.
Headers
X-stringmax length 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
BodyCancelPaymentSessionRequestapplication/json
Request to cancel an active payment session.
metadataobject with string keysCustom key-value pairs for additional cancellation information.
Show child attributes
*stringreasonstringOptional reason for cancelling the payment session.
Responses
200Payment session canceled successfully
application/json
Payment session canceled successfully
Payment session canceled successfully
objectPaymentSession
A single checkout attempt that collects payment for an order while the customer is present. Create one during your checkout flow, let the customer pay, then pass its paymentSessionId when you submit the order.
There are two ways to collect the payment. A hosted session gives you hostedUrl, and you send the customer to that page. An embedded session (create it with hosted set to false) gives you providerContext, and you show the payment form inside your own checkout page.
Use a payment link instead when the customer is not in an active checkout (e.g., to send a payment page by email), and read the order's payment intent to see the resulting charges and refunds.
cancelstringThe URL the customer is redirected to if they cancel the payment.
createdstringdate-timerequiredWhen this payment session was created.
hostedstringuriThe hosted checkout page to redirect the customer to in order to complete payment. A hosted session only.
metadataobject with string keysrequiredCustom key-value pairs for additional payment session information.
Show child attributes
*stringorderstringrequiredThe unique identifier of the order this payment session is for.
paymentstringThe saved payment method to use for this payment (for returning customers).
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
paymentstringrequiredThe unique identifier for this payment session.
providerobjectWhat the payment provider needs to render its payment form inside your own checkout page. It is returned only when you create the payment session with hosted set to false, and only by the create call. A hosted session gives you hostedUrl instead.
This object is the one place where the API is specific to a payment provider. Read the child object that agrees with paymentProvider, and add a new child when you add a provider. Every other payment field stays independent of the provider.
Show child attributes
paymentenum<string>requiredPayment service provider that processes the transaction.
values
STRIPEBILLOGRAM
stripeobjectThe Stripe values that mount an embedded Stripe Checkout in your own page. Load Stripe.js with the publishable key and the connected account, then mount the checkout with the client secret. The client secret authorizes this one payment session. Do not store it and do not send it to anybody but the payer's browser.
Show child attributes
clientstringrequiredThe client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout.
connectedstringrequiredThe Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account.
publishablestringrequiredThe Stripe publishable key to load Stripe.js with. The key is public.
returnstringThe URL the customer is redirected to after payment completion.
savebooleanrequiredWhether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.
statusenum<string>requiredCurrent status of a payment session lifecycle.
values
PENDINGREQUIRES_ACTIONCOMPLETEDFAILEDCANCELEDEXPIRED
updatedstringdate-timerequiredWhen this payment session was last updated.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
404The requested resource was not found.
application/json
The requested resource was not found.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the 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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
412A precondition for this request was not met.
application/json
A precondition for this request was not met.
A precondition for this request was not met.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
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.
codestringdeprecatedrequiredDeprecated. 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 objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames 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 ofA 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
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe 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.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames 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.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies 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
curl https://apiv2.example.com/api/v2/end-user/payment-sessions/a3b4c5d6-e7f8-9012-3456-123456789012/cancel \
--request POST \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"metadata": {
"cancelled_by": "customer_service",
"ticket_id": "SUPP-12345"
},
"reason": "Customer changed their mind"
}'fetch('https://apiv2.example.com/api/v2/end-user/payment-sessions/a3b4c5d6-e7f8-9012-3456-123456789012/cancel', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
metadata: {
cancelled_by: 'customer_service',
ticket_id: 'SUPP-12345'
},
reason: 'Customer changed their mind'
})
})requests.post(
"https://apiv2.example.com/api/v2/end-user/payment-sessions/a3b4c5d6-e7f8-9012-3456-123456789012/cancel",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
},
json={
"metadata": {
"cancelled_by": "customer_service",
"ticket_id": "SUPP-12345"
},
"reason": "Customer changed their mind"
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/payment-sessions/a3b4c5d6-e7f8-9012-3456-123456789012/cancel"
payload := strings.NewReader(`{
"metadata": {
"cancelled_by": "customer_service",
"ticket_id": "SUPP-12345"
},
"reason": "Customer changed their mind"
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"cancelUrl": "https://example.com/order/checkout",
"createdAt": "2024-09-29T10:00:00Z",
"hostedUrl": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901",
"metadata": {
"campaign": "summer_2024",
"source": "mobile_app"
},
"orderId": "e3f4a5b6-c7d8-9012-3456-123456789012",
"paymentProfileId": "f4a5b6c7-d8e9-0123-4567-234567890123",
"paymentProvider": "STRIPE",
"paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
"providerContext": {
"paymentProvider": "STRIPE",
"stripe": {
"clientSecret": "cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5",
"connectedAccountId": "acct_1H8x2vLkdIwHu7ix",
"publishableKey": "pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9"
}
},
"returnUrl": "https://example.com/order/confirmation",
"savePaymentProfile": true,
"status": "PENDING",
"updatedAt": "2024-09-29T10:30: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": "conflict",
"hint": "Reload the resource to get its latest state before retrying.",
"message": "The request conflicts with the current state of the resource."
}{
"code": "precondition_failed",
"hint": "Fetch the current resource and retry with an up-to-date precondition.",
"message": "A precondition given in the request headers was not met."
}{
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support.",
"message": "An unexpected error occurred on the server."
}