Handling Successful Embedded Actions

Once a successful action has been performed on an embedded component (such as a successful payment or card saved), you have a few options for handling the result. You should verify the response came from ChargeDesk if using the results to perform business logic. You should also verify payment success before shipping physical products or providing unrevokable access such as one time digital downloads.

Option 1: Do Nothing

There is no need to handle successful actions on embedded pages if no additional business logic is required. If you don't add a specific method for handling the successful response, an informative message will be displayed to the customer letting them know that the action was performed successfully. The charge will still be successfully created, or card saved without any action from you. This data will be passed to your payment gateway and synced to ChargeDesk automatically.

Option 2: Use the 'successURL' field

You can enter a URL to redirect the customer to on a successful action using the successURL field. Typically this will be another page on your site which lets the customer know the action was performed successfully. You can include any of the response fields listed below in this URL using by wrapping them in {}. For example, to obtain the customer id and charge id, you could use the following URL.

successURL: "https://yourdomain.com/success?customer={customer_id}&charge={charge_id}"

To perform business logic based on the result, you should only use the secure parameters e.g.

successURL: "https://yourdomain.com/success?secure_response={secure_response}"

Option 3: Use the 'onSuccess' handler

The final option is to handle a successful result programmatically using the onSuccess handler. This will call a JavaScript function which you can use to decide how to handle the response. The response fields in the next section will be available on the response object.

Please note: If you provide both a successURL and an onSuccess handler, the onSuccess handler will be ignored. If you provide an onSuccess handler then no message will be shown to the user on a successful action (the embedded component will be blank), so you should inform the user that the action was a success.

onSuccess: function(response) {
    alert("Success: "+response.msg+" Your customer ID is "+response.customer_id);
}

Response Fields

The following fields may available to be replaced in the successURL and as keys in the response object for the onSuccess handler. The available fields depends on the type of the action performed and the payment gateway used.

• msg
  A string informing the user that the action was performed successfully. This would be the message displayed to the user if a success handler is not used.
• customer_id
  The ChargeDesk ID of the customer created in the transaction. Will match the customer ID from your payment gateway in most cases.
• gateway_id
  The ID of the gateway which the customer used to perform the action.
• company_id
  The ChargeDesk Company ID used to perform the action.
• charge_id
  The ChargeDesk Charge ID for the created transaction.
  Only available when a transaction has been created by the action.
• charge_status
  The status of the charge created by this transaction.
  Only available when a transaction has been created by the action.
• transaction_id
  The Transaction ID (from your payment gateway) for the created transaction.
  Only available when a transaction has been created by the action.
• product_id
  The ChargeDesk Product ID for the created transaction.
  Only available when a product was used by the action.
• subscription_id
  The ChargeDesk Subscription ID for the created subscription.
  Only available when a subscription was created by the action.
• subscription_status
  The status of the subscription created by this transaction.
  Only available when a subscription was created by the action.
• timestamp
  The time when the action was performed in Unix time (seconds since epoch).
• secure_response
  A string containing an encoded version of the response object. Can be passed to your server to verify the response came from ChargeDesk.

Verify Payment Success

When the customer is sent to the successURL or the onSuccess handler is called, you should verify that the payment has completed successfully before performing business actions, such as shipping products or sending digital downloads. You should wait until the status of the charge is paid before performing these actions to ensure the payment will appear in your account. Some gateways have charges enter a pending state before settlement where they can still fail after initial verification has completed.

This is also particularly true when creating subscriptions as subscriptions can be created but not immediately charged. You should wait until the subscriptions is active and the first charge is paid before completing checkout business logic. You can use the subscription_status and charge_status response fields to check initially if the customer passes these checks. If these checks fail, you can watch for webhook events such as subscription_updated and charge_paid to know when the customer has successfully paid.