telnesstech
View as MarkdownOpen in ClaudeOpen in ChatGPT

Payment Sessions

Create and manage payment sessions for orders.

Create payment session

POST/payment-sessions

Create 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-Idempotency-Keystringmax length 256

A 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.

orderIdstringrequired

The unique identifier of the order to create a payment session for.

paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
paymentProfileIdstring

A previously saved payment method to prefill on the payment page, for returning customers.

savePaymentProfileboolean

Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.

setAsDefaultPaymentProfileboolean

Whether 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.

grantAutopayConsentboolean

Whether 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.

hostedboolean

Whether 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.

returnUrlstringrequired

The 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.

cancelUrlstring

The URL the customer is redirected to if they cancel the payment on the hosted page. A hosted session only.

brandingobject

The 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
backgroundColorstringpattern ^#[0-9a-fA-F]{6}$

The background color of the payment form, as a hex value with a leading number sign.

buttonColorstringpattern ^#[0-9a-fA-F]{6}$

The color of the payment button, as a hex value with a leading number sign.

borderStyleenum<string>

The shape of the buttons and the input fields of the payment form.

values

  • PILL
  • RECTANGULAR
  • ROUNDED
displayNamestringmax length 100

The name that the payment form shows at the top. Your legal business name stays on the receipt and in the terms.

metadataobject with string keys

A 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
*string

Responses

201

Payment session created successfully

application/json

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.

paymentSessionIdstringrequired

The unique identifier for this payment session.

orderIdstringrequired

The unique identifier of the order this payment session is for.

paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
paymentProfileIdstring

The saved payment method to use for this payment (for returning customers).

savePaymentProfilebooleanrequired

Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.

hostedUrlstringuri

The hosted checkout page to redirect the customer to in order to complete payment. A hosted session only.

providerContextobject

What 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
paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
stripeobject

The 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
clientSecretstringrequired

The client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout.

publishableKeystringrequired

The Stripe publishable key to load Stripe.js with. The key is public.

connectedAccountIdstringrequired

The Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account.

returnUrlstring

The URL the customer is redirected to after payment completion.

cancelUrlstring

The URL the customer is redirected to if they cancel the payment.

statusenum<string>required

Current status of a payment session lifecycle.

values

  • PENDING
  • REQUIRES_ACTION
  • COMPLETED
  • FAILED
  • CANCELED
  • EXPIRED
metadataobject with string keysrequired

Custom key-value pairs for additional payment session information.

Show child attributes
*string
createdAtstringdate-timerequired

When this payment session was created.

updatedAtstringdate-timerequired

