ConvesioPay Checkout Integration API

## Sections
• [Introduction](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/introduction.md): 🚀 ConvesioPay ConvesioPay is the ultimate enterprise payments platform, designed to reduce risk and increase revenue – all with white-glove support by Convesio's expert support team. ConvesioPay integrates seamlessly with our comprehensive commerce platform, providing advanced engagement marketing, scalable infrastructure, and essential growth features for businesses of all sizes. Enterprise scale for businesses of all sizes Transact on the web and via invoice Robust reporting and administrative tools for managing payment operations Full-stack support from website to payout, via Slack and email
• [Authentication and API Keys](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/api-authentication/authentication.md): Every ConvesioPay Checkout API integration requires the following credentials to perform all functionality securely and efficiently: apiKey - Identifies the requesting account, can be used client side. secretKey - Required secure credential for all backend requests, must NOT be exposed client side. clientKey - A client key is required for each website the Checkout Component is mounted on and whitelists that host as an authorized destination for your integration to take payments on. All necessary integration credentials (ie secret key, API key, client key…required for Convesio.js ) can be generated and viewed on the Connected Integrations page of the dashboard in Advanced Settings. Although, it is possible and recommended to generate these on behalf of the merchant with 1 click with the Connect API. All API requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. ConvesioPay retains the right to rotate your secret keys if a public leak is detected.
• [Connect an Integration](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/api-authentication/connect-an-integration.md): All necessary integration credentials (ie secret key, API key, client key…required for the Checkout API) can be generated, viewed, and destroyed on the Connected Integrations page of the dashboard in Advanced Settings. However, it is recommended to utilize the Connect/Disconnect endpoints in your integration to securely generate these credentials on behalf of the merchant with 1 click. You will need to collect some details about the merchant, along with predetermined information about your integration, to assemble a server side request to ConvesioPay to properly create the Connected Integration details for you and have your integration display the generated credentials. Secret keys should only be displayed once upon generation, stored securely where necessary in your integration, and not be displayed again. This endpoint does not make any assumptions to create or render any UI for you to facilitate the collection the required data. However, here are a few example screenshots of how you might present a form to collect and securely submit the data to ConvesioPay to create the necessary Connected Integration details in our system. Please include an option for ConvesioPay support to make use of an adminClientKey as an alternative to the merchant's account password. Connection requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. This endpoint requires you to collect and submit the merchant's ConvesioPay account email and password in the form of Basic Authentication. Never store merchant ConvesioPay account credentials in your integration. Don’t expose these values in the frontend of your application. Connect integration requests must be made server side. The following properties are required to use this endpoint: integrationName domain webhooks NOTE - This endpoint will return a unique, per domain integrationName string in the response body that is generated for you from the provided integrationName and domain values. You will need this value in order to successfully list or update integration level payment methods in your integration (you can also find this value as the name of the integration on the Connected Integrations page of the dashboard in Advanced Settings). If the correct string is not provided, the customer will be able to use all globally enabled payment methods in ConvesioPay for the merchant.
• [Disconnect an Integration](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/api-authentication/disconnect-an-integration.md): All integration credentials (ie secret key, API key, client key…required for the Checkout API) can be generated, viewed, and destroyed on the Connected Integrations page of the dashboard in Advanced Settings. However, it is recommended to utilize the Connect/Disconnect endpoints in your integration to securely generate or destroy these credentials on behalf of the merchant with 1 click. This endpoint does not make any assumptions to create or render any UI for you to facilitate the disconnecting of your integration. However, here are a few example screenshots of how you might present an option in your integration to securely destroy the previously created Connected Integration credentials in ConvesioPay. Disconnect requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side.
• [Including ConvesioPay.js](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/getting-started/including-convesiopay-js.md): Include the ConvesioPay.js script on your site. It should always be loaded directly from https://js.convesiopay.com , rather than included in a bundle or hosted yourself.
• [Initializing ConvesioPay.js](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/getting-started/initializing-convesiopay-js.md): ConvesioPay(apiKey) Use ConvesioPay(apiKey) to create an instance of the ConvesioPay object . The ConvesioPay object is your entrypoint to the rest of the ConvesioPay.js SDK. Your ConvesioPay API key is required when calling this function, as it identifies your website and its ability to accept payments to ConvesioPay. View the sample code below. Don’t submit any personally identifiable information in requests made with this key and instead use your actual key. You can get all required keys (ie API key, client key, secret key, etc) from the Connected Integrations page of the dashboard in Advanced Settings. You can learn more about the Checkout API Authentication and Keys here if you missed it. You need only create one instance of the ConvesioPay object in your code. Method parameters apiKey - string REQUIRED The API key identifies the requesting account
• [Create Component (OL)](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/checkout-component/create-component.md): cpay.component(options) This method is used to create the ConvesioPay checkout component. The checkout component renders PCI compliant payment form fields that will tokenize payment methods to be passed to your integration's backend for processing payments securely. The component uses the optional customerEmail and integration parameters to provide important functionality. The customerEmail is used to check for any known tokenized stored payment methods available (not available for all integrations, your integration must have stored payment method access). If no email is provided, the component will not be able to facilitate the use of any stored payment methods and will require all card information to be securely collected again. The integration parameter here is used to filter payment methods available for this integration specifically. Please note that, if you used the Connect Integration API , this value should actually be the ConvesioPay generated string returned in the response called the integrationName (you can also find this value as the name of the integration on the Connected Integrations page of the dashboard in Advanced Settings). If the correct name is not provided, the customer will be able to use all globally enabled payment methods in ConvesioPay for the merchant. Learn more about how you can enable and/or disable Payment Methods in the dashboard. Method parameters environment - string REQUIRED The environment you want to make a payment on, possible values are ‘test’ or ‘live’ customerEmail - string The email of the customer that will be making a payment. Though it is optional, customers will not be able to make use stored payment methods in the checkout component without it. integration - string The ConvesioPay unique, per domain string that is generated for you and returned in the Connect Integration API response body theme - string An optional theme name to change the look and feel of the credit Checkout Component form. Currently supported values are light or dark (the light theme is used by default if no theme is provided). express - boolean An optional property to create a minimal version of the component featuring only accelerated payment method buttons (ApplePay, GooglePay) disabledPaymentMethods - object Optionally disable specific payment methods for this instance of the component by passing boolean truthy values for each payment method to hide Unified View (Default) By default accelerated payment methods like ApplePay are bundled with all other payment methods (ie Credit Card, BTCPay) in their own accordion. JavaScript const component = cpay.component({ environment: 'test', customerEmail: 'abc@domain.com', integration: 'string', theme: 'dark' }); Express Checkout View If you want to provide accelerated payment methods on their own, likely prior to the checkout flow (ie on a product or cart page), you can do so easily by simply passing the express property in the session config. JavaScript const component = cpay.component({ environment: 'test', customerEmail: 'abc@domain.com', integration: 'string', theme: 'dark', express: true // Enable express mode }); Disabling Specific Accelerated Payment Methods In order for accelerated payment methods to be visible they must be first enabled at the Global or Integration level. However, you may also elect to disable specific payment methods just for a specific instance of the component mounted by passing a disabledPaymentMethods object. JavaScript const component = cpay.component({ environment: 'test', customerEmail: 'abc@domain.com', integration: 'string', theme: 'dark', disabledPaymentMethods: { // Disable specific payment methods cards: true, applePay: false, googlePay: true } });
• [(DEPRECATED) Create Component](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/checkout-component/deprecated-create-component.md): There is a newer version of this page here , you are currently viewing outdated information based pre-orchestration protocol. If you are not yet utilizing our Orchestration Layer, please contact support for more information. cpay.component(options) This method is used to create the ConvesioPay checkout component. The checkout component renders PCI compliant payment form fields that will tokenize payment methods to be passed to your integration's backend for processing payments securely. The component uses the optional customerEmail and integration parameters to provide important functionality. The customerEmail is used to check for any known tokenized stored payment methods available (not available for all integrations, your integration must have stored payment method access). If no email is provided, the component will not be able to facilitate the use of any stored payment methods and will require all card information to be securely collected again. The integration parameter here is used to filter payment methods available for this integration specifically. Please note that, if you used the Connect Integration API , this value should actually be the ConvesioPay generated string returned in the response called the integrationName (you can also find this value as the name of the integration on the Connected Integrations page of the dashboard in Advanced Settings). If the correct name is not provided, the customer will be able to use all globally enabled payment methods in ConvesioPay for the merchant. Learn more about how you can enable and/or disable Payment Methods in the dashboard. Method parameters environment - string REQUIRED The environment you want to make a payment on, possible values are ‘test’ or ‘live’ clientKey - string REQUIRED The client key provides access for the website to accept payments customerEmail - string The email of the customer that will be making a payment. Though it is optional, customers will not be able to make use stored payment methods in the checkout component without it. integration - string The ConvesioPay unique, per domain string that is generated for you and returned in the Connect Integration API response body theme - string An optional theme name to change the look and feel of the credit Checkout Component form. Currently supported values are light or dark (the light theme is used by default if no theme is provided).
• [Mount Component](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/checkout-component/mount-the-component.md): component.mount(domElement) This method attaches your checkout component to the DOM. element.mount accepts a CSS selector for the DOM element like #component-container . You need to create a container DOM element to mount the component in. The checkout component requires SSL. The page address must start with https:// rather than http:// for your integration to work. Method parameters domElement - string REQUIRED The DOM element your component will be mounted
• [Update Component](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/checkout-component/update-component.md): It is recommended that you create the component with all desired properties before mounting but sometimes that is not possible in the integration consuming the component. For that reason, there are a couple methods you can use to dynamically update the component config elements and rehydrate the UI without needing to destroy, create, and remount the component. When updating the component with accelerated payment methods selected, if a payment token was already created via customer confirmation, existing payment tokens will be invalidated and a change event will be fired accordingly. You can use this change event to properly disable payment attempts temporarily and notify the customer that they will need to create another payment token. Learn more in Events and Validation component.updateEmail() This method provides a way to seamlessly update the customerEmail that was originally provided (or not) in the Create Component call. This can be useful, for instance, if for some reason you need to create the component in your integration before a customer can fill out a checkout form required to get all the payment information. While the component will function without customerEmail some functionaility will be excluded. This allows you to pass the updated email when you have access. component.updateAmount() This method provides a way to seamlessly update the amount and/or currency that was originally provided (or not) in the Create Component call. This can be useful if you are updating values in your integration at different stages of the checkout process (ie applying coupons, updating cart totals, additional charges, or upsells, etc.). The amount provided in the component config initially can potentially become stale and need to be updated. This allows you to pass the updated amount whenever necessary.
• [Events and Validation](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/checkout-component/component-validation.md): component.on('change', handler) The only way to communicate with the checkout component is by listening to an event. We expose a change event you can subscribe to in the checkout component. The change event is triggered when the component's value changes and provides valuable feedback on the payment status and details. Method parameters event - string REQUIRED The name of the event (ie ‘change’) handler - function REQUIRED The callback function provided to be invoked when the event is fired. The event argument will be passed in with the following properties: Credit Card Field Validation Handler Event Properties type - string The name of the payment method type isValid - boolean True if all field values are valid and all data has been collected necessary to make a payment valid - object An object containing field names that are true if they are valid, or false if not errors - object An object containing field names that are null if they are valid, or error message strings if not Accelerated Payment Methods Handler Event Properties type - string The name of the payment method type isSuccessful - boolean True if the tokenized payment intent was successfully created or initiated (depending on the payment method) token - string The payment token that represents the card details entered into the component along with some information about the origin of the customer. email - string The shipping email associated with the customer from the ApplePay/GooglePay response billingContact - object The billing contact object from the ApplePay/GooglePay response containing the name and billing address information shippingContact - object The shipping contact object from the ApplePay/GooglePay response containing the name, email, and shipping address information shippingMethod - object The shipping method object containing the label, detail, amount, and identifier errors - array An empty array if all field names are valid, or error message strings if not. A few possible examples with regard to previous tokens becoming invalidated after updating component values: Email changed — previous payment authorization is no longer valid. Please re-authorize Amount changed — previous payment authorization is no longer valid. Please re-authorize Accelerated payment methods may have additional optional events you can subscribe to. To learn more about those, read about the accelerated payment method's specific payment intent session method parameters (ie Create ApplePay Session ). Payment intents for BTCPay payments are considered successful if the BTCPay invoice was created with all necessary payment data. The component will not receive change events beyond this point in the payment lifecycle (ie when the customer initiates payment or when the payment has been confirmed).
• [Global Level](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-methods/enable-disable-payment-methods.md): All Checkout API integrations will automaticaly consider payment methods that are “globally” available on the Checkout API Settings Payment Methods page of the dashboard in Advanced Settings to be available and allowed. So that means when you mount the Checkout Component in your integration, each globally available payment method will show up (unless unavailable in the browser environment, like ApplePay when not in Safari for instance) as an available option for your customers to checkout with unless you either disable it on the Payment Methods page for all Checkout API integrations or disable it explicitly for individual integrations on the Checkout API Settings Connected Integrations page of the dashboard in Advanced Settings. Payment methods can be managed in the ConvesioPay Dashboard on the following pages in Advanced Settings: Global - Payment Methods Integration Specific - Connected Integrations By default, all merchants start with Credit Cards enabled as the base payment method. All other payment methods must be configured as desired. Some payment methods have specific requirements and you can learn more about these when enabling them in the dashboard. Learn more about explicitly enabling or disabling payment methods for your integration .
• [Integration Level](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-methods/integration-specific-payment-methods.md): Any globally available payment methods can be explicitly disabled or re-enabled on the Connected Integrations page of the dashboard in Advanced Settings. For instance, if a merchant has already enabled ApplePay as a payment method but only wants to offer Credit Cards in one of their connected integrations, they can do that. if a payment method has not yet been enabled globally, it cannot be disabled or re-enabled at the integration level. It must be enabled at the global level first. More importantly, you can do this programatically accomplish this native to your integration in the Checkout API. To learn more about explicitly reading or updating payment methods in your integration, look at the API docs on the next couple pages. Payment methods can be managed in the ConvesioPay Dashboard on the following pages in Advanced Settings: Global - Payment Methods Integration Specific - Connected Integrations
• [List Integration Payment Methods](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-methods/list-integration-payment-methods.md): You can easily filter payment methods that are available at the integration level by simply passing your integration name as a query parameter. This can be useful if you want to be able to show the merchant or customer what payment methods customers can use to checkout with on an internal integration page (outside of the Checkout Component). And more importantly, you can give the your integration the power to update which of those payment methods are available from within your integration. To take advantage of this feature properly, be sure to pass the optional integration query string parameter. The value should be equal to the Connected Integration name. If you used the Connect Integration API , this would be the generated integrationName string returned in the Connect API response. This same value can be passed into the config object when you create the component to filter payment methods available for this integration specifically (you can also find this value as the name of the integration on the Connected Integrations page of the dashboard in Advanced Settings). If the correct name is not provided, the customer will be able to use all globally enabled payment methods in ConvesioPay for the merchant. Payment Method list requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. Payment Method list requests must be made server side, do not attempt to list a payment method client side.
• [Update Integration Payment Methods](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-methods/update-integration-payment-methods.md): It is possible to programmatically allow your integration to update which globally enabled payment methods are available from within your integration. Use the Secret Key associated with your integration in the API request to able to disable or re-enable any payment method at the integration level. To take advantage of this feature properly, be sure to pass the optional integration query string parameter. The value should be equal to the Connected Integration name. If you used the Connect Integration API , this would be the generated integrationName string returned in the Connect API response. This same value can be passed into the config object when you create the component to filter payment methods available for this integration specifically (you can also find this value as the name of the integration on the Connected Integrations page of the dashboard in Advanced Settings). If the correct name is not provided, the customer will be able to use all globally enabled payment methods in ConvesioPay for the merchant. Payment Method update requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. Payment Method update requests must be made server side, do not attempt to update a payment method client side.
• [Create Card Token](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-intents/create-card-token.md): component.createToken() Creates a payment token that represents the card details entered into the component along with some information about the origin of the customer. You can use this token to create a card payment server side with the API. Do not attempt to create a card payment request client side. The following properties are required to use this method: amount - number REQUIRED Total amount to be paid in minor units currency - string REQUIRED 3 character ISO currency code Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units). Best Practices for Tokenization Since tokenization of card details cannot occur until valid information has been provided, you will need to wait for the isValid status from the Component change event as depicted here . But while it's tempting to create the token in the change event handler directly, care should be given to use the change event to only manage state and create a token directly before creating the payment request. You can create more than one token if necessary due to new information but the createToken() method is rate limited to preven abuse. A few things to keep in mind: Never call createToken() inside the change event handler. the change event fires on every field interaction (typing, focus, blur). Use it only to enable/disable your submit button or handle validation errors visually in your integration if necessary. Call createToken() only on explicit user action (Pay/Submit button click). This guarantees exactly one token per checkout attempt without risk of rate limiting and/or missing recent changes in your payment request. If you must create the token before submit (ie to pre-authorize), gate method attempts to fire only once per valid state transition. Implementation Example JavaScript let isCardValid = false; // Handle real-time credit card field validation errors from the component. component.on('change', (event) => { if (event.type === 'card') { isCardValid = event.isValid; if (!isCardValid) { // Handle errors, one or more component fields are not valid console.log(event.errors); } } }); async function onSubmit() { if (!isCardValid) return; const token = await component.createToken({ amount: 1000, currency: 'USD' }); // Proceed with payment using the created token... } Rate Limiting The createToken() method is subject to rate limiting to prevent excessive use. Only one token can be created per 3 seconds. If the method is invoked more frequently, rate limiting will occur and instead of a token string, the Promise will return an error object (more details below). Success Method returns token - promise Returns a Promise that resolves with a tokenized payment method ( string ) required to securely create a payment Errors In the event there could be an issue converting the customer's card details into a secure payment token, the component will throw an error. If you would like to test this error you can use token_error for the Cardholder Name when you call the component.createToken() method (see other possible error examples below). Error response returns token - promise Returns a Promise that resolves with a JavaScript Erro r object (see below) Miscellaneous Error Example JavaScript "error": { "type": "tokenCreationError", "message": "Unable to create a valid payment token." } Rate Limit Error Example JavaScript "error": { "type": "rateLimitError", "message": "Too many tokenization requests. Please retry after a short delay.", "hint": "Call createToken() in your payment submit handler, not on input change events.", "retryAfter": 2 } Multiple Token Requests In Flight Example JavaScript error: { type: 'inFlightError', message: 'A token creation request is already in progress.', hint: 'Ensure createToken() is called only once per payment submission, not on input change events.' }
• [Create ApplePay Session (OL)](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-intents/create-applepay-session-ol.md): component.createApplePaySession() Creates an ApplePay session that allows the customer to initiate a tokenized payment intent that represents the payment details the customer provided along with some information about their origin. This is considered a setup method that should be called promptly after mounting the component if you want to offer ApplePay and must be called before the customer interacts with the component. In order to take ApplePay payments in your integration, you will need to enable it on the Checkout API Payment Methods page in the dashboard in Advanced Settings and ensure that the domain is registered and listed in the ApplePay Domains table. Once the customer chooses to Pay with ApplePay , an authorization request is triggered. Simultaneously, if the ApplePay session is successfully authorized via Face ID or Touch ID, ConvesioPay will securely and automatically create the payment token that represents the card details entered into the component along with some information about the origin of the customer. You can get that token from the component event change handler. You will need to use this as the paymentToken later when you are ready to create the payment. You can use this token to create a card payment server side with the API. Customers can take advantage of ApplePay when viewing your integration on an Apple device and are signed into the same or another Apple device with ApplePay enabled that can authorize the payment via Face ID or Touch ID. The following properties are required to use this method: integration - string REQUIRED The name of your ConvesioPay integration returnUrl - string REQUIRED The url to return the user to if a redirect is necessary amount - number REQUIRED Total amount to be paid in minor units currency - string REQUIRED 3 character ISO currency code Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units). The following properties are optional when using this method (read more about each below): shippingType - string The list of supported shipping types to display/allow in the ApplePay sheet for purchased items. Possible values can be: shipping delivery storePickup servicePickup supportedCountries - array An array of strings representing a list of 2 letter country codes to display in the ApplePay sheet as supported shippingMethods - array An array of objects representing supported shipping methods to display in the ApplePay sheet. Each object must contain the following properties: label - string A short description of the shipping method detail - string Additional description of the shipping method amount - string The nonnegative cost associated with this shipping method identifier - string A value you define that is used to identify this shipping method lineItems - array An array of objects used to explain additional charges, discounts, and pending costs to display in the ApplePay sheet. Each object must contain the following properties: label - string A short, localized description of the line item type - string A value that indicates whether the line item is final or pending amount - string The monetary value associated with the line item onShippingAddressChange - object The event handler to call when the customer selects a shipping address in the ApplePay sheet onShippingMethodChange - object The event handler to call when the customer selects a shipping method onPaymentMethodChange - object The event handler to call when the customer selects a payment method Implementation Examples of Optional ApplePay Properties shippingType JavaScript const applePaySession = await component.createApplePaySession({ // Other required and optional items omitted for brevity shippingType: 'shipping' // ['shipping'|'delivery'|'storePickup'|'servicePickup'] }); supportedCountries JavaScript const applePaySession = await component.createApplePaySession({ // Other required and optional items omitted for brevity supportedCountries: ['US', 'CA', 'GB'] }); shippingMethods JavaScript const applePaySession = await component.createApplePaySession({ // Other required and optional items omitted for brevity shippingMethods: [ { label: 'Standard Shipping', detail: '5-7 business days', amount: 500, identifier: 'standard' }, { label: 'Express Shipping', detail: '1-2 business days', amount: 1500, identifier: 'express' } ] }); lineItems JavaScript const applePaySession = await component.createApplePaySession({ // Other required and optional items omitted for brevity lineItems: [ { label: 'Subtotal', amount: 1500 }, { label: 'Shipping', amount: 500 }, { label: 'Tax', amount: 120 } ] }); onShippingAddressChange JavaScript const applePaySession = await component.createApplePaySession({ // Other required and optional items omitted for brevity onShippingAddressChange: async (shippingContact) => { // Recalculate tax/shipping based on new address. // MUST return within 30 seconds or Apple Pay shows "Payment Not Completed". const newTax = calculateTax(shippingContact.countryCode, shippingContact.administrativeArea); const newShipping = getShippingCost(shippingContact.countryCode); const newTotal = 1500 + newTax + newShipping; return { newTotal: { label: 'My Store', amount: (newTotal / 100).toFixed(2), type: 'final' }, newLineItems: [ { label: 'Subtotal', amount: (1500 / 100).toFixed(2), type: 'final' }, { label: 'Shipping', amount: (newShipping / 100).toFixed(2), type: 'final' }, { label: 'Tax', amount: (newTax / 100).toFixed(2), type: 'final' } ], // To reject an address: // errors: [new ApplePayError('addressUnserviceable', 'postalAddress', 'We cannot ship to this address')] }; } }); onShippingMethodChange JavaScript const applePaySession = await component.createApplePaySession({ // Other required and optional items omitted for brevity onShippingMethodChange: async (shippingMethod) => { const shippingCost = shippingMethod.identifier === 'express' ? 1500 : 500; const newTotal = 1500 + shippingCost + 120; return { newTotal: { label: 'My Store', amount: (newTotal / 100).toFixed(2), type: 'final' }, newLineItems: [ { label: 'Subtotal', amount: (1500 / 100).toFixed(2), type: 'final' }, { label: 'Shipping', amount: (shippingCost / 100).toFixed(2), type: 'final' }, { label: 'Tax', amount: (120 / 100).toFixed(2), type: 'final' } ], }; } }); onPaymentMethodChange JavaScript const applePaySession = await component.createApplePaySession({ // Other required and optional items omitted for brevity onPaymentMethodChange: async (paymentMethod) => { // Useful if you charge different rates per card network. // Typical paymentMethod.type values can be 'credit', 'debit', 'prepaid', etc. if (paymentMethod.type === 'credit') { // Add 3% processing fee for credit cards return { newTotal: { label: 'My Store', amount: '103.00', type: 'final' }, newLineItems: [ { label: "Subtotal", amount: "100.00" }, { label: "Processing Fee", amount: "3.00" } ] }; } else { // No change return { newTotal: { label: 'My Store', amount: '100.00', type: 'final' }, newLineItems: [ { label: "Subtotal", amount: "100.00" } ] }; } } }); Handling Payment Events We expose a change event you can subscribe to in the checkout component. The change event is triggered when the component's value changes and provides valuable feedback on the payment status and details. You can learn more about these change events here .
• [(DEPRECATED) Create ApplePay Session](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-intents/create-applepay-payment.md): component.createApplePaySession() Creates an ApplePay session that allows the customer to initiate a tokenized payment intent that represents the payment details the customer provided along with some information about their origin. This is considered a setup method that should be called promptly after mounting the component if you want to offer ApplePay and must be called before the customer interacts with the component. In order to take ApplePay payments in your integration, you will need to enable it on the Checkout API Payment Methods page in the dashboard in Advanced Settings and ensure that the domain is registered and listed in the ApplePay Domains table. Once the customer chooses to Pay with ApplePay , an authorization request is triggered. Simultaneously, if the ApplePay session is successfully authorized via Face ID or Touch ID, ConvesioPay will securely and automatically create the payment token that represents the card details entered into the component along with some information about the origin of the customer. You can get that token from the component event change handler. You will need to use this as the paymentToken later when you are ready to create the payment. You can use this token to create a card payment server side with the API. Do not attempt to create a card payment request client side. The following properties are required to use this method: integration - string REQUIRED The name of your ConvesioPay integration returnUrl - string REQUIRED The url to return the user to if a redirect is necessary amount - number REQUIRED Total amount to be paid in minor units currency - string REQUIRED 3 character ISO currency code email - string REQUIRED The email of the customer name - string REQUIRED The name of the customer Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units). The following properties are optional when using this method (see Create a Card Payment for more details on their data structure): billingAddress - object The customer's billing address shippingAddress - object The customer's shipping address lineItems - object Information about the line items for the order Customers can take advantage of ApplePay when viewing your integration in the Safari browser on an Apple device and are signed into the same or another Apple device with ApplePay enabled that can authorize the payment via Face ID or Touch ID. Handling Payment Events We expose a change event you can subscribe to in the checkout component. The change event is triggered when the component's value changes and provides valuable feedback on the payment status and details. You can learn more about these change events here .
• [Create GooglePay Session (OL)](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-intents/create-googlepay-session-ol.md): component.createGooglePaySession() Creates an GooglePay session that allows the customer to initiate a tokenized payment intent that represents the payment details the customer provided along with some information about their origin. This is considered a setup method that should be called promptly after mounting the component if you want to offer GooglePay and must be called before the customer interacts with the component. In order to take GooglePay payments in your integration, you will need to enable it on the Checkout API Payment Methods page in the dashboard in Advanced Settings and ensure that the domain is registered and listed in the GooglePay Domains table. Once the customer chooses to Pay with GooglePay , an authorization request is triggered. Simultaneously, if the GooglePay session is successfully authorized over the web or wallet, ConvesioPay will securely and automatically create the payment token that represents the card details entered into the component along with some information about the origin of the customer. You can get that token from the component event change handler. You will need to use this as the paymentToken later when you are ready to create the payment. You can use this token to create a card payment server side with the API. The following properties are required to use this method: integration - string REQUIRED The name of your ConvesioPay integration returnUrl - string REQUIRED The url to return the user to if a redirect is necessary amount - number REQUIRED Total amount to be paid in minor units currency - string REQUIRED 3 character ISO currency code Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units). The following properties are optional when using this method (read more about each below): shippingType - string The list of supported shipping types to display/allow in the GooglePay popup for purchased items. Possible values can be: shipping delivery storePickup servicePickup supportedCountries - array An array of strings representing a list of 2 letter country codes to display in the GooglePay popup as supported shippingMethods - array An array of objects representing supported shipping methods to display in the GooglePay popup. Each object must contain the following properties: label - string A short description of the shipping method detail - string Additional description of the shipping method amount - string The nonnegative cost associated with this shipping method identifier - string A value you define that is used to identify this shipping method lineItems - array An array of objects used to explain additional charges, discounts, and pending costs to display in the GooglePay popup. Each object must contain the following properties: label - string A short, localized description of the line item type - string A value that indicates whether the line item is final or pending amount - string The monetary value associated with the line item onShippingAddressChange - object The event handler to call when the customer selects a shipping address in the GooglePay popup onShippingMethodChange - object The event handler to call when the customer selects a shipping method Implementation Examples of Optional GooglePay Properties shippingType JavaScript const googlePaySession = await component.createGooglePaySession({ // Other required and optional items omitted for brevity shippingType: 'shipping' // ['shipping'|'delivery'|'storePickup'|'servicePickup'] }); supportedCountries JavaScript const googlePaySession = await component.createGooglePaySession({ // Other required and optional items omitted for brevity supportedCountries: ['US', 'CA', 'GB'] }); shippingMethods JavaScript const googlePaySession = await component.createGooglePaySession({ // Other required and optional items omitted for brevity shippingMethods: [ { label: 'Standard Shipping', detail: '5-7 business days', amount: 500, identifier: 'standard' }, { label: 'Express Shipping', detail: '1-2 business days', amount: 1500, identifier: 'express' } ] }); lineItems JavaScript const googlePaySession = await component.createGooglePaySession({ // Other required and optional items omitted for brevity lineItems: [ { label: 'Subtotal', amount: 1500 }, { label: 'Shipping', amount: 500 }, { label: 'Tax', amount: 120 } ] }); onShippingAddressChange JavaScript const googlePaySession = await component.createGooglePaySession({ // Other required and optional items omitted for brevity onShippingAddressChange: async (shippingContact) => { // Recalculate tax/shipping based on new address. // MUST return within 30 seconds or Google Pay shows "Payment Not Completed". const newTax = calculateTax(shippingContact.countryCode, shippingContact.administrativeArea); const newShipping = getShippingCost(shippingContact.countryCode); const newTotal = 1500 + newTax + newShipping; return { newTotal: { label: 'My Store', amount: (newTotal / 100).toFixed(2), type: 'final' }, newLineItems: [ { label: 'Subtotal', amount: (1500 / 100).toFixed(2), type: 'final' }, { label: 'Shipping', amount: (newShipping / 100).toFixed(2), type: 'final' }, { label: 'Tax', amount: (newTax / 100).toFixed(2), type: 'final' } ], // To reject an address: // error: { // reason: 'SHIPPING_ADDRESS_UNSERVICEABLE', // message: 'We cannot ship to this address', // intent: 'SHIPPING_ADDRESS' // } }; } }); onShippingMethodChange JavaScript const googlePaySession = await component.createGooglePaySession({ // Other required and optional items omitted for brevity onShippingMethodChange: async (shippingMethod) => { const shippingCost = shippingMethod.identifier === 'express' ? 1500 : 500; const newTotal = 1500 + shippingCost + 120; return { newTotal: { label: 'My Store', amount: (newTotal / 100).toFixed(2), type: 'final' }, newLineItems: [ { label: 'Subtotal', amount: (1500 / 100).toFixed(2), type: 'final' }, { label: 'Shipping', amount: (shippingCost / 100).toFixed(2), type: 'final' }, { label: 'Tax', amount: (120 / 100).toFixed(2), type: 'final' } ], }; } }); Handling Payment Events We expose a change event you can subscribe to in the checkout component. The change event is triggered when the component's value changes and provides valuable feedback on the payment status and details. You can learn more about these change events here .
• [Create BTCPay Session](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-intents/create-btcpay-session.md): Creates an BTCPay session that allows the customer to initiate a tokenized payment intent that represents the payment details the customer provided along with some information about their origin. After creating the session server-side, you will want to create the BTCPay payment intent with the session object returned from the BTCPay session response. These 2 steps are considered setup methods that should be called promptly after mounting the component if you want to offer BTCPay and must be called before the customer interacts with the component. In order to take BTCPay payments in your integration, you will need enable the BTCPay Server integration on the Integrations page and then enable it as a payment method on the Checkout API Payment Methods page in the dashboard in Advanced Settings. BTCPay session requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. BTCPay session requests must be made server side, do not attempt to create a payment client side. The following properties are required to use this endpoint: integration returnUrl orderNumber amount currency email name Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units).
• [Create BTCPay Intent](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-intents/create-btcpay-payment.md): component.createBTCPayIntent(sessionObject) Creates a BTCPay payment intent that correspods to the tokenized payment data and customer details passed into the session created before this step. After creating the BTCPay payment intent, you must to create a BTCPay session server-side. These 2 steps are considered setup methods that should be called promptly after mounting the component if you want to offer BTCPay and must be called before the customer interacts with the component. Once the customer chooses to Pay with Crypto , a BTCPay invoice request is triggered with the active session and there is no need for a separate API call to create the payment. The customer will be presented options to pay with their crypto wallet and ConvesioPay will track the Payment Lifecyle and report accordingly. In order to take BTCPay payments in your integration, you will need enable the BTCPay Server integration on the Integrations page and then enable it as a payment method on the Checkout API Payment Methods page in the dashboard in Advanced Settings. The following properties are required to use this method: session - string REQUIRED The BTCPay session created Handling Payment Events We expose a change event you can subscribe to in the checkout component. The change event is triggered when the component's value changes and provides valuable feedback on the payment status and details. You can learn more about these change events here .
• [Affirm Payments](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payment-intents/affirm-payments.md): When a customer clicks the Pay with Affirm button, the component will attempt to create a payment token for Affirm. If the customer information required is valid and the token is created successfully, a change event will fire with event.isSuccessful set to true and an event.token property containing the token. Pass this token as the paymentToken in your payment request, the same way you would for any other payment method. Customer Action Required Affirm payments require a customer action step before the payment can be completed. Similar to 3DS authentication, the payment response will include a Pending status and an actionRequired object. Use the same redirect handling you use for 3DS payments to send the customer to complete their Affirm session. Example Response JSON "status": "Pending", "actionRequired": { "type": "redirect", "redirectUrl": "https://convesiopay.com/verify-customer/1234567890987654321" }, … After Authorization When a redirect is required, the payment status will remain Pending . Affirm session links are typically valid for 24 hours, during which the customer must complete the Affirm verification step. Once the customer completes their session, the payment will be submitted for authorization and the final status will be updated to Succeeded or Failed . ConvesioPay will send a webhook notification with the result.
• [Payments Life Cycle](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/payments-life-cycle.md): ConvesioPay manages the intricate processes of a complete payment flow, which moves through several stages throughout its lifecycle. You can reference the Webhooks section to learn more about how you can get payment updates by subscribing to the ConvesioPay Checkout API webhook. The following are the possible payment statuses: Payment Status Description Pending If you configured your account to Manually Capture payments, in the ConvesioPay dashboard under Advanced Settings > Checkout Settings , then all payments will authorize the payment method but will not capture funds until explicitly captured by the merchant. Succeeded All merchant accounts are set to Auto Capture payments by default. In this case, most payments are authorized and funds are then quickly captured. Failed Failed status occurs in cases where a payment has been refused by the card issuer, was authorized but uncaptured and eventually expired, etc. Cancelled Authorized but uncaptured payments can be cancelled in the ConvesioPay dashboard or via a supported integration. Refunded Authorized and captured payments can be refunded in the ConvesioPay dashboard or via a supported integration. Disputed A payment can be disputed for a period of time (varies by issuer) if the card holder makes a request to the card issuer. Blocked If a payment is considered to be of high risk by our fraud management technology, the payment will be blocked.
• [Create a Payment (OL)](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/create-a-payment-ol.md): Creates a new payment with the token (tokenized payment method) collected from one of your customers via the checkout component. Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side. For Credit Card or BTCPay payments, The following properties are required to use this endpoint for credit cards or BTCPay: integration returnUrl paymentToken orderNumber amount currency email name For accelerated payment methods like ApplePay or GooglePay , name , email , billingAddress , and shippingAddress are provided via the accelerated payment method integration itself and are not required in the payment request. The following properties are required to use this endpoint : integration returnUrl paymentToken orderNumber amount currency Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units).
• [(DEPRECATED) Create a Payment](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/deprecated-create-a-payment.md): There is a newer version of this page here , you are currently viewing outdated information based pre-orchestration protocol. If you are not yet utilizing our Orchestration Layer, please contact support for more information. Creates a new payment with the token (tokenized payment method) collected from one of your customers via the checkout component. Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side. The following properties are required to use this endpoint: integration returnUrl paymentToken orderNumber amount currency email name Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units).
• [Create a Payment Link](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/create-a-payment-link.md): Payment Links can be used to take payments without requiring a website or other integration. Get started selling products or services without a single line of code or integrate them into your marketing emails, sales processes, CRMs. You can quickly and easily create, copy, and paste a link anywhere or optionally enable them to be automatically emailed to your customer upon creation. You can customize the look and feel of a Payment Link by uploading your logo and specifying your brand colors on the Payment Link Branding page of the dashboard in Advanced Settings. Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side. The following properties are required to use this endpoint: amount currency email name Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units).
• [Test Cards](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/test-cards.md): Before accepting live payments, if you are testing in Test Mode you can use the card details on this page to test your integration. Note - Test cards can not be used with ApplePay and attempted ApplePay payments with real cards will fail in Test Mode. To Test Successful Payments Card Number Card Type Expiration Date CVC 4000 0200 0000 0000 Visa 03/30 737 5100 0600 0000 0002 Mastercard 12/29 737 6011 6011 6011 6611 Discover 03/30 737 To Trigger a Failed Payment Card Number Card Type Expiration Date CVC 4000 0200 0000 0000 Visa 03/29 737 To Test Payments that trigger 3DS Card Number 3DS Flow Card Type Expiration Date CVC 5201 2815 0512 9736 Frictionless Mastercard 03/30 737 4212 3456 7891 0006 Challenge Action Visa 03/30 737
• [Webhooks](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/webhooks.md): Get notified about ConvesioPay Checkout API events. Webhooks are subscriptions to ConvesioPay events to a specific notification URL. The notification URL receives event notifications from ConvesioPay. These notifications are delivered as a JSON data payload from a POST request. When subscribing to this webhook, the server hosting your notification URL must confirm the successful receipt of the event. You can register your notification URL for the Checkout API Payment webhook in the dashboard on the Advanced Settings page. Your webhook subscription must do the following: Receive a POST event notification. Respond with a 2xx HTTP status in a timely manner. Require that connections use HTTPS . Store the event notification data safely. Note the paymentId and eventCode fields in the body of each event notification. Design your application to use bypass processing event notifications if these values to bypass processing if it's a repeated value. Event Webhook Retries ConvesioPay will attempt to continue to deliver (retry) event webhook notifications if it believes the webhook delivery was unsuccessful. ConvesioPay considers the delivery unsuccessful in the event that a 2xx HTTP status code isn't received in a timely manner or a status code other than 2xx is returned. Retries are processed at recurring intervals with exponential backoff for up to 72 hours after the originating event. After 72 hours, ConvesioPay will consider the webhook notification to have failed and will not attempt to resend the notification. The retry policy looks like this: Retry attempt Backoff 1-5 Every minute for 5m 6-13 Every 15 minutes for 2h 14-18 Every hour for 5h 19-21 Every day for 3d Validate Event Webhooks After you verify that your event webhook subscription is working, you need to add code to the server hosting your notification URL so that your application can process the event information. Because your notification URL is public and can be called by anyone, you need to validate each event notification to confirm that it came from ConvesioPay. A POST request to your notification URL could potentially compromise your application. All ConvesioPay Checkout API webhook notifications will include both the x-convesiopay-hmacsha256-signature and x-convesiopay-timestamp request headers. The value of the "signature" header is an HMAC-SHA-256 signature generated using the webhook signature key you provided when registering the webhook in the dashboard and the value of the x-convesiopay-timestamp request header. You can validate the webhook notification by generating the HMAC-SHA-256 value in your own code and comparing it to the signature of the event webhook notification you received. NOTE - A malicious agent can compromise your notification endpoint by using a timing analysis attack to determine the key you're using to decrypt and compare webhook signatures. You should use a constant-time crypto library to prevent such attacks by masking the actual time taken to decrypt and compare signatures. The following functions generates an HMAC-SHA256 signature from your signature key. You can then compare the result with the event notification's x-convesiopay-hmacsha256-signature . NOTE - When validating your webhook event notifications, make sure that you're using the x-convesiopay-timestamp in the request header, not the request body, as the signature value without any whitespace. For example, "x-convesiopay-timestamp": "2024-11-08T18:24:41.859Z" Here is an example of how you might do this in a Node.js application: JavaScript const crypto = require("crypto"); const convesioPayTimestamp = request.headers["x-convesiopay-timestamp"]; request.headers["x-convesiopay-hmacsha256-signature"]; const webhookSignature = process.env.{YOUR_WEBHOOK_SIGNATURE}; const rawKey = Buffer.from(webhookSignature, "utf8"); const hmacSignature = crypto .createHmac("sha256", rawKey) .update(convesioPayTimestamp, "utf8") .digest("base64"); /* Compare signatures */ if (convesioPayHmacSignature === hmacSignature) { console.log("Signature is valid"); } else { console.log("Signature is invalid"); } Here is an example of how you might do this in a PHP application: PHP $convesioPayTimestamp = $_SERVER['HTTP_X_CONVESIOPAY_TIMESTAMP']; $convesioPayHmacSignature = $_SERVER['HTTP_X_CONVESIOPAY_HMACSHA256_SIGNATURE']; $webhookSignature = getenv('{YOUR_WEBHOOK_SIGNATURE}'); $hmacSignature = base64_encode(hash_hmac("sha256", $convesioPayTimestamp, $webhookSignature, true)); /* Comapare signatures */ if ($convesioPayHmacSignature === $hmacSignature) { echo "Signature is valid"; } else { echo "Signature is invalid"; } Payment Event Webhook Reference All payment event webhook requests will include the following header for reference in case you are ingesting events for more than one account at the same webhook notification URL and/or need assistance with de-duping notifications regarding retries: X-ConvesioPay-Merchant-API-Key X-ConvesioPay-Event-Id Payment Event Webhook Payload Properties eventType - string The event type of the webhook notification paymentId - string A unique ID for the payment createdAt - string The timestamp the payment was created updatedAt - string The timestamp the payment was updated status - string Indicates whether the payment is Pending, Succeeded, Failed, Blocked, Refunded, Cancelled, or Disputed orderNumber - string The payment reference provided in the payment request integration - string The name of your ConvesioPay integration amount - string Total amount paid in minor units returnUrl - string The url to return the user to if a redirect is necessary currency - string 3 character ISO currency code email - string The email of the customer name - string The name of the customer paymentMethodDetails - object The payment method details used for the payment disputeDetails - object The dispute details associated with the payment if applicable Payment Webhook Request Body Example: JSON { "eventType": "payment", "paymentId": "993617895215577D", "createdAt": "2024-10-18T15:15:43.203Z", "updatedAt": "2024-10-18T15:17:43.203Z", "status": "Succeeded", "orderNumber": "string", "amount": 10, "integration": "string", "returnUrl": "string", "currency": "USD", "customerId": "1a234b567c89d", "email": "jsmith@test.com", "name": "John Smith", "billingAddress": { "houseNumberOrName": "5647", "street": "Cypress Hill Ave.", "city": "Middlefield", "stateOrProvince": "CA", "postalCode": "94303", "country": "US" }, "shippingAddress": { "houseNumberOrName": "5647", "street": "Cypress Hill Ave.", "city": "Middlefield", "stateOrProvince": "CA", "postalCode": "94303", "country": "US" }, "lineItems": [ { "description": "Rock Fountain", "quantity": 1, "amountIncludingTax": 27500 }, { "description": "Fountain Pump", "quantity": 1, "amountIncludingTax": 1275 }, { "description": "Concrete for fountain installation", "quantity": 5, "amountIncludingTax": 4750 } ], "paymentMethodDetails": { "type": "card", "brand": "visa", "cardHolderName": "John Smith", "expirationDate": "03/2030", "last4": "1234", "storedPaymentMethodId": "1234567890" }, "disputeDetails": { "cardNumberLastFour": "1234", "disputedOn": "2026-04-10T12:41:20.566Z", "respondBy": "2026-05-20T12:40:58.000Z", "status": "Undefended", "needsResponse": true } } Payment Method Update Event Webhook Reference All payment method update event webhook requests will include the following header for reference in case you are ingesting events for more than one account at the same webhook notification URL and/or need assistance with de-duping notifications regarding retries: X-ConvesioPay-Merchant-API-Key X-ConvesioPay-Event-Id Customer Payment Method Update Event Webhook Payload Properties eventType - string The event type of the webhook notification customerId - string The ConvesioPay ID of the customer email - string The email of the customer action - string The action performed by the customer for the payment method update. Possible values are create, update, delete, or setDefault. affectedPaymentMethodId - string The ID of the payment method affected defaultPaymentMethodId - string The ID of the payment method currently set as the default. Primarily only used for recurring payments if a storedPaymentMethodId is not explicitly provided) storedPaymentMethods - string The customer's stored payment methods (cards on file) Customer Payment Method Update Webhook Request Body Example: JSON { "eventType": "paymentMethods", "customerId": "1a234b567c89d", "email": "jsmith@test.com", "action": "setDefault", "defaultPaymentMethodId": "1234567890", "affectedPaymentMethodId": "1234567890", "storedPaymentMethods": [ { "brand": "mc", "expiryMonth": "12", "expiryYear": "29", "holderName": "John Smith", "id": "0987654321", "lastFour": "0002", "type": "scheme" }, { "brand": "visa", "expiryMonth": "03", "expiryYear": "30", "holderName": "John Smith", "id": "1234567890", "lastFour": "0000", "type": "scheme" } ] }
• [3D Secure Authentication](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/3d-secure-authentication.md): When a payment request is made, several conditions may trigger 3D Secure (3DS) authentication. ConvesioPay supports multiple 3DS authentication flows, whether triggered explicitly in the payment request, required due to fraud signals, geographic regulations, or enforced by the downstream Payment Service Provider (PSP). ConvesioPay is designed to minimize friction while ensuring compliance and maximizing authorization success rates. Frictionless Whenever possible, ConvesioPay attempts to perform frictionless authentication by leveraging customer and transaction data collected during the payment process. Also known as Silent 3DS, this approach enriches the data sent to the PSP with signals such as device fingerprinting, customer behavior, and historical transaction data—allowing authentication to occur without requiring customer interaction. This provides the best possible user experience while still meeting authentication requirements. Customer Challenge IIf a customer challenge is required, ConvesioPay will attempt to handle it without requiring a full-page redirect. When supported, challenges are handled directly within the Checkout Component, allowing the payment to be authenticated seamlessly in-context. ConvesioPay will also pre-authorize payments using enriched transaction data to improve authorization success rates. If a redirect is required, the payment response will include an actionRequired parameter indicating that additional customer interaction is needed to complete the payment. If necessary, ConvesioPay will instruct the integration to redirect the customer to a 3DS verification URL. Even in these cases, ConvesioPay first attempts a frictionless authentication using enriched data before requiring customer interaction. Below is an example of a payment response when additional action is required: Example Response JSON "status": "Pending", "actionRequired": { "type": "redirect", "redirectUrl": "https://convesiopay.com/verify-customer/1234567890987654321" }, … After Authorization When a redirect or challenge is required, the payment status will remain Pending . 3DS verification links are typically valid for 10–15 minutes. During this time, the customer must complete the required authentication step. Once completed—whether frictionlessly or via challenge—the payment will be submitted for authorization. The final status will then be updated to Succeeded or Failed , and ConvesioPay will send a webhook notification with the result. External 3D Secure 2 Authentication This is intended for integrations that perform external 3DS authentication, outside of ConvesioPay, and want to submit the resulting ECI, CAVV, transaction ID, and authentication status with the payment authorization request. Use threeDSData to provide the result of a completed external 3-D Secure authentication. When supplied, ConvesioPay will use the provided authentication data during authorization instead of initiating a new 3DS flow. Example threeDSData Object to include in the Payment Request JSON "threeDSData": { "cavv": "AAABBBCCC...", "eci": "05", "xid": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b", "version": "2.2.0", "authenticationStatus": "Y" }, …
• [List Payments](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/list-payments.md): Retrieves a list of payments taken by the account and integration making the request. New payments or changes to payments might take several seconds to appear. The maximum results per page is 100. Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side.
• [Get a Single Payment](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/get-a-single-payment.md): Retrieves details for a single payment. Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side. The following path parameters are required to use this endpoint: paymentId
• [Refund a Payment](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/refund-a-payment.md): Refunds a payment with the corresponding paymentId (either partially or in full). Refunds can only be made on payments that have Succeeded . The funds must have been captured and not only authorized. ConvesioPay auto-captures funds for successfully authorized payments by default but merchants can change this behavior in the Checkout Settings . Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side. The following path parameters are required to use this endpoint: paymentId The following properties are required in the request body to use this endpoint: currency amount Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units).
• [Manually Capture Payment](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/manually-capture-payment.md): Manually captures a payment with the corresponding paymentId . Capture requests can only be made for payments that have a Pending status. The funds must have been previously authorized but not yet captured. ConvesioPay auto-captures funds for successfully authrorized payments by default but merchants can change this behavior in the Checkout Settings . Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side. The following path parameters are required to use this endpoint: paymentId The following properties are required in the request body to use this endpoint: currency amount Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units).
• [Cancel a Payment](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/payments/cancel-a-payment.md): Cancels a payment with the corresponding paymentId . Only payments that have a Pending status can be cancelled. The funds must have been previously authorized but not yet captured. ConvesioPay auto-captures funds for successfully authrorized payments by default but merchants can change this behavior in the Checkout Settings . Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side.hkj The following path parameters are required to use this endpoint: paymentId
• [Create an S2S Card Payment](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/server-to-server-payments/create-a-card-payment.md): Some integrators may desire to create direct S2S (or Server-to-Server) card payments on behalf of their merchants using the sensitive, raw card data their platform has already externally vaulted or otherwise collected via their own processes, requiring PCI compliance to handle card data securely. This method bypasses the need to present additional customer-facing checkout UI. It is ideal for automated, backend, or subscription-based billing systems. Unlike using the Checkout Component, where the customer securely enters their card details into the Component rendered on the merchant's site in order to create a secure payment token that can be used to make a payment later, S2S card payments allow the integration to directly submit the card data and keep the customer within their own (or the merchant's own) app or website UI entirely, offering a seamless user experience. NOTE - S2S Payments are not generally available for everyone. This API requires explicit special permission. If you are interested in utilizing S2S Payments in your integration please contact support at pay@convesio.com . Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side. The following properties are required to use this endpoint: integration returnUrl paymentMethod orderNumber amount currency email name Though not strictly required, browserInfo and ipAddress are strongly recommended to promote higher authorization rates and better fraud prevention experience with the S2S payment flow. Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units).
• [Add a Card On File](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/server-to-server-payments/add-a-card-on-file.md): As an integrator making S2S payments, if you are required to store cards on file before creating an initial payment you will need to pre-authorize cards for future MIT payments (Merchant Intiated Transactions) while you have access to all the card details. Cards can be added on file and stored for future payments if you can include the CVC. ConvesioPay does not store CVCs long-term but it is required when adding the card on file with intent for MIT. When using this endpoint to create a card on file the payment method ID that was stored will be present in the payment webhook request, not in the payment response. The storedPaymentMethodId can then be used to create a Card On File Payment . NOTE - S2S Payments are not generally available for everyone. This API requires explicit special permission. If you are interested in utilizing S2S Payments in your integration please contact support at pay@convesio.com . Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side. The following properties are required to use this endpoint: paymentMethod integration email name Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units).
• [Recurring Payments](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/subscriptions/recurring-payments.md): The Checkout API supports making recurring payments in 2 forms for customers that choose to check option to store their payment methods on file for future payments: Card on File Payments (Unmanaged Subscriptions) - Card on File Payments allow you to utilize a customer's stored payment method to make recurring payments in your integrations. It should be understood that your customers must be aware of and expect each recurring payment request before it occurs. A great example of this would be an integration that manages subscription flows outside of ConvesioPay (ie customers with existing subscriptions via your integration and the requirement is to be able to use the Checkout API to make the recurring payment at that subscription's communicated interval). Managed Subscriptions (Coming Soon) - We don't yet support Managed Subscriptions but it is on our roadmap to release soon. Managed Subscriptions will allow you to utilize ConvesioPay's managed subscription flows to take recurring payments on a set schedule (ie daily, weekly, monthly, or annually) for access to a service or product in your integration. With Managed Subscriptions, customers are automatically charged on a fixed interval and your customer's stored payment method is charged on the same date every billing cycle.
• [Create a Card On File Payment](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/subscriptions/create-a-card-on-file-payment.md): Creates a new payment from a stored payment method collected and securely persisted at the request of one of your customers via the checkout component. Payment requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. All payment requests must be made server side, do not attempt to create a payment client side. The following properties are required to use this endpoint: integration returnUrl orderNumber amount currency customer Note - Please note that all currency amount fields are in minor units (ie $9.49 would be expressed as 949 ). Also be aware that the minimum processable amount is 50 cents (ie 50 in minor units).
• [Update Cards on File](https://docs.convesiopay.com/convesiopay-payment-checkout-integration-api/customers/update-cards-on-file.md): When integrating with the ConvesioPay Checkout API, there may be times where your customers need to manage their cards on file. This API endpoint provides a way for the integrator to generate a secure link to the ConvesioPay Card Manager on behalf of the customer. This creates a method for the customer to do the following during the life of the Card Manager session: Add new cards Update existing cards Delete existing cards Set the default (used for recurring payments if a storedPaymentMethodId is not explicitly provided) To grant your customers access to the Card Manager, you simply need to pass the customerId in the API request and the customer will be emailed a secure link including a short-term session to manage their stored payment methods. Note - Card Manager sessions are only valid for 15 minutes for the security of the customer. Also if more than 3 active sessions exist in a 15 minute period, additional requests will be denied. You can customize the logo and brand colors for the Card Manager and the secure link email to be consistent with your integration branding in the dashboard on the Card Manager Branding page in Advanced Settings. Card Manager requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. Customer Card Manager session requests must be made server side, do not attempt to request a link to the Card Manager client side. The following properties are required to use this endpoint: customerId