Aller au contenu

Payments: Confirm

La référence API est disponible en anglais uniquement.

POST/payments/{payment_id}/confirm

Confirms a payment intent that was previously created with confirm: false. This action attempts to authorize the payment with the payment processor.

Expected status transitions after confirmation:

  • succeeded: If authorization is successful and capture_method is automatic.
  • requires_capture: If authorization is successful and capture_method is manual.
  • failed: If authorization fails.

Path parameters

  • payment_idstringrequired

    The identifier for payment

Request body PaymentsConfirmRequest (object)

  • amountinteger, nullable

    The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD). This field is mandatory for creating a payment.

  • order_tax_amountinteger, nullable

    Total tax amount applicable to the order, in the lowest denomination of the currency.

  • currencystring (enum), nullable

    The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

    Possible values: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD and 148 more

  • amount_to_captureinteger, nullable

    The amount to be captured from the user's payment method, in the lowest denomination. If not provided, and capture_method is automatic, the full payment amount will be captured. If capture_method is manual, this can be specified in the /capture call. Must be less than or equal to the authorized amount.

  • shipping_costinteger, nullable

    The shipping cost for the payment. This is required for tax calculation in some regions.

  • payment_idstring, nullable

    Optional. A merchant-provided unique identifier for the payment, contains 30 characters long (e.g., "pay_mbabizu24mvu3mela5njyhpit4"). If provided, it ensures idempotency for the payment creation request. If omitted, Cardencer generates a unique ID for the payment.

  • capture_methodstring (enum), nullable

    Specifies how the payment is captured.

    • automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
    • manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.

    Possible values: automatic, manual, manual_multiple, scheduled, sequential_automatic

  • authentication_typestring (enum), nullable

    Specifies the type of cardholder authentication to be applied for a payment.

    • ThreeDs: Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS authentication will be activated, potentially shifting chargeback liability to the issuer.
    • NoThreeDs: Indicates that 3D Secure authentication should not be performed. The liability for chargebacks typically remains with the merchant. This is often the default if not specified.

    Note: The actual authentication behavior can also be influenced by merchant configuration and specific processor defaults. Some processors might still enforce 3DS or bypass it regardless of this parameter.

    Possible values: three_ds, no_three_ds

  • billingAddress (object), nullable
    Show 3 child attributes
    • addressAddressDetails (object), nullable

      Address details

    • phonePhoneDetails (object), nullable
    • emailstring, nullable
  • confirmboolean, nullable

    If set to true, Cardencer attempts to confirm and authorize the payment immediately after creation, provided sufficient payment method details are included. If false or omitted (default is false), the payment is created with a status such as requires_payment_method or requires_confirmation, and a separate POST /payments/{payment_id}/confirm call is necessary to proceed with authorization.

  • customerCustomerDetails (object), nullable

    Passing this object creates a new customer or attaches an existing customer to the payment

    Show 7 child attributes
    • idstring, nullable

      The identifier for the customer.

    • namestring, nullable

      The customer's name

    • emailstring, nullable

      The customer's email address

    • phonestring, nullable

      The customer's phone number

    • phone_country_codestring, nullable

      The country code for the customer's phone number

    • tax_registration_idstring, nullable

      The tax registration identifier of the customer.

    • document_detailsCustomerDocumentDetails (object), nullable
  • customer_idstring, nullable

    The identifier for the customer

  • off_sessionboolean, nullable

    Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. When making a recurring payment by passing a mandate_id, this parameter is mandatory

  • descriptionstring, nullable

    An arbitrary string attached to the payment. Often useful for displaying to users or for your own internal record-keeping.

  • return_urlstring, nullable

    The URL to redirect the customer to after they complete the payment process or authentication. This is crucial for flows that involve off-site redirection (e.g., 3DS, some bank redirects, wallet payments).

  • setup_future_usagestring (enum), nullable

    Specifies how the payment method can be used for future payments.

    • off_session: The payment method can be used for future payments when the customer is not present.
    • on_session: The payment method is intended for use only when the customer is present during checkout. If omitted, defaults to on_session.

    Possible values: off_session, on_session

  • payment_method_dataPaymentMethodDataRequest, nullable

    The payment method information provided for making a payment

    Show 1 child attributes
    • billingAddress (object), nullable
  • payment_methodstring (enum), nullable

    Indicates the type of payment method. Eg: 'card', 'wallet', etc.

    Possible values: card, card_redirect, pay_later, wallet, bank_redirect, bank_transfer, crypto, bank_debit, reward, real_time_payment, upi, voucher and 4 more

  • payment_tokenstring, nullable

    As Cardencer tokenises the sensitive details about the payments method, it provides the payment_token as a reference to a stored payment method, ensuring that the sensitive details are not exposed in any manner.

  • shippingAddress (object), nullable
    Show 3 child attributes
    • addressAddressDetails (object), nullable

      Address details

    • phonePhoneDetails (object), nullable
    • emailstring, nullable
  • statement_descriptor_namestring, nullable

    For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters. To be deprecated soon, use billing_descriptor instead.

  • statement_descriptor_suffixstring, nullable

    Provides information about a card payment that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 22 characters for the concatenated descriptor. To be deprecated soon, use billing_descriptor instead.

  • order_detailsarray of OrderDetailsWithAmount (object), nullable

    Use this object to capture the details about the different products for which the payment is being made. The sum of amount across different products here should be equal to the overall payment amount

    Show 20 child attributes
    • product_namestringrequired

      Name of the product that is being purchased

    • quantityintegerrequired

      The quantity of the product to be purchased

    • amountintegerrequired

      the amount per quantity of product

    • tax_ratenumber, nullable

      tax rate applicable to the product

    • total_tax_amountinteger, nullable

      total tax amount applicable to the product

    • requires_shippingboolean, nullable
    • product_img_linkstring, nullable

      The image URL of the product

    • product_idstring, nullable

      ID of the product that is being purchased

    • categorystring, nullable

      Category of the product that is being purchased

    • sub_categorystring, nullable

      Sub category of the product that is being purchased

    • brandstring, nullable

      Brand of the product that is being purchased

    • product_typestring (enum), nullable

      Possible values: physical, digital, travel, ride, event, accommodation

    • product_tax_codestring, nullable

      The tax code for the product

    • descriptionstring, nullable

      Description for the item

    • skustring, nullable

      Stock Keeping Unit (SKU) or the item identifier for this item.

    • upcstring, nullable

      Universal Product Code for the item.

    • commodity_codestring, nullable

      Code describing a commodity or a group of commodities pertaining to goods classification.

    • unit_of_measurestring, nullable

      Unit of measure used for the item quantity.

    • total_amountinteger, nullable

      Total amount for the item.

    • unit_discount_amountinteger, nullable

      Discount amount applied to this item.

  • client_secretstring, nullable

    It's a token used for client side verification.

  • mandate_dataMandateData (object), nullable

    Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.

    Show 3 child attributes
    • update_mandate_idstring, nullable

      A way to update the mandate's payment method details

    • customer_acceptanceCustomerAcceptance (object), nullable

      This "CustomerAcceptance" object is passed during Payments-Confirm request, it enlists the type, time, and mode of acceptance properties related to an acceptance done by the customer. The customer_acceptance sub object is usually passed by the SDK or client.

    • mandate_typeMandateType (one of object | object), nullable
  • customer_acceptanceCustomerAcceptance (object), nullable

    This "CustomerAcceptance" object is passed during Payments-Confirm request, it enlists the type, time, and mode of acceptance properties related to an acceptance done by the customer. The customer_acceptance sub object is usually passed by the SDK or client.

    Show 3 child attributes
    • acceptance_typestring (enum)required

      This is used to indicate if the mandate was accepted online or offline

      Possible values: online, offline

    • accepted_atstring, nullable

      Specifying when the customer acceptance was provided

    • onlineOnlineMandate (object), nullable

      Details of online mandate

  • mandate_idstring, nullable

    A unique identifier to link the payment to a mandate. To do Recurring payments after a mandate has been created, pass the mandate_id instead of payment_method_data

  • browser_infoBrowserInformation (object), nullable

    Browser information to be used for 3DS 2.0

    Show 15 child attributes
    • color_depthinteger, nullable

      Color depth supported by the browser

    • java_enabledboolean, nullable

      Whether java is enabled in the browser

    • java_script_enabledboolean, nullable

      Whether javascript is enabled in the browser

    • languagestring, nullable

      Language supported

    • screen_heightinteger, nullable

      The screen height in pixels

    • screen_widthinteger, nullable

      The screen width in pixels

    • time_zoneinteger, nullable

      Time zone of the client

    • ip_addressstring, nullable

      Ip address of the client

    • accept_headerstring, nullable

      List of headers that are accepted

    • user_agentstring, nullable

      User-agent of the browser

    • os_typestring, nullable

      The os type of the client device

    • os_versionstring, nullable

      The os version of the client device

    • device_modelstring, nullable

      The device model of the client

    • accept_languagestring, nullable

      Accept-language of the browser

    • refererstring, nullable

      Identifier of the source that initiated the request.

  • payment_experiencestring (enum), nullable

    To indicate the type of payment experience that the customer would go through

    Possible values: redirect_to_url, invoke_sdk_client, display_qr_code, one_click, link_wallet, invoke_payment_app, display_wait_screen, collect_otp

  • payment_method_typestring (enum), nullable

    Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

    Possible values: ach, affirm, afterpay_clearpay, alfamart, ali_pay, ali_pay_hk, alma, amazon_pay, paysera, apple_pay, atome, bacs and 105 more

  • allowed_payment_method_typesarray of string (enum), nullable

    Use this parameter to restrict the Payment Method Types to show for a given PaymentIntent

  • retry_actionstring (enum), nullable

    Denotes the retry action

    Possible values: manual_retry, requeue

  • metadataobject, nullable

    You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

  • payment_linkboolean, nullable

    Whether to generate the payment link for this payment or not (if applicable)

  • payment_link_configPaymentCreatePaymentLinkConfig, nullable

    Configure a custom payment link for the particular payment

    Show 26 child attributes
    • themestring, nullable

      custom theme for the payment link

    • logostring, nullable

      merchant display logo

    • seller_namestring, nullable

      Custom merchant name for payment link

    • sdk_layoutstring, nullable

      Custom layout for sdk

    • display_sdk_onlyboolean, nullable

      Display only the sdk for payment link

    • enabled_saved_payment_methodboolean, nullable

      Enable saved payment method option for payment link

    • hide_card_nickname_fieldboolean, nullable

      Hide card nickname field option for payment link

    • show_card_form_by_defaultboolean, nullable

      Show card form by default for payment link

    • transaction_detailsarray of PaymentLinkTransactionDetails (object), nullable

      Dynamic details related to merchant to be rendered in payment link

    • background_imagePaymentLinkBackgroundImageConfig (object), nullable
    • details_layoutstring (enum), nullable

      Possible values: layout1, layout2

    • payment_button_textstring, nullable

      Text for payment link's handle confirm button

    • custom_message_for_card_termsstring, nullable

      Text for customizing message for card terms

    • custom_message_for_payment_method_typesarray of PaymentMethodConfig (object), nullable

      List of custom T&C messages grouped by payment method

    • payment_button_colourstring, nullable

      Custom background colour for payment link's handle confirm button

    • skip_status_screenboolean, nullable

      Skip the status screen after payment completion

    • payment_button_text_colourstring, nullable

      Custom text colour for payment link's handle confirm button

    • background_colourstring, nullable

      Custom background colour for the payment link

    • sdk_ui_rulesobject, nullable

      SDK configuration rules

    • payment_link_ui_rulesobject, nullable

      Payment link configuration rules

    • enable_button_only_on_form_readyboolean, nullable

      Flag to enable the button only when the payment form is ready for submission

    • payment_form_header_textstring, nullable

      Optional header for the SDK's payment form

    • payment_form_label_typestring (enum), nullable

      Possible values: above, floating, never

    • show_card_termsstring (enum), nullable

      Possible values: always, auto, never

    • is_setup_mandate_flowboolean, nullable

      Boolean to control payment button text for setup mandate calls

    • color_icon_card_cvc_errorstring, nullable

      Hex color for the CVC icon during error state

  • payment_link_config_idstring, nullable

    Custom payment link config id set at business profile, send only if business_specific_configs is configured

  • payment_typestring (enum), nullable

    The type of the payment that differentiates between normal and various types of mandate payments. Use 'setup_mandate' in case of zero auth flow.

    Possible values: normal, new_mandate, setup_mandate, recurring_mandate, installment

  • request_incremental_authorizationboolean, nullable

    Request an incremental authorization, i.e., increase the authorized amount on a confirmed payment before you capture it.

  • session_expiryinteger, nullable

    Will be used to expire client secret after certain amount of time to be supplied in seconds (900) for 15 mins

  • request_external_three_ds_authenticationboolean, nullable

    Whether to perform external authentication (if applicable)

  • three_ds_dataExternalThreeDsData (object), nullable
    Show 5 child attributes
    • authentication_cryptogramCryptogram (one of object), nullable

      Represents the 3DS cryptogram data returned after authentication.

    • ds_trans_idstring, nullable

      Directory Server Transaction ID generated during the 3DS process.

    • versionstring, nullable

      The version of the 3DS protocol used (e.g., "2.1.0" or "2.2.0").

    • ecistring, nullable

      Electronic Commerce Indicator (ECI) value representing the 3DS authentication result.

    • transaction_statusstring (enum)required

      Indicates the transaction status

      Possible values: Y, N, U, A, R, C, D, I

  • recurring_detailsRecurringDetails (one of object | object | object | object | object | object | object), nullable

    Details required for recurring payment

  • request_extended_authorizationboolean, nullable

    Optional boolean value to extent authorization period of this payment

    capture method must be manual or manual_multiple

  • merchant_order_reference_idstring, nullable

    Your unique identifier for this payment or order. This ID helps you reconcile payments on your system. If provided, it is passed to the processor if supported.

  • skip_external_tax_calculationboolean, nullable

    Whether to calculate tax for this payment intent

  • psd2_sca_exemption_typestring (enum), nullable

    SCA Exemptions types available for authentication

    Possible values: low_value, transaction_risk_analysis

  • ctp_service_detailsCtpServiceDetails (object), nullable
    Show 5 child attributes
    • merchant_transaction_idstring, nullable

      merchant transaction id

    • correlation_idstring, nullable

      network transaction correlation id

    • x_src_flow_idstring, nullable

      session transaction flow id

    • providerstring (enum), nullable

      Possible values: visa, mastercard

    • encrypted_payloadstring, nullable

      Encrypted payload

  • force_3ds_challengeboolean, nullable

    Indicates if 3ds challenge is forced

  • threeds_method_comp_indstring (enum), nullable

    Indicates if 3DS method data was successfully completed or not

    Possible values: Y, N, U

  • is_iframe_redirection_enabledboolean, nullable

    Indicates if the redirection has to open in the iframe

  • all_keys_requiredboolean, nullable

    If enabled, provides whole processor response

  • payment_channelPaymentChannel (one of string (enum) | string (enum) | string (enum) | object), nullable

    Describes the channel through which the payment was initiated.

  • tax_statusstring (enum), nullable

    Possible values: taxable, exempt

  • discount_amountinteger, nullable

    Total amount of the discount you have applied to the order or transaction.

  • shipping_amount_taxinteger, nullable

    This Unit struct represents MinorUnit in which core amount works

  • duty_amountinteger, nullable

    This Unit struct represents MinorUnit in which core amount works

  • order_datestring, nullable

    Date the payer placed the order.

  • enable_partial_authorizationboolean, nullable

    Allow partial authorization for this payment

  • is_stored_credentialboolean, nullable

    Boolean flag indicating whether this payment method is stored and has been previously used for payments

  • mit_categorystring (enum), nullable

    Specifies the category of a Merchant Initiated Transaction (MIT). In the case of MIT, mit_category tells what kind of MIT is being processed. In the case of CIT, it tells the future intended MIT type.

    Possible values: installment, unscheduled, recurring, resubmission

  • billing_descriptorBillingDescriptor (object), nullable

    Billing Descriptor information to be sent to the payment gateway

    Show 6 child attributes
    • namestring, nullable

      name to be put in billing description

    • citystring, nullable

      city to be put in billing description

    • phonestring, nullable

      phone to be put in billing description

    • statement_descriptorstring, nullable

      a short description for the payment

    • statement_descriptor_suffixstring, nullable

      Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor.

    • referencestring, nullable

      A reference to be shown on billing description

  • tokenizationstring (enum), nullable

    The type of tokenization to use for the payment method

    Possible values: skip_psp, tokenize_at_psp

  • partner_merchant_identifier_detailsPartnerMerchantIdentifierDetails (object), nullable

    Information identifying partner and merchant application initiating the request

    Show 2 child attributes
    • partner_detailsPartnerApplicationDetails (object), nullable

      Information identifying partner / external platform details

    • merchant_detailsMerchantApplicationDetails (object), nullable

      Information identifying merchant details

  • installment_optionsarray of InstallmentOption (object), nullable

    Installment payment options grouped by payment method. When provided, the payment is treated as an installment payment.

    Show 2 child attributes
    • payment_methodstring (enum)required

      Indicates the type of payment method. Eg: 'card', 'wallet', etc.

      Possible values: card, card_redirect, pay_later, wallet, bank_redirect, bank_transfer, crypto, bank_debit, reward, real_time_payment, upi, voucher and 4 more

    • installmentsarray of InstallmentOptionData (object)required

      List of available installment configurations

  • installment_dataInstallmentRequest (object), nullable

    Installment selection sent by the customer during payment confirmation.

    Show 2 child attributes
    • number_of_installmentsintegerrequired

      Number of installments chosen by the customer

    • billing_frequencystring (enum)required

      Billing frequency for a card installment plan

      Possible values: month

Responses

  • 200Payment confirmed
  • 400Missing mandatory fields

Request

curl --request POST \
  --url https://sandbox.cardencer.com/payments/{payment_id}/confirm \
  --header 'Content-Type: application/json' \
  --header 'api-key: snd_...' \
  --data '{
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "1963-05-03T04:07:52.723Z",
      "online": {
        "ip_address": "127.0.0.1",
        "user_agent": "amet irure esse"
      }
    },
    "payment_method": "card",
    "payment_method_data": {
      "card": {
        "card_cvc": "123",
        "card_exp_month": "10",
        "card_exp_year": "25",
        "card_holder_name": "joseph Doe",
        "card_number": "4242424242424242"
      }
    },
    "payment_method_type": "credit"
  }'

Response

{
  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "merchant_id": "merchant_1668273825",
  "status": "requires_confirmation",
  "amount": 6540,
  "net_amount": 6540,
  "amount_capturable": 6540,
  "processor_merchant_id": "merchant_1689512302",
  "currency": "AED",
  "payment_method": "card",
  "attempt_count": 0
}