Create a new checkout session

post https://api.copperx.dev/api/v1/checkout/sessions

Checkout Sessions allow you to create one-off payments in a fixed or variable amount or start subscriptions for your customers. You should create a new Checkout Session for each payment attempt. Once you create a Checkout Session on your server, you need to redirect user to the Checkout Session URL to complete the payment flow.

Body Params

mode

string

The mode of the Checkout Session.

clientReferenceId

string

Unique ID string used to identify the session in your backend. This can be your payment ID, cart ID, or similar used to link this Checkout Session with your internal system.

nameCollection

boolean

Whether to collect the customer's name. Default: false

emailCollection

boolean

Whether to collect the customer's email address. Default: false

phoneNumberCollection

boolean

Whether to collect the customer's phone number Default: false

shippingAddressCollection

boolean

Whether to collect the customer's shipping address. Default: false

billingAddressCollection

boolean

Whether to collect the customer's billing address. Default: false

expiresAt

date-time

The time at which the session will expire. Default: 1 Hour

customFields

object

afterCompletion

string

The action to take after the payment is completed. You can choose to redirect user to your application or use the default payment confirmation page provided by Copperx

afterCompletionConfirmMsg

string

The message to show after successful payment. Only applicable when afterCompletion is set to hosted_confirmation

customerId

string

The ID of the customer if you want to associate the session with a customer

metadata

object

A set of key-value pairs that you can attach to a Checkout Session object

submitType

string

Defaults to pay

The type of submit button to display on the Checkout page

customerCreation

string

Whether to create a customer for the session. If required, a customer will be created for subsequent payments

customerUpdate

object

The customer update settings to use for this checkout to update existing customer details

allowPromotionCodes

boolean

Enables user redeemable promotion codes.

successUrl

string

required

The URL to redirect the customer to after payment is completed. Only applicable when afterCompletion is set to redirect

cancelUrl

string

The URL to redirect the customer to if they decide to cancel payment

customerData

object

The checkout sessions's customer data to be prefilled

lineItems

object

required

The line items to be used in checkout session. Line items are the individual prices that the customer will be charged for

paymentSetting

object

The payment method settings to use for this checkout's payment

taxRateIds

array of strings

taxRateIds

defaultPromotionCode

string

The default promotion code to auto apply to this checkout session, when checkout session is created.If promotion code is invalid or expired still checkout session is created without applying promotion code.You need to check whether promotion code applied or not at your end when get create checkout session response.

Responses

Response body

object

string

required

createdAt

date-time

updatedAt

date-time

organizationId

string

required

Organization id of the checkout session

mode

string

The mode of the Checkout Session.

payment subscription

paymentLinkId

uuid

The payment link id used to create this checkout session

subscriptionId

uuid

The subscription created from this checkout session

invoiceId

uuid

The invoice created from this checkout session

amountTotal

int64

required

≥ 0

A non-zero amount filled in with 8 decimal places. For example, 1 USDC is 100000000.

amountSubtotal

int64

required

≥ 0

Amount subtotal is total of all line items excluding tax, shipping, application fee and discount. A non-zero amount filled in with 8 decimal places. For example, 1 USDC is 100000000.

amountGasFee

int64

Amount fee is extra amount on top of amountSubtotal. If charged from end user.

amountFee

int64

Amount fee is extra amount on top of amountSubtotal. If charged from end user.

amountNet

int64

amountDetails

object

The amount details of the payment

currency

string

required

The currency of the payment

usdc usdt pyusd eurc brett dai btc eth matic bnb sol busd trx food bonk wif goat spx truf pengu usd inr

amountTotal

int64

required

The total amount of the payment after discounts and taxes

amountSubtotal

int64

required

The total amount of the payment before discounts and taxes

amountDiscount

int64

required

The total amount of the payment discount

amountTax

int64

required

The total amount of the payment tax

amountFee

int64

required

The total amount of the payment application fee

amountGasFee

int64

The total amount of the transaction gas fee. If null then we are not able to calculate gasFee

feePercentage

number

The fee percentage to apply

applyFee

boolean

required

The flag to apply fee

applyGasFee

boolean

required

The flag to apply gas fee

discountAmounts

array of objects

required

The list of discount amounts

discountAmounts*

object

amount

int64

required

The amount of the discount

couponId

string

required

The coupon id of the discount

currency

