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.

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.

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 Code	Description
200 OK	Everything worked as expected.
400 Bad Request	Often due to a missing, required parameter.
401 Unauthorized	Invalid accessId or accessKey.
500 Server error	Something went wrong on Trustly's end.
503 Service Unavailable	The 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 Code	Description
100	Internal error. An internal error (an internal database exception for example) occurred when trying to process the request.
150	Remote error. A remote error (the consumer's bank interface is down) occurred when trying to process the request. This is an internal error.
200	Invalid parameter error. One of the request parameters is invalid (sending an invalid amount format string for example).
300	Security error. These are generic security errors that can happen when trying to process the request.
326	Expired split token.
330	Invalid account.
331	Not enough balance.
375	Access control error. These occurs when some security parameter (accessId, accessKey or requestSignature) is invalid and the request cannot be processed.
390	Fraud analysis. Suspicious transaction or negative data.

Micro Challenge Deposits

Adding support for Micro Challenge Deposits (MCD)

Create the initial bank authorization

🚧
Warning

Handle the redirect

Retrieving the test verification code

Initiate the verification flow

📘
Tip

📘
Info

Enter the test verification code

Handle the redirect

Testing

Error Handling

Adding support for Micro Challenge Deposits (MCD)

Create the initial bank authorization

🚧Warning

Handle the redirect

Retrieving the test verification code

Initiate the verification flow

📘Tip

📘Info

Enter the test verification code

Handle the redirect

Testing

Error Handling

🚧
Warning

📘
Tip

📘
Info