When this payment session 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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /payment-sessions
curl https://apiv2.example.com/api/v2/payment-sessions \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "paymentProvider": "STRIPE",
  "savePaymentProfile": true,
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout",
  "metadata": {
    "source": "web-checkout"
  }
}'
fetch('https://apiv2.example.com/api/v2/payment-sessions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    orderId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
    paymentProvider: 'STRIPE',
    savePaymentProfile: true,
    returnUrl: 'https://example.com/order/confirmation',
    cancelUrl: 'https://example.com/order/checkout',
    metadata: {
      source: 'web-checkout'
    }
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/payment-sessions",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "paymentProvider": "STRIPE",
      "savePaymentProfile": True,
      "returnUrl": "https://example.com/order/confirmation",
      "cancelUrl": "https://example.com/order/checkout",
      "metadata": {
        "source": "web-checkout"
      }
    }
)
package main

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

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

	payload := strings.NewReader(`{
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "paymentProvider": "STRIPE",
  "savePaymentProfile": true,
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout",
  "metadata": {
    "source": "web-checkout"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	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))

}
{
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "paymentProvider": "STRIPE",
  "savePaymentProfile": true,
  "hostedUrl": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901",
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout",
  "status": "PENDING",
  "metadata": {
    "source": "web-checkout"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get payment session

GET/payment-sessions/{paymentSessionId}

Retrieve details of a specific payment session by its identifier.

Path parameters

paymentSessionIdstringrequired

The unique identifier of the payment session to retrieve.

Responses

200

Payment session retrieved successfully

application/json

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.

paymentSessionIdstringrequired

The unique identifier for this payment session.

orderIdstringrequired

The unique identifier of the order this payment session is for.

paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
paymentProfileIdstring

The saved payment method to use for this payment (for returning customers).

savePaymentProfilebooleanrequired

Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.

hostedUrlstringuri

The hosted checkout page to redirect the customer to in order to complete payment. A hosted session only.

providerContextobject

What 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
paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
stripeobject

The 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
clientSecretstringrequired

The client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout.

publishableKeystringrequired

The Stripe publishable key to load Stripe.js with. The key is public.

connectedAccountIdstringrequired

The Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account.

returnUrlstring

The URL the customer is redirected to after payment completion.

cancelUrlstring

The URL the customer is redirected to if they cancel the payment.

statusenum<string>required

Current status of a payment session lifecycle.

values

  • PENDING
  • REQUIRES_ACTION
  • COMPLETED
  • FAILED
  • CANCELED
  • EXPIRED
metadataobject with string keysrequired

Custom key-value pairs for additional payment session information.

Show child attributes
*string
createdAtstringdate-timerequired

When this payment session was created.

updatedAtstringdate-timerequired

When this payment session 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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /payment-sessions/{paymentSessionId}
curl https://apiv2.example.com/api/v2/payment-sessions/f2a3b4c5-d6e7-8901-2345-012345678901 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/payment-sessions/f2a3b4c5-d6e7-8901-2345-012345678901', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/payment-sessions/f2a3b4c5-d6e7-8901-2345-012345678901",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)
package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/payment-sessions/f2a3b4c5-d6e7-8901-2345-012345678901"

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

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

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

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

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

}
{
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
  "orderId": "e3f4a5b6-c7d8-9012-3456-123456789012",
  "paymentProvider": "STRIPE",
  "paymentProfileId": "f4a5b6c7-d8e9-0123-4567-234567890123",
  "savePaymentProfile": true,
  "hostedUrl": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901",
  "providerContext": {
    "paymentProvider": "STRIPE",
    "stripe": {
      "clientSecret": "cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5",
      "publishableKey": "pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9",
      "connectedAccountId": "acct_1H8x2vLkdIwHu7ix"
    }
  },
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout",
  "status": "PENDING",
  "metadata": {
    "source": "mobile_app",
    "campaign": "summer_2024"
  },
  "createdAt": "2024-09-29T10:00:00Z",
  "updatedAt": "2024-09-29T10:30:00Z"
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Cancel payment session

POST/payment-sessions/{paymentSessionId}/cancel

Cancel an active payment session, preventing further payment attempts.

Path parameters

paymentSessionIdstringrequired

The unique identifier of the payment session to cancel.

Headers

X-Idempotency-Keystringmax length 256

A 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.

reasonstring

Optional reason for cancelling the payment session.

metadataobject with string keys

Custom key-value pairs for additional cancellation information.

Show child attributes
*string

Responses

200

Payment session canceled successfully

application/json

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.

paymentSessionIdstringrequired

The unique identifier for this payment session.

orderIdstringrequired

The unique identifier of the order this payment session is for.

paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
paymentProfileIdstring

The saved payment method to use for this payment (for returning customers).

savePaymentProfilebooleanrequired

Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.

hostedUrlstringuri

The hosted checkout page to redirect the customer to in order to complete payment. A hosted session only.

providerContextobject

What 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
paymentProviderenum<string>required

Payment service provider that processes the transaction.

values

  • STRIPE
  • BILLOGRAM
stripeobject

The 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
clientSecretstringrequired

The client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout.

publishableKeystringrequired

The Stripe publishable key to load Stripe.js with. The key is public.

connectedAccountIdstringrequired

The Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account.

returnUrlstring

The URL the customer is redirected to after payment completion.

cancelUrlstring

The URL the customer is redirected to if they cancel the payment.

statusenum<string>required

Current status of a payment session lifecycle.

values

  • PENDING
  • REQUIRES_ACTION
  • COMPLETED
  • FAILED
  • CANCELED
  • EXPIRED
metadataobject with string keysrequired

Custom key-value pairs for additional payment session information.

Show child attributes
*string
createdAtstringdate-timerequired

When this payment session was created.

updatedAtstringdate-timerequired

When this payment session 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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes
messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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
hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /payment-sessions/{paymentSessionId}/cancel
curl https://apiv2.example.com/api/v2/payment-sessions/a3b4c5d6-e7f8-9012-3456-123456789012/cancel \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "reason": "Customer changed their mind",
  "metadata": {
    "cancelled_by": "customer_service",
    "ticket_id": "SUPP-12345"
  }
}'
fetch('https://apiv2.example.com/api/v2/payment-sessions/a3b4c5d6-e7f8-9012-3456-123456789012/cancel', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reason: 'Customer changed their mind',
    metadata: {
      cancelled_by: 'customer_service',
      ticket_id: 'SUPP-12345'
    }
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/payment-sessions/a3b4c5d6-e7f8-9012-3456-123456789012/cancel",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "reason": "Customer changed their mind",
      "metadata": {
        "cancelled_by": "customer_service",
        "ticket_id": "SUPP-12345"
      }
    }
)
package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/payment-sessions/a3b4c5d6-e7f8-9012-3456-123456789012/cancel"

	payload := strings.NewReader(`{
  "reason": "Customer changed their mind",
  "metadata": {
    "cancelled_by": "customer_service",
    "ticket_id": "SUPP-12345"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	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))

}
{
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
  "orderId": "e3f4a5b6-c7d8-9012-3456-123456789012",
  "paymentProvider": "STRIPE",
  "paymentProfileId": "f4a5b6c7-d8e9-0123-4567-234567890123",
  "savePaymentProfile": true,
  "hostedUrl": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901",
  "providerContext": {
    "paymentProvider": "STRIPE",
    "stripe": {
      "clientSecret": "cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5",
      "publishableKey": "pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9",
      "connectedAccountId": "acct_1H8x2vLkdIwHu7ix"
    }
  },
  "returnUrl": "https://example.com/order/confirmation",
  "cancelUrl": "https://example.com/order/checkout",
  "status": "PENDING",
  "metadata": {
    "source": "mobile_app",
    "campaign": "summer_2024"
  },
  "createdAt": "2024-09-29T10:00:00Z",
  "updatedAt": "2024-09-29T10:30:00Z"
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}
{
  "message": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}