string

required

Currency of the amount

usdc usdt pyusd eurc brett dai btc eth matic bnb sol busd trx food bonk wif goat spx truf pengu

paymentMethodTypes

array of strings

length between 1 and 1

A list of the types of payment methods (e.g. wallet) this Checkout Session is allowed to accept.

paymentMethodTypes

paymentSetting

object

The payment method settings to use for this checkout's payment

paymentMethodTypes

array of strings

length between 1 and 1

A list of the types of payment methods

paymentMethodTypes

allowedChains

array of objects

The list of chains allowed for the payment. If not provided, all chains supported by the organization are enabled.

allowedChains

object

chainId

number

required

blacklistCurrencies

array of strings

The list of currencies to disable for the payment. Note: This field is only used for checkout session API atm.

blacklistCurrencies

withdrawalAddress

string

This is optional, default withdrawal address configured in dashboard under settings > payment methods is used. The custom withdrawal address to use for this chain instead of stored default withdrawal address.

withdrawalAddresses

array of objects

length between 2 and 4

The list of withdrawal addresses to split the payment. If provided, the sum of all split percentages should be 100.

withdrawalAddresses

object

splitPercentage

number

required

0 to 100

address

string

required

The withdrawal address for the split percentage

preferredChainId

number

The preferred chain's id

allowSwap

boolean

Defaults to false

Whether the user can swap the payment currency

allowFiatPayment

boolean

Whether to allow payment with fiat currency. If set to true, the payment will be made in fiat currency.
This is experimental field and supposed to change. Default: false

status

string

required

The status of the session

open complete incomplete expired

paymentStatus

string

required

The status of the payment

unpaid paid

expiresAt

date-time

The time at which the session will expire. Default: 1 Hour

customerId

string

The ID of the customer if you want to associate the session with a customer

customer

object

The customer detail from saved customer's information. This is only available when customer id is provided or customer is stored

name

string

The name

string

The email

phone

string

The phone

organizationName

string

The organization name

address

object

The address

uuid

required

Customer's id

createdAt

date-time

Customer's created at

updatedAt

date-time

Customer's updated at

customerReferenceId

string

Customer's reference id

shipping

object

Customer's shipping address

taxIds

object

visibility

string

Customer's visibility. If Dashboard then displayed on dashboard UI. If API then only returned in API response only.

10 20

metadata

object

Customer's metadata

Has additional fields

customerNumber

string

required

Customer number assigned by the system

customerDetails

object

The checkout sessions's customer detail

name

string

phone

string

organizationName

string

The organization name

address

object

taxIds

object

clientReferenceId

string

Unique ID string used to identify the session in your backend. This can be your payment ID, cart ID, or similar used to link this Checkout Session with your internal system.

customerCreation

string

Whether to create a customer for the session. If required, a customer will be created for subsequent payments

if_required always

customerUpdate

object

The customer update settings to use for this checkout to update existing customer details

address

string

auto never

name

string

auto never

shipping

string

auto never

url

string

required

The URL to redirect the customer to complete payment

successUrl

string

The URL to redirect the customer to after payment is completed. Only applicable when afterCompletion is set to redirect

cancelUrl

string

The URL to redirect the customer to if they decide to cancel payment

submitType

string

Defaults to pay

The type of submit button to display on the Checkout page

pay book donate

metadata

object

A set of key-value pairs that you can attach to a Checkout Session object

Has additional fields

nameCollection

boolean

Whether to collect the customer's name. Default: false

emailCollection

boolean

Whether to collect the customer's email address. Default: false

phoneNumberCollection

boolean

Whether to collect the customer's phone number Default: false

shippingAddressCollection

boolean

Whether to collect the customer's shipping address. Default: false

billingAddressCollection

boolean

Whether to collect the customer's billing address. Default: false

customFields

object

fields

array of objects

fields

object

key

string

required

type

string

required

text numeric dropdown

label

object

required

optional

boolean

required

Defaults to false

text

object

numeric

object

dropdown

object

afterCompletion

string

The action to take after the payment is completed. You can choose to redirect user to your application or use the default payment confirmation page provided by Copperx

redirect hosted_confirmation

afterCompletionConfirmMsg

string

The message to show after successful payment. Only applicable when afterCompletion is set to hosted_confirmation

shippingDetails

object

The shipping address to use for this checkout

