Payment intents

API Version

Product Catalog

Library

A payment_intent is created to help you navigate the 3DS flow of collecting payment from your customer. It is necessary only for implementing 3DS flow using Chargebee.js.

Auto-expiry

All payment_intents with status as inited, in_progress or authorized become expired after an hour automatically.

Sample payment intent [ JSON ]

{
    "amount": 5000,
    "created_at": 1517501515,
    "currency_code": "USD",
    "expires_at": 1517503315,
    "gateway": "chargebee",
    "gateway_account_id": "gw___test__KyVnGlSBWTQeudG",
    "id": "__test__KyVnHhSBWTQz2Cu__test__0DZayCQMcAwDkEIPpUrGwkiyL25s7W1X",
    "modified_at": 1517501515,
    "object": "payment_intent",
    "payment_method_type": "card",
    "status": "inited"
}

id

string, max chars=150
Identifier for PaymentIntent.

status

enumerated string
Current status of PaymentIntent.

Possible values are

initedIntent is initialized.in_progressStatus will be in_progress if the Active Payment Attempt state is in requires_identification, requires_challenge or requires_redirection.authorized3DS verification successfully completed.consumedIf any Chargebee operation such as create subscription etc. is completed using the intent, it will be in consumed state. Intent cannot be used if it's already in consumed state.expiredIntent has expired, since it was not consumed before the predefined time-out.

currency_code

optional, string, max chars=3
The currency code (ISO 4217 format) of the amount used in transaction.

amount

in cents, min=0
Amount(in cents) to be authorized for 3DS flow.

gateway_account_id

string, max chars=50
The gateway account used for performing the 3DS flow.

expires_at

timestamp(UTC) in seconds
Timestamp indicating when the PaymentIntent will expire if left unconsumed.

reference_id

optional, string, max chars=200
Reference for payment method at gateway. Only applicable when the PaymentIntent is created for cards stored in the gateway.

payment_method_type

optional, enumerated string, default=card
The payment method of this intent

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

Show all values[+]

success_url

optional, string, max chars=250
The URL the customer will be directed to once 3DS verification is successful. Applicable only when payment_method_type is ideal, sofort, dotpay or giropay.

failure_url

optional, string, max chars=250
The URL the customer will be directed to when 3DS verification fails. Applicable only when payment_method_type is ideal, sofort, dotpay or giropay.

created_at

timestamp(UTC) in seconds
Timestamp indicating when the PaymentIntent was created.

modified_at

timestamp(UTC) in seconds
Timestamp indicating when the PaymentIntent was last modified.

resource_version

optional, long
Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this payment intent was last updated.

customer_id

string, max chars=50

The unique identifier of the customer for whom the payment_intent will be created. If specified, the payment_intent will be used exclusively for that customer. If not specified, the payment_intent won’t be associated with any customer and will be available for any customer.

See also

Customer resource lookup and creation

gateway

optional, string
Gateway associated with the PaymentIntent.

business_entity_id

optional, string, max chars=50
The unique ID of the business entity of this payment_intent

active_payment_attempt
Show attributes [+]

optional, payment_attempt
Active payment attempt for the PaymentIntent.

Active payment attempt attributes

id

optional, string, max chars=70
Identifier for PaymentIntent's active payment attempt.

status

enumerated string
Current status of active payment attempt

Possible values are

initedPayment attempt is initialized.requires_identificationCustomer's device fingerprint is used to verify their identity. It needs to be sent to the Issuing Bank for verification.requires_challengeThe transaction has to go through 3DS Challenge flow and the customer needs to authenticate via 3DS 2.0requires_redirectionThe transaction has to go through 3DS Redirection flow and the customer needs to authenticate via 3DS 1.0authorized3DS verification successfully completed.refused3DS verification attempt failed.pending_authorizationWaiting for the authorization.

payment_method_type

optional, enumerated string, default=card
The payment method of this attempt

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

Show all values[+]

id_at_gateway

optional, string, max chars=50
Reference of PaymentIntent at gateway

error_code

optional, string, max chars=100
Error code received from the payment gateway on failure.

error_text

optional, string, max chars=65k
Error message received from the payment gateway on failure.

created_at

timestamp(UTC) in seconds
Timestamp indicating when the active payment attempt was created.

modified_at

timestamp(UTC) in seconds
Timestamp indicating when the active payment attempt was last modified.

error_detail [+]

optional, gateway_error_detail
Comprehensive information regarding the error experienced during an unsuccessful or declined transaction. Learn more about gateway error references

Error detail attributes

request_id

optional, string, max chars=100
This is a unique identifier assigned by the payment gateway. It is used to track the request at the payment gateway

