Micro Challenge Deposits

Adding support for Micro Challenge Deposits (MCD)

If your account has been enabled to process Micro Challenge Deposit (MCD) verification requests, there is an additional step you must take to finish the verification process.

Create the initial bank authorization

The initial bank authorization does not change. Pass in the same establishData object as was provided during the original authorization.

var establishData = {
  accessId: {accessId},
  requestSignature: {requestSignature},
  merchantId: {merchantId},
  description: 'transaction description',
  merchantReference: 'merchant reference',
  paymentType: 'Retrieval',
  returnUrl: "https://yourapp.com/path/return",
  cancelUrl: "https://yourapp.com/path/cancel"   
};

Note: see the Securing Requests reference for details on how to calculate the requestSignature


🚧

Warning

Do not pass Consumer PII (name, email address, etc) in the description field. You can pass Consumer PII in the customer object.

404 404

Handle the redirect

Once you get a successful redirect to your returnUrl, confirm if the user needs to continue the verification process. Ensure the payment.paymentProvider.type value is 2 (Manual Entry), the status is 2 (Authorized), and the payment.account.verified is false. Because the payment.paymentProvider.type is 2 (Manual Entry) and the payment.account.verified value is false, message to the user to return to your site when they are ready to verify their account.

Retrieving the test verification code

You can use our Sandbox Merchant Portal to view the test account verification deposit code that was generated for the Bank Authorization.

1. After signing into the Sandbox Merchant Portal, find the Bank Authorization transaction your created earlier.

2. Click on the Transaction ID to bring up the details. Scroll down to the 'Account Verification Deposits' section. Copy the 'Reference Code' value.

Initiate the verification flow

The following examples are using the JavaScript SDK. For guidance on building for mobile apps see the Mobile Apps guide.

1. To load the SDK on the page, use the following JavaScript tag (replacing {accessId} with the Access Id provided to you by Trustly):

<script src="https://sandbox.trustly.com/start/scripts/trustly.js?accessId={accessId}"> </script>

2. To provide optional Trustly configuration options, create a TrustlyOptions object:

var TrustlyOptions = {
  closeButton: false,
  dragAndDrop: false,
  widgetContainerId: "widget-container-id" //Page element container for the widget
};

For details on the Trustly configuration options, refer to the SDK Specification.

3. To provide the transaction details to the SDK, create an establishData object:

var establishData = {
  accessId: {accessId},
  requestSignature: {requestSignature},
  merchantId: {merchantId},
  transactionId: {transactionId},
  merchantReference: 'merchant reference',
  returnUrl: 'https://merchant.com/trustly/return',
  cancelUrl: 'https://merchant.com/trustly/cancel'		
};

📘

Tip

Ensure you're securing your call by including the requestSignature parameter.

4. Finally, call the Trustly SDK's establish function:

Trustly.establish(establishData, TrustlyOptions);

The following is a full HTML page using the above example.

📘

Info

You'll want to replace {accessId} and {merchantId} with the values provided to you by Trustly

<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script>
      var TrustlyOptions = {
        closeButton: false,
        dragAndDrop: true,
        widgetContainerId: 'widget',
      };
    </script>
    <script src="https://sandbox.trustly.com/start/scripts/trustly.js?accessId={accessId}"></script>
  </head>
  <body style="margin: 0;">
    <div id="widget"></div>
  </body>
   <script>
    var establishData = {
      accessId: {accessId},
      requestSignature: {requestSignature},
      merchantId: {merchantId},
      transactionId: {transactionId},
      merchantReference: 'merchant reference',
      returnUrl: 'https://merchant.com/trustly/return',
      cancelUrl: 'https://merchant.com/trustly/cancel'		
    };
    Trustly.establish(establishData, TrustlyOptions);
  </script>
</html>

Enter the test verification code

Using the verification HTML you created above, launch the Trustly Lightbox.

404

After entering the code retrieved from the Sandbox Merchant Portal and clicking OK, the user is directed back to your site.

Handle the redirect

Once you get a successful redirect to your returnUrl, confirm if the user is indeed verified. Ensure the payment.paymentProvider.type value is 2 (Manual Entry), the status is 2 (Authorized), and the payment.account.verified is true. If payment.account.verified is true, the account is verified.

Testing

Trustly offers a Demo Bank in the Sandbox environment that can be used to trigger a number of testing scenarios. Read more in Testing.

Error Handling

Trustly uses conventional HTTP response codes to indicate success or failure of an API request.

HTTP Status CodeDescription
200 OKEverything worked as expected.
400 Bad RequestOften due to a missing, required parameter.
401 UnauthorizedInvalid accessId or accessKey.
500 Server errorSomething went wrong on Trustly's end.
503 Service UnavailableThe server is currently unable to handle the request due to a temporary overloading or server maintenance.

Not all errors map cleanly onto HTTP response codes, however. In addition to the HTTP response code, Trustly returns an array of error objects that describes the errors as a JSON string such as the example below.

{
  "errors": [
    {
      "domain" : "com.trustly.merchantgateway.v1.exception.InvalidParameterException",
      "code" : 200,
      "message" : "Could not find a transaction using Id 10000021"
    }
  ]
}
Error CodeDescription
100Internal error. An internal error (an internal database exception for example) occurred when trying to process the request.
150Remote error. A remote error (the consumer's bank interface is down) occurred when trying to process the request. This is an internal error.
200Invalid parameter error. One of the request parameters is invalid (sending an invalid amount format string for example).
300Security error. These are generic security errors that can happen when trying to process the request.
326Expired split token.
330Invalid account.
331Not enough balance.
375Access control error. These occurs when some security parameter (accessId, accessKey or requestSignature) is invalid and the request cannot be processed.
390Fraud analysis. Suspicious transaction or negative data.