name

string

The name

string

The email

phone

string

The phone

organizationName

string

The organization name

address

object

The address

billingDetails

object

The billing address to use for this checkout

name

string

The name

string

The email

phone

string

The phone

organizationName

string

The organization name

address

object

The address

lineItems

object

required

The list of line items to display on the session

object

string

data

array of objects

data

object

description

string

quantity

number

price

object

required

taxRates

array of objects

taxRates

object

string

required

name

string

required

The name of the tax rate.

description

string

The description of the tax rate.

country

string

The country of the tax rate.

percentage

number

required

0 to 100

Percent that will be added to subtotal as a tax.

type

string

required

The type of the tax rate.

exclusive inclusive

isDefault

boolean

required

amountTotal

int64

amountSubtotal

int64

amountTax

int64

currency

string

usdc usdt pyusd eurc brett dai btc eth matic bnb sol busd trx food bonk wif goat spx truf pengu usd inr

addresses

array of objects

required

The list of payment addresses associated with the session. It is the list of the addresses that will be used to pay the amount.

addresses*

object

string

required

createdAt

date-time

updatedAt

date-time

checkoutSessionId

string

required

asset

object

required

paymentAddress

string

required

gas

int64

This approx estimated gas required to withdraw amount from the payment address. It is in gas unit, and need to multiply by gas price to get the total gas fee in native token

gasAmount

int64

This the approx estimated total amount a user should pay in checkout session currency as transaction fees. This is equivalent to gas * gasPrice. This amount is in 8 (currency decimals)This can be null if gas fee is inclusive of subtotal and not additionally charged

paymentIntent

object

required

The payment intent associated with the session. Payment intent is created when the session is created.

string

required

createdAt

date-time

updatedAt

date-time

organizationId

uuid

required

amount

int64

amountReceived

int64

currency

string

usdc usdt pyusd eurc brett dai btc eth matic bnb sol busd trx food bonk wif goat spx truf pengu usd inr

status

string

required

requires_payment_method requires_confirmation requires_action processing requires_capture canceled succeeded

paymentMethodId

uuid

required

description

string

paymentMethod

object

paymentMethodTypes

array of strings

paymentMethodTypes

transferAccountAddress

string

transactions

array of objects

required

transactions*

object

type

string

required

Transaction type

incoming outgoing event transfer

transactionRelayId

string

Transaction relay id

transactionHash

string

Transaction hash

nonce

number

Transaction nonce

gasLimit

number

Transaction gas limit used in payment

validUntil

string

Transaction valid until

fromAddress

string

required

Transaction from address

toAddress

string

required

Transaction to address

currency

string

required

Transaction currency

usdc usdt pyusd eurc brett dai btc eth matic bnb sol busd trx food bonk wif goat spx truf pengu usd inr

createdAt

date-time

Transaction created at

amount

int64

Transaction amount in 8 decimals

amountRaw

string

required

Transaction amount raw received from alchemy

assetId

string

required

Transaction asset id

asset

object

required

transactionUrl

string

Transaction url

paymentReceipt

object

canceledAt

date-time

cancellationReason

string

stripe

object

isMarkRefunded

boolean | null

markRefundedAt

date-time | null

markRefundedComment

string | null

isMarkRefunded

boolean

Whether to mark the payment as refunded

allowPromotionCodes

boolean

Enables user redeemable promotion codes.

discounts

array of objects

required

The list of discounts applied to the session

discounts*

object

amount

int64

required

The amount of the discount

couponId

string

required

The coupon id of the discount

coupon

object

required

The coupon of the discount

defaultPromotionCode

string

The default promotion code to apply to the session

isManualPayment

boolean

required

Language

Credentials

Bearer

JWT

URL


xxxxxxxxxx
28
1
curl --request POST \
2
     --url https://api.copperx.dev/api/v1/checkout/sessions \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "submitType": "pay",
8
  "lineItems": {
9
    "data": [
10
      {
11
        "priceData": {
12
          "currency": "usdc",
13
          "interval": "day",
14
          "productData": {
15
            "visibility": 10
16
          },
17
          "type": "one_time"
18
        },
19
        "quantity": 1
20
      }
21
    ]
22
  },
23
  "paymentSetting": {
24
    "allowSwap": false,
25
    "allowFiatPayment": false
26
  }
27
}
28
'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200

401

500