error_category

optional, string, max chars=100
This parameter categorizes the type of error that occurred for the request. It helps in understanding whether the error is due to API error, validation, processing, network issues, and more

error_code

optional, string, max chars=100
A gateway-specific code that corresponds to the particular error encountered for the request. This code can be used for identifying the error in a standardized manner across the gateway's services

error_message

optional, string, max chars=65k
A message provided by the gateway that describes the nature of the error encountered

decline_code

optional, string, max chars=100
When a transaction is declined, this code is provided by the gateway to specify the reason for the decline

decline_message

optional, string, max chars=65k
This message gives a descriptive explanation of the reason for the transaction's decline

network_error_code

optional, string, max chars=100
This code represents errors that originate from the payment network (such as Visa, MasterCard, and more). It is different from the gateway error code and is specific to the network's error-handling system

network_error_message

optional, string, max chars=65k
This the network related error message from the gateway, this is a detailed message provided by the payment network explaining the nature of the network error encountered

error_field

optional, string, max chars=100
This parameter indicates which specific data field or attribute in the request caused the error

recommendation_code

optional, string, max chars=100
After an error has occurred, the gateway or payment network may provide a recommendation code. This code suggests a course of action or remedy that you can follow to resolve the issue

recommendation_message

optional, string, max chars=65k
This message is intended to provide guidance or suggestions on action or remedy that you can follow to resolve the issue

processor_error_code

optional, string, max chars=100
This code is provided by the payment processor (the entity that handles the transaction between the bank accounts and the payment networks) and indicates errors that occur at this stage of the payment process

processor_error_message

optional, string, max chars=65k
This message describes the specific error that the payment processor encountered

error_cause_id

optional, string, max chars=150
A Chargebee-defined code that corresponds to the specific error encountered during the request. This code helps in identifying and standardizing the error across different gateway services for consistent error handling.

id

string, max chars=150
Identifier for PaymentIntent.

status

enumerated string
Current status of PaymentIntent.

Possible values are

currency_code

optional, string, max chars=3
The currency code (ISO 4217 format) of the amount used in transaction.

amount

in cents, min=0
Amount(in cents) to be authorized for 3DS flow.

gateway_account_id

string, max chars=50
The gateway account used for performing the 3DS flow.

expires_at

timestamp(UTC) in seconds
Timestamp indicating when the PaymentIntent will expire if left unconsumed.

reference_id

optional, string, max chars=200
Reference for payment method at gateway. Only applicable when the PaymentIntent is created for cards stored in the gateway.

payment_method_type

optional, enumerated string, default=card
The payment method of this intent

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

Show all values[+]

success_url

optional, string, max chars=250
The URL the customer will be directed to once 3DS verification is successful. Applicable only when payment_method_type is ideal, sofort, dotpay or giropay.

failure_url

optional, string, max chars=250
The URL the customer will be directed to when 3DS verification fails. Applicable only when payment_method_type is ideal, sofort, dotpay or giropay.

created_at

timestamp(UTC) in seconds
Timestamp indicating when the PaymentIntent was created.

modified_at

timestamp(UTC) in seconds
Timestamp indicating when the PaymentIntent was last modified.

resource_version

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this payment intent was last updated.

customer_id

string, max chars=50

See also

Customer resource lookup and creation

gateway

optional, string
Gateway associated with the PaymentIntent.

business_entity_id

optional, string, max chars=50
The unique ID of the business entity of this payment_intent

active_payment_attempt

optional, payment_attempt
Active payment attempt for the PaymentIntent.

Creates a PaymentIntent object. This is to be used with Chargebee.js API to complete the 3DS flow for new or stored cards.

While creating, specify the appropriate gateway account and amount. Exact amount can be estimated using our Estimate API.

Customer resource lookup and creation

When customer[id] is provided for this operation, it is looked up by Chargebee, and if found, the payment_intent is created for it. If not found, the payment_intent is created without any customer association and will be available for any customer.

Multiple business entities

If multiple business entities are created for the site, the customer resource lookup and creation happen within the context of the business entity specified in this API call. If no business entity is specified, the customer resource lookup is performed within the site context, and if not found, the resource is created for the default business entity of the site.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_intents \
     -u {site_api_key}:\
     -d amount=5000 \
     -d currency_code="USD"

copy

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_intents \
     -u {site_api_key}:\
     -d amount=5000 \
     -d currency_code="USD"

Sample Response [ JSON ]

{
    "payment_intent": {
        "amount": 5000,
        "created_at": 1517501515,
        "currency_code": "USD",
        "expires_at": 1517503315,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWTQeudG",
        "id": "__test__KyVnHhSBWTQz2Cu__test__0DZayCQMcAwDkEIPpUrGwkiyL25s7W1X",
        "modified_at": 1517501515,
        "object": "payment_intent",
        "payment_method_type": "card",
        "status": "inited"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_intents

business_entity_id[]

optional, string, max chars=50

Sets the context for this operation to the business entity specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.

Note

An alternative way of passing this parameter is by means of a custom HTTP header.

See also

Customer resource lookup and creation.

customer_id[]

optional, string, max chars=50

See also

Customer resource lookup and creation

amount[]

required, in cents, min=0
Amount(in cents) to be authorized for 3DS flow.

currency_code[]

required, string, max chars=3
The currency code (ISO 4217 format) of the amount used in transaction.

gateway_account_id[]

optional, string, max chars=50
The gateway account used for performing the 3DS flow.

reference_id[]

optional, string, max chars=200
Reference for payment method at gateway. Only applicable when the PaymentIntent is created for cards stored in the gateway.

payment_method_type[]

optional, enumerated string, default=card
The payment method of this intent.

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

Show all values[+]

success_url[]

optional, string, max chars=250
The URL the customer will be directed to once 3DS verification is successful. Applicable only when payment_method_type is ideal, sofort, dotpay or giropay.

failure_url[]

optional, string, max chars=250
The URL the customer will be directed to when 3DS verification fails. Applicable only when payment_method_type is ideal, sofort, dotpay or giropay.

payment_intent

always returned
Resource object representing payment_intent

Updating properties on a PaymentIntent object. All the subsequent 3DS transaction attempts will have the updated values.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_intents/__test__KyVnHhSBWTR3ZCw__test__6AP6PXGBruIztRxpb4L0Si0Rihcur2fil \
     -u {site_api_key}:\
     -d amount=4000 \
     -d currency_code="USD"

copy

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_intents/__test__KyVnHhSBWTR3ZCw__test__6AP6PXGBruIztRxpb4L0Si0Rihcur2fil \
     -u {site_api_key}:\
     -d amount=4000 \
     -d currency_code="USD"

Sample Response [ JSON ]

{
    "payment_intent": {
        "amount": 4000,
        "created_at": 1517501515,
        "currency_code": "USD",
        "expires_at": 1517503315,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWTQeudG",
        "id": "__test__KyVnHhSBWTR3ZCw__test__6AP6PXGBruIztRxpb4L0Si0Rihcur2fil",
        "modified_at": 1517501515,
        "object": "payment_intent",
        "payment_method_type": "card",
        "status": "inited"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_intents/{payment-intent-id}

amount[]

optional, in cents, min=0
Amount(in cents) to be authorized for 3DS flow.

currency_code[]

optional, string, max chars=3
The currency code (ISO 4217 format) of the amount used in transaction.

gateway_account_id[]

optional, string, max chars=50
The gateway account used for performing the 3DS flow.

payment_method_type[]

optional, enumerated string, default=card
The payment method of this intent.

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

Show all values[+]

success_url[]

optional, string, max chars=250
The URL the customer will be directed to once 3DS verification is successful. Applicable only when payment_method_type is ideal, sofort, dotpay or giropay.

failure_url[]

optional, string, max chars=250
The URL the customer will be directed to when 3DS verification fails. Applicable only when payment_method_type is ideal, sofort, dotpay or giropay.

payment_intent

always returned
Resource object representing payment_intent

Retrieves the PaymentIntent resource.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_intents/__test__KyVnHhSBWTR1HCv__test__5COaMLU3JrmJkDQKOFQqcdOocdusvy0UBl \
     -u {site_api_key}:

copy

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_intents/__test__KyVnHhSBWTR1HCv__test__5COaMLU3JrmJkDQKOFQqcdOocdusvy0UBl \
     -u {site_api_key}:

Sample Response [ JSON ]

{
    "payment_intent": {
        "amount": 5000,
        "created_at": 1517501515,
        "currency_code": "USD",
        "expires_at": 1517503315,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWTQeudG",
        "id": "__test__KyVnHhSBWTR1HCv__test__5COaMLU3JrmJkDQKOFQqcdOocdusvy0UBl",
        "modified_at": 1517501515,
        "object": "payment_intent",
        "payment_method_type": "card",
        "status": "inited"
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/payment_intents/{payment-intent-id}

payment_intent

always returned
Resource object representing payment_intent

Auto-expiry

Sample payment intent [ JSON ]

API Index URL GET

Model Class

Payment intent attributes

Consent Fields for Payment intent

Custom Fields for Payment intent

Create a payment intent ¶

Customer resource lookup and creation

Multiple business entities

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update a payment intent ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a payment intent ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL