Post Response Module

Some payments cannot be completed in a single server-to-server call. The issuer may need to challenge your customer, or the payment method may need to send them to an external provider. When that happens, the BR-DGE REST API returns a post-response action: a small instruction telling you that something must happen in the customer's browser before the payment can proceed.

The Post Response Module carries out that instruction for you. You hand it the action object exactly as your server received it, and the module renders the challenge, talks to the relevant provider, and resolves with the result you need to finish the payment.

How it works

A post-response action is always a three-way conversation between your server, your customer's browser, and BR-DGE. Your server never handles the challenge itself — it only passes the action along.

sequenceDiagram
    autonumber
    participant Browser as Customer's browser
    participant Server as Your server
    participant BRDGE as BR-DGE REST API
    participant PSP as PSP / Issuer
 
    Browser->>Server: Submit checkout details
    Server->>BRDGE: POST /v1/payments
    BRDGE-->>Server: 202 Accepted, actionRequired: true, action: { ... }
    Server-->>Browser: The action object
    Browser->>Browser: handleAction(action)
    Browser->>PSP: SDK performs the challenge
    PSP-->>Browser: Authentication outcome
    Browser-->>Server: Resolved result (code, nonce)
    Server->>BRDGE: POST /v1/payments with the nonce
    BRDGE-->>Server: 201 Approved, or another action
    Server-->>Browser: Final outcome

In words:

1. Your server creates a payment and receives a 202 Accepted response containing actionRequired: true and an action object. For 3-D Secure this arrives with response code 2001.
2. Your server passes the action object to your client. Nothing else from the response is needed.
3. Your client passes it to handleAction. The module resolves with a result — typically a nonce under response code 2002.
4. Your client sends that result to your server, which completes the payment using a ProviderThreeDSecureNonce payment instrument.
5. Depending on the PSP, step 4 may return another action. If it does, repeat from step 2.

For the wider context, see the 3-D Secure Payment Flow and Post-Response Actions.

Before you begin

You will need:

The Web SDK is plain ES5 JavaScript. There is no build step, no bundler and no framework requirement — the scripts attach a global comcarde object to the page.

Install

Add the module script to your page, after the client script. Use the sandbox asset host while developing and the production host for live traffic.

<script src="https://sandbox-assets.comcarde.com/web/v2/js/client.min.js"></script>
<script src="https://sandbox-assets.comcarde.com/web/v2/js/post-response-action.min.js"></script>

<script src="https://assets.comcarde.com/web/v2/js/client.min.js"></script>
<script src="https://assets.comcarde.com/web/v2/js/post-response-action.min.js"></script>

Load order matters: client.min.js must be parsed before the module script runs, and both must be present before you call comcarde.client.create.

Quick start

The minimum viable integration. Create the client, create the module, hand it an action.

comcarde.client.create(
  {
    authorization: clientApiKey // your Client API Key
  },
  function (clientErr, clientInstance) {
    if (clientErr) {
      console.error('Client creation failed', clientErr);
      return;
    }
 
    comcarde.postResponseAction.create(
      {
        client: clientInstance
      },
      function (err, postResponseActionInstance) {
        if (err) {
          console.error('Module creation failed', err);
          return;
        }
 
        // The 'action' object from your server's payment response.
        var action = actionFromServerResponse;
 
        postResponseActionInstance
          .handleAction(action)
          .then(function (response) {
            // The action completed. Inspect response.code to decide what to do next.
            console.log(response.code, response.message);
          })
          .catch(function (handleErr) {
            console.error('handleAction failed', JSON.stringify(handleErr));
          });
      }
    );
  }
);

API reference

comcarde.postResponseAction.create(options, callback)

Creates a module instance bound to a client instance.

The callback receives an error or an instance — always check err before using the instance. Errors follow the standard Web SDK error shape:

{
  "code": "4001",
  "message": "Access denied."
}

Create the instance once when your checkout page loads and reuse it. You do not need a fresh instance per action.

instance.handleAction(action[, callbacks])

Executes a post-response action. Returns a Promise.

The action object

Pass this through verbatim. Do not reshape it, add fields, or strip fields — the module uses type to select the correct PSP-specific handler.

{
  "action": {
    "type": "3D_SECURE",
    "paymentId": "22669f90-5bf0-45df-ba8c-ea6d4235a5da",
    "data": {
      "clientToken": "aaabbb",
      "verifyCardPayload": "payload"
    }
  }
}

The resolved response

The codes you are most likely to see:

Other codes are possible depending on the payment method and PSP, so write your handler with a default branch rather than assuming only the two above.

threeDSecureInfo

Supplied when the PSP returns authentication detail. Always check the object exists before reading it.

Callbacks

You can optionally pass functions that fire at points during execution, which is useful for managing spinners and re-enabling your pay button.

var callbacks = {
  windowClosed: function () {
    // The customer dismissed the challenge window.
    hideSpinner();
    enablePayButton();
  },
  actionCompleted: function () {
    // The action finished; the promise is about to resolve.
    hideSpinner();
  }
};
 
postResponseActionInstance.handleAction(action, callbacks);

Controlling the challenge z-index

3-D Secure challenges are rendered in a modal window layered over your checkout page. If your own page has high-stacking elements — a sticky header, a cookie banner, a basket drawer, a loading overlay — they can appear on top of the challenge, or hide it entirely. The customer sees a blank or partially obscured overlay and abandons.

Pass threeDSModalZIndex in the styles object when creating the module to place the challenge window at a specific z-index:

comcarde.postResponseAction.create(
  {
    client: clientInstance,
    styles: {
      threeDSModalZIndex: 12000
    }
  },
  function (err, postResponseActionInstance) {
    if (err) {
      console.error('Module creation failed', err);
      return;
    }
 
    // ... handleAction as usual
  }
);

Set this to a value above the highest z-index on your checkout page. Audit what you actually use rather than guessing — third-party scripts such as chat widgets, consent managers, and session-recording tools frequently sit in the tens of thousands.

Because this affects presentation only, it cannot cause an authentication failure — but it is a common cause of apparent ones, where the challenge renders correctly and the customer simply cannot see or interact with it. If you see an unexplained cluster of THREE_D_SECURE_METHOD_FAILURE errors or windowClosed callbacks, check this before escalating.

Worked example: 3-D Secure

This is the full pattern, including the liability-shift decision and the error path.

comcarde.client.create(
  {
    authorization: clientApiKey // your Client API Key
  },
  function (clientErr, clientInstance) {
    if (clientErr) {
      console.error('Client creation failed', clientErr);
      return;
    }
 
    comcarde.postResponseAction.create(
      {
        client: clientInstance
      },
      function (err, postResponseActionInstance) {
        if (err) {
          console.error('Module creation failed', err);
          return;
        }
 
        var action = paymentResponse.action;
 
        postResponseActionInstance
          .handleAction(action)
          .then(function (response) {
            var paymentId = response.paymentId;
 
            if (response.code === '2002') {
              // Authentication finished. A nonce is available to complete the payment.
              var info = response.threeDSecureInfo;
 
              if (info && info.liabilityShifted) {
                // Authentication succeeded, or the issuer does not support 3-D Secure
                // while the payment method does. Either way, fraud liability now sits
                // with the issuer. Complete the payment on your server.
                completePaymentOnServer(paymentId, response.nonce);
                return;
              }
 
              // Liability has NOT shifted. You may still complete the payment, but you
              // must set threeDSecureRequired to false on the follow-up request, and
              // you carry the fraud risk. This is a commercial decision.
              if (info && info.liabilityShiftPossible) {
                // Instrument was eligible for 3-D Secure but authentication did not
                // succeed. Higher risk.
              } else {
                // Instrument was never eligible for 3-D Secure.
              }
 
              handleUnauthenticatedPayment(paymentId, response.nonce, info);
              return;
            }
 
            if (response.code === '2004') {
              // An error occurred during authentication.
              showRetryableError();
              return;
            }
 
            // Any other code: log it and fail safe rather than silently continuing.
            console.warn('Unexpected code from handleAction', response.code, response.message);
            showGenericError();
          })
          .catch(function (handleErr) {
            // handleErr usually carries a 3-D Secure action error code explaining what
            // went wrong. Include it verbatim in any support request.
            console.error(
              'Exception while processing 3-D Secure action: ' + JSON.stringify(handleErr)
            );
            showGenericError();
          });
      }
    );
  }
);

Deciding what to do when liability has not shifted

liabilityShifted: false is not automatically a decline. It is a risk decision only you can make.

To complete a payment where liability has not shifted, set threeDSecureRequired to false on the follow-up request. Otherwise it will be rejected.

Error reference

When handleAction rejects, the error usually carries one of the codes below. Log the entire error object — not just the code — and include it in any support request along with the paymentId.

General 3-D Secure errors

Malformed action errors

These indicate the action object reaching handleAction is not what the module expected. In almost every case the cause is in the relay between your server and your client: partial serialisation, an object being stringified twice, or only part of the payload being forwarded.

PSP-specific errors

The two FAILED_TO_LOAD_SDK errors mean a third-party script could not be fetched from the customer's browser. Check your content security policy allows the PSP's script domains.

Troubleshooting

Some PSPs require additional fields on the original payment request before 3-D Secure will work at all — in particular browserData, channel and origin. If authentication fails consistently for a given PSP, confirm those are populated before investigating the client.

Testing

Use the sandbox asset host and API subdomain together, and drive challenges with the simulator PSPs.

Worth covering explicitly before you go live:

• A frictionless authentication that resolves with 2002 and a liability shift.
• A challenge rendered on your real checkout page, with headers, banners and any third-party widgets present, to confirm the z-index is high enough. A challenge that renders fine in isolation can still be buried in production.
• A challenge the customer abandons, to verify your windowClosed handling and that your pay button becomes usable again.
• A payment requiring two consecutive actions, to prove your loop works.
• A 2004 processing error, to verify your error path.

Related documentation

• Web SDK Introduction — creating the client and handling SDK errors
• Post-Response Actions — the server-side view
• 3-D Secure Payment Flow — end-to-end sequence
• POST /v1/payments — see the Payment with ProviderThreeDSecureNonce example for completing an authenticated payment
• Response Codes — full code list
• Auto 3-D Secure Step-up — automatic step-up behaviour
• Support — include the paymentId and